Part 1
요약·해설
RAM-disk, FAT, SD card, LittleFS와 host-side mount 절차를 단계별로 설명합니다.
RAM · FLASH · SD
None · FAT · littlefs
SCSI · FUSE
Part 2
접을 수 있는 영어 원문 전체
영어 원문 전체 펼치기
9E6DB24389FCAA51C176DD77EAB07EF24350D6C5C664444A64F6DDAA6CA0EF22
.. zephyr:code-sample:: usb-mass
:name: USB Mass Storage
:relevant-api: usbd_api usbd_msc_device _usb_device_core_api file_system_api
Expose board's RAM or FLASH as a USB disk using USB Mass Storage driver.
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
:zephyr_file:`samples/subsys/usb/mass` in the Zephyr project tree.
Requirements
************
This project requires a USB device driver, and either 96KiB of RAM or a FLASH device.
Building and Running
********************
This sample can be built for multiple boards, customized through overlays found
in :zephyr_file:`samples/subsys/usb/mass/boards` in the Zephyr project tree.
The selection between a RAM-based or a FLASH-based disk and file system
can be chosen passing Kconfig configuration via the -D command-line switch.
RAM-disk Example without any file system
========================================
The default configurations selects RAM-based disk without any file system.
This example only needs additional 96KiB RAM for the RAM-disk and is intended
for testing USB mass storage class implementation.
.. zephyr-app-commands::
:zephyr-app: samples/subsys/usb/mass
:board: reel_board
:gen-args: -DEXTRA_DTC_OVERLAY_FILE="ramdisk.overlay"
:goals: build
:compact:
FAT FS Example
==============
If more than 96KiB are available, FAT files system can be used
with a RAM-disk. Alternatively it is possible with the FLASH-based disk.
In this example we will build the sample with a RAM-based disk:
.. zephyr-app-commands::
:zephyr-app: samples/subsys/usb/mass
:board: reel_board
:gen-args: -DEXTRA_DTC_OVERLAY_FILE="ramdisk.overlay" -DCONFIG_APP_MSC_STORAGE_RAM=y
:goals: build
:compact:
In this example we will build the sample with a FLASH-based disk and FAT
file system for Adafruit Feather nRF52840 Express. This board configures
to use the external 16 MiBi QSPI flash chip with a 2 MiBy FAT partition.
.. zephyr-app-commands::
:zephyr-app: samples/subsys/usb/mass
:board: adafruit_feather/nrf52840
:gen-args: -DCONFIG_APP_MSC_STORAGE_FLASH_FATFS=y
: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=0008, bcdDevice= 2.03
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: 86FE679A598AC47A
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 sg4 type 0
sd 3:0:0:0: [sdb] 256 512-byte logical blocks: (131 kB/128 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 output to the console will look something like this
(file system contents will be different):
.. code-block:: none
*** Booting Zephyr OS build zephyr-v2.3.0-1991-g4c8d1496eafb ***
Area 4 at 0x0 on GD25Q16 for 2097152 bytes
Mount /NAND:: 0
/NAND:: bsize = 512 ; frsize = 1024 ; blocks = 2028 ; bfree = 1901
/NAND: opendir: 0
F 0 SAMPLE.TXT
End of files
[00:00:00.077,423] <inf> main: The device is put in USB mass storage mode.
On most operating systems the drive will be automatically mounted.
SD Card Example
===============
This example requires SD card support, see :ref:`disk_access_api`, and
a SD card formatted with FAT filesystem.
If a board with SD card controller is available, the example can be built as
follows:
.. zephyr-app-commands::
:zephyr-app: samples/subsys/usb/mass
:board: mimxrt1050_evk
:gen-args: -DCONFIG_APP_MSC_STORAGE_SDCARD=y
:goals: build
:compact:
In case the board has no support for SD card controller, but the card can
be connected to SPI using e.g. a shield, example can be built as follows:
.. zephyr-app-commands::
:zephyr-app: samples/subsys/usb/mass
:board: nrf52840dk/nrf52840
:shield: waveshare_epaper_gdeh0154a07
:gen-args: -DCONFIG_APP_MSC_STORAGE_SDCARD=y
:goals: build
:compact:
Depending on the size of the media it can take time until the file system has
initialized the card and it is available via USB. It should also be noted that
the transfer speed over SPI is very slow.
.. code-block:: none
*** Booting Zephyr OS build v2.5.0-rc3-73-gd85067f0a759 ***
Mount /SD:: 0
[00:00:00.281,585] <inf> sdhc_spi: Found a ~3751 MiB SDHC card.
[00:00:00.282,867] <inf> sdhc_spi: Manufacturer ID=27 OEM='SM' Name='00000' Revision=0x10 Serial=0x16fdd47b
[00:00:00.308,654] <inf> sdhc_spi: Found a ~3751 MiB SDHC card.
[00:00:00.309,906] <inf> sdhc_spi: Manufacturer ID=27 OEM='SM' Name='00000' Revision=0x10 Serial=0x16fdd47b
/SD:: bsize = 512 ; frsize = 32768 ; blocks = 119776 ; bfree = 119773
/SD: opendir: 0
D 0 42
F 1111 TEST.TXT
End of files
[00:00:18.588,043] <inf> main: The device is put in USB mass storage mode.
LittleFS Example
================
This board configures to use the external 64 MiBi QSPI flash chip with a
128 KiBy `littlefs`_ partition compatible with the one produced by the
:zephyr:code-sample:`littlefs` sample.
.. zephyr-app-commands::
:zephyr-app: samples/subsys/usb/mass
:board: nrf52840dk/nrf52840
:gen-args: -DCONFIG_APP_MSC_STORAGE_FLASH_LITTLEFS=y
:goals: build
:compact:
After you have built and flashed the sample app image to your board,
connect the board's two USB connectors (debug and nRF USB) to a host
running a littlefs-FUSE-capable operating system. The output to the
console will look something like this (file system contents will be
different):
.. code-block:: none
*** Booting Zephyr OS build zephyr-v2.2.0-1966-g7815942d5fc5 ***
Area 4 at 0x0 on MX25R64 for 65536 bytes
[00:00:00.005,310] <inf> main: The device is put in USB mass storage mode.
[00:00:00.009,002] <inf> littlefs: LittleFS version 2.2, disk version 2.0
[00:00:00.009,063] <inf> littlefs: FS at MX25R64:0x0 is 16 0x1000-byte blocks with 512 cye
[00:00:00.009,063] <inf> littlefs: sizes: rd 16 ; pr 16 ; ca 64 ; la 32
[00:00:00.011,718] <inf> littlefs: /lfs mounted
Mount /lfs: 0
/lfs: bsize = 16 ; frsize = 4096 ; blocks = 16 ; bfree = 13
/lfs opendir: 0
F 8 hi
F 128 linux
F 5 newfile
End of files
For information on mounting littlefs file system on Linux or FreeBSD
systems refer to the "littlefs Usage" section below.
littlefs Usage
==============
While a FAT-based file system can be mounted by many systems automatically,
mounting the littlefs file system on a Linux or FreeBSD system can be
accomplished using the `littlefs-FUSE`_ utility.
First determine the local device name from the system log, e.g.:
.. code-block:: none
Apr 25 08:10:25 tirzah kernel: [570310.921039] scsi 17:0:0:0: Direct-Access ZEPHYR ZEPHYR USB DISK 0.01 PQ: 0 ANSI: 0 CCS
Apr 25 08:10:25 tirzah kernel: [570310.921550] sd 17:0:0:0: Attached scsi generic sg4 type 0
Apr 25 08:10:25 tirzah kernel: [570310.922277] sd 17:0:0:0: [sdd] 256 512-byte logical blocks: (131 kB/128 KiB)
Apr 25 08:10:25 tirzah kernel: [570310.922696] sd 17:0:0:0: [sdd] Write Protect is off
This shows that the block device associated with the USB drive is
``/dev/sdd``:
.. code-block:: shell
tirzah[447]$ ll /dev/sdd
brw-rw---- 1 root disk 8, 48 Apr 25 08:10 /dev/sdd
This can be mounted as a file system with the following commands:
.. code-block:: shell
sudo chmod a+rw /dev/sdd # required to allow user access
mkdir /tmp/lfs
lfs \
--read_size=16 \
--prog_size=16 \
--block_size=4096 \
--block_count=32 \
--cache_size=64 \
--lookahead_size=32 \
/dev/sdd /tmp/lfs
which produces output like this (disk contents will vary):
.. code-block:: none
tirzah[467]$ ls -l /tmp/lfs
total 0
-rwxrwxrwx 0 root root 8 Dec 31 1969 hi
-rwxrwxrwx 0 root root 128 Dec 31 1969 linux
-rwxrwxrwx 0 root root 5 Dec 31 1969 newfile
``lfs`` is a mount command and you should take care to unmount the
device before removing the USB drive:
.. code-block:: shell
umount /tmp/lfs
littlefs parameter selection
----------------------------
Be aware that the parameters passed to :command:`lfs` in the example
above **must** exactly match the corresponding parameters used to
initialize the file system. The required parameters can be observed
from the Zephyr mount log messages:
.. code-block:: none
[00:00:00.009,002] <inf> littlefs: LittleFS version 2.2, disk version 2.0
[00:00:00.009,063] <inf> littlefs: FS at MX25R64:0x0 is 16 0x1000-byte blocks with 512 cye
[00:00:00.009,063] <inf> littlefs: sizes: rd 16 ; pr 16 ; ca 64 ; la 32
* ``--read_size`` corresponds to the ``rd`` size and is 16;
* ``--prog_size`` corresponds to the ``pr`` size and is 16;
* ``--block_size`` comes from ``0x1000-byte blocks`` and is 4096 (0x1000);
* ``--block_count`` comes from ``16 0x1000-byte blocks`` and is 16;
* ``--cache_size`` comes from the ``ca`` size and is 64;
* ``--lookahead_size`` comes from the ``la`` size and is 32
If any of the parameters are inconsistent between the Zephyr and Linux
specification the file system will not mount correctly.
.. _littlefs: https://github.com/littlefs-project/littlefs
.. _littlefs-FUSE: https://github.com/littlefs-project/littlefs-fuse
Part 3
한국어 전문 번역
개요
Zephyr project의 USB Mass Storage driver를 사용해 board의 RAM 또는 FLASH를 USB disk로 노출하는 sample입니다. Source는 samples/subsys/usb/mass에 있습니다.
요구 사항
USB device driver와 96 KiB RAM 또는 FLASH device 가운데 하나가 필요합니다.
빌드 및 실행
여러 board용으로 build할 수 있으며, project tree의 samples/subsys/usb/mass/boards에 있는 overlay로 board별 구성을 적용합니다. RAM 기반 disk와 FLASH 기반 disk, file system 선택은 -D command-line switch로 Kconfig configuration을 전달해 결정합니다.
File system 없는 RAM-disk 예제
기본 configuration은 file system이 없는 RAM 기반 disk를 선택합니다. RAM-disk용으로 96 KiB RAM만 추가로 필요하며 USB Mass Storage Class 구현 자체를 시험하기 위한 구성입니다.
west build -b reel_board samples/subsys/usb/mass -- -DEXTRA_DTC_OVERLAY_FILE="ramdisk.overlay"
FAT FS 예제
96 KiB보다 많은 RAM을 사용할 수 있다면 RAM-disk에 FAT file system을 구성할 수 있습니다. FLASH 기반 disk에도 FAT를 사용할 수 있습니다. 다음은 RAM 기반 FAT disk를 build하는 example입니다.
west build -b reel_board samples/subsys/usb/mass -- -DEXTRA_DTC_OVERLAY_FILE="ramdisk.overlay" -DCONFIG_APP_MSC_STORAGE_RAM=y
다음은 Adafruit Feather nRF52840 Express에서 FLASH 기반 disk와 FAT file system을 사용하는 example입니다. 이 board는 외부 16 MiB QSPI flash chip의 2 MiB partition을 FAT용으로 구성합니다.
west build -b adafruit_feather/nrf52840 samples/subsys/usb/mass -- -DCONFIG_APP_MSC_STORAGE_FLASH_FATFS=y
Image를 build하고 board에 flash한 뒤 Linux PC 같은 host에 연결합니다. journalctl에는 USB Mass Storage, SCSI direct-access device와 removable block device sdb가 나타납니다.
$ 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=0008, bcdDevice= 2.03
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: 86FE679A598AC47A
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 sg4 type 0
sd 3:0:0:0: [sdb] 256 512-byte logical blocks: (131 kB/128 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
Console에는 storage area, mount 결과, block 크기와 남은 공간, directory 내용, USB mass storage mode 진입 message가 표시됩니다. 실제 file system 내용은 달라질 수 있습니다.
*** Booting Zephyr OS build zephyr-v2.3.0-1991-g4c8d1496eafb ***
Area 4 at 0x0 on GD25Q16 for 2097152 bytes
Mount /NAND:: 0
/NAND:: bsize = 512 ; frsize = 1024 ; blocks = 2028 ; bfree = 1901
/NAND: opendir: 0
F 0 SAMPLE.TXT
End of files
[00:00:00.077,423] <inf> main: The device is put in USB mass storage mode.
대부분의 operating system은 이 drive를 자동으로 mount합니다.
SD Card 예제
FAT file system으로 format된 SD card와 SD card 지원이 필요합니다. 자세한 storage 접근 조건은 disk access API를 참고합니다. SD card controller가 있는 board에서는 다음과 같이 mimxrt1050_evk용 image를 build합니다.
west build -b mimxrt1050_evk samples/subsys/usb/mass -- -DCONFIG_APP_MSC_STORAGE_SDCARD=y
Board에 SD card controller가 없지만 shield 등을 통해 card를 SPI에 연결할 수 있다면 다음과 같이 nRF52840 DK와 Waveshare shield를 지정해 build합니다.
west build -b nrf52840dk/nrf52840 --shield waveshare_epaper_gdeh0154a07 samples/subsys/usb/mass -- -DCONFIG_APP_MSC_STORAGE_SDCARD=y
Media 크기에 따라 file system이 card를 초기화하고 USB에서 사용할 수 있게 될 때까지 시간이 걸릴 수 있습니다. SPI를 통한 전송 속도도 매우 느립니다. Console에서 SDHC card 탐지, mount와 USB mass storage mode 진입을 확인합니다.
*** Booting Zephyr OS build v2.5.0-rc3-73-gd85067f0a759 ***
Mount /SD:: 0
[00:00:00.281,585] <inf> sdhc_spi: Found a ~3751 MiB SDHC card.
[00:00:00.282,867] <inf> sdhc_spi: Manufacturer ID=27 OEM='SM' Name='00000' Revision=0x10 Serial=0x16fdd47b
[00:00:00.308,654] <inf> sdhc_spi: Found a ~3751 MiB SDHC card.
[00:00:00.309,906] <inf> sdhc_spi: Manufacturer ID=27 OEM='SM' Name='00000' Revision=0x10 Serial=0x16fdd47b
/SD:: bsize = 512 ; frsize = 32768 ; blocks = 119776 ; bfree = 119773
/SD: opendir: 0
D 0 42
F 1111 TEST.TXT
End of files
[00:00:18.588,043] <inf> main: The device is put in USB mass storage mode.
LittleFS 예제
이 configuration은 외부 64 MiB QSPI flash chip에 128 KiB littlefs partition을 사용하며, Zephyr littlefs sample이 만드는 partition과 호환됩니다.
west build -b nrf52840dk/nrf52840 samples/subsys/usb/mass -- -DCONFIG_APP_MSC_STORAGE_FLASH_LITTLEFS=y
Image를 build하고 flash한 뒤 board의 debug USB와 nRF USB connector를 모두 littlefs-FUSE를 지원하는 host에 연결합니다. Console에는 QSPI area, littlefs version과 geometry, mount 결과, directory 내용이 나타납니다.
*** Booting Zephyr OS build zephyr-v2.2.0-1966-g7815942d5fc5 ***
Area 4 at 0x0 on MX25R64 for 65536 bytes
[00:00:00.005,310] <inf> main: The device is put in USB mass storage mode.
[00:00:00.009,002] <inf> littlefs: LittleFS version 2.2, disk version 2.0
[00:00:00.009,063] <inf> littlefs: FS at MX25R64:0x0 is 16 0x1000-byte blocks with 512 cye
[00:00:00.009,063] <inf> littlefs: sizes: rd 16 ; pr 16 ; ca 64 ; la 32
[00:00:00.011,718] <inf> littlefs: /lfs mounted
Mount /lfs: 0
/lfs: bsize = 16 ; frsize = 4096 ; blocks = 16 ; bfree = 13
/lfs opendir: 0
F 8 hi
F 128 linux
F 5 newfile
End of files
Linux 또는 FreeBSD에서 littlefs를 mount하는 방법은 다음 ‘littlefs 사용법’ 절에서 설명합니다.
littlefs 사용법
FAT 기반 file system은 많은 system에서 자동 mount되지만, Linux 또는 FreeBSD에서 littlefs를 mount하려면 littlefs-FUSE utility를 사용할 수 있습니다.
먼저 system log에서 USB drive의 local device name을 확인합니다.
Apr 25 08:10:25 tirzah kernel: [570310.921039] scsi 17:0:0:0: Direct-Access ZEPHYR ZEPHYR USB DISK 0.01 PQ: 0 ANSI: 0 CCS
Apr 25 08:10:25 tirzah kernel: [570310.921550] sd 17:0:0:0: Attached scsi generic sg4 type 0
Apr 25 08:10:25 tirzah kernel: [570310.922277] sd 17:0:0:0: [sdd] 256 512-byte logical blocks: (131 kB/128 KiB)
Apr 25 08:10:25 tirzah kernel: [570310.922696] sd 17:0:0:0: [sdd] Write Protect is off
이 log에서는 USB drive에 대응하는 block device가 /dev/sdd임을 알 수 있습니다.
tirzah[447]$ ll /dev/sdd
brw-rw---- 1 root disk 8, 48 Apr 25 08:10 /dev/sdd
사용자 접근 권한을 부여하고 mount point를 만든 뒤, Zephyr file system geometry와 일치하는 option으로 lfs를 실행합니다.
sudo chmod a+rw /dev/sdd # required to allow user access
mkdir /tmp/lfs
lfs \
--read_size=16 \
--prog_size=16 \
--block_size=4096 \
--block_count=32 \
--cache_size=64 \
--lookahead_size=32 \
/dev/sdd /tmp/lfs
Mount가 성공하면 /tmp/lfs에서 disk 내용을 확인할 수 있습니다. 실제 file 목록은 달라질 수 있습니다.
tirzah[467]$ ls -l /tmp/lfs
total 0
-rwxrwxrwx 0 root root 8 Dec 31 1969 hi
-rwxrwxrwx 0 root root 128 Dec 31 1969 linux
-rwxrwxrwx 0 root root 5 Dec 31 1969 newfile
lfs는 mount command입니다. USB drive를 분리하기 전에 반드시 device를 unmount해야 합니다.
umount /tmp/lfs
littlefs parameter 선택
위 example에서 lfs에 전달한 parameter는 file system 초기화에 사용된 해당 parameter와 정확히 일치해야 합니다. 필요한 값은 Zephyr mount log에서 확인할 수 있습니다.
[00:00:00.009,002] <inf> littlefs: LittleFS version 2.2, disk version 2.0
[00:00:00.009,063] <inf> littlefs: FS at MX25R64:0x0 is 16 0x1000-byte blocks with 512 cye
[00:00:00.009,063] <inf> littlefs: sizes: rd 16 ; pr 16 ; ca 64 ; la 32
--read_size는rdsize에 대응하며 16입니다.--prog_size는prsize에 대응하며 16입니다.--block_size는0x1000-byte blocks에서 얻으며 4096(0x1000)입니다.--block_count는16 0x1000-byte blocks에서 얻으며 16입니다.--cache_size는casize에 대응하며 64입니다.--lookahead_size는lasize에 대응하며 32입니다.
Zephyr와 Linux 쪽 specification에서 parameter 하나라도 일치하지 않으면 file system이 올바르게 mount되지 않습니다.
Source
출처
영어 원문에는 문단, 문서 지시문, 표, 코드, 코드 심벌, 경로를 그대로 보존했습니다.