From 255dd215abd8b1248c0744884eef50c8b75e1dc7 Mon Sep 17 00:00:00 2001 From: Sebastian Romero Date: Mon, 4 Sep 2023 10:26:43 +0200 Subject: [PATCH 1/4] Add API documentation --- docs/api.md | 99 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 99 insertions(+) create mode 100644 docs/api.md diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 0000000..a8d4491 --- /dev/null +++ b/docs/api.md @@ -0,0 +1,99 @@ +# Summary + + Members | Descriptions +--------------------------------|--------------------------------------------- +`enum ` [`StorageDevices`](#_arduino___p_o_s_i_x_storage_8h_1a97a26676f4f644e3db23bb63b9227546) | Enum to select the storage device to use. +`enum ` [`FileSystems`](#_arduino___p_o_s_i_x_storage_8h_1ac01996562b852a6b36ad87908429ad35) | Enum to select the file system to use. +`enum ` [`MountFlags`](#_arduino___p_o_s_i_x_storage_8h_1a069889b849809b552adf0513c6db2b85) | Enum to select the mount mode to use. The default mode is Read/Write. +`public int ` [`mount`](#_arduino___p_o_s_i_x_storage_8h_1a22178afb74ae05ab1dcf8c50eb4a9d1f)`(const enum ` [`StorageDevices`](#_arduino___p_o_s_i_x_storage_8h_1a97a26676f4f644e3db23bb63b9227546)` deviceName, const enum ` [`FileSystems`](#_arduino___p_o_s_i_x_storage_8h_1ac01996562b852a6b36ad87908429ad35)` fileSystem, const enum ` [`MountFlags`](#_arduino___p_o_s_i_x_storage_8h_1a069889b849809b552adf0513c6db2b85)` mountFlags)` | Attach a file system to a device. +`public int ` [`umount`](#_arduino___p_o_s_i_x_storage_8h_1a57b5f0c881dedaf55fe1b9c5fa59e1f8)`(const enum ` [`StorageDevices`](#_arduino___p_o_s_i_x_storage_8h_1a97a26676f4f644e3db23bb63b9227546)` deviceName)` | Remove the attached file system from a device. +`public int ` [`register_hotplug_callback`](#_arduino___p_o_s_i_x_storage_8h_1a1a914f0970d317b6a74bef4368cbcae8)`(const enum ` [`StorageDevices`](#_arduino___p_o_s_i_x_storage_8h_1a97a26676f4f644e3db23bb63b9227546)` deviceName, void(*)() callbackFunction)` | Register a hotplug callback function. Currently only supported for DEV_USB on Portenta C33. +`public int ` [`deregister_hotplug_callback`](#_arduino___p_o_s_i_x_storage_8h_1ae80d0ace82aad5ef4a130953290efbd7)`(const enum ` [`StorageDevices`](#_arduino___p_o_s_i_x_storage_8h_1a97a26676f4f644e3db23bb63b9227546)` deviceName)` | Deregister a previously registered hotplug callback function. Not currently supported on any platform. +`public int ` [`mkfs`](#_arduino___p_o_s_i_x_storage_8h_1a834ae6d0e65c5b47f9d8932f7ad0c499)`(const enum ` [`StorageDevices`](#_arduino___p_o_s_i_x_storage_8h_1a97a26676f4f644e3db23bb63b9227546)` deviceName, const enum ` [`FileSystems`](#_arduino___p_o_s_i_x_storage_8h_1ac01996562b852a6b36ad87908429ad35)` fileSystem)` | Format a device (make file system). + +## Members + +#### `enum ` [`StorageDevices`](#_arduino___p_o_s_i_x_storage_8h_1a97a26676f4f644e3db23bb63b9227546) + +Enum to select the storage device to use. + + Values | Descriptions +--------------------------------|--------------------------------------------- +DEV_SDCARD | SD Card. +DEV_USB | USB Thumb Drive. + +#### `enum ` [`FileSystems`](#_arduino___p_o_s_i_x_storage_8h_1ac01996562b852a6b36ad87908429ad35) + +Enum to select the file system to use. + + Values | Descriptions +--------------------------------|--------------------------------------------- +FS_FAT | FAT file system. +FS_LITTLEFS | LittleFS file system. + +#### `enum ` [`MountFlags`](#_arduino___p_o_s_i_x_storage_8h_1a069889b849809b552adf0513c6db2b85) + +Enum to select the mount mode to use. The default mode is Read/Write. + + Values | Descriptions +--------------------------------|--------------------------------------------- +MNT_DEFAULT | Default mount mode (Read/Write) +MNT_RDONLY | Read only mode. + +#### `public int ` [`mount`](#_arduino___p_o_s_i_x_storage_8h_1a22178afb74ae05ab1dcf8c50eb4a9d1f)`(const enum ` [`StorageDevices`](#_arduino___p_o_s_i_x_storage_8h_1a97a26676f4f644e3db23bb63b9227546)` deviceName, const enum ` [`FileSystems`](#_arduino___p_o_s_i_x_storage_8h_1ac01996562b852a6b36ad87908429ad35)` fileSystem, const enum ` [`MountFlags`](#_arduino___p_o_s_i_x_storage_8h_1a069889b849809b552adf0513c6db2b85)` mountFlags)` + +Attach a file system to a device. + +#### Parameters +* `deviceName` The device to attach to: DEV_SDCARD or DEV_USB. + +* `fileSystem` The file system type to attach: FS_FAT or FS_LITTLEFS. + +* `mountFlags` The only valid flag at this time: MNT_DEFAULT. + +#### Returns +On success: 0. On failure: -1 with an error code in the errno variable. + +#### `public int ` [`umount`](#_arduino___p_o_s_i_x_storage_8h_1a57b5f0c881dedaf55fe1b9c5fa59e1f8)`(const enum ` [`StorageDevices`](#_arduino___p_o_s_i_x_storage_8h_1a97a26676f4f644e3db23bb63b9227546)` deviceName)` + +Remove the attached file system from a device. + +#### Parameters +* `deviceName` The device to remove from: DEV_SDCARD or DEV_USB. + +#### Returns +On success: 0. On failure: -1 with an error code in the errno variable. + +#### `public int ` [`register_hotplug_callback`](#_arduino___p_o_s_i_x_storage_8h_1a1a914f0970d317b6a74bef4368cbcae8)`(const enum ` [`StorageDevices`](#_arduino___p_o_s_i_x_storage_8h_1a97a26676f4f644e3db23bb63b9227546)` deviceName, void(*)() callbackFunction)` + +Register a hotplug callback function. Currently only supported for DEV_USB on Portenta C33. + +#### Parameters +* `deviceName` The device to register for: DEV_SDCARD or DEV_USB. + +* `callbackFunction` A function pointer to the callback. + +#### Returns +On success: 0. On failure: -1 with an error code in the errno variable. + +#### `public int ` [`deregister_hotplug_callback`](#_arduino___p_o_s_i_x_storage_8h_1ae80d0ace82aad5ef4a130953290efbd7)`(const enum ` [`StorageDevices`](#_arduino___p_o_s_i_x_storage_8h_1a97a26676f4f644e3db23bb63b9227546)` deviceName)` + +Deregister a previously registered hotplug callback function. Not currently supported on any platform. + +#### Parameters +* `deviceName` The device to deregister for: DEV_SDCARD or DEV_USB. + +#### Returns +On success: 0. On failure: -1 with an error code in the errno variable. + +#### `public int ` [`mkfs`](#_arduino___p_o_s_i_x_storage_8h_1a834ae6d0e65c5b47f9d8932f7ad0c499)`(const enum ` [`StorageDevices`](#_arduino___p_o_s_i_x_storage_8h_1a97a26676f4f644e3db23bb63b9227546)` deviceName, const enum ` [`FileSystems`](#_arduino___p_o_s_i_x_storage_8h_1ac01996562b852a6b36ad87908429ad35)` fileSystem)` + +Format a device (make file system). + +#### Parameters +* `deviceName` The device to format: DEV_SDCARD or DEV_USB. + +* `fileSystem` The file system type to format: FS_FAT or FS_LITTLEFS. FS_FAT is probably the better choice for both SD Cards and USB thumb drives in most cases. + +#### Returns +On success: 0. On failure: -1 with an error code in the errno variable. From 7ac0aeba84d6e301e03a85ac3bd2383b7cb5e1fe Mon Sep 17 00:00:00 2001 From: Sebastian Romero Date: Mon, 4 Sep 2023 11:42:10 +0200 Subject: [PATCH 2/4] Add missing documentation for enums --- src/Arduino_POSIXStorage.h | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/Arduino_POSIXStorage.h b/src/Arduino_POSIXStorage.h index ee71da1..1c2b31f 100644 --- a/src/Arduino_POSIXStorage.h +++ b/src/Arduino_POSIXStorage.h @@ -88,21 +88,24 @@ ********************************************************************************************************* */ +/// @brief Enum to select the storage device to use. enum StorageDevices : uint8_t { DEV_SDCARD, ///< SD Card DEV_USB ///< USB Thumb Drive }; +/// @brief Enum to select the file system to use. enum FileSystems : uint8_t { FS_FAT, ///< FAT file system FS_LITTLEFS ///< LittleFS file system }; +/// @brief Enum to select the mount mode to use. The default mode is Read/Write. enum MountFlags : uint8_t { - MNT_DEFAULT, ///< Default mount mode + MNT_DEFAULT, ///< Default mount mode (Read/Write) MNT_RDONLY ///< Read only mode }; From 53e83ce227e21b2be82721d4a87a7ab2843e715a Mon Sep 17 00:00:00 2001 From: Sebastian Romero Date: Mon, 4 Sep 2023 11:42:23 +0200 Subject: [PATCH 3/4] Extract API documentation into separate document --- docs/README.md | 61 +------------------------------------------------- 1 file changed, 1 insertion(+), 60 deletions(-) diff --git a/docs/README.md b/docs/README.md index df4b976..aea0133 100644 --- a/docs/README.md +++ b/docs/README.md @@ -41,66 +41,7 @@ Many ISO C standard functions are also made available. For example: fopen, fprin Start pathnames on SD Cards with "/sdcard/" and pathnames on USB thumb drives with "/usb/". See the Examples section below for examples. -The following are additional functions provided by the library: - -### `int` [`mount`](#)`(enum StorageDevices deviceName, enum FileSystems fileSystem, enum MountFlags mountFlags)` - -Attach a file system to a device. - -#### Parameters -* `deviceName` The device to attach to: DEV_SDCARD or DEV_USB. -* `fileSystem` The file system type to attach: FS_FAT or FS_LITTLEFS. -* `mountFlags` The only valid flag at this time: MNT_DEFAULT (future platforms might also support MNT_RDONLY). - -#### Returns -On success: 0. On failure: -1 with an error code in the errno variable. - - -### `int` [`umount`](#)`(enum StorageDevices deviceName)` - -Remove the attached file system from a device. - -#### Parameters -* `deviceName` The device to remove from: DEV_SDCARD or DEV_USB. - -#### Returns -On success: 0. On failure: -1 with an error code in the errno variable. - - -### `int` [`register_hotplug_callback`](#)`(enum StorageDevices deviceName, void (*callbackFunction)())` - -Register a hotplug callback function. Currently only supported for DEV_USB on Portenta C33. - -#### Parameters -* `deviceName` The device to register for: DEV_SDCARD or DEV_USB. -* `callbackFunction` A function pointer to the callback. - -#### Returns -On success: 0. On failure: -1 with an error code in the errno variable. - - -### `int` [`deregister_hotplug_callback`](#)`(enum StorageDevices deviceName)` - -Deregister a previously registered hotplug callback function. Not currently supported on any platform. - -#### Parameters -* `deviceName` The device to deregister for: DEV_SDCARD or DEV_USB. - -#### Returns -On success: 0. On failure: -1 with an error code in the errno variable. - - -### `int` [`mkfs`](#)`(enum StorageDevices deviceName, enum FileSystems fileSystem)` - -Format a device (make file system). - -#### Parameters -* `deviceName` The device to format: DEV_SDCARD or DEV_USB. -* `fileSystem` The file system type to format: FS_FAT or FS_LITTLEFS. FS_FAT is probably the better choice for both SD Cards and USB thumb drives in most cases. - -#### Returns -On success: 0. On failure: -1 with an error code in the errno variable. - +See [here](./api.md) for a complete description of the API. ## Examples From 84a2ede8bf16454a41b3f662a37f6309acedf392 Mon Sep 17 00:00:00 2001 From: Sebastian Romero Date: Mon, 4 Sep 2023 11:55:42 +0200 Subject: [PATCH 4/4] Add empty line after docs for each member --- docs/api.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/api.md b/docs/api.md index a8d4491..e082fe0 100644 --- a/docs/api.md +++ b/docs/api.md @@ -22,6 +22,8 @@ Enum to select the storage device to use. DEV_SDCARD | SD Card. DEV_USB | USB Thumb Drive. +
+ #### `enum ` [`FileSystems`](#_arduino___p_o_s_i_x_storage_8h_1ac01996562b852a6b36ad87908429ad35) Enum to select the file system to use. @@ -31,6 +33,8 @@ Enum to select the file system to use. FS_FAT | FAT file system. FS_LITTLEFS | LittleFS file system. +
+ #### `enum ` [`MountFlags`](#_arduino___p_o_s_i_x_storage_8h_1a069889b849809b552adf0513c6db2b85) Enum to select the mount mode to use. The default mode is Read/Write. @@ -40,6 +44,8 @@ Enum to select the mount mode to use. The default mode is Read/Write. MNT_DEFAULT | Default mount mode (Read/Write) MNT_RDONLY | Read only mode. +
+ #### `public int ` [`mount`](#_arduino___p_o_s_i_x_storage_8h_1a22178afb74ae05ab1dcf8c50eb4a9d1f)`(const enum ` [`StorageDevices`](#_arduino___p_o_s_i_x_storage_8h_1a97a26676f4f644e3db23bb63b9227546)` deviceName, const enum ` [`FileSystems`](#_arduino___p_o_s_i_x_storage_8h_1ac01996562b852a6b36ad87908429ad35)` fileSystem, const enum ` [`MountFlags`](#_arduino___p_o_s_i_x_storage_8h_1a069889b849809b552adf0513c6db2b85)` mountFlags)` Attach a file system to a device. @@ -53,6 +59,7 @@ Attach a file system to a device. #### Returns On success: 0. On failure: -1 with an error code in the errno variable. +
#### `public int ` [`umount`](#_arduino___p_o_s_i_x_storage_8h_1a57b5f0c881dedaf55fe1b9c5fa59e1f8)`(const enum ` [`StorageDevices`](#_arduino___p_o_s_i_x_storage_8h_1a97a26676f4f644e3db23bb63b9227546)` deviceName)` @@ -63,6 +70,7 @@ Remove the attached file system from a device. #### Returns On success: 0. On failure: -1 with an error code in the errno variable. +
#### `public int ` [`register_hotplug_callback`](#_arduino___p_o_s_i_x_storage_8h_1a1a914f0970d317b6a74bef4368cbcae8)`(const enum ` [`StorageDevices`](#_arduino___p_o_s_i_x_storage_8h_1a97a26676f4f644e3db23bb63b9227546)` deviceName, void(*)() callbackFunction)` @@ -75,6 +83,7 @@ Register a hotplug callback function. Currently only supported for DEV_USB on Po #### Returns On success: 0. On failure: -1 with an error code in the errno variable. +
#### `public int ` [`deregister_hotplug_callback`](#_arduino___p_o_s_i_x_storage_8h_1ae80d0ace82aad5ef4a130953290efbd7)`(const enum ` [`StorageDevices`](#_arduino___p_o_s_i_x_storage_8h_1a97a26676f4f644e3db23bb63b9227546)` deviceName)` @@ -85,6 +94,7 @@ Deregister a previously registered hotplug callback function. Not currently supp #### Returns On success: 0. On failure: -1 with an error code in the errno variable. +
#### `public int ` [`mkfs`](#_arduino___p_o_s_i_x_storage_8h_1a834ae6d0e65c5b47f9d8932f7ad0c499)`(const enum ` [`StorageDevices`](#_arduino___p_o_s_i_x_storage_8h_1a97a26676f4f644e3db23bb63b9227546)` deviceName, const enum ` [`FileSystems`](#_arduino___p_o_s_i_x_storage_8h_1ac01996562b852a6b36ad87908429ad35)` fileSystem)` @@ -97,3 +107,4 @@ Format a device (make file system). #### Returns On success: 0. On failure: -1 with an error code in the errno variable. +