This directory contains an USB Mass Storage Bulk-Only driver. It uses
the Usb session interface to access the USB device and provides Genode's
Block service to its client.

Behavior
--------

This driver only supports USB Mass Storage Bulk-Only devices that use the
SCSI Block Commands set (direct-access). Devices using different command
sets, e.g, SD/HC devices or some external disc drives will not work properly
if at all. The driver will query the device and tries to use the first
bulk-only interface it finds.

The following configuration snippets demonstrates how to use the driver:

!<start name="usb_block" ram="4M">
!  <provides> <service name="Block"/> </provides>
!  <config report="yes" writeable="yes" interface="0"
!          alt_setting="0" lun="0" reset_device="no" verbose_scsi="no"/>
!  <route>
!   <service name="Usb"> <child name="usb"/> </service>
!   <any-service> <parent/> <any-child/> </any-service>
!  </route>
!</start>

A policy matching the block-driver instance has to be configured at the USB
host controller driver.

!<start name="usb" ram="12M">
!  <provides><service name="Usb"/></provides>
!  <config>
!    <policy label="usb_block -> ">
!      <device vendor_id="0x13fe" product_id="0x5200"/>
!      <device name="usb-1-2"/>
!    </policy>
!  </config>
!</start>

The 'report' attribute instructs the driver to generate a 'devices' report
that contains meta information about the USB device it is accessing and
hence the Block session it is providing.

!<devices>
!  <device vendor="QEMU" product="QEMU USB HARDDRIVE" block_size="512" block_count="8192" writeable="no"/>
!</devices>

The report contains a 'device' node that includes the device's vendor name and
the product description as well as its block size and the number of blocks.
Although the parent node is called 'devices' the driver is only able to access
one and the same device and the report will therefore always contain one device
only.

The following attributes can be used to configure specific aspects of the
driver.

* The 'writeable' attribute denotes the permission of the Block session
  client to write to the USB device. Independent thereof the driver will
  query the device and will set the Block session operations accordingly.
* The 'interface' attribute specifies the USB interface the driver should
  use, while 'alt_setting' allows for selecting the appropriate alternate
  setting.
* If the device provides multiple SCSI devices the 'lun' attribute is used
  to select the right one.
* The 'reset_device' attribute instructs the driver to send a 'bulk-only
  mass storage reset' command to the device at the beginning of the
  initialization step. This command caused problems on at least one device,
  so it is omitted by default.
* The 'verbose_scsi' attribute can be useful for debugging.

The configuration of the USB block driver is applied on startup only and,
thus, cannot be changed at run-time. Therefore, the driver is either used in
a static system configuration where it is configured once or, in case of a
dynamic system configuration, a proper configuration is created on demand
for each new driver instance.
