86 lines
3.6 KiB
Markdown
86 lines
3.6 KiB
Markdown
# System / `usbmsc` USB storage driver
|
||
|
||
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:
|
||
|
||
```c
|
||
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:
|
||
|
||
```shell
|
||
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`).
|