Build 329

CONTRIBUTING.txt

@@ -0,0 +1,80 @@
+Reliance Edge Contribution Guidelines
+=====================================
+
+This document describes how to go about contributing to Reliance Edge.
+
+How Can I Contribute?
+---------------------
+
+A few examples of how you can contribute:
+
+- Fixing bugs, including: compiler warnings, portability issues, or erroneous
+  driver logic.
+- Porting Reliance Edge to a new RTOS.
+- Improving the documentation, including: fixing typos, dead links, or poor
+  wording; or pointing out unclear or incomplete instructions.
+- Creating new tools or tests.
+- Adding new features or APIs (though for major new features, it might be good
+  to discuss your idea with Datalight).
+
+Suggestions and feedback of any kind are welcome at
+<RelianceEdgeSupport@datalight.com>.  If there is something about Reliance Edge
+which you like or do not like, let us know.
+
+Reporting Bugs
+--------------
+
+To report bugs, please create a GitHub issue or contact
+<RelianceEdgeSupport@datalight.com>.  Search the existing GitHub issues to make
+sure that your issue is not a known issue.
+
+Submitting Changes
+------------------
+
+To submit code changes, fork the Reliance Edge repository, commit your changes,
+and use GitHub to submit a pull request.  See details here:
+
+<https://help.github.com/articles/using-pull-requests/>
+
+After submitting a pull request, it will be reviewed by Datalight engineers.
+You may be asked to make changes via the comments on the pull request.  If the
+pull request contributes a substantial amount of code, you will need to assign
+copyright to Datalight before it will be accepted (see the next section).
+
+Pull requests will never be directly merged into the Reliance Edge GitHub repo.
+Due to quality assurance and packaging requirements, pull requests which are
+accepted will be incorporated indirectly and pushed into the GitHub repository
+as part of a build.  As such, all pull requests will be closed, but a comment
+will indicate whether the changes were incorporated or not.
+
+For the portions of the _Developer's Guide_ that are included in the GitHub
+repository (like the API documentation, which is derived from Doxygen comments
+in the code), changes should be submitted as pull requests just like code.  For
+the prose chapters which are excluded from the repository, send an email to
+<RelianceEdgeSupport@datalight.com> to request changes.
+
+Copyright
+---------
+
+Datalight policy is that Datalight must own the copyright of all code
+incorporated into Reliance Edge; if contributing a substantial amount of code,
+you must file a copyright assignment agreement.  After submitting your pull
+request, contact <RelianceEdgeSupport@datalight.com> if you believe you will
+need to assign the copyright.  If Datalight determines that a copyright
+assignment agreement is required, and you have not made contact, you will be
+notified via a comment left on the pull request.
+
+CREDITS.TXT
+-----------
+
+CREDITS.TXT is a list of people who have made non-trivial contributions to
+Reliance Edge.  If you contribute to Reliance Edge, it is understood that
+Datalight may, at our discretion, add your name and GitHub account name to
+CREDITS.TXT, unless you explicitly request to be excluded.
+
+Datalight Coding Style
+----------------------
+
+Code contributed to Reliance Edge should make an attempt to follow Datalight
+coding style.  See the doc/coding_style.txt document.
+

CREDITS.txt

@@ -0,0 +1,18 @@
+Reliance Edge Credits
+=====================
+
+This is a list (or partial list) of people who have made non-trivial or
+noteworthy contributions to the Reliance Edge project.  It is sorted by name.
+Entries are formatted as below:
+
+Real Name (githubaccount)
+Short description of how Real Name contributed to Reliance Edge.
+
+The real name may be withheld by request and the GitHub account name might be
+missing if the contributor does not use GitHub.
+
+Credits
+-------
+
+None yet! ;)
+

README.md

