84 lines
3.8 KiB
ReStructuredText
84 lines
3.8 KiB
ReStructuredText
|
===========================================
|
|||
|
|
``usbmsc`` USB Mass Storage Device Commands
|
|||
|
|
===========================================
|
|||
|
|
|
|||
|
|
This add-on registers a block device driver, then exports the block the device
|
|||
|
|
using the USB storage class driver. In order to use this add-on, your
|
|||
|
|
board-specific logic must provide the function::
|
|||
|
|
|
|||
|
|
void board_usbmsc_initialize(void);
|
|||
|
|
|
|||
|
|
This function will be called by the ``system/usbmsc`` indirectly via the ``boardctl``
|
|||
|
|
``BOARDIOC_USBDEV_CONTROL`` command in order to do the actual registration of the
|
|||
|
|
block device drivers. For examples of the implementation of
|
|||
|
|
``board_usbmsc_initialize()`` see
|
|||
|
|
``boards/arm/lpc214x/mcu123-lpc214x/src/up_usbmsc.c`` or
|
|||
|
|
``boards/arm/stm32/stm3210e-eval/src/usbmsc.c``.
|
|||
|
|
|
|||
|
|
Configuration options:
|
|||
|
|
|
|||
|
|
- ``CONFIG_NSH_BUILTIN_APPS`` – This add-on can be built as two NSH "built-in"
|
|||
|
|
commands if this option is selected: ``msconn`` will connect the USB mass
|
|||
|
|
storage device; ``msdis`` will disconnect the USB storage device.
|
|||
|
|
|
|||
|
|
- ``CONFIG_BOARDCTL`` – Enables the ``boardctl()`` interfaces.
|
|||
|
|
|
|||
|
|
- ``CONFIG_BOARDCTL_USBDEVCTRL`` – Enables the ``BOARDIOC_USBDEV_CONTROL``
|
|||
|
|
``boardctl()`` command.
|
|||
|
|
|
|||
|
|
- ``CONFIG_SYSTEM_USBMSC_NLUNS`` – Defines the number of logical units (LUNs)
|
|||
|
|
exported by the USB storage driver. Each LUN corresponds to one exported block
|
|||
|
|
driver (or partition of a block driver). May be ``1``, ``2``, or ``3``. Default is
|
|||
|
|
``1``.
|
|||
|
|
|
|||
|
|
- ``CONFIG_SYSTEM_USBMSC_DEVMINOR1`` – The minor device number of the block driver
|
|||
|
|
for the first LUN. For example, ``N`` in ``/dev/mmcsdN``. Used for registering the
|
|||
|
|
block driver. Default is zero.
|
|||
|
|
|
|||
|
|
- ``CONFIG_SYSTEM_USBMSC_DEVPATH1`` – The full path to the registered block
|
|||
|
|
driver. Default is ``/dev/mmcsd0``
|
|||
|
|
|
|||
|
|
- ``CONFIG_SYSTEM_USBMSC_DEVMINOR2`` and ``CONFIG_SYSTEM_USBMSC_DEVPATH2``
|
|||
|
|
Similar parameters that would have to be provided if
|
|||
|
|
``CONFIG_SYSTEM_USBMSC_NLUNS`` is ``2`` or ``3``. No defaults.
|
|||
|
|
|
|||
|
|
- ``CONFIG_SYSTEM_USBMSC_DEVMINOR3`` and ``CONFIG_SYSTEM_USBMSC_DEVPATH3``
|
|||
|
|
Similar parameters that would have to be provided if
|
|||
|
|
``CONFIG_SYSTEM_USBMSC_NLUNS`` is ``3``. No defaults.
|
|||
|
|
|
|||
|
|
- ``CONFIG_SYSTEM_USBMSC_DEBUGMM`` – Enables some debug tests to check for memory
|
|||
|
|
usage and memory leaks.
|
|||
|
|
|
|||
|
|
If ``CONFIG_USBDEV_TRACE`` is enabled (or ``CONFIG_DEBUG_FEATURES`` and
|
|||
|
|
``CONFIG_DEBUG_USB``), then the code will also manage the USB trace output. The
|
|||
|
|
amount of trace output can be controlled using:
|
|||
|
|
|
|||
|
|
- ``CONFIG_SYSTEM_USBMSC_TRACEINIT`` – Show initialization events.
|
|||
|
|
- ``CONFIG_SYSTEM_USBMSC_TRACECLASS`` – Show class driver events.
|
|||
|
|
- ``CONFIG_SYSTEM_USBMSC_TRACETRANSFERS`` – Show data transfer events.
|
|||
|
|
- ``CONFIG_SYSTEM_USBMSC_TRACECONTROLLER`` – Show controller events.
|
|||
|
|
- ``CONFIG_SYSTEM_USBMSC_TRACEINTERRUPTS`` – Show interrupt-related events.
|
|||
|
|
|
|||
|
|
Error results are always shown in the trace output
|
|||
|
|
|
|||
|
|
**Note 1**: When built as an NSH add-on command (``CONFIG_NSH_BUILTIN_APPS=y``),
|
|||
|
|
Caution should be used to assure that the SD drive (or other storage device) is
|
|||
|
|
not in use when the USB storage device is configured. Specifically, the SD
|
|||
|
|
driver should be unmounted like::
|
|||
|
|
|
|||
|
|
nsh> mount -t vfat /dev/mmcsd0 /mnt/sdcard # Card is mounted in NSH
|
|||
|
|
...
|
|||
|
|
nsh> umount /mnd/sdcard # Unmount before connecting USB!!!
|
|||
|
|
nsh> msconn # Connect the USB storage device
|
|||
|
|
...
|
|||
|
|
nsh> msdis # Disconnect USB storate device
|
|||
|
|
nsh> mount -t vfat /dev/mmcsd0 /mnt/sdcard # Restore the mount
|
|||
|
|
|
|||
|
|
Failure to do this could result in corruption of the SD card format.
|
|||
|
|
|
|||
|
|
**Note 2**: This add-on used internal USB device driver interfaces. As such, it
|
|||
|
|
relies on internal OS interfaces that are not normally available to a user-space
|
|||
|
|
program. As a result, this add-on cannot be used if a NuttX is built as a
|
|||
|
|
protected, supervisor kernel (``CONFIG_BUILD_PROTECTED`` or
|
|||
|
|
``CONFIG_BUILD_KERNEL``).
|