You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mynewt.apache.org by ad...@apache.org on 2017/03/07 09:24:19 UTC
[2/5] incubator-mynewt-site git commit: Updating filesystem and block
driver docs
Updating filesystem and block driver docs
- Update FS documentation with multiple disk support
- Document the the FAT filesystem
- Document the MMC driver
- Document the AT45DB SPI flash driver
Project: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/commit/1cee1a2d
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/1cee1a2d
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/1cee1a2d
Branch: refs/heads/develop
Commit: 1cee1a2d53dff157ea1fdea4d039000fbf611d99
Parents: 8dcf979
Author: Fabio Utzig <ut...@utzig.org>
Authored: Wed Mar 1 16:33:14 2017 -0300
Committer: Fabio Utzig <ut...@utzig.org>
Committed: Mon Mar 6 11:19:17 2017 -0300
----------------------------------------------------------------------
docs/os/modules/drivers/driver.md | 16 ++++-
docs/os/modules/drivers/flash.md | 121 +++++++++++++++++++++++++++++++++
docs/os/modules/drivers/mmc.md | 87 ++++++++++++++++++++++++
docs/os/modules/fs/fatfs.md | 44 ++++++++++++
docs/os/modules/fs/fs/fs.md | 46 ++++++++++++-
mkdocs.yml | 9 +++
6 files changed, 319 insertions(+), 4 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/1cee1a2d/docs/os/modules/drivers/driver.md
----------------------------------------------------------------------
diff --git a/docs/os/modules/drivers/driver.md b/docs/os/modules/drivers/driver.md
index 8c5b586..d090809 100644
--- a/docs/os/modules/drivers/driver.md
+++ b/docs/os/modules/drivers/driver.md
@@ -41,10 +41,22 @@ Device drivers in the Mynewt context includes libraries that interface with devi
* Device drivers should be searchable. The plan is to have the newt tool offer a `newt pkg search` capability. This is work in progress. You are welcome to join the conversation on the dev@ mailing list!
-
-###Example
+### Example
The Mynewt core repo includes an example of a driver using the HAL to provide extra functionality - the UART driver. It uses HAL GPIO and UART to provide multiple serial ports on the NRF52 (but allowed on other platforms too.)
The gist of the driver design is that there is an API for the driver (for use by applications), and then sub-packages to that driver that implement that driver API using the HAL and BSP APIs.
+### Implemented drivers
+
+Drivers live under `hw/drivers`. The current list of supported drivers includes:
+
+| Driver | Description |
+|---------|-------------|
+| [adc](adc.md) | TODO: ADC driver. |
+| [flash](flash.md) | SPI/I2C flash drivers. |
+| [lwip](lwip.md) | TODO: LWIP. |
+| [mmc](mmc.md) | MMC/SD card driver. |
+| [nimble](/network/ble/ble_intro/) | NIMBLE. |
+| [sensors](sensors.md) | TODO: sensors. |
+| [uart](uart.md) | TODO: UART driver. |
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/1cee1a2d/docs/os/modules/drivers/flash.md
----------------------------------------------------------------------
diff --git a/docs/os/modules/drivers/flash.md b/docs/os/modules/drivers/flash.md
new file mode 100644
index 0000000..fdd0e5d
--- /dev/null
+++ b/docs/os/modules/drivers/flash.md
@@ -0,0 +1,121 @@
+## <font color="#F2853F" style="font-size:24pt">flash</font>
+
+The flash driver subsystem is a work in progress which aims at supporting
+common external SPI/I2C flash/eeprom memory chips. This is equivalent
+to what Linux calls `MTD` for `Memory Technology Devices`.
+
+At the moment the only `flash` device that is already supported is the
+AT45DBxxx SPI flash family with the `at45db` driver.
+
+The flash driver aims for full compatibility with the `hal_flash` API,
+which means initialization and usage can be performed by any `fs` that
+supports the `hal_flash` interface.
+
+#### Initialization
+
+To be compatible with the standard `hal_flash` interface, the `at45db` driver
+embeds a `struct hal_flash` to its own `struct at45db_dev`. The whole `at45db_dev`
+struct is shown below.
+
+```c
+struct at45db_dev {
+ struct hal_flash hal;
+ struct hal_spi_settings *settings;
+ int spi_num;
+ void *spi_cfg; /** Low-level MCU SPI config */
+ int ss_pin;
+ uint32_t baudrate;
+ uint16_t page_size; /** Page size to be used, valid: 512 and 528 */
+ uint8_t disable_auto_erase; /** Reads and writes auto-erase by default */
+};
+```
+
+To ease with initialization a helper function `at45db_default_config` was added.
+It returns an already initialized `struct at45db_dev` leaving the user with just
+having to provide the SPI related config.
+
+To initialize the device, pass the `at45db_dev` struct to `at45db_init`.
+
+```c
+int at45db_init(const struct hal_flash *dev);
+```
+
+For low-level access to the device the following functions are provided:
+
+```c
+int at45db_read(const struct hal_flash *dev, uint32_t addr, void *buf,
+ uint32_t len);
+int at45db_write(const struct hal_flash *dev, uint32_t addr, const void *buf,
+ uint32_t len);
+int at45db_erase_sector(const struct hal_flash *dev, uint32_t sector_address);
+int at45db_sector_info(const struct hal_flash *dev, int idx, uint32_t *address,
+ uint32_t *sz);
+```
+
+Also, `nffs` is able to run on the device due to the fact that standard `hal_flash`
+interface compatibility is provided. Due to current limitations of `nffs`, it can
+only run on `at45db` if the internal flash of the MCU is not being used.
+
+#### Dependencies
+
+To include the `at45db` driver on a project, just include it as a dependency in your
+pkg.yml:
+
+```
+pkg.deps:
+ - hw/drivers/flash/at45db
+```
+
+#### Header file
+
+The `at45db` SPI flash follows the standard `hal_flash` interface but requires
+that a special struct
+
+```c
+#include <at45db/at45db.h>
+```
+
+#### Example
+
+This following examples assume that the `at45db` is being used on a STM32F4 MCU.
+
+```c
+static const int SPI_SS_PIN = MCU_GPIO_PORTA(4);
+static const int SPI_SCK_PIN = MCU_GPIO_PORTA(5);
+static const int SPI_MISO_PIN = MCU_GPIO_PORTA(6);
+static const int SPI_MOSI_PIN = MCU_GPIO_PORTA(7);
+
+struct stm32f4_hal_spi_cfg spi_cfg = {
+ .ss_pin = SPI_SS_PIN,
+ .sck_pin = SPI_SCK_PIN,
+ .miso_pin = SPI_MISO_PIN,
+ .mosi_pin = SPI_MOSI_PIN,
+ .irq_prio = 2
+};
+
+struct at45db_dev *my_at45db_dev = NULL;
+
+my_at45db_dev = at45db_default_config();
+my_at45db_dev->spi_num = 0;
+my_at45db_dev->spi_cfg = &spi_cfg;
+my_at45db_dev->ss_pin = spi_cfg.ss_pin;
+
+rc = at45db_init((struct hal_flash *) my_at45db_dev);
+if (rc) {
+ /* XXX: error handling */
+}
+```
+
+The enable `nffs` to run on the `at45db`, the `flash_id` 0 needs to map to
+provide a mapping from 0 to this struct.
+
+```c
+const struct hal_flash *
+hal_bsp_flash_dev(uint8_t id)
+{
+ if (id != 0) {
+ return NULL;
+ }
+ return &my_at45db_dev;
+}
+```
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/1cee1a2d/docs/os/modules/drivers/mmc.md
----------------------------------------------------------------------
diff --git a/docs/os/modules/drivers/mmc.md b/docs/os/modules/drivers/mmc.md
new file mode 100644
index 0000000..15c7c7f
--- /dev/null
+++ b/docs/os/modules/drivers/mmc.md
@@ -0,0 +1,87 @@
+## <font color="#F2853F" style="font-size:24pt">mmc</font>
+
+The MMC driver provides support for SPI based MMC/SDcard interfaces. It exports
+a `disk_ops` struct that can be used by any FS. Currently only `fatfs` can run
+over MMC.
+
+#### Initialization
+
+```c
+int mmc_init(int spi_num, void *spi_cfg, int ss_pin)
+```
+
+Initializes the mmc driver to be used by a FS.
+
+MMC uses the `hal_gpio` interface to access the SPI `ss_pin` and the `hal_spi`
+interface for the communication with the card. `spi_cfg` must be a hw dependent
+structure used by `hal_spi_init` to initialize the SPI subsystem.
+
+#### Dependencies
+
+To include the `mmc` driver on a project, just include it as a dependency in your
+pkg.yml:
+
+```
+pkg.deps:
+ - hw/drivers/mmc
+```
+
+#### Returned values
+
+MMC functions return one of the following status codes:
+
+| Return code | Description |
+|----------------------|-------------------------------------------------------|
+| MMC\_OK | Success. |
+| MMC\_CARD_ERROR | General failure on the card. |
+| MMC\_READ_ERROR | Error reading from the card. |
+| MMC\_WRITE_ERROR | Error writing to the card. |
+| MMC\_TIMEOUT | Timed out waiting for the execution of a command. |
+| MMC\_PARAM_ERROR | An invalid parameter was given to a function. |
+| MMC\_CRC_ERROR | CRC error reading card. |
+| MMC\_DEVICE_ERROR | Tried to use an invalid device. |
+| MMC\_RESPONSE_ERROR | A command received an invalid response. |
+| MMC\_VOLTAGE_ERROR | The interface doesn't support the requested voltage. |
+| MMC\_INVALID_COMMAND | The interface haven't accepted some command. |
+| MMC\_ERASE_ERROR | Error erasing the current card. |
+| MMC\_ADDR_ERROR | Tried to access an invalid address. |
+
+#### Header file
+
+```c
+#include "mmc/mmc.h"
+```
+
+#### <a name="Example"></a>Example
+
+This example runs on the STM32F4-Discovery and prints out a listing of
+the root directory on the currently installed card.
+
+```c
+// NOTE: error handling removed for clarity!
+
+struct stm32f4_hal_spi_cfg spi_cfg = {
+ .ss_pin = SPI_SS_PIN,
+ .sck_pin = SPI_SCK_PIN,
+ .miso_pin = SPI_MISO_PIN,
+ .mosi_pin = SPI_MOSI_PIN,
+ .irq_prio = 2
+};
+
+mmc_init(0, &spi_cfg, spi_cfg.ss_pin);
+disk_register("mmc0", "fatfs", &mmc_ops);
+
+fs_opendir("mmc0:/", &dir);
+
+while (1) {
+ rc = fs_readdir(dir, &dirent);
+ if (rc == FS_ENOENT) {
+ break;
+ }
+
+ fs_dirent_name(dirent, sizeof(out_name), out_name, &u8_len);
+ printf("%s\n", out_name);
+}
+
+fs_closedir(dir);
+```
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/1cee1a2d/docs/os/modules/fs/fatfs.md
----------------------------------------------------------------------
diff --git a/docs/os/modules/fs/fatfs.md b/docs/os/modules/fs/fatfs.md
new file mode 100644
index 0000000..b409235
--- /dev/null
+++ b/docs/os/modules/fs/fatfs.md
@@ -0,0 +1,44 @@
+# The FAT File System
+
+Mynewt provides an implementation of the FAT filesystem which is currently
+supported on MMC/SD cards.
+
+### Description
+
+> File Allocation Table (FAT) is a computer file system architecture and a family
+> of industry-standard file systems utilizing it. The FAT file system is a legacy
+> file system which is simple and robust. It offers good performance even in
+> lightweight implementations, but cannot deliver the same performance, reliability
+> and scalability as some modern file systems.
+
+### Configuration
+
+`fatfs` configuration can be tweaked by editing `fs/fatfs/include/fatfs/ffconf.h`.
+The current configuraton was chosen to minimize memory use and some options address
+limitations existing in the OS:
+
+* Write support is enabled by default (can be disable to minimize memory use).
+* Long filename (up to 255) support is disabled.
+* When writing files, time/dates are not persisted due to current lack of a
+ standard `hal_rtc` interface.
+* No unicode support. Vanilla config uses standard US codepage 437.
+* Formatting of new volumes is disabled.
+* Default number of volumes is configured to 1.
+
+### API
+
+To include `fatfs` on a project just include is as a dependency in your
+project:
+
+```
+pkg.deps:
+ - fs/fatfs
+```
+
+It can now be used through the standard file system abstraction functions as
+described in [FS API](/os/modules/fs/fs/fs#API).
+
+#### Example
+
+An example of using `fatfs` on a MMC card is provided on the
+[MMC](/os/modules/drivers/mmc#Example) documentation.
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/1cee1a2d/docs/os/modules/fs/fs/fs.md
----------------------------------------------------------------------
diff --git a/docs/os/modules/fs/fs/fs.md b/docs/os/modules/fs/fs/fs.md
index 188ad49..fc4b2de 100644
--- a/docs/os/modules/fs/fs/fs.md
+++ b/docs/os/modules/fs/fs/fs.md
@@ -47,10 +47,52 @@ pkg.deps:
The `libs/imgmgr` package uses the `fs/fs` API for all file system operations.
+### Support for multiple filesystems
+
+When using a single filesystem/disk, it is valid to provide paths in the standard
+unix way, eg, `/<dir-name>/<file-name>`. When trying to run more than one filesystem
+or a single filesystem in multiple devices simultaneosly, an extra name has to be
+given to the disk that is being used. The abstraction for that was added as the
+`fs/disk` package which is a dependency of `fs/fs`. It adds the following extra
+user function:
+
+```c
+int disk_register(const char *disk_name, const char *fs_name, struct disk_ops *dops)
+```
+
+As an example os usage:
+
+```c
+disk_register("mmc0", "fatfs", &mmc_ops);
+disk_register("flash0", "nffs", NULL);
+```
+
+This registers the name `mmc0` to use `fatfs` as the filesystem and `mmc_ops` for
+the low-level disk driver and also registers `flash0` to use `nffs`. `nffs` is
+currently strongly bound to the `hal_flash` interface, ignoring any other possible
+`disk_ops` given.
+
+#### struct disk_ops
+
+To support a new low-level disk interface, the `struct disk_ops` interface must
+be implemented by the low-level driver. Currently only `read` and `write` are
+effectively used (by `fatfs`).
+
+```c
+struct disk_ops {
+ int (*read)(uint8_t, uint32_t, void *, uint32_t);
+ int (*write)(uint8_t, uint32_t, const void *, uint32_t);
+ int (*ioctl)(uint8_t, uint32_t, void *);
+ SLIST_ENTRY(disk_ops) sc_next;
+}
+```
+
###Thread Safety
+
All `fs/fs` functions are thread safe.
-###Header Files
+###Header Files
+
All code which uses the `fs/fs` package needs to include the following header:
```c
@@ -66,7 +108,7 @@ struct fs_dir;
struct fs_dirent;
```
-###API
+### <a name="API"></a>API
Functions in `fs/fs` that indicate success or failure do so with the following set of return codes:
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/1cee1a2d/mkdocs.yml
----------------------------------------------------------------------
diff --git a/mkdocs.yml b/mkdocs.yml
index 87a7cfd..ea06968 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -275,6 +275,7 @@ pages:
- 'fs_write': 'os/modules/fs/fs/fs_write.md'
- 'fsutil_read_file': 'os/modules/fs/fs/fsutil_read_file.md'
- 'fsutil_write_file': 'os/modules/fs/fs/fsutil_write_file.md'
+ - 'FAT File System': 'os/modules/fs/fatfs.md'
- 'Newtron Flash File System':
- toc: 'os/modules/fs/nffs/nffs.md'
- 'Data Structures':
@@ -306,6 +307,14 @@ pages:
- 'Creating HAL': 'os/modules/hal/hal_creation.md'
- Drivers:
- toc: 'os/modules/drivers/driver.md'
+ - 'Supported Drivers':
+ #- 'adc': 'os/modules/drivers/adc.md'
+ - 'flash': 'os/modules/drivers/flash.md'
+ # - 'lwip': 'os/modules/drivers/lwip.md'
+ - 'mmc': 'os/modules/drivers/mmc.md'
+ - 'nimble': 'network/ble/ble_intro.md'
+ #- 'sensors': 'os/modules/drivers/sensors.md'
+ #- 'uart': 'os/modules/drivers/uart.md'
- Test Utilities:
- toc: 'os/modules/testutil/testutil.md'
- 'Functions/Macros':