--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,7 @@
+2010-11-13  John Dallaway  <john@dallaway.org.uk>
+
+	* sgml/doclist: Add USB mass storage documentation.
+	
 2010-02-25  John Dallaway  <john@dallaway.org.uk>
 
 	* sgml/makemakefile: Update copyright dates.

--- 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

--- 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  <john@dallaway.org.uk>
+
+     * cdl/usbs_msd.cdl: Reference per-package documentation.
+
+2010-11-13  Christophe Coutand  <ccoutand@stmi.com>
+
+     * doc/usbs_msd.sgml: Added package documentation
+
 2010-11-12  Christophe Coutand  <ccoutand@stmi.com>
 
      *include/usbs_msd_opcode.h

--- 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 }

new file mode 100644
--- /dev/null
+++ b/packages/io/usb/msd/slave/current/doc/usbs_msd.sgml
@@ -0,0 +1,275 @@
+<!-- DOCTYPE reference  PUBLIC "-//OASIS//DTD DocBook V3.1//EN" -->
+
+<!-- {{{ Banner                         -->
+
+<!-- =============================================================== -->
+<!--                                                                 -->
+<!--     usbs_msd.sgml                                               -->
+<!--                                                                 -->
+<!--     USB slave-side Mass Storage Support package.                -->
+<!--                                                                 -->
+<!-- =============================================================== -->
+<!-- ####ECOSDOCCOPYRIGHTBEGIN####                                   -->
+<!-- =============================================================== -->
+<!-- Copyright (C) 2010 Free Software Foundation, Inc.               -->
+<!-- This material may be distributed only subject to the terms      -->
+<!-- and conditions set forth in the Open Publication License, v1.0  -->
+<!-- or later (the latest version is presently available at          -->
+<!-- http://www.opencontent.org/openpub/)                            -->
+<!-- Distribution of the work or derivative of the work in any       -->
+<!-- standard (paper) book form is prohibited unless prior           -->
+<!-- permission obtained from the copyright holder                   -->
+<!-- =============================================================== -->
+<!-- ####ECOSDOCCOPYRIGHTEND####                                     -->
+<!-- =============================================================== -->
+<!-- #####DESCRIPTIONBEGIN####                                       -->
+<!--                                                                 -->
+<!-- Author(s):   ccoutand                                           -->
+<!-- Contact(s):                                                     -->
+<!-- Date:        2010/11/13                                         -->
+<!-- Version:     0.01                                               -->
+<!--                                                                 -->
+<!-- ####DESCRIPTIONEND####                                          -->
+<!-- =============================================================== -->
+
+<!-- }}} -->
+
+<part id="io-usb-slave-msd">
+  <!-- reference id="io-usb-slave-msd" -->
+  <title>eCos Support for USB Mass Storage Peripherals</title>
+  
+  <!-- {{{ Intro                          -->
+  
+  <refentry id="usbs-msd-intro">
+    <refmeta>
+      <refentrytitle>Introduction</refentrytitle>
+    </refmeta>
+    <refnamediv>
+      <refname>Introduction</refname>
+      <refpurpose>
+        eCos support for USB Mass Storage Peripherals
+      </refpurpose>
+    </refnamediv>
+    
+    <refsect1><title>Introduction</title>
+      <para>
+        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.
+      </para>
+      <para>
+        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:
+      </para>
+      <screen width=72 format=linespecific>
+        $ ecosconfig add usbs_msd
+      </screen>
+      <para>
+        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 <literal>usbs_msd_start()</literal> 
+        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.
+      </para>
+    </refsect1>
+  </refentry>
+  
+  <!-- }}} -->
+  <!-- {{{ Config                          -->
+  
+  <refentry id="usbs-msd-config">
+    <refmeta>
+      <refentrytitle>Configuration</refentrytitle>
+    </refmeta>
+    <refnamediv>
+      <refname>Configuration</refname>
+      <refpurpose>Configuration USB Mass Storage Peripherals</refpurpose>
+    </refnamediv>
+    
+    <refsect1><title>Configuration</title>
+      <para>
+        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.
+      </para>
+
+      <refsect2><title>Endpoints</title>     
+      <para>
+        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
+        <literal>CYGDAT_IO_USB_SLAVE_MSD0_EP0</literal>. 
+        The default values is set to <literal>"usbs_at91_ep0"</literal>. 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 <literal>CYGDAT_IO_USB_SLAVE_MSD0_TX_EP</literal> 
+         and <literal>CYGDAT_IO_USB_SLAVE_MSD0_RX_EP</literal> respectively.
+
+        In addition, the  TX and RX enpoints number must be provided by the user. 
+        They are configured with  <literal>CYGNUM_IO_USB_SLAVE_MSD0_TX_EP_NUM</literal> 
+        and <literal>CYGNUM_IO_USB_SLAVE_MSD0_RX_EP_NUM</literal>
+
+        In case of dynamic endpoints configuration, only the endpoint number is mandatory.
+      </para>
+
+      <para>
+        The last endpoints configuration parameters are the entpoints buffer size. They are set with:
+      <programlisting>
+      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
+      </programlisting>
+        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
+        <literal>CYGSEM_IO_USB_SLAVE_MSD_STALL_ENABLE</literal>.
+      </para>
+      </refsect2>
+      <refsect2><title>Enumeration</title>  
+      <para>
+        The USB MSD device will make its vendor:product ID known to
+        the host. This should be configured
+        with <literal>CYGNUM_IO_USB_SLAVE_MSD0_VENDOR_ID</literal> and
+        <literal>CYGNUM_IO_USB_SLAVE_MSD0_PRODUCT_ID</literal> NOTE:
+        The default configurations are not valid for commercial products, but
+        should work for testing.
+      </para>
+       <para>
+        The USB enumeration also contains text strings to describe the
+        device. The manufacturer string can be set with
+        <literal>CYGDAT_IO_USB_SLAVE_MSD0_MFG_STR</literal>. The product name
+        can be set with <literal>CYGDAT_IO_USB_SLAVE_MSD0_MFG_STR</literal>,
+        finally, the serial number can be set
+        with <literal>CYGDAT_IO_USB_SLAVE_MSD0_SERIAL_STR</literal>.
+      </para>
+      </refsect2>
+      <refsect2><title>Storage</title>  
+      <para>
+        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
+        <literal>USBS_MSD_CBW_MAX_LUN</literal> 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 
+        <literal>CYGDAT_IO_USB_SLAVE_MSD0_LUN0_NAME</literal>. The default value 
+        is assigned to <literal>"/dev/ramdisk0/1"</literal>, the first partition of the ramdisk
+         used by the test application.
+      </para>
+      </refsect2>      
+    </refsect1>
+  </refentry>
+  
+  <!-- }}} -->
+  <!-- {{{ Host Config                          -->
+  
+  <refentry id="usbs-msd-host-config">
+    <refmeta>
+      <refentrytitle>Host Configuration</refentrytitle>
+    </refmeta>
+    <refnamediv>
+      <refname>Host Configuration</refname>
+      <refpurpose>Host Configuration for USB Mass Storage like Peripherals
+      </refpurpose>
+    </refnamediv>
+    
+    <refsect1>
+      <title>Host Configuration</title>
+      <para>
+        With modern host operating system, no specific configuration of the 
+        host shall be required to bring up the eCos USB-Mass Storage Device.
+      </para>
+      <refsect2><title>SCSI command set</title>  
+      <para>
+       The USB-Mass Storage device will respond to a set of SCSI commands:
+      <programlisting>
+      INQUIRY
+      READ_CAPACITY
+      READ_10
+      WRITE_10
+      REQUEST_SENSE
+      TEST_UNIT_READY
+      </programlisting>
+      and partially to the commands:
+      <programlisting>
+      SENSE_6
+      VERIFY_10
+      REVENT_ALLOW_MEDIUM_REMOVAL
+      </programlisting>
+      </para>   
+      </refsect2>       
+    </refsect1>
+  </refentry>
+  
+  <!-- }}} -->
+  <!-- {{{ Using                         -->
+  
+  <refentry id="usbs-msd-using">
+   <refmeta>
+      <refentrytitle>Example</refentrytitle>
+    </refmeta>
+    <refnamediv>
+      <refname>Example</refname>
+      <refpurpose>Example for USB Mass Storage like Peripherals
+      </refpurpose>
+    </refnamediv>  
+    <refsect1>
+      <title>RAM disk</title>
+      <para>
+        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 <literal>"/dev/ramdisk0"</literal>. A FAT12 filesystem is created on top of it 
+        as the first partition of the disk. The partition is therefore accessible from 
+        <literal>"/dev/ramdisk0/1"</literal>. 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.
+      </para>   
+      <refsect2><title>Configuration</title>  
+      <para>
+        The test application was primarly tested with the AT91 architecture. The control 
+        endpoint is set to <literal>"usbs_at91_ep0"</literal> and the buffer size
+        to 8 bytes.
+        The TX endpoint is set to <literal>"usbs_at91_ep1"</literal> and the buffer size
+        to 64 bytes (with Tx (USB IN) endpoint number set to 1).
+        The RX endpoint is set to <literal>"usbs_at91_ep2"</literal> and the buffer size
+        to 64 bytes (with Rx (USB OUT) endpoint number set to 2).                 
+      </para>   
+      </refsect2>  
+   </refsect1>         
+  </refentry> 
+       
+  <!-- }}} -->
+</part>
+<!-- /reference -->