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:37:01 UTC
incubator-mynewt-site git commit: added new docs under drivers
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 <ad...@runtime.io>
Authored: Tue Mar 7 10:34:21 2017 +0100
Committer: aditihilbert <ad...@runtime.io>
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.