@@ -1,2 +1,112 @@
-# reliance-edge
-File System for Decision-Quality Data at the Edge of the IoT
+# Reliance Edge
+
+Reliance Edge is a small, portable, highly reliable power-fail safe file system
+for resource-constrained embedded systems like microcontrollers.  It is written
+in C and provides a familiar POSIX-like file system API, making it easy to use
+in your application; or an alternate minimalist API if your application has
+simple storage needs.  Reliance Edge is highly configurable and can be tuned to
+the precise needs of your application.
+
+## Documentation
+
+The complete documentation for Reliance Edge is distributed separately.  It
+includes an API reference and detailed discussions of various aspects of using
+Reliance Edge, including porting, building, configuring, and testing.  This
+complete documentation, called the _Developer's Guide_, can be obtained for free
+from here:
+
+<http://www.datalight.com/reliance-edge>
+
+In addition this README, see [doc/release_notes.md](doc/release_notes.md) for a
+list of updates to Reliance Edge and a list of known issues.
+
+## Why Use Reliance Edge?
+
+Reliance Edge is ideal for small embedded systems with data storage
+requirements, especially if there is a chance of sudden power loss or other
+system failures.  Compared to "raw" disk access, using a file system like
+Reliance Edge removes the burden of tracking which sectors belong to which
+objects, and allows data to be updated more reliably.  Compared to the FAT file
+system, using Reliance Edge eliminates the possibility that file system data
+will be left in an inconsistent state, corrupting the disk; Reliance Edge does
+not need a fsck/CHKDSK utility.  Compared to journaling file systems, Reliance
+Edge has less overhead and results in less storage media wear for longer device
+lifetimes.
+
+Reliance Edge uses a unique transactional model that not only prevents file
+system corruption but also allows a set of changes to be made in an atomic "all
+or nothing" fashion.  This is very useful for applications that make sets of
+interrelated changes.  By using the features of Reliance Edge, a set of changes
+can be incorporated into a single atomic transaction, which is committed in its
+entirety or not at all even if interrupted by power loss; this means the
+application does not need code to recover from partially-finished updates.
+
+## Hardware
+
+The typical hardware for Reliance Edge is a 32-bit microcontroller, but other
+targets are possible.  In its typical configurations, Reliance Edge needs at
+least 4 KB to 5 KB of RAM, 10 to 18 KB of code space (on the ROM or NOR flash),
+and 600 to 750 bytes of stack.
+
+Reliance Edge is not designed for high-end embedded systems that run complicated
+operating systems like Linux or Windows Embedded Compact.  Embedded systems of
+that variety are better served by other file systems, like Datalight's
+[Reliance Nitro](http://www.datalight.com/products/embedded-file-systems/reliance-nitro).
+
+## Getting Reliance Edge Working
+
+Before you can use Reliance Edge, it must be ported and configured.  At a
+minimum, porting includes filling-in functions so that Reliance Edge can issue
+commands to your storage medium; depending on your needs, other functions may
+need to be filled in as well.  These functions reside in a subdirectory in the
+os/ directory; see os/stub/ for a blank set of functions.  Configuring includes
+creating a project directory (start by copying projects/newproj) and creating
+the two configuration files (redconf.h/redconf.c) using the Reliance Edge
+Configuration Utility (included with the _Developer's Guide_ download).
+
+These topics are covered in much greater detail in the _Developer's Guide_,
+linked above.
+
+## Using Reliance Edge
+
+Using Reliance Edge is a simple matter of including the primary Reliance Edge
+application header in your application (either include/redposix.h or
+include/redfse.h) and compiling and linking against Reliance Edge binaries.
+The Reliance Edge driver must be initialized before it is used (via the
+red\_init() or RedFseInit() functions) and then volumes can be mounted and file
+and directory functions invoked.  The Reliance Edge API is documented in the
+_Developer's Guide_ (linked above) and also via comments in the source code.
+
+## Licensing
+
+Reliance Edge is an open-source project licensed under the GNU General Public
+License v2 (GPLv2).  Businesses and individuals that for commercial or other
+reasons cannot comply with the terms of the GPLv2 license may obtain a
+commercial license before incorporating Reliance Edge into proprietary software
+for distribution in any form.  Visit <http://www.datalight.com/reliance-edge>
+for more information.  The commercial distribution also includes extra tests and
+tools not distributed with the GPLv2 version.
+
+See LICENSE.txt for the full license terms of this distribution of the product.
+
+## Getting Help
+
+If you need assistance using Reliance Edge, and you have already consulted the
+_Developer's Guide_, contact <RelianceEdgeSupport@datalight.com>.
+
+In the near future, a community forum or message board will be set up to
+facilitate discussion of Reliance Edge and allow users to get help from
+Datalight and from each other.  In the meantime, please use the email address
+given above.
+
+## Contributing
+
+Contributions to Reliance Edge are welcome.  Our policy is that Datalight must
+own the copyright of all code incorporated into Reliance Edge; if contributing a
+significant amount of code, you will be asked to file a copyright assignment
+agreement.  See CONTRIBUTING.txt for further details and contribution
+guidelines.
+
+To report bugs, please create a GitHub issue or contact
+<RelianceEdgeSupport@datalight.com>.
+

README.txt

@@ -0,0 +1,129 @@
+
+
+RELIANCE EDGE
+
+
+Reliance Edge is a small, portable, highly reliable power-fail safe file
+system for resource-constrained embedded systems like microcontrollers.
+It is written in C and provides a familiar POSIX-like file system API,
+making it easy to use in your application; or an alternate minimalist
+API if your application has simple storage needs. Reliance Edge is
+highly configurable and can be tuned to the precise needs of your
+application.
+
+
+Documentation
+
+The complete documentation for Reliance Edge is distributed separately.
+It includes an API reference and detailed discussions of various aspects
+of using Reliance Edge, including porting, building, configuring, and
+testing. This complete documentation, called the _Developer's Guide_,
+can be obtained for free from here:
+
+http://www.datalight.com/reliance-edge
+
+In addition this README, see doc/release_notes.md for a list of updates
+to Reliance Edge and a list of known issues.
+
+
+Why Use Reliance Edge?
+
+Reliance Edge is ideal for small embedded systems with data storage
+requirements, especially if there is a chance of sudden power loss or
+other system failures. Compared to "raw" disk access, using a file
+system like Reliance Edge removes the burden of tracking which sectors
+belong to which objects, and allows data to be updated more reliably.
+Compared to the FAT file system, using Reliance Edge eliminates the
+possibility that file system data will be left in an inconsistent state,
+corrupting the disk; Reliance Edge does not need a fsck/CHKDSK utility.
+Compared to journaling file systems, Reliance Edge has less overhead and
+results in less storage media wear for longer device lifetimes.
+
+Reliance Edge uses a unique transactional model that not only prevents
+file system corruption but also allows a set of changes to be made in an
+atomic "all or nothing" fashion. This is very useful for applications
+that make sets of interrelated changes. By using the features of
+Reliance Edge, a set of changes can be incorporated into a single atomic
+transaction, which is committed in its entirety or not at all even if
+interrupted by power loss; this means the application does not need code
+to recover from partially-finished updates.
+
+
+Hardware
+
+The typical hardware for Reliance Edge is a 32-bit microcontroller, but
+other targets are possible. In its typical configurations, Reliance Edge
+needs at least 4 KB to 5 KB of RAM, 10 to 18 KB of code space (on the
+ROM or NOR flash), and 600 to 750 bytes of stack.
+
+Reliance Edge is not designed for high-end embedded systems that run
+complicated operating systems like Linux or Windows Embedded Compact.
+Embedded systems of that variety are better served by other file
+systems, like Datalight's Reliance Nitro.
+
+
+Getting Reliance Edge Working
+
+Before you can use Reliance Edge, it must be ported and configured. At a
+minimum, porting includes filling-in functions so that Reliance Edge can
+issue commands to your storage medium; depending on your needs, other
+functions may need to be filled in as well. These functions reside in a
+subdirectory in the os/ directory; see os/stub/ for a blank set of
+functions. Configuring includes creating a project directory (start by
+copying projects/newproj) and creating the two configuration files
+(redconf.h/redconf.c) using the Reliance Edge Configuration Utility
+(included with the _Developer's Guide_ download).
+
+These topics are covered in much greater detail in the _Developer's
+Guide_, linked above.
+
+
+Using Reliance Edge
+
+Using Reliance Edge is a simple matter of including the primary Reliance
+Edge application header in your application (either include/redposix.h
+or include/redfse.h) and compiling and linking against Reliance Edge
+binaries. The Reliance Edge driver must be initialized before it is used
+(via the red_init() or RedFseInit() functions) and then volumes can be
+mounted and file and directory functions invoked. The Reliance Edge API
+is documented in the _Developer's Guide_ (linked above) and also via
+comments in the source code.
+
+
+Licensing
+
+Reliance Edge is an open-source project licensed under the GNU General
+Public License v2 (GPLv2). Businesses and individuals that for
+commercial or other reasons cannot comply with the terms of the GPLv2
+license may obtain a commercial license before incorporating Reliance
+Edge into proprietary software for distribution in any form. Visit
+http://www.datalight.com/reliance-edge for more information. The
+commercial distribution also includes extra tests and tools not
+distributed with the GPLv2 version.
+
+See LICENSE.txt for the full license terms of this distribution of the
+product.
+
+
+Getting Help
+
+If you need assistance using Reliance Edge, and you have already
+consulted the _Developer's Guide_, contact
+RelianceEdgeSupport@datalight.com.
+
+In the near future, a community forum or message board will be set up to
+facilitate discussion of Reliance Edge and allow users to get help from
+Datalight and from each other. In the meantime, please use the email
+address given above.
+
+
+Contributing
+
+Contributions to Reliance Edge are welcome. Our policy is that Datalight
+must own the copyright of all code incorporated into Reliance Edge; if
+contributing a significant amount of code, you will be asked to file a
+copyright assignment agreement. See CONTRIBUTING.txt for further details
+and contribution guidelines.
+
+To report bugs, please create a GitHub issue or contact
+RelianceEdgeSupport@datalight.com.