git.sur5r.net Git - freertos/blob - FreeRTOS-Plus/Source/Reliance-Edge/README.md

   1 # Reliance Edge
   2
   3 Reliance Edge is a small, portable, highly reliable power-fail safe file system
   4 for resource-constrained embedded systems like microcontrollers.  It is written
   5 in C and provides a familiar POSIX-like file system API, making it easy to use
   6 in your application; or an alternate minimalist API if your application has
   7 simple storage needs.  Reliance Edge is highly configurable and can be tuned to
   8 the precise needs of your application.
   9
  10 ## Getting Help
  11
  12 You will find this section later in our readme as well - but we wanted to tell
  13 you up front: DATALIGHT WANTS TO HEAR FROM YOU!  Whether it's just to make
  14 comments about the product, to suggest new features, or to tell us what you
  15 don't like - reach out!  All comments and inquiries can be directed to
  16 <RelianceEdgeSupport@datalight.com>.
  17
  18 ## Documentation
  19
  20 The complete documentation for Reliance Edge is distributed separately.  It
  21 includes an API reference and detailed discussions of various aspects of using
  22 Reliance Edge, including porting, building, configuring, and testing.  This
  23 complete documentation, called the _Developer's Guide_, can be obtained for free
  24 from here:
  25
  26 <http://www.datalight.com/reliance-edge>
  27
  28 In addition this README, see doc/release_notes.md for a list of updates
  29 to Reliance Edge and a list of known issues. There is also a quick-start
  30 guide in the doc/ directory that describes step-by-step how to compile
  31 and run Reliance Edge in a simulated Windows environment.
  32
  33 ## Why Use Reliance Edge?
  34
  35 Reliance Edge is ideal for small embedded systems with data storage
  36 requirements, especially if there is a chance of sudden power loss or other
  37 system failures.  Compared to "raw" disk access, using a file system like
  38 Reliance Edge removes the burden of tracking which sectors belong to which
  39 objects, and allows data to be updated more reliably.  Compared to the FAT file
  40 system, using Reliance Edge eliminates the possibility that file system data
  41 will be left in an inconsistent state, corrupting the disk; Reliance Edge does
  42 not need a fsck/CHKDSK utility.  Compared to journaling file systems, Reliance
  43 Edge has less overhead and results in less storage media wear for longer device
  44 lifetimes.
  45
  46 Reliance Edge uses a unique transactional model that not only prevents file
  47 system corruption but also allows a set of changes to be made in an atomic "all
  48 or nothing" fashion.  This is very useful for applications that make sets of
  49 interrelated changes.  By using the features of Reliance Edge, a set of changes
  50 can be incorporated into a single atomic transaction, which is committed in its
  51 entirety or not at all even if interrupted by power loss; this means the
  52 application does not need code to recover from partially-finished updates.
  53
  54 ## Hardware
  55
  56 The typical hardware for Reliance Edge is a 32-bit microcontroller, but other
  57 targets are possible.  In its typical configurations, Reliance Edge needs at
  58 least 4 KB to 5 KB of RAM, 11 to 18 KB of code space (on the ROM or NOR flash),
  59 and 500 to 700 bytes of stack.
  60
  61 Reliance Edge is not designed for high-end embedded systems that run complicated
  62 operating systems like Linux or Windows Embedded Compact.  Embedded systems of
  63 that variety are better served by other file systems, like Datalight's
  64 [Reliance Nitro](http://www.datalight.com/products/embedded-file-systems/reliance-nitro).
  65
  66 ## Getting Reliance Edge Working
  67
  68 Before you can use Reliance Edge, it must be ported and configured.  At a
  69 minimum, porting includes filling-in functions so that Reliance Edge can issue
  70 commands to your storage medium; depending on your needs, other functions may
  71 need to be filled in as well.  These functions reside in a subdirectory in the
  72 os/ directory; see os/stub/ for a blank set of functions.  Configuring includes
  73 creating a project directory (start by copying projects/newproj) and creating
  74 the two configuration files (redconf.h/redconf.c) using the Reliance Edge
  75 Configuration Utility (which can be downloaded from
  76 <http://www.datalight.com/reliance-edge>).
  77
  78 These topics are covered in much greater detail in the _Developer's Guide_,
  79 linked above.
  80
  81 ## Using Reliance Edge
  82
  83 Using Reliance Edge is a simple matter of including the primary Reliance Edge
  84 application header in your application (either include/redposix.h or
  85 include/redfse.h) and compiling and linking against Reliance Edge binaries.
  86 The Reliance Edge driver must be initialized before it is used (via the
  87 red\_init() or RedFseInit() functions) and then volumes can be mounted and file
  88 and directory functions invoked.  The Reliance Edge API is documented in the
  89 _Developer's Guide_ (linked above) and also via comments in the source code.
  90
  91 ## Licensing
  92
  93 Reliance Edge is an open-source project licensed under the GNU General Public
  94 License v2 (GPLv2).  Businesses and individuals that for commercial or other
  95 reasons cannot comply with the terms of the GPLv2 license may obtain a
  96 commercial license before incorporating Reliance Edge into proprietary software
  97 for distribution in any form.  Visit <http://www.datalight.com/reliance-edge>
  98 for more information.  The commercial distribution also includes extra tests and
  99 tools not distributed with the GPLv2 version.
 100
 101 See LICENSE.txt for the full license terms of this distribution of the product.
 102
 103 ## Getting Help
 104
 105 If you need assistance using Reliance Edge, and you have already consulted the
 106 _Developer's Guide_, contact <RelianceEdgeSupport@datalight.com>.
 107
 108 In the near future, a community forum or message board will be set up to
 109 facilitate discussion of Reliance Edge and allow users to get help from
 110 Datalight and from each other.  In the meantime, please use the email address
 111 given above.
 112
 113 ## Contributing
 114
 115 Contributions to Reliance Edge are welcome.  Our policy is that Datalight must
 116 own the copyright of all code incorporated into Reliance Edge; if contributing a
 117 significant amount of code, you will be asked to file a copyright assignment
 118 agreement.  See CONTRIBUTING.txt for further details and contribution
 119 guidelines.
 120
 121 To report bugs, please create a GitHub issue or contact
 122 <RelianceEdgeSupport@datalight.com>.
 123