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

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