Repository: incubator-mynewt-site Updated Branches: refs/heads/develop 0763285c7 -> fddb472da
Updated filesystem doc 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/fddb472d Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/fddb472d Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/fddb472d Branch: refs/heads/develop Commit: fddb472da64a6a3f886e940c923281595d42f945 Parents: 0763285 Author: Peter Snyder <[email protected]> Authored: Mon Jan 9 12:50:45 2017 -0800 Committer: Peter Snyder <[email protected]> Committed: Mon Jan 9 12:50:45 2017 -0800 ---------------------------------------------------------------------- docs/os/modules/fs/fs/fs.md | 49 ++++++++++--------------- docs/os/modules/fs/nffs/nffs.md | 71 ++++-------------------------------- 2 files changed, 27 insertions(+), 93 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/fddb472d/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 e36995a..71a8125 100644 --- a/docs/os/modules/fs/fs/fs.md +++ b/docs/os/modules/fs/fs/fs.md @@ -4,47 +4,38 @@ Mynewt provides a file system abstraction layer (`fs/fs`) to allow client code t ###Description -Applications should aim to minimize the amount of code which depends on a particular file system implementation. When possible, only depend on the `fs/fs` package. In the simplest case, the only code which needs to know which file system is in use is the code which initializes the file system. In terms of the Mynewt hierarchy, the **app** package must depend on a specific file system package, while **library** packages should only depend on `fs/fs`. +Applications should aim to minimize the amount of code which depends on a particular file system implementation. When possible, only depend on the +`fs/fs` package. +In terms of the Mynewt hierarchy, the **app** package must depend on a specific file system package, while **library** packages should only depend on `fs/fs`. -The following example illustrates how file system dependencies should be managed. In the slinky application, the app is responsible for initializing the file system, so it depends on a concrete file system package called `fs/nffs` (Newtron Flash File System). The app explicitly initializes nffs via calls to `nffs_init()`, `nffs_detect()` and `nffs_format()`. +Applications wanting to access a filesystem are required to responsible for +including the necessary packages in their applications pkg.yml file. + +the file system, so it depends on a concrete file system package called `fs/nffs` (Newtron Flash File System). ```no-highlight # repos/apache-mynewt-core/apps/slinky/pkg.yml pkg.name: repos/apache-mynewt-core/apps/slinky pkg.deps: - - fs/nffs + - fs/fs # include the file operations interfaces + - fs/nffs # include the NFFS filesystem implementation +``` -# [...] ``` +# repos/apache-mynewt-core/apps/slinky/syscfg.yml +# [...] + # Package: apps/<example app> +# [...] + CONFIG_NFFS: 1 # initialize and configure NFFS into the system +# Consult the documentation for nffs for a broader explanation of NFFS_DETECT_FAIL +# NFFS_DETECT_FAIL: 1 # Ignore NFFS detection issues +# NFFS_DETECT_FAIL: 2 # Format a new NFFS file system on failure to detect -```c -/* repos/apache-mynewt-core/apps/slinky/src/main.c */ - -#include "nffs/nffs.h" - -int -main(int argc, char **argv) -{ - int rc; - int cnt; - struct nffs_area_desc descs[NFFS_AREA_MAX]; - - rc = nffs_init(); - assert(rc == 0); - - cnt = NFFS_AREA_MAX; - rc = flash_area_to_nffs_desc(FLASH_AREA_NFFS, &cnt, descs); - assert(rc == 0); - if (nffs_detect(descs) == FS_ECORRUPT) { - rc = nffs_format(descs); - assert(rc == 0); - } - // [...] -} +# [...] ``` -On the other hand, code which uses the file system after it has been initialized need only depend on `fs/fs`. For example, the `libs/imgmgr` package is a library which provides firmware upload and download functionality via the use of a file system. This library is only used after the main app has initialized the file system, and therefore only depends on the `fs/fs` package. +Code which uses the file system after the system has been initialized need only depend on `fs/fs`. For example, the `libs/imgmgr` package is a library which provides firmware upload and download functionality via the use of a file system. This library is only used after the system has been initialized, and therefore only depends on the `fs/fs` package. ```no-highlight # repos/apache-mynewt-core/libs/imgmgr/pkg.yml http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/fddb472d/docs/os/modules/fs/nffs/nffs.md ---------------------------------------------------------------------- diff --git a/docs/os/modules/fs/nffs/nffs.md b/docs/os/modules/fs/nffs/nffs.md index e5995ee..7bc4693 100644 --- a/docs/os/modules/fs/nffs/nffs.md +++ b/docs/os/modules/fs/nffs/nffs.md @@ -24,78 +24,21 @@ Thus, each area must comprise a discrete number of blocks. ####Initialization -Before nffs can be used, it must be initialized. There are two means of initializing an nffs file system: +As part of overall system initialization, mynewt re-initialized the filesystem as follows: -1. Restore an existing file system via detection. -2. Create a new file system via formatting. +1. Restores an existing file system via detection. +2. Creates a new file system via formatting. A typical initialization sequence is the following: 1. Detect an nffs file system in a specific region of flash. -2. If no file system was detected, format a new file system in the same flash region. - -Both methods require the user to describe how the flash memory should be divided into nffs areas. This is accomplished with an array of [struct nffs\_area\_desc](nffs_area_desc.md). - -Typically, a product's flash layout is exposed via its BSP-specific `bsp_flash_dev()` function. This function retrieves the layout of the specified flash device resident in the BSP. The result of this function can then be converted into the `struct nffs_area_desc[]` that nffs requires. The below example, taken from the slinky project, illustrates the nffs initialization procedure. - -```c -/*** hw/hal/include/hal/flash_map.h */ - -/* - * Flash area types - */ -#define FLASH_AREA_BOOTLOADER 0 -#define FLASH_AREA_IMAGE_0 1 -#define FLASH_AREA_IMAGE_1 2 -#define FLASH_AREA_IMAGE_SCRATCH 3 -#define FLASH_AREA_NFFS 4 -``` - -```c -/*** project/slinky/src/main.c */ - -int -main(int argc, char **argv) -{ - int rc; - int cnt; - - /* NFFS_AREA_MAX is defined in the BSP-specified bsp.h header file. */ - struct nffs_area_desc descs[NFFS_AREA_MAX]; - - /* Initialize nffs's internal state. */ - rc = nffs_init(); - assert(rc == 0); - - /* Convert the set of flash blocks we intend to use for nffs into an array - * of nffs area descriptors. - */ - cnt = NFFS_AREA_MAX; - rc = flash_area_to_nffs_desc(FLASH_AREA_NFFS, &cnt, descs); - assert(rc == 0); - - /* Attempt to restore an existing nffs file system from flash. */ - if (nffs_detect(descs) == FS_ECORRUPT) { - /* No valid nffs instance detected; format a new one. */ - rc = nffs_format(descs); - assert(rc == 0); - } - /* [ ... ] */ -} -``` +2. If no file system was detected, if configured to do so, format a new file system in the same flash region. -After nffs has been initialized, the application can access the file system via the [file system abstraction layer](../fs/fs.md). - -###Configuration - -The nffs file system is configured by populating fields in a global [struct nffs\_config](nffs_config.md) instance. Each field in the structure corresponds to a setting. All configuration must be done prior to calling nffs\_init(). +Note that in the latter case, the behavior is controlled with a variable in the syscfg.yml file. If NFFS_DETECT_FAIL is set to 1, the system ignores NFFS filesystem detection issues, but unless a new filesystem is formatted manually, all filesystem access will fail. If NFFS_DETECT_FAIL is set to 2, the system will format a new filesystem - note however this effectively deletes all existing data in the NFFS flash areas. +Both methods require the user to describe how the flash memory should be divided into nffs areas. This is accomplished with an array of [struct nffs\_area\_desc](nffs_area_desc.md) configured as part of the BSP configureation. -The global `struct nffs_config` instance is exposed in `nffs/nffs.h` as follows: - -```c -extern struct nffs_config nffs_config; -``` +After nffs has been initialized, the application can access the file system via the [file system abstraction layer](../fs/fs.md). ###Data Structures
