44 update readme and nixsh

CONTRIBUTING.md

@@ -1,44 +1,91 @@
-# Contributing
+The Exciting World of Ledger C
+------------------------------
 
-## Hacking with [Nix](https://nixos.org/nix/)
+Knowing C will help you in this adventure. But not as much as it should. There are some fun twists when it comes to Ledger C. Explore them below. Memorize them. There *will* be a quiz...
 
-The `nix/` folder contains helper scripts for working with the ledger via Nix.
+### Exceptions
 
-### Installing
-`nix/install.sh` will install both the wallet and baking apps. Use
-`nix/install.sh s baking` to install just the baking app or
-`nix/install.sh s wallet` to install just the wallet.
+C doesn't have them. So you don't have to think about bracketing, exception safety, RAII, try/catch, all that.
 
-### Developing
-Use `nix/env.sh <s or x>` to enter a shell where you can run `make` and it will just work. You can also pass a command instead, e.g. `nix/env.sh s --run "make clean SHELL=bash"`. All `make` commands should be prefixed with `SHELL=bash`. Check the Makefile to see what options exist
+Well not on the Ledger. You have exceptions! Which means you also have out-of-band code paths, and you now have to worry about exception safety.
 
-For development, use `nix/watch.sh s make APP=<tezos_baking|tezos_wallet>` to incrementally build on every change. Be sure to `nix/env.sh s --run "make clean SHELL=bash"` if you start watching a different `APP`.
+You can `THROW` a `uint16_t` like this `THROW(0x9000)`.
 
-#### Debugging
-Set `DEBUG=1` in the `Makefile` to so that the user-defined `parse_error()` macro provides a line-number. For `printf` style debugging see [Ledger's official instructions](https://ledger.readthedocs.io/en/latest/userspace/debugging.html)
+Handling exceptions looks like this.
 
-### Building
-To do a full Nix build run `nix/build.sh`. You can pass `nix-build` arguments to this to build specific attributes, e.g. `nix/build.sh -A nano.s.wallet`.
+```c
+volatile int something = 0;
+BEGIN_TRY {
+    TRY {
+        //do something;
+    }
+    CATCH(EXC_PARSE_ERROR) {
+        //do something on parse error
+    }
+    CATCH_OTHER(e) {
+        THROW(e);
+    }
+    FINALLY { }
+}
+END_TRY;
+```
 
-### Using tezos-client
-Set environment variable `TEZOS_LOG="client.signer.ledger -> debug"` when running tezos-client to get the byte-level IO being sent
-directly to/from the ledger
+Exceptions that make it all the way to the top of the application are caught and returned as status codes from the APDU.
 
+#### Gotchas
 
-### Editor Integration
+  1. If a variable will be accessed both outside and inside the `BEGIN_TRY`/`END_TRY` block it must be `volatile`. The compiler doesn't expect these shenanigans and will optimize incorrectly if you don't.
+  2. Do not `return` in the `TRY` block. It will cause the Ledger to crash. Instead use a `volatile` variable to capture the result you want to `return` at the end.
+  3. Don't try to leave out blocks like `CATCH_OTHER(e)` and `FINALLY`. I don't know if that will work right and it's not worth the risk.
 
-#### Visual Studio Code
+#### Implications
 
-  1. Install `llvm-vs-code-extensions.vscode-clangd` extension.
-  2. Run `nix/setup-vscode.sh` to create local configuration. Note that these files are non-relocatable so you need to rerun this if you move the directory.
-  3. Restart Visual Studio Code.
+  1. If you have some global state and an exception is thrown then, unless you do something about it, that global state will remain. That might be a *very bad thing*. As long as you use globals our way (see Globals Our Way) you should be safe.
 
-### Releasing
 
-`nix/build.sh -A nano.s.release.all`
+### Globals Our Way
 
-`nix/build.sh -A nano.x.release.all`
+`static const` globals are fine. `static` non-const are not fine for two reasons:
 
-### Notes on testing
+  1. If you try to initialize them (which you would want to do!) then the app will crash. For example `static int my_bool = 3;` crashes whenever you try to read or write `my_bool`...
+  2. Instead of getting initialized to 0 like the C standard says, they are initialized to `0xA5`. Yes this can cause the compiler to incorrectly optimize your code.
 
-See `test/README.md`
+So just don't use `static` non-const globals. Instead we have `globals.h` which defines a large `struct` wher you can put your globals. At the beginning of the application we `memset(&global, 0, sizeof(global))` to clear it all to zeros.
+
+Anything inside of `global.apdu` will get cleared when an exception gets to the top of the app (see Exceptions). To benefit from this behavior you should never return an error code via the in-band way of sending bytes back. All errors should be sent via `THROW`.
+
+### Relocation
+
+When we said `static const` globals were fine, we meant that they were possible. There is
+a major gotcha, however: if you initialize a `static const` value with a pointer to another
+`static` or `static const` value, the pointers might be incorrect and require relocation.
+
+For example:
+
+```
+static const char important_string[] = "Important!";
+static const char **important_string_ptrs = { important_string, NULL };
+const char *str1 = important_string_ptrs[0];
+const char *str2 = important_string;
+```
+
+`str` will now have the wrong value. `str2` will not. The reason `str1`
+has the wrong value is that the linker gets confused with a reference
+from one `static const` variable to another `static` variable on this
+platform. To resolve, you can use the `PIC` macro, which will fix broken
+pointers but never break a good pointer. Because of this, you can use
+it liberally and not have to worry about breaking anything:
+
+```
+static const char important_string[] = "Important!";
+static const char **important_string_ptrs = { important_string, NULL };
+const char *str1 = PIC(important_string_ptrs[0]); // necessary use of PIC
+const char *str2 = PIC(important_string); // unnecessary but harmless use of PIC
+```
+
+Many of the UI functions call `PIC` for you, so just because a UI function
+accepts a data structure, doesn't mean that data structure is valid.
+
+### Dynamic Allocation
+
+Nope. Don't even try. No `malloc`/`calloc`/`free`. Use globals (see Globals).