From a4e054ce16d41b1bb1254b15848b46aa04099a86 Mon Sep 17 00:00:00 2001 From: Jaeden Amero Date: Tue, 14 Feb 2017 14:51:06 +0000 Subject: [PATCH] docs: Add initial uVisor Onboarding Guide --- docs/core/ONBOARD.md | 103 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 103 insertions(+) create mode 100644 docs/core/ONBOARD.md diff --git a/docs/core/ONBOARD.md b/docs/core/ONBOARD.md new file mode 100644 index 00000000..1a9437af --- /dev/null +++ b/docs/core/ONBOARD.md @@ -0,0 +1,103 @@ +# uVisor Onboarding Guide + +Welcome to the uVisor team, where the fun never ends! You've discovered our +wonderful onboarding guide, designed to get you on board and making meaningful +contributions as quickly as is reasonable. + +The uVisor Onboarding Guide is broken into multiple segments, of which there is +only one segment currently. + + - [uVisor Design Rules](#uvisor-design-rules) + +## uVisor Design Rules + +These rules were learned the hard way: through detailed technical oversight +working on uVisor. Often, a design would arise from any of our team members +that'd solve a problem in a nice way, except that it'd break some unwritten +rule the rest of the team kept stored in their heads. The design would be +rejected, and the team member dejected. Sometimes, the team member would have +to do as many as five design iterations until design approval. If only the team +member had known the unwritten rules when they set out on their initial design! +After all these design iterations, the resulting design truly was better, but +much time could have been saved had the design rules been written down. + +The written uVisor Design Rules are designed to help you, the potential +contributor, come up with workable designs quicker, by writing down those +previously unwritten design rules. This should also help save the rest of the +team's time as well, as less "architecture review" technical oversight meetings +should be required. This also makes design work possible from contributors +outside the core uVisor team employed by ARM. + +Any new feature, design, or redesign will have to follow these rules. The +business priorities of the day will also impose additional constraints on +designs, but we make no attempt to document those volatile constraints here. +The rules we focus on here will remain relatively static over the course of +uVisor development. + +These are clumped together in rough categories, in no particular order. + +### Portability + +Keep uVisor independent from other software components as much as possible. +This maximizes uVisor's resiliency and usefulness. During the transition +between mbed OS 3 and mbed OS 5, uVisor core didn't have to change much at all; +most changes came from integrating uVisor with an RTOS on ARMv7-M. + + - uVisor core should not contain OS-specific code. + - uVisor APIs should not match one-to-one with an OS API + - It will end up being a lot of work to port the uVisor API to a different + OS where the API doesn't match as well. We don't want to write code to + abstract differences between operating systems. + - uVisor core should only contain CPU-core- or MPU-specific code. + - uVisor lib can contain OS-specific code. + - Two different operating systems may use two different uVisor lib binaries. + + +### Usability + +Make uVisor APIs easy to use. + + - Where possible, perform operations on behalf of the user that the user might + forget to do. Perform higher-level operations all together as a whole, even + if that makes the API less orthogonal. For instance, don't make a user obtain + a handle in one function call and then open a handle in another function + call, obtain and open the handle for the user all in one go. + - Make APIs explicit and flat. Don't require the user to have knowledge of + layers of APIs, or require them to do things in certain orders. For example, + make the user provide a list of functions as RPC targets when they want to + wait for incoming RPC, as opposed to making the user provide the list up + front in exchange for a cookie they use later on when waiting. This makes + the information relevant to the API call available as close to the point of + use as possible. + + +### Security + + - Don't trust user provided values. Check and sanitize everything. + - Use the uVisor threat model to decide what inputs you can trust. For + example, values provided from flash can be trusted (perhaps until we have + modular firmware update). Values provided from box-private SRAM can be + trusted as having come from the box that owns that SRAM, but still must be + sanitized and validated should those values be used by another box or uVisor + itself (even indirectly). + + +### Performance + + - Minimize the number of transitions between user mode and uVisor. On ARMv7-M, + we use SVCs to transition to uVisor. SVCs come with a relatively high cost. + On ARMv8-M, we use SG to transition to uVisor (or uVisor Secure Device + Services [SDS]). SG also has to stack a lot of state. + + +### Updating the Design Rules + +If you find your solutions getting rejected due to some "unwritten rule" you +wished you would have known about before designing and implementing your +solution, please document that rule here. Be sure the rational of the new rule +is well understood and communicated by your addition. + +Also, these rules aren't set in stone; these aren't permanent, never to be +changed rules. There has been an attempt to clearly document the rationale +behind each rule so that we have the institutional memory sufficient to change +the rules where and when necessary.