samples: usb: mass: rewrite documentation
The USB mass storage documentation was completely outdated. Rewrite it using reStructuredText, and mentioning the two possible overlays. Signed-off-by: Aurelien Jarno <aurelien@aurel32.net>
This commit is contained in:
Aurelien Jarno
Anas Nashif
parent
91159849a1
commit
e8a59728e1
2 changed files with 67 additions and 83 deletions
67
samples/subsys/usb/mass/README.rst
Normal file
67
samples/subsys/usb/mass/README.rst
Normal file
|
|
@ -0,0 +1,67 @@
|
||||||
|
.. _usb_mass:
|
||||||
|
|
||||||
|
USB Mass Storage Sample Application
|
||||||
|
###################################
|
||||||
|
|
||||||
|
Overview
|
||||||
|
********
|
||||||
|
|
||||||
|
This sample app demonstrates use of a USB Mass Storage driver by the Zephyr
|
||||||
|
project. This very simple driver enumerates a board with either RAM or FLASH
|
||||||
|
into an USB disk. This sample can be found under
|
||||||
|
:file:`samples/subsys/usb/mass` in the Zephyr project tree.
|
||||||
|
|
||||||
|
Requirements
|
||||||
|
************
|
||||||
|
|
||||||
|
This project requires a USB device driver, and either 16KiB of RAM or a FLASH
|
||||||
|
device.
|
||||||
|
|
||||||
|
Building and Running
|
||||||
|
********************
|
||||||
|
|
||||||
|
This sample can be built for multiple boards. The selection between a RAM-based
|
||||||
|
or a FLASH-based disk can be selected using the ``overlay-ram-disk.conf`` or
|
||||||
|
the ``overlay-flash-disk.conf`` overlays. In this example we will build the sample
|
||||||
|
with a RAM-based disk and for the quark_se_c1000_devboard board:
|
||||||
|
|
||||||
|
.. zephyr-app-commands::
|
||||||
|
:zephyr-app: samples/subsys/usb/mass
|
||||||
|
:board: quark_se_c1000_devboard
|
||||||
|
:gen-args: -DOVERLAY_CONFIG="overlay-ram-disk.conf"
|
||||||
|
:goals: build
|
||||||
|
:compact:
|
||||||
|
|
||||||
|
After you have built and flashed the sample app image to your board, plug the
|
||||||
|
board into a host device, for example, a PC running Linux.
|
||||||
|
The board will be detected as shown by the Linux journalctl command:
|
||||||
|
|
||||||
|
.. code-block:: console
|
||||||
|
|
||||||
|
$ journalctl -k -n 17
|
||||||
|
usb 2-2.4: new full-speed USB device number 29 using xhci_hcd
|
||||||
|
usb 2-2.4: New USB device found, idVendor=2fe3, idProduct=0100, bcdDevice= 0.11
|
||||||
|
usb 2-2.4: New USB device strings: Mfr=1, Product=2, SerialNumber=3
|
||||||
|
usb 2-2.4: Product: Zephyr MSC sample
|
||||||
|
usb 2-2.4: Manufacturer: ZEPHYR
|
||||||
|
usb 2-2.4: SerialNumber: 0.01
|
||||||
|
usb-storage 2-2.4:1.0: USB Mass Storage device detected
|
||||||
|
scsi host3: usb-storage 2-2.4:1.0
|
||||||
|
scsi 3:0:0:0: Direct-Access ZEPHYR ZEPHYR USB DISK 0.01 PQ: 0 ANSI: 0 CCS
|
||||||
|
sd 3:0:0:0: Attached scsi generic sg1 type 0
|
||||||
|
sd 3:0:0:0: [sdb] 32 512-byte logical blocks: (16.4 kB/16.0 KiB)
|
||||||
|
sd 3:0:0:0: [sdb] Write Protect is off
|
||||||
|
sd 3:0:0:0: [sdb] Mode Sense: 03 00 00 00
|
||||||
|
sd 3:0:0:0: [sdb] No Caching mode page found
|
||||||
|
sd 3:0:0:0: [sdb] Assuming drive cache: write through
|
||||||
|
sdb:
|
||||||
|
sd 3:0:0:0: [sdb] Attached SCSI removable disk
|
||||||
|
|
||||||
|
The disk contains a simple ``README.TXT`` file with the following content:
|
||||||
|
|
||||||
|
.. code-block:: console
|
||||||
|
|
||||||
|
This is a RAM Disk based USB Mass Storage demo for Zephyr.
|
||||||
|
|
||||||
|
Files can be added or removed like with a simple USB disk, of course within
|
||||||
|
the 16KiB limit.
|
||||||
|
|
@ -1,83 +0,0 @@
|
||||||
USB Mass Storage
|
|
||||||
================
|
|
||||||
|
|
||||||
Description:
|
|
||||||
|
|
||||||
This sample application turns the development board into a USB mass storage
|
|
||||||
device. Currently, USB device controller support
|
|
||||||
is only available for Quark SE based boards. So, this sample will only work on
|
|
||||||
those boards, such as Arduino 101. By playing around with options in the
|
|
||||||
prj.conf, you can select the storage for the mass storage device.
|
|
||||||
|
|
||||||
Usage
|
|
||||||
-----
|
|
||||||
Plug the board in a host device, for example, a PC running Linux.
|
|
||||||
The board will be detected as a mass storage device. The user should have
|
|
||||||
valid contents in Flash, which can be accomplished by running a fat_fs test
|
|
||||||
initially or can try formatting using the appropriate host utility.
|
|
||||||
The RAM Disk config should run out of the box.
|
|
||||||
|
|
||||||
--------------------------------------------------------------------------------
|
|
||||||
|
|
||||||
Building and Running Project:
|
|
||||||
|
|
||||||
Refer to https://www.zephyrproject.org/doc/boards/x86/arduino_101/doc/board.html
|
|
||||||
for details on flashing the image into an Arduino 101.
|
|
||||||
|
|
||||||
--------------------------------------------------------------------------------
|
|
||||||
|
|
||||||
Troubleshooting:
|
|
||||||
|
|
||||||
Problems caused by outdated project information can be addressed by
|
|
||||||
issuing one of the following commands then rebuilding the project:
|
|
||||||
|
|
||||||
make clean # discard results of previous builds
|
|
||||||
# but keep existing configuration info
|
|
||||||
or
|
|
||||||
make pristine # discard results of previous builds
|
|
||||||
# and restore pre-defined configuration info
|
|
||||||
|
|
||||||
Some Known issues:
|
|
||||||
1. If you are seeing issues on Arduino 101, try with
|
|
||||||
quark_se_c1000_devboard, only RAM Disk storage is supported on that board.
|
|
||||||
I have done a quick sanity check on Linux, Mac and Windows hosts and works
|
|
||||||
fine.
|
|
||||||
|
|
||||||
2. With Arduino 101, some issues were seen with some/older boards.
|
|
||||||
The boards with issues was functional with some hosts but showed issues with
|
|
||||||
other hosts. The USB protocol traces were captured and these are likely to be
|
|
||||||
hardware/timing/lower layer issues unrelated to the added protocol layer,
|
|
||||||
as we were unable to see any obvious protocol violations. Flash access was
|
|
||||||
verified on working boards/hosts.
|
|
||||||
|
|
||||||
Additional experiments with Arduino 101 show that issues are almost always
|
|
||||||
observed when connected under xHCI root hub's USB ports. On the same host,
|
|
||||||
when connected under eHCI hub's downstream ports, the board functionality could
|
|
||||||
be verified. So we suggest playing around with lsusb -t to identifty a non xHCI
|
|
||||||
USB port to plug in your Arduino 101.
|
|
||||||
--------------------------------------------------------------------------------
|
|
||||||
|
|
||||||
Sample Output (differs based on debug verbosity selected):
|
|
||||||
|
|
||||||
[general] [INF] mass_storage_init: Sect Count 32
|
|
||||||
[general] [INF] mass_storage_init: Memory Size 16384
|
|
||||||
[general] [INF] usb_dw_ep_set: usb_dw_ep_set ep 0, mps 64, type 0
|
|
||||||
[general] [DBG] mass_storage_status_cb: USB device supended
|
|
||||||
[general] [INF] usb_dw_ep_set: usb_dw_ep_set ep 80, mps 64, type 0
|
|
||||||
|
|
||||||
[general] [INF] main: The device is put in USB mass storage mode.
|
|
||||||
|
|
||||||
[general] [DBG] mass_storage_status_cb: USB device reset detected 4
|
|
||||||
[general] [DBG] mass_storage_status_cb: USB device connected
|
|
||||||
[general] [DBG] mass_storage_status_cb: USB device reset detected 4
|
|
||||||
[general] [DBG] mass_storage_status_cb: USB device connected
|
|
||||||
[general] [INF] usb_dw_ep_set: usb_dw_ep_set ep 84, mps 64, type 2
|
|
||||||
[general] [INF] usb_dw_ep_set: usb_dw_ep_set ep 3, mps 64, type 2
|
|
||||||
[general] [DBG] mass_storage_status_cb: USB device configured
|
|
||||||
[general] [DBG] mass_storage_class_handle_req:MSC_REQUEST_GET_MAX_LUN
|
|
||||||
[general] [DBG] mass_storage_bulk_out: > BO - READ_CBW
|
|
||||||
[general] [DBG] CBWDecode: >> INQ
|
|
||||||
[general] [DBG] mass_storage_bulk_in: < BI - SEND_CSW
|
|
||||||
[general] [DBG] mass_storage_bulk_in: < BI - WAIT_CSW
|
|
||||||
[general] [DBG] mass_storage_bulk_out: > BO - READ_CBW
|
|
||||||
[general] [DBG] CBWDecode: >> TUR
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue