ceedling 0.9.0 → 1.0.1

data/vendor/c_exception/README.md

@@ -0,0 +1,236 @@
+CException ![CI](https://github.com/ThrowTheSwitch/CException/workflows/CI/badge.svg)
+==========
+
+_This Documentation Is Released Under a Creative Commons 3.0 Attribution Share-Alike License_
+
+CException is simple exception handling in C. It is significantly faster than full-blown C++ exception handling 
+but loses some flexibility. It is portable to any platform supporting `setjmp`/`longjmp`.
+
+Getting Started
+================
+
+The simplest way to get started is to just grab the code and pull it into your project:
+
+```
+git clone https://github.com/throwtheswitch/cexception.git
+```
+
+If you want to contribute to this project, you'll also need to have Ruby and Ceedling installed to run the unit tests.
+
+Usage
+=====
+
+### So what's it good for?
+
+Mostly error handling. Passing errors down a long chain of function calls gets ugly. Sometimes really ugly. 
+So what if you could just specify certain places where you want to handle errors, and all your errors were 
+transferred there? Let's try a lame example:
+
+CException uses C standard library functions setjmp and longjmp to operate. As long as the target system 
+has these two functions defined, this library should be useable with very little configuration. It even 
+supports environments where multiple program flows are in use, such as real-time operating systems... 
+we started this project for use in embedded systems... but it obviously can be used for larger systems too.
+
+### Error Handling with CException:
+
+```
+void functionC(void) {
+  //do some stuff
+  if (there_was_a_problem)
+    Throw(ERR_BAD_BREATH);
+  //this stuff never gets called because of error
+}
+```
+
+There are about a gajillion exception frameworks using a similar setjmp/longjmp method out there... and there 
+will probably be more in the future. Unfortunately, when we started our last embedded project, all those that 
+existed either (a) did not support multiple tasks (therefore multiple stacks) or (b) were way more complex 
+than we really wanted. CException was born.
+
+Why?
+====
+
+### It's ANSI C
+
+...and it beats passing error codes around.
+
+### You want something simple...
+
+CException throws a single id. You can define those ID's to be whatever you like. 
+You might even choose which type that number is for your project. But that's as far as it goes. We weren't interested 
+in passing objects or structs or strings... just simple error codes. Fast. Easy to Use. Easy to Understand.
+
+### Performance...
+
+CException can be configured for single tasking or multitasking. In single tasking, there is 
+very little overhead past the setjmp/longjmp calls (which are already fast). In multitasking, your only additional 
+overhead is the time it takes you to determine a unique task id (0 to num_tasks).
+
+How?
+====
+
+Code that is to be protected are wrapped in `Try { }` blocks. The code inside the Try block is _protected_, 
+meaning that if any Throws occur, program control is directly transferred to the start of the Catch block. 
+The Catch block immediately follows the Try block. It's ignored if no errors have occurred.
+
+A numerical exception ID is included with Throw, and is passed into the Catch block. This allows you to handle 
+errors differently or to report which error has occurred... or maybe it just makes debugging easier so you 
+know where the problem was Thrown.
+
+Throws can occur from anywhere inside the Try block, directly in the function you're testing or even within 
+function calls (nested as deeply as you like). There can be as many Throws as you like, just remember that 
+execution of the guts of your Try block ends as soon as the first Throw is triggered. Once you throw, you're 
+transferred to the Catch block. A silly example:
+
+```
+void SillyExampleWhichPrintsZeroThroughFive(void) {
+  volatile CEXCEPTION_T e;
+  int i;
+  while (i = 0; i < 6; i++) {
+    Try {
+      Throw(i);
+      //This spot is never reached
+    } 
+    Catch(e) {
+      printf(“%i “, e);
+    }
+  }
+}
+```
+
+Limitations
+===========
+
+This library was made to be as fast as possible, and provide basic exception handling. It is not a full-blown 
+exception library like C++. Because of this, there are a few limitations that should be observed in order to 
+successfully utilize this library:
+
+### Return & Goto
+
+Do not directly `return` from within a `Try` block, nor `goto` into or out of a `Try` block.
+The `Try` macro allocates some local memory and alters a global pointer. These are cleaned up at the 
+top of the `Catch` macro. Gotos and returns would bypass some of these steps, resulting in memory leaks 
+or unpredictable behavior.
+
+### Local Variables
+
+If (a) you change local (stack) variables within your `Try` block, and (b) wish to make use of the updated 
+values after an exception is thrown, those variables should be made `volatile`.
+
+Note that this is ONLY for locals and ONLY when you need access to them after a `Throw`.
+
+Compilers optimize (and thank goodness they do). There is no way to guarantee that the actual memory 
+location was updated and not just a register unless the variable is marked volatile.
+
+### Memory Management
+
+Memory which is `malloc`'d within a `Try` block is not automatically released when an error is thrown. This 
+will sometimes be desirable, and other times may not. It will be the responsibility of the code you put in 
+the `Catch` block to perform this kind of cleanup.
+
+There's just no easy way to track `malloc`'d memory, etc., without replacing or wrapping `malloc` 
+calls or something like that. This is a lightweight framework, so these options were not desirable.
+
+CException API
+==============
+
+### `Try { ... }`
+
+`Try` is a macro which starts a protected block. It MUST be followed by a pair of braces or a single 
+protected line (similar to an 'if'), enclosing the data that is to be protected. It MUST be followed by 
+a `Catch` block (don't worry, you'll get compiler errors to let you know if you mess any of that up).
+
+The `Try` block is your protected block. It contains your main program flow, where you can ignore errors 
+(other than a quick `Throw` call). You may nest multiple `Try` blocks if you want to handle errors at
+multiple levels, and you can even rethrow an error from within a nested `Catch`.
+
+### `Catch(e) { }`
+
+`Catch` is a macro which ends the `Try` block and starts the error handling block. The `Catch` block 
+is executed if and only if an exception was thrown while within the `Try` block. This error was thrown 
+by a `Throw` call somewhere within `Try` (or within a function called within `Try`, or a function called 
+by a function called within `Try`... you get the idea.).
+
+`Catch` receives a single id of type `CEXCEPTION_T` which you can ignore or use to handle the error in 
+some way. You may throw errors from within Catches, but they will be caught by a `Try` wrapping the `Catch`, 
+not the one immediately preceeding.
+
+### `Throw(e)`
+
+`Throw` is the method used to throw an error. `Throw`s should only occur from within a protected 
+(`Try`...`Catch`) block, though it may easily be nested many function calls deep without an impact 
+on performance or functionality. `Throw` takes a single argument, which is an exception id which will be 
+ passed to `Catch` as the reason for the error. If you wish to _re-throw_ an error, this can be done by
+calling `Throw(e)` with the error code you just caught. It _IS_ valid to throw from a `Catch` block.
+
+### `ExitTry()`
+
+`ExitTry` is a method used to immediately exit your current Try block but NOT treat this as an error. Don't 
+run the Catch. Just start executing from after the Catch as if nothing had happened.
+
+Configuration
+=============
+
+CException is a mostly portable library. It has one universal dependency, plus some macros which are required if 
+working in a multi-tasking environment.
+
+The standard C library setjmp must be available. Since this is part of the standard library, it's all good.
+
+If working in a multitasking environment, you need a stack frame for each task. Therefore, you must define 
+methods for obtaining an index into an array of frames and to get the overall number of id's are required. If 
+the OS supports a method to retrieve task ID's, and those tasks are number 0, 1, 2... you are in an ideal 
+situation. Otherwise, a more creative mapping function may be required. Note that this function is likely to 
+be called twice for each protected block and once during a throw. This is the only added overhead in the system.
+
+You have options for configuring the library, if the defaults aren't good enough for you. You can add defines 
+at the command prompt directly. You can always include a configuration file before including `CException.h`. 
+You can make sure `CEXCEPTION_USE_CONFIG_FILE` is defined, which will force make CException look for 
+`CExceptionConfig.h`, where you can define whatever you like. However you do it, you can override any or 
+all of the following:
+
+### `CEXCEPTION_T`
+
+Set this to the type you want your exception id's to be. Defaults to an 'unsigned int'.
+
+### `CEXCEPTION_NONE`
+
+Set this to a number which will never be an exception id in your system. Defaults to `0x5a5a5a5a`.
+
+### `CEXCEPTION_GET_ID`
+
+If in a multi-tasking environment, this should be set to be a call to the function described in #2 above. 
+It defaults to just return 0 all the time (good for single tasking environments, not so good otherwise).
+
+### `CEXCEPTION_NUM_ID`
+
+If in a multi-tasking environment, this should be set to the number of ID's required (usually the number 
+of tasks in the system). Defaults to 1 (good for single tasking environments or systems where you will only 
+use this from one task).
+
+### `CEXCEPTION_NO_CATCH_HANDLER (id)`
+
+This macro can be optionally specified. It allows you to specify code to be called when a Throw is made 
+outside of Try...Catch protection. Consider this the emergency fallback plan for when something has gone 
+terribly wrong.
+
+### And More!
+
+You may also want to include any header files which will commonly be needed by the rest of your application 
+where it uses exception handling here. For example, OS header files or exception codes would be useful.
+
+Finally, there are some hook macros which you can implement to inject your own target-specific code in 
+particular places. It is a rare instance where you will need these, but they are here if you need them:
+
+* `CEXCEPTION_HOOK_START_TRY` - called immediately before the Try block
+* `CEXCEPTION_HOOK_HAPPY_TRY` - called immediately after the Try block if no exception was thrown
+* `CEXCEPTION_HOOK_AFTER_TRY` - called immediately after the Try block OR before an exception is caught
+* `CEXCEPTION_HOOK_START_CATCH` - called immediately before the catch
+
+Testing
+=======
+
+If you want to validate that CException works with your tools or that it works with your custom 
+configuration, you may want to run the included test suite. This is the test suite (along with real 
+projects we've used it on) that we use to make sure that things actually work the way we claim.
+The test suite makes use of Ceedling, which uses the Unity Test Framework. It will require a native C compiler. 
+The example makefile and rakefile both use gcc. 

data/vendor/c_exception/docs/CException.md

@@ -0,0 +1,289 @@
+CException
+==========
+
+CException is a basic exception framework for C, suitable for use in
+embedded applications.  It provides an exception framework similar in
+use to C++, but with much less overhead.
+
+CException uses C standard library functions `setjmp` and `longjmp` to
+operate.  As long as the target system has these two functions defined,
+this library should be useable with very little configuration.  It
+even supports environments where multiple program flows are in use,
+such as real-time operating systems.
+
+There are about a gabillion exception frameworks using a similar
+setjmp/longjmp method out there... and there will probably be more
+in the future. Unfortunately, when we started our last embedded
+project, all those that existed either (a) did not support multiple
+tasks (therefore multiple stacks) or (b) were way more complex than
+we really wanted.  CException was born.
+
+*Why use CException?*
+
+0. It's ANSI C, and it beats passing error codes around.
+1. You want something simple... CException throws a single id. You can
+   define those ID's to be whatever you like. You might even choose which
+   type that number is for your project. But that's as far as it goes.
+   We weren't interested in passing objects or structs or strings...
+   just simple error codes.
+2. Performance... CException can be configured for single tasking or
+   multitasking. In single tasking, there is very little overhead past
+   the setjmp/longjmp calls (which are already fast). In multitasking,
+   your only additional overhead is the time it takes you to determine
+   a unique task id 0 - num_tasks.
+
+For the latest version, go to [ThrowTheSwitch.org](http://throwtheswitch.org)
+
+CONTENTS OF THIS DOCUMENT
+=========================
+
+* Usage
+* Limitations
+* API
+* Configuration
+* Testing
+* License
+
+
+Usage
+-----
+
+Code that is to be protected are wrapped in `Try { } Catch { }` blocks.
+The code directly following the Try call is "protected", meaning that
+if any Throws occur, program control is directly transferred to the
+start of the Catch block.
+
+A numerical exception ID is included with Throw, and is made accessible
+from the Catch block.
+
+Throws can occur from within function calls (nested as deeply as you
+like) or directly from within the function itself.
+
+Limitations
+-----------
+
+This library was made to be as fast as possible, and provide basic
+exception handling.  It is not a full-blown exception library.  Because
+of this, there are a few limitations that should be observed in order
+to successfully utilize this library:
+
+1. Do not directly "return" from within a `Try` block, nor `goto`
+   into or out of a `Try` block.
+
+   *Why?*
+
+   The `Try` macro allocates some local memory and alters a global
+   pointer.  These are cleaned up at the top of the `Catch` macro.
+   Gotos and returns would bypass some of these steps, resulting in
+   memory leaks or unpredictable behavior.
+
+
+2. If (a) you change local (stack) variables within your `Try` block,
+   AND (b) wish to make use of the updated values after an exception
+   is thrown, those variables should be made `volatile`. Note that this
+   is ONLY for locals and ONLY when you need access to them after a
+   `Throw`.
+
+   *Why?*
+
+   Compilers optimize.  There is no way to guarantee that the actual
+   memory location was updated and not just a register unless the
+   variable is marked volatile.
+
+   As an example, if we had the following code, the value `b` is 
+   very likely at risk. It is assigned to the value `3` inside the
+   `Try` block, but the compiler may or may not have written that 
+   variable to an actual memory location when the Throw happens. If 
+   it did, the `printf` will have a `3` for the second value. If not,
+   it will still have a `0`. Changing `b` to `volatile` would
+   guarantee it is the correct value.
+   
+   ```
+   void func(int *a)
+   {
+     // ...
+     int b = 0;
+     Try {
+       *a += 2;
+       b = *a;
+       Throw(MY_EX);
+     } Catch(e) {
+       // ...
+     }
+     printf("%d ?= %d", a, b);
+   }
+   void main()
+   {
+     int x = 1;
+     func(&x);
+     printf("%d", x);
+   }
+   ```
+   
+   With most compilers, the `*a` and `x` values are NOT at risk.
+   We're dereferencing the pointer, which usually will force 
+   memory interaction. Optimizing compilers DO optimize, though, 
+   and it IS possible that even these values may have been cached
+   and not written to the final memory location. In those instances,
+   they would both report `1`.
+   
+   If you have a lot of situations like this and a strong optimizing
+   compiler, it is best to reduce the optimization level when using
+   CException.
+
+3. Memory which is `malloc`'d or `new`'d is not automatically released
+   when an error is thrown.  This will sometimes be desirable, and
+   other times may not.  It will be the responsibility of the `Catch`
+   block to perform this kind of cleanup.
+
+   *Why?*
+
+   There's just no easy way to track `malloc`'d memory, etc., without
+   replacing or wrapping malloc calls or something like that.  This
+   is a light framework, so these options were not desirable.
+
+API
+---
+
+###Try
+
+`Try` is a macro which starts a protected block.  It MUST be followed by
+a pair of braces or a single protected line (similar to an 'if'),
+enclosing the data that is to be protected.  It **must** be followed by a
+`Catch` block (don't worry, you'll get compiler errors to let you know if
+you mess any of that up).
+
+
+###Catch(e)
+
+`Catch` is a macro which ends the `Try` block and starts the error handling
+block. The `Catch` block is called if and only if an exception was thrown
+while within the `Try` block.  This error was thrown by a `Throw` call
+somewhere within `Try` (or within a function called within `Try`, or a function
+called by a function called within `Try`, etc).
+
+The single parameter `e` is filled with the error code which was thrown.
+This can be used for reporting, conditional cleanup, etc. (or you can just
+ignore it if you really want... people ignore return codes all the time,
+right?).  `e` should be of type `EXCEPTION_T`
+
+
+###Throw(e)
+
+This is the method of throwing an error. A `Throw` should only occur from within a
+protected (`Try` ... `Catch`) block, though it may easily be nested many function
+calls deep without an impact on performance or functionality. `Throw` takes
+a single argument, which is an exception id which will be passed to `Catch`
+as the reason for the error.
+
+If you wish to rethrow an error, this can be done by calling `Throw(e)` with
+the error code you just caught.  It **is** valid to throw from a catch block.
+
+
+###ExitTry()
+
+On rare occasion, you might want to immediately exit your current `Try` block
+but **not** treat this as an error. Don't run the `Catch`. Just start executing
+from after the `Catch` as if nothing had happened... That's what `ExitTry` is
+for.
+
+
+CONFIGURATION
+-------------
+
+CException is a mostly portable library.  It has one universal
+dependency, and some macros which are required if working in a
+multi-tasking environment.
+
+1. The standard C library setjmp must be available.  Since this is part
+   of the standard library, chances are good that you'll be fine.
+
+2. If working in a multitasking environment, methods for obtaining an
+   index into an array of frames and to get the overall number of
+   id's are required.  If the OS supports a method to retrieve Task
+   ID's, and those Tasks are number 0, 1, 2... you are in an ideal
+   situation.  Otherwise, a more creative mapping function may be
+   required.  Note that this function is likely to be called twice
+   for each protected block and once during a throw.  This is the
+   only overhead in the system.
+
+
+Exception.h
+-----------
+
+By convention, most projects include `Exception.h` which defines any
+further requirements, then calls `CException.h` to do the gruntwork.  All
+of these are optional.  You could directly include `CException.h` if
+you wanted and just use the defaults provided.
+
+* `CEXCEPTION_T`
+  * Set this to the type you want your exception id's to be.  Defaults to 'unsigned int'.
+
+* `CEXCEPTION_NONE`
+  * Set this to a number which will never be an exception id in your system.  Defaults to `0x5a5a5a5a`.
+
+* `CEXCEPTION_GET_ID`
+  * If in a multi-tasking environment, this should be
+    set to be a call to the function described in #2 above.
+    Defaults to just return `0` all the time (good for
+    single tasking environments)
+
+* `CEXCEPTION_NUM_ID`
+  * If in a multi-tasking environment, this should be set
+    to the number of ID's required (usually the number of
+    tasks in the system).  Defaults to `1` (for single
+    tasking environments).
+
+* `CEXCEPTION_NO_CATCH_HANDLER(id)`
+  * This macro can be optionally specified.
+    It allows you to specify code to be called when a Throw
+    is made outside of `Try` ... `Catch` protection.  Consider
+    this the emergency fallback plan for when something has
+    gone terribly wrong.
+
+You may also want to include any header files which will commonly be
+needed by the rest of your application where it uses exception handling
+here.  For example, OS header files or exception codes would be useful.
+
+
+Finally, there are some hook macros which you can implement to inject
+your own target-specific code in particular places. It is a rare instance
+where you will need these, but they are here if you need them:
+
+
+* `CEXCEPTION_HOOK_START_TRY`
+  * called immediately before the Try block
+
+* `CEXCEPTION_HOOK_HAPPY_TRY`
+  * called immediately after the Try block if no exception was thrown
+
+* `CEXCEPTION_HOOK_AFTER_TRY`
+  * called immediately after the Try block OR before an exception is caught
+
+* `CEXCEPTION_HOOK_START_CATCH`
+  * called immediately before the catch
+
+
+TESTING
+-------
+
+If you want to validate that CException works with your tools or that
+it works with your custom configuration, you may want to run the test
+suite.
+
+
+The test suite included makes use of the `Unity` Test Framework.  It will
+require a native C compiler. The example makefile uses MinGW's gcc.
+Modify the makefile to include the proper paths to tools, then run `make`
+to compile and run the test application.
+
+* `C_COMPILER`
+  * The C compiler to use to perform the tests
+
+* `C_LIBS`
+  * The path to the C libraries (including setjmp)
+
+* `UNITY_DIR`
+  * The path to the Unity framework (required to run tests)
+    (get it at [ThrowTheSwitch.org](http://throwtheswitch.org))
+

data/vendor/c_exception/docs/CODE_OF_CONDUCT.md

@@ -0,0 +1,138 @@
+
+# ThrowTheSwitch.org Code of Conduct
+
+Thank you for participating in a ThrowTheSwitch.org community project! We want
+this to continue to be a warm and inviting place for everyone to share ideas
+and get help. To accomplish this goal, we've developed this Code of Conduct.
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+hello@thingamabyte.com.
+
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations