diff --git a/doc/nanos-getting-started.md b/doc/nanos-getting-started.md index 276ad82..d449975 100644 --- a/doc/nanos-getting-started.md +++ b/doc/nanos-getting-started.md @@ -11,6 +11,9 @@ apps onto the Nano S, and basic communication between Nano S and a python interface on the computer. Located at: [LedgerHQ/blue-loader-python](https://github.com/LedgerHQ/blue-loader-python). +* The various python scripts are documented reasonably well at: +[Script Reference](https://ledger.readthedocs.io/projects/blue-loader-python/en/0.1.15/script_reference.html) + **Sample Apps:** These provide examples of basic operations on the Nano S device. Located at: [LedgerHQ/blue-sample-apps](https://github.com/LedgerHQ/blue-sample-apps). @@ -27,3 +30,61 @@ A tutorial for building, installing, and running the Hello World sample app is located here: (part of the docs mentioned above) [Getting started](http://ledger.readthedocs.io/en/latest/nanos/setup.html). It may be slightly out of date. + +## Notes and tidbits + +### Hardware memory and executable formats + +Some basic info about the Nano S execution environment memory specs and +layout can be divined by looking at the linker scripts `script.ld` and +`script.ux.ld` in the SDK at +[LedgerHQ/nanos-secure-sdk](https://github.com/LedgerHQ/nanos-secure-sdk). + +Note, what follows here comes from my *very fuzzy* understanding of the +linking and loading process and of the BOLOS architecture, and thus is +conjectural and could be very wrong, but... from these scripts it can be +devined, e.g., that UX code (I think this is BOLOS-provided library code +with different security priveledges that the app developer doesn't write, +but this is a pure guess) is loaded into a 2 kB window with a 768 byte +(wow!) stack size; and that application code is loaded into a 4 kB window +with another 768 byte stack. Obviously, this is an *extrememly* tight +execution envirement. + +Some wiggle-room is provided by the fact that there is also a read-only (to +the application) non-volatile flash ram window of 400 kB. According to docs +at +[(Ledger docs)](http://ledger.readthedocs.io/en/latest/userspace/memory.html), +the executable code and const-declared variables are stored here, so that +the limited available volatile ram is not used up for this. And also, a +mechanism is provided to carve off *some* of the ro nvram as rw so that apps +can keep some persistant storage. + +I actally have no idea how to read these linker scripts, so my conclusions +here are "as best I understand them." There is some documentation on linker +scripts here: +[LD Scripts](https://sourceware.org/binutils/docs/ld/Scripts.html). + +Another interesting oddity: the link script places "RAM-initialized +variables" into a memory region titled DISCARD and apparently mapped to a +non-existent region of address-space on the Nano. This would have the +effect of just vaporizing ram-initialized variables altogether, I would +(naively??) think. It's weird, but I do think this is exactly what it does, +because the BOLOS documentation includes this warning: + +> Initializers of global non-const variables (including NVRAM variables) are +> ignored. As such, this data must be initialized by application code. + +So global data cannot have initializers. Got it. Couldn't tell you why, but +got it. :thumbsup:. + +Another point: BOLOS code, being embedded, makes frequent use of the +**volatile** keyword. For some reminders of when/what/why `volatile` is +used, here are two links that came up in my google search: +* [How to Use C's volatile Keyword](https://barrgroup.com/Embedded-Systems/How-To/C-Volatile-Keyword) +* [Nine ways to break your systems code using volatile](https://blog.regehr.org/archives/28) + +Ah, one reason for such frequent use of `volatile` is the TRY/CATCH macros +evidently can confuse the optimizer in some way. For this reason, it is +recommended to declare variables that may be modified inside +try/catch/finally contexts as `volatile`. Referenced in the docs here: +[Error Handling](http://ledger.readthedocs.io/en/latest/userspace/troubleshooting.html#error-handling).