blob: 03417156e4b0d1a276e2147a07f4481d88510e02 [file] [log] [blame]
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<!-- This is broken by doc revisioning.
-->
<link rel="shortcut icon" href="../../../../../img/favicon.ico">
<title>toc - Apache Mynewt</title>
<link href="../../../../../css/bootstrap-3.0.3.min.css" rel="stylesheet">
<link rel="stylesheet" href="../../../../../css/highlight.css">
<link href="../../../../../css/base.css" rel="stylesheet">
<link href="../../../../../css/custom.css" rel="stylesheet">
<link href="../../../../../css/v2.css" rel="stylesheet">
<link href="https://fonts.googleapis.com/css?family=Lato" rel="stylesheet">
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/font-awesome/4.5.0/css/font-awesome.min.css">
<!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
<!--[if lt IE 9]>
<script src="https://oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
<script src="https://oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script>
<![endif]-->
<script>
(function(i, s, o, g, r, a, m) {
i["GoogleAnalyticsObject"] = r;
(i[r] =
i[r] ||
function() {
(i[r].q = i[r].q || []).push(arguments);
}),
(i[r].l = 1 * new Date());
(a = s.createElement(o)), (m = s.getElementsByTagName(o)[0]);
a.async = 1;
a.src = g;
m.parentNode.insertBefore(a, m);
})(window, document, "script", "//www.google-analytics.com/analytics.js", "ga");
ga("create", "UA-72162311-1", "auto");
ga("send", "pageview");
</script>
</head>
<body class="toc">
<div class="container">
<div class="row v2-main-banner">
<a class="logo-cell" href="/">
<img class="logo" src="/img/logo.png">
</a>
<div class="tagline-cell">
<h4 class="tagline">An OS to build, deploy and securely manage billions of devices</h4>
</div>
<div class="news-cell">
<div class="well">
<h4>Latest News:</h4> <a href="/download">Apache Mynewt 1.12.0, Apache NimBLE 1.7.0 </a> released (April 4, 2024)
</div>
</div>
</div>
</div>
<nav id="navbar" class="navbar navbar-inverse affix-top" data-spy="affix" data-offset-top="150" role="navigation">
<div class="container">
<!-- Collapsed navigation -->
<div class="navbar-header">
<!-- Expander button -->
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
</div>
<!-- Expanded navigation -->
<div class="navbar-collapse collapse">
<!-- Main navigation -->
<ul class="nav navbar-nav navbar-right">
<li
class=""
>
<a href="/"><i class="fa fa-home" style="font-size: larger;"></i></a>
</li>
<li
class="important"
>
<a href="/quick-start/">Quick Start</a>
</li>
<li
class=""
>
<a href="/about/">About</a>
</li>
<li
class=""
>
<a href="/talks/">Talks</a>
</li>
<li
class="active"
>
<a href="/documentation/">Documentation</a>
</li>
<li
class=""
>
<a href="/download/">Download</a>
</li>
<li
class=""
>
<a href="/community/">Community</a>
</li>
<li
class=""
>
<a href="/events/">Events</a>
</li>
</ul>
</div>
</div>
</nav>
<div class="container">
<div class="row">
<div class="col-md-3 v2-sidebar sidebar-container"><div id="docSidebar" class="hidden-print" role="complementary">
<div class="top">
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../../../../../search.html" method="get">
<div class="form-group">
<input type="text" name="q" class="form-control" placeholder="Search documentation" />
</div>
</form>
</div>
</div>
<ul class="toc-nav">
<li class="doc-version"><select class="form-control" onchange="if (this.value) window.location.href=this.value">
<option value="/latest">
Version: master
</option>
<option value="/v1_12_0/" >
Version: 1.12.0
</option>
<option value="/v1_11_0/" >
Version: 1.11.0
</option>
<option value="/v1_10_0/" >
Version: 1.10.0
</option>
<option value="/v1_9_0/" >
Version: 1.9.0
</option>
<option value="/v1_8_0/" >
Version: 1.8.0
</option>
<option value="/v1_7_0/" >
Version: 1.7.0
</option>
<option value="/v1_6_0/" >
Version: 1.6.0
</option>
<option value="/v1_5_0/" >
Version: 1.5.0
</option>
<option value="/v1_4_0/" >
Version: 1.4.0
</option>
<option value="/v1_3_0/os/introduction" >
Version: 1.3.0
</option>
<option value="/v1_2_0/os/introduction" >
Version: 1.2.0
</option>
<option value="/v1_1_0/os/introduction" >
Version: 1.1.0
</option>
<option value="/v1_0_0/os/introduction" selected="selected" >
Version: 1.0.0
</option>
<option value="/v0_9_0/os/introduction" >
Version: 0.9.0
</option>
</select></li>
<li ><a href="../../../../introduction/">Mynewt Documentation</a>
<ul>
<li ><a href="../../../../get_started/get_started/">Basic Setup</a>
</li>
<li >
<a href="../../../../get_started/vocabulary/">Concepts</a>
</li>
<li ><a href="../../../../tutorials/tutorials/">Tutorials</a>
</li>
<li ><a href="../../../../os_user_guide/">OS User Guide</a>
<ul>
<li ><a href="../../../../core_os/mynewt_os/">OS Core</a>
</li>
<li ><a href="../../../../core_os/porting/port_os/">Porting to your Platform</a>
</li>
<li ><a href="../../../console/console/">Console</a>
</li>
<li ><a href="../../../shell/shell/">Shell</a>
</li>
<li ><a href="../../../split/split/">Split Images</a>
</li>
<li ><a href="../../../bootloader/bootloader/">Bootloader</a>
</li>
<li><a href="
./
">File System</a>
<ul>
<li class="active"><a href="./">File System Abstraction</a>
<ul>
<li >
<a href="../fs_return_codes/">Return Codes</a>
</li>
<li><a href="
../fs_ops/
">Data Structures</a>
</li>
<li><a href="
../fs_close/
">Functions</a>
</li>
</ul>
</li>
<li >
<a href="../../fatfs/">FAT File System</a>
</li>
<li ><a href="../../nffs/nffs/">Newtron Flash File System</a>
</li>
<li >
<a href="../../otherfs/">Other File Systems</a>
</li>
</ul>
</li>
<li ><a href="../../../hal/hal/">Hardware Abstraction Layer</a>
</li>
<li ><a href="../../../drivers/driver/">Drivers</a>
</li>
<li ><a href="../../../testutil/testutil/">Test Utilities</a>
</li>
<li ><a href="../../../devmgmt/newtmgr/">Device Management with Newt Manager</a>
</li>
<li ><a href="../../../imgmgr/imgmgr/">Image Manager</a>
</li>
<li >
<a href="../../../baselibc/">Baselibc library</a>
</li>
<li ><a href="../../../json/json/">JSON</a>
</li>
<li ><a href="../../../fcb/fcb/">Flash Circular Buffer</a>
</li>
<li ><a href="../../../stats/stats/">Stats</a>
</li>
<li ><a href="../../../logs/logs/">Logs</a>
</li>
<li ><a href="../../../sysinitconfig/sysinitconfig/">System Configuration And Initialization</a>
</li>
</ul>
</li>
<li><a href="
../../../../../network/ble/ble_intro/
">BLE User Guide</a>
</li>
<li ><a href="../../../../../newt/newt_intro/">Newt Tool Guide</a>
</li>
<li ><a href="../../../../../newtmgr/overview/">Newt Manager Guide</a>
</li>
<li >
<a href="../../../../../known_issues/">Known Issues</a>
</li>
</ul>
</li>
<li><a href="
../../../../../faq/go_env/
">Appendix</a>
</li>
</ul>
</div></div>
<div class="col-md-9" role="main">
<div class="doc-header">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="/documentation/">Docs</a></li>
<li>&raquo; File System Abstraction</li>
<li>&raquo; File System</li>
<li>&raquo; <a href="os/os_user_guide/">OS User Guide</a></li>
<li>&raquo; <a href="os/introduction/">Mynewt Documentation</a></li>
</ul>
</div>
</div>
<div class="alert alert-warning">
<p>
Version 1.0.0 is not the most recent version of the Apache Mynewt
documentation. Click <a href="/latest">here</a> to read the latest
version.
</p>
</div>
<h1 id="file-system-abstraction">File System Abstraction</h1>
<p>Mynewt provides a file system abstraction layer (<code>fs/fs</code>) to allow client code to be file system agnostic. By accessing the file system via the <code>fs/fs</code> API, client code can perform file system operations without being tied to a particular implementation. When possible, library code should use the <code>fs/fs</code> API rather than accessing the underlying file system directly.</p>
<h3 id="description">Description</h3>
<p>Applications should aim to minimize the amount of code which depends on a particular file system implementation. When possible, only depend on the
<code>fs/fs</code> package.
In terms of the Mynewt hierarchy, an <strong>app</strong> package must depend on a specific file system package, while <strong>library</strong> packages should only depend on <code>fs/fs</code>.</p>
<p>Applications wanting to access a filesystem are required to include the necessary packages in their applications pkg.yml file.
In the following example, the <a href="../../nffs/nffs/"><code>Newtron Flash File System</code></a>
is used.</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code># repos/apache-mynewt-core/apps/slinky/pkg.yml
pkg.name: repos/apache-mynewt-core/apps/slinky
pkg.deps:
- fs/fs # include the file operations interfaces
- fs/nffs # include the NFFS filesystem implementation
</code></pre></div>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code># repos/apache-mynewt-core/apps/slinky/syscfg.yml
# [...]
# Package: apps/&lt;example app&gt;
# [...]
CONFIG_NFFS: 1 # initialize and configure NFFS into the system
# NFFS_DETECT_FAIL: 1 # Ignore NFFS detection issues
# NFFS_DETECT_FAIL: 2 # Format a new NFFS file system on failure to detect
# [...]
</code></pre></div>
<p>Consult the documentation for <a href="../../nffs/nffs/"><code>nffs</code></a> for a more detailed explanation of NFFS_DETECT_FAIL</p>
<p>Code which uses the file system after the system has been initialized need only depend on <code>fs/fs</code>. For example, the <code>libs/imgmgr</code> 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 <code>fs/fs</code> package.</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code># repos/apache-mynewt-core/libs/imgmgr/pkg.yml
pkg.name: libs/imgmgr
pkg.deps:
- fs/fs
# [...]
</code></pre></div>
<p>The <code>libs/imgmgr</code> package uses the <code>fs/fs</code> API for all file system operations.</p>
<h3 id="support-for-multiple-filesystems">Support for multiple filesystems</h3>
<p>When using a single filesystem/disk, it is valid to provide paths in the standard
unix way, eg, <code>/&lt;dir-name&gt;/&lt;file-name&gt;</code>. 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
<code>fs/disk</code> package which is a dependency of <code>fs/fs</code>. It adds the following extra
user function:</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code><span style="color: #A90D91">int</span> <span style="color: #000000">disk_register</span>(<span style="color: #A90D91">const</span> <span style="color: #A90D91">char</span> <span style="color: #000000">*disk_name</span>, <span style="color: #A90D91">const</span> <span style="color: #A90D91">char</span> <span style="color: #000000">*fs_name</span>, <span style="color: #A90D91">struct</span> <span style="color: #3F6E75">disk_ops</span> <span style="color: #000000">*dops</span>)
</code></pre></div>
<p>As an example os usage:</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code><span style="color: #000000">disk_register</span>(<span style="color: #C41A16">&quot;mmc0&quot;</span>, <span style="color: #C41A16">&quot;fatfs&quot;</span>, <span style="color: #000000">&amp;mmc_ops</span>);
<span style="color: #000000">disk_register</span>(<span style="color: #C41A16">&quot;flash0&quot;</span>, <span style="color: #C41A16">&quot;nffs&quot;</span>, <span style="color: #A90D91">NULL</span>);
</code></pre></div>
<p>This registers the name <code>mmc0</code> to use <code>fatfs</code> as the filesystem and <code>mmc_ops</code> for
the low-level disk driver and also registers <code>flash0</code> to use <code>nffs</code>. <code>nffs</code> is
currently strongly bound to the <code>hal_flash</code> interface, ignoring any other possible
<code>disk_ops</code> given.</p>
<h4 id="struct-disk_ops">struct disk_ops</h4>
<p>To support a new low-level disk interface, the <code>struct disk_ops</code> interface must
be implemented by the low-level driver. Currently only <code>read</code> and <code>write</code> are
effectively used (by <code>fatfs</code>).</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code><span style="color: #A90D91">struct</span> <span style="color: #3F6E75">disk_ops</span> {
<span style="color: #A90D91">int</span> (<span style="color: #000000">*read</span>)(<span style="color: #A90D91">uint8_t</span>, <span style="color: #A90D91">uint32_t</span>, <span style="color: #A90D91">void</span> <span style="color: #000000">*</span>, <span style="color: #A90D91">uint32_t</span>);
<span style="color: #A90D91">int</span> (<span style="color: #000000">*write</span>)(<span style="color: #A90D91">uint8_t</span>, <span style="color: #A90D91">uint32_t</span>, <span style="color: #A90D91">const</span> <span style="color: #A90D91">void</span> <span style="color: #000000">*</span>, <span style="color: #A90D91">uint32_t</span>);
<span style="color: #A90D91">int</span> (<span style="color: #000000">*ioctl</span>)(<span style="color: #A90D91">uint8_t</span>, <span style="color: #A90D91">uint32_t</span>, <span style="color: #A90D91">void</span> <span style="color: #000000">*</span>);
<span style="color: #000000">SLIST_ENTRY</span>(<span style="color: #000000">disk_ops</span>) <span style="color: #000000">sc_next</span>;
}
</code></pre></div>
<h3 id="thread-safety">Thread Safety</h3>
<p>All <code>fs/fs</code> functions are thread safe.</p>
<h3 id="header-files">Header Files</h3>
<p>All code which uses the <code>fs/fs</code> package needs to include the following header:</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code><span style="color: #633820">#include</span> <span style="color: #177500">&quot;fs/fs.h&quot;</span>
</code></pre></div>
<h3 id="data-structures">Data Structures</h3>
<p>All <code>fs/fs</code> data structures are opaque to client code.</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code><span style="color: #A90D91">struct</span> <span style="color: #3F6E75">fs_file</span>;
<span style="color: #A90D91">struct</span> <span style="color: #3F6E75">fs_dir</span>;
<span style="color: #A90D91">struct</span> <span style="color: #3F6E75">fs_dirent</span>;
</code></pre></div>
<h3 id="api"><a name="API"></a>API</h3>
<p>Functions in <code>fs/fs</code> that indicate success or failure do so with the following set of return codes:</p>
<ul>
<li><a href="../fs_return_codes/">Return Codes</a></li>
</ul>
<p>The functions available in this OS feature are:</p>
<table>
<thead>
<tr>
<th>Function</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="../fs_close/">fs_close</a></td>
<td>Closes the specified file and invalidates the file handle.</td>
</tr>
<tr>
<td><a href="../fs_closedir/">fs_closedir</a></td>
<td>Closes the specified directory handle.</td>
</tr>
<tr>
<td><a href="../fs_dirent_is_dir/">fs_dirent_is_dir</a></td>
<td>Tells you whether the specified directory entry is a sub-directory or a regular file.</td>
</tr>
<tr>
<td><a href="../fs_dirent_name/">fs_dirent_name</a></td>
<td>Retrieves the filename of the specified directory entry.</td>
</tr>
<tr>
<td><a href="../fs_filelen/">fs_filelen</a></td>
<td>Retrieves the current length of the specified open file.</td>
</tr>
<tr>
<td><a href="../fs_getpos/">fs_getpos</a></td>
<td>Retrieves the current read and write position of the specified open file.</td>
</tr>
<tr>
<td><a href="../fs_mkdir/">fs_mkdir</a></td>
<td>Creates the directory represented by the specified path.</td>
</tr>
<tr>
<td><a href="../fs_open/">fs_open</a></td>
<td>Opens a file at the specified path.</td>
</tr>
<tr>
<td><a href="../fs_opendir/">fs_opendir</a></td>
<td>Opens the directory at the specified path.</td>
</tr>
<tr>
<td><a href="../fs_read/">fs_read</a></td>
<td>Reads data from the specified file.</td>
</tr>
<tr>
<td><a href="../fs_readdir/">fs_readdir</a></td>
<td>Reads the next entry in an open directory.</td>
</tr>
<tr>
<td><a href="../fs_register/">fs_register</a></td>
<td>Registers a file system with the abstraction layer.</td>
</tr>
<tr>
<td><a href="../fs_rename/">fs_rename</a></td>
<td>Performs a rename and/or move of the specified source path to the specified destination.</td>
</tr>
<tr>
<td><a href="../fs_seek/">fs_seek</a></td>
<td>Positions a file's read and write pointer at the specified offset.</td>
</tr>
<tr>
<td><a href="../fs_unlink/">fs_unlink</a></td>
<td>Unlinks the file or directory at the specified path.</td>
</tr>
<tr>
<td><a href="../fs_write/">fs_write</a></td>
<td>Writes the supplied data to the current offset of the specified file handle.</td>
</tr>
</tbody>
</table>
<p>Additional file system utilities that bundle some of the basic functions above are:</p>
<table>
<thead>
<tr>
<th>Function</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="../fsutil_read_file/">fsutil_read_file</a></td>
<td>Opens a file at the specified path, retrieve data from the file starting from the specified offset, and close the file and invalidate the file handle.</td>
</tr>
<tr>
<td><a href="../fsutil_write_file/">fsutil_write_file</a></td>
<td>Open a file at the specified path, write the supplied data to the current offset of the specified file handle, and close the file and invalidate the file handle.</td>
</tr>
</tbody>
</table>
<div class="row">
<ul class="nav nav-pills" style="margin-bottom: 10px">
<li>
</li>
<li class="pull-right">
</li>
</ul>
</div>
<footer class="row">
<div class="col-xs-12">
<p class="copyright">Apache Mynewt (incubating) is available under Apache License, version 2.0.</p>
</div>
<div class="col-xs-12">
<div class="logos">
<a href="https://www.apache.org/">
<img src="/img/asf_logo_wide_small.png" alt="Apache" title="Apache">
</a>
<p>
Copyright © 2015-2021 The Apache Software Foundation.<br>
<small class="footnote">
Apache Mynewt, Mynewt, Apache, the Apache feather logo, and the Apache Mynewt
project logo are either registered trademarks or trademarks of the Apache
Software Foundation in the United States and other countries.
</small>
</p>
<a href="">
<img src="https://www.countit.com/images/add_to_slack.png" alt="Slack Icon" title="Join our Slack Community" />
</a>
</div>
</div>
<a href="https://www.apache.org/licenses/">
<button class="button-footer-asf">
License
</button>
</a>
<a href="https://www.apache.org/foundation/sponsorship.html">
<button class="button-footer-asf">
Sponsorship
</button>
</a>
<a href="https://www.apache.org/foundation/thanks.html">
<button class="button-footer-asf">
Thanks
</button>
</a>
<a href="https://www.apache.org/security/">
<button class="button-footer-asf">
Security
</button>
</a>
<a href="https://apache.org/events/current-event">
<button class="button-footer-asf">
ASF Events
</button>
</a>
</footer>
</div>
</div>
</div>
<script src="../../../../../js/jquery-1.10.2.min.js"></script>
<script src="../../../../../js/bootstrap-3.0.3.min.js"></script>
<script src="../../../../../js/highlight.pack.js"></script>
<script src="../../../../../js/base.js"></script>
<script src="../../../../../js/custom.js"></script>
<script src="search/main.js"></script>
</body>
</html>