Repository: incubator-mynewt-site Updated Branches: refs/heads/master 555f8433d -> a3fef09c9
added new docs under drivers 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/a3fef09c Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/a3fef09c Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/a3fef09c Branch: refs/heads/master Commit: a3fef09c9a15ccebb8b26b2bd9f29754d2c670de Parents: 555f843 Author: aditihilbert <[email protected]> Authored: Tue Mar 7 10:34:21 2017 +0100 Committer: aditihilbert <[email protected]> Committed: Tue Mar 7 10:34:21 2017 +0100 ---------------------------------------------------------------------- docs/os/modules/drivers/flash.md | 121 ++++++++++++++++++++++++++++++++++ docs/os/modules/drivers/mmc.md | 87 ++++++++++++++++++++++++ docs/os/modules/fs/fatfs.md | 44 +++++++++++++ 3 files changed, 252 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/a3fef09c/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/a3fef09c/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/a3fef09c/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..4ec72ff --- /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 disabled 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 it 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.
