diff --git a/Documentation/guides/automounter.rst b/Documentation/guides/automounter.rst new file mode 100644 index 0000000000000..45a2afe275954 --- /dev/null +++ b/Documentation/guides/automounter.rst @@ -0,0 +1,69 @@ +============ +Auto-Mounter +============ + +General Description +=================== +NuttX implements an auto-mounter than can make working with SD cards or other +removable media easier. With the auto-mounter, the file system will be +automatically mounted when media is inserted and automatically unmounted when +the media is removed. + +The auto is enable by selecting in the NuttX configuration:: + + CONFIG_FS_AUTOMOUNTER=y + + +WARNING: SD cards should never be removed without first unmounting them. This +is to avoid data and possible corruption of the file system. Certainly this is +the case if you are writing to the SD card at the time of the removal. If you +use the SD card for read-only access, however, then I cannot think of any +reason why removing the card without mounting would be harmful. + +For applications that write to the removable media, the automatic unmount is +still beneficial (as opposed to leaving a broken mount in place) although +should not be relied upon for a proper solution. + +Board-Specific Support +====================== + +Like many components of NuttX, the auto-mounter has a upper-half/lower-half +architecture: + +* **Upper half** The upper half is the file ``fs/fs_automount.c``. This upper + half performs the basic automount activities. It responds to media + insertion and removal events by mounting and unmounting the file system on + the media. This includes logic to handle unmount retries: The unmount cannot + be performed while applications have open files on the media. In this case, + the auto-mounter will periodically retry the unmount until all of the + applications close there references to files on the non-existent media. + +* **Lower Half** The lower half is defined by a standard interface. That + interface definition is in the header file ``include/nuttx/fs/automount.h``. + The lower half interface provides: (1) mount information including file + system type, block driver path, and mount point path, (2) mount and unmount + retry delays, and (3) and callbacks to attach to and management the media + insertion / removal interrupts. + +Example Implementation +====================== + +There is an example implementation of this lower half interface at +``boards/arm/sama5/sama5d4-ek/src/sam_automount.c``. The ``boards/arm/sama5/sama5d4-ek/Kconfig`` +as the board-specific configuration for the auto-mounter. You can see +the configuration settings in the ``boards/arm/sama5/sama5d4-ek/configs/nsh/defconfig`` +and ``boards/arm/sama5/sama5d4-ek/configs/nxwm/defconfig`` configuration files:: + + CONFIG_SAMA5D4EK_HSMCI0_AUTOMOUNT=y + CONFIG_SAMA5D4EK_HSMCI0_AUTOMOUNT_FSTYPE="vfat" + CONFIG_SAMA5D4EK_HSMCI0_AUTOMOUNT_BLKDEV="/dev/mmcsd0" + CONFIG_SAMA5D4EK_HSMCI0_AUTOMOUNT_MOUNTPOINT="/mnt/sdcard" + CONFIG_SAMA5D4EK_HSMCI0_AUTOMOUNT_DDELAY=1000 + CONFIG_SAMA5D4EK_HSMCI0_AUTOMOUNT_UDELAY=2000 + +These setting determine the values in the lower half interface. The interrupt is +provided by a PIO pin defined in ``boards/arm/sama5/sama5d4-ek/src/sama5e4-ek.h`` and +the implementation of the interface and callbacks is in +``boards/arm/sama5/sama5d4-ek/src/sam_automount.c``. + + diff --git a/Documentation/guides/index.rst b/Documentation/guides/index.rst index 34e12f375df28..ebc074bfd9352 100644 --- a/Documentation/guides/index.rst +++ b/Documentation/guides/index.rst @@ -25,3 +25,4 @@ Guides gdbwithpython.rst ofloader.rst testingtcpip.rst + automounter.rst