# HG changeset patch # User jld # Date 1289649441 0 # Node ID 9843108eda9d1cd1e98bd7cf611b287c0a0bc36c # Parent faa94c77900cac06a4108c8d25b1389607d67cc7 * doc/sgml/doclist: Add USB mass storage documentation. * packages/io/usb/msd/slave/current/doc/usbs_msd.sgml: New documentation file. * packages/io/usb/msd/slave/current/cdl/usbs_msd.cdl: Reference per-package documentation. diff --git a/doc/ChangeLog b/doc/ChangeLog --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,7 @@ +2010-11-13 John Dallaway + + * sgml/doclist: Add USB mass storage documentation. + 2010-02-25 John Dallaway * sgml/makemakefile: Update copyright dates. diff --git a/doc/sgml/doclist b/doc/sgml/doclist --- a/doc/sgml/doclist +++ b/doc/sgml/doclist @@ -41,6 +41,7 @@ services/power/common/current/doc/power. io/usb/slave/current/doc/usbs.sgml io/usb/eth/slave/current/doc/usbseth.sgml io/usb/serial/slave/current/doc/usbs_serial.sgml +io/usb/msd/slave/current/doc/usbs_msd.sgml hal/synth/arch/current/doc/synth.sgml hal/m68k/arch/current/doc/m68k.sgml hal/m68k/mcf52xx/var/current/doc/mcf52xx.sgml diff --git a/packages/io/usb/msd/slave/current/ChangeLog b/packages/io/usb/msd/slave/current/ChangeLog --- a/packages/io/usb/msd/slave/current/ChangeLog +++ b/packages/io/usb/msd/slave/current/ChangeLog @@ -1,3 +1,11 @@ +2010-11-13 John Dallaway + + * cdl/usbs_msd.cdl: Reference per-package documentation. + +2010-11-13 Christophe Coutand + + * doc/usbs_msd.sgml: Added package documentation + 2010-11-12 Christophe Coutand *include/usbs_msd_opcode.h diff --git a/packages/io/usb/msd/slave/current/cdl/usbs_msd.cdl b/packages/io/usb/msd/slave/current/cdl/usbs_msd.cdl --- a/packages/io/usb/msd/slave/current/cdl/usbs_msd.cdl +++ b/packages/io/usb/msd/slave/current/cdl/usbs_msd.cdl @@ -52,6 +52,7 @@ cdl_package CYGPKG_IO_USB_SLAVE_MSD { display "USB slave mass storage support" include_dir "cyg/io/usb" parent CYGPKG_IO_USB_SLAVE + doc ref/io-usb-slave-msd.html requires { CYGPKG_KERNEL } requires { CYGPKG_IO_DISK } diff --git a/packages/io/usb/msd/slave/current/doc/usbs_msd.sgml b/packages/io/usb/msd/slave/current/doc/usbs_msd.sgml new file mode 100644 --- /dev/null +++ b/packages/io/usb/msd/slave/current/doc/usbs_msd.sgml @@ -0,0 +1,275 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + eCos Support for USB Mass Storage Peripherals + + + + + + Introduction + + + Introduction + + eCos support for USB Mass Storage Peripherals + + + + Introduction + + Currently, the eCos USB-Mass Storage Device (MSD) slave package + provides support only for the SCSI transparent command set. The + package flexibility allows future extension for other sub-class, + .i.e. RBC, UFI etc.. + The package requires the actual storage media to use the eCos disk + interface. Disk sector size is assumed 512 bytes. + + + The USB-MSD package is not tied to any specific + hardware. It requires the presence of USB hardware on the + target and a suitable device driver to make endpoints + available for this code to use. The configuration system + cannot load the eCos package automatically for specific + targets, in the way that a USB device driver or an ethernet + driver can be loaded automatically. Instead, the package has + to be added explicitly. When using the command line tools this + will involve an operation like the following: + + + $ ecosconfig add usbs_msd + + + Typically, this will automatically cause the USB device driver + to become active. The USB-Mass Storage Device driver runs as a + thread, therefore requires the kernel package to be active. To + start the MSD interface, user must call the usbs_msd_start() + function. No other user intervention is required. + The MSD driver will interact directly with the storage media. + Care should be taken not to mount/use the filesystem present on + the media while used as a mass storage. This could potentially + damage the filesystem. + + + + + + + + + + Configuration + + + Configuration + Configuration USB Mass Storage Peripherals + + + Configuration + + The USB Mass Storage Device interface uses the bulk transfer mode. It needs + three endpoints for the communication with the host to be complete. + The control endpoint (commonly EP0), the transmission and reception + endpoints. The default CDL file contains configuration for + the USB-Mass Storage Device 0. While it is uncommon to have several USB + ports on a device, it is not impossible, hence user can update the package and + create a second device .e.g. MSD1. + + + Endpoints + + Each endpoint shall be configured according to the underlying hardware. + The endpoints configuration includes, the structure name, endpoint number + and buffer size according to the USB chip specification. + + The control endpoint is selected with + CYGDAT_IO_USB_SLAVE_MSD0_EP0. + The default values is set to "usbs_at91_ep0". This is the control + endpoint for the Atmel AT91 USB device driver. + + The TX and RX endpoints can be assigned statically or dynamically (assuming the USB + device driver supports it). In case of static configuration, the bulk IN and bulk OUT + endpoints are configured with CYGDAT_IO_USB_SLAVE_MSD0_TX_EP + and CYGDAT_IO_USB_SLAVE_MSD0_RX_EP respectively. + + In addition, the TX and RX enpoints number must be provided by the user. + They are configured with CYGNUM_IO_USB_SLAVE_MSD0_TX_EP_NUM + and CYGNUM_IO_USB_SLAVE_MSD0_RX_EP_NUM + + In case of dynamic endpoints configuration, only the endpoint number is mandatory. + + + + The last endpoints configuration parameters are the entpoints buffer size. They are set with: + + CYGNUM_IO_USB_SLAVE_MSD0_EP0_MAX_PACKET_SIZE + CYGNUM_IO_USB_SLAVE_MSD0_TX_EP_MAX_PACKET_SIZE + CYGNUM_IO_USB_SLAVE_MSD0_RX_EP_MAX_PACKET_SIZE + + A mass storage device must stall one or both bulk endpoints in + several situations. However, not all eCos USB device drivers seems + to implement this functionality correctly. Hence, this option is + disable by default. Testing shows that both Linux and Windows can + handle mass storage device with stall disable as long as all data transfer phase + are handled correctly. Enpoint stall can be enable with + CYGSEM_IO_USB_SLAVE_MSD_STALL_ENABLE. + + + Enumeration + + The USB MSD device will make its vendor:product ID known to + the host. This should be configured + with CYGNUM_IO_USB_SLAVE_MSD0_VENDOR_ID and + CYGNUM_IO_USB_SLAVE_MSD0_PRODUCT_ID NOTE: + The default configurations are not valid for commercial products, but + should work for testing. + + + The USB enumeration also contains text strings to describe the + device. The manufacturer string can be set with + CYGDAT_IO_USB_SLAVE_MSD0_MFG_STR. The product name + can be set with CYGDAT_IO_USB_SLAVE_MSD0_MFG_STR, + finally, the serial number can be set + with CYGDAT_IO_USB_SLAVE_MSD0_SERIAL_STR. + + + Storage + + To access the storage media, the USB MSD package requires the storage + media to use the eCos disk interface. The disk sector size is assumed + to be 512 bytes. Multiple logical units are supported by the package + (2 by default). + More logical units can be supported by changing the + USBS_MSD_CBW_MAX_LUN definition according + to the user needs. Two logical units can be either 2 partitions on the same + disk or 2 partitions on 2 different physical disks. + The first logical unit can be set with + CYGDAT_IO_USB_SLAVE_MSD0_LUN0_NAME. The default value + is assigned to "/dev/ramdisk0/1", the first partition of the ramdisk + used by the test application. + + + + + + + + + + + Host Configuration + + + Host Configuration + Host Configuration for USB Mass Storage like Peripherals + + + + + Host Configuration + + With modern host operating system, no specific configuration of the + host shall be required to bring up the eCos USB-Mass Storage Device. + + SCSI command set + + The USB-Mass Storage device will respond to a set of SCSI commands: + + INQUIRY + READ_CAPACITY + READ_10 + WRITE_10 + REQUEST_SENSE + TEST_UNIT_READY + + and partially to the commands: + + SENSE_6 + VERIFY_10 + REVENT_ALLOW_MEDIUM_REMOVAL + + + + + + + + + + + + Example + + + Example + Example for USB Mass Storage like Peripherals + + + + RAM disk + + The "ram disk" is a test application supplied to verify / debug the USB-Mass Storage + package. The minimal functionality of this test case is to create a tiny "ram disk" + device large of around 32 sectors of 512 bytes each. The disk devtab entry + is "/dev/ramdisk0". A FAT12 filesystem is created on top of it + as the first partition of the disk. The partition is therefore accessible from + "/dev/ramdisk0/1". The default behavior of the application is to + start the USB MSD thread. Once plugged into the host machine, an empty drive + called eCos-3.0 shall appear in the host explorer. + To test further, the FAT filesystem package can be included while compiling the test + application. If included, before the MSD driver is started, the application will + create 2 files (fee and foo) and 1 directory (bar) in the filesystem. Both files and + directory shall appear in the host explorer. + + Configuration + + The test application was primarly tested with the AT91 architecture. The control + endpoint is set to "usbs_at91_ep0" and the buffer size + to 8 bytes. + The TX endpoint is set to "usbs_at91_ep1" and the buffer size + to 64 bytes (with Tx (USB IN) endpoint number set to 1). + The RX endpoint is set to "usbs_at91_ep2" and the buffer size + to 64 bytes (with Rx (USB OUT) endpoint number set to 2). + + + + + + + +