From b5630b74ce1be3128f27a8c32ca6afe3772d7174 Mon Sep 17 00:00:00 2001 From: bunnie Date: Sat, 19 Jun 2021 01:36:35 +0800 Subject: [PATCH] update documentation --- services/gam/README.md | 55 +++++++++++++++++++++++++++++------ services/xous-names/README.md | 31 +++++++++----------- 2 files changed, 60 insertions(+), 26 deletions(-) diff --git a/services/gam/README.md b/services/gam/README.md index 59cabac6d..903add1b7 100644 --- a/services/gam/README.md +++ b/services/gam/README.md @@ -4,10 +4,10 @@ The GAM provides abstract UI primitives to other modules. The goal is to have this module work in close conjunction with the `graphics-server`, and all other modules would route abstract UI -requests through this module. +requests through this module. ## Structure -At a high level, you can think of the GAM as a firewall around the `graphics-server`. +At a high level, you can think of the GAM as a firewall around the `graphics-server`. The `graphics-server` has no concept of what pixel belongs where; it's happy to mutate a pixel that is anywhere within the physical hardware framebuffer. @@ -28,20 +28,20 @@ to the GAM to not share secure GUIDs with insecure processes. Thus the security of a `Canvas` rests in the difficulty of guessing the 128-bit GUID, and also in the system not leaking GUIDs. -Every GAM drawing object includes the GUID of the `Canvas` to which it should be drawn. +Every GAM drawing object includes the GUID of the `Canvas` to which it should be drawn. Upon receiving a draw request, it validates that the GUID exists, and applies any other relevant rules (for example, a higher security process can use the GAM to prohibit all drawing of lower security processes by marking their -`Canvas` as not drawable). +`Canvas` as not drawable). All GAM drawing objects specify pixel offsets from a `(0,0)` top-left coordinate system. The GAM then handles translating these offsets from a virtual `(0,0)` -Canvas offset to a physical region of a screen through the `clip_rect` +Canvas offset to a physical region of a screen through the `clip_rect` record within the `Canvas`. The coordinate space of the `clip_rect` is fixed to the screen's coordinates, that is, `(0,0)` in the top left, X increasing to the right, Y increasing down. -A `Canvas` also stores a `pan_offset`. The `pan_offset` is added to every +A `Canvas` also stores a `pan_offset`. The `pan_offset` is added to every coordinate inside the objects that refer to a `Canvas` and then the result is clipped with `clip_rect`; this allows for easy implementation of panning and scrolling. (Note: this feature is largely untested as of March 2021) @@ -81,6 +81,18 @@ attribute and can handle content stacking; but between trust domains, it's both a trust and complexity issue to allow for simultaneous stacking of trust domains with live, full-content update of the underlying layers. +### Defacing +Defacing is a policy implemented by the GAM which ensures that when trusted +objects are overlaid on top of less trusted objects, the less trusted objects +cannot be mistaken for a trusted object. This is to assist users with avoiding +phishing attacks through Ux elements presented on less trusted canvases that +look like trusted objects. + +Defacing basically takes a bit of entropy from the TRNG and renders it in +the form of random lines drawn across the defaced area. This allows users +to still read the text within the defaced area, but makes it more difficult +to mistake this area for something trusted. + ### TextView A `TextView` object is a heavy data structure that contains both a `xous::String` @@ -98,7 +110,7 @@ are then mutably lent to the GAM using an `rkyv` lend wrapper; the calling thread then blocks until the GAM completes the rendering operation. For layouts that need to adjust in height based on variable-length text strings, -the calling application can use the `bounds_hint`/`TextBounds` to help manage this. +the calling application can use the `bounds_hint`/`TextBounds` to help manage this. The bounds of a `TextView` can either be a fixed-sized rectangle, or a box that grows up and out from a point plus a width. So, for example, a `TextView` could have an anchor in the lower-right hand corner, plus a maximum width, and the height of the @@ -106,7 +118,7 @@ box will be computed based as the text is rendered. The height of text can't be known a-priori, because for example, emoji glyphs and hanzi characters will have a different height than latin characters. A `dry_run` option is also available for a `TextView` so one can simulate the rendering to determine the height -without paying the compuational price. +without paying the compuational price. One can think of a `TextView` as a text bubble, that can have rounded or square corners, and its content string can be rendered with a selection of options @@ -119,7 +131,32 @@ Thus, a typical "chat-style" app where text bubbles show a history of the chat going from the most recent at the bottom of the screen to the oldest at the top, would start by rendering variable-height text bubbles on the bottom, getting the returned value of the rendered height, and setting the height of the next bubble -on top for rendering, and then rendering that. +on top for rendering, and then rendering that. `TextView` can both be directly rendered to a `Canvas`, or managed by secondary object such as a `Menu` or `List` to compose other UI elements. + +### Menu + +A `Menu` object encodes the state of a graphical menu. It's meant to be paired +with a dedicated thread that serves as an event loop. You can look at the +main menu implementation inside the GAM for ane example of how this is done. +Most event loops will look about the same; it's not pulled into the object +itself because there isn't a `safe` way yet in Xous to pass an object into +a thread that the object spawns. + +Building a menu is fairly straight forward: + +- create the `Menu` object by calling `Menu::new(name: &str)`. This will automatically +register an empty `Menu` layout as a Ux element inside the GAM. +- add menu items by calling `.add_item()` on your `Menu` object +- run the event loop and pass events back to the `Menu` object for processing + +Each `MenuItem` has the following fields: +- `name`: the text shown for the item +- `action_conn`: a xous CID to the target server that receives the action of the menu item +- `action_opcode`: the local opcode of the target server. Opcodes are private to the server, +so menu-actionable opcodes need to be revealed with a helper method on the target server. +- `action_payload`: an enum that encodes the payload of the Opcode. For now, only Scalar payloads are implemented, +but the framework is there for some kind of a Frankenstein static-buffer to be passed on to targets +- `close_on_select`: a boolean which indicates if the menu should automatically close once the item is selected diff --git a/services/xous-names/README.md b/services/xous-names/README.md index 8c52e3fe3..addb20b16 100644 --- a/services/xous-names/README.md +++ b/services/xous-names/README.md @@ -17,7 +17,12 @@ string into the SID except by resolving it with `xous-name-server`. On boot, a trusted set of processes are started which form the operating system. These must all claim names in the name space before any further processes are started, to prevent later processes from -claiming their names. +claiming their names. Servers can also optionally limit the total +number of connections allowed, which effectively makes them unreachable +by less trusted code that is run after the core trusted set of processes +have started up. The `trusted_init_done()` libary call on the name +server will return true if all the servers that have a connection +limit have fully populated all of their connections. The exception to random SIDs are the `xous-name-server`, `xous-log-server ` (note the trailing space), and `ticktimer-server`. @@ -36,10 +41,10 @@ A new process that intends to receive messages uses the `register_name` convenie function in the `xous-names/src/lib.rs` file, with the following procedure. 1. It calls `register_name` with a preferred ASCII name string, -limited to 64 characters. The convenience function wraps this in an `rkyv` -object and passes it as mutable-borrowed memory to the name server. +limited to 64 characters. It also specifies how many connections the server +will allow. `None` on the specifier means no limit. -2. `xous-name-server` returns the borrowed memory to the server, where the +1. `xous-name-server` returns the borrowed memory to the server, where the buffer has been replaced with a response field. In the case that the registration is affirmed, the SID field in `Registration` contains the assigned SID of calling process. In the case that the name is determined to be invalid @@ -117,19 +122,11 @@ does not "leak" memory. The current implementation is a hash map that matches randomly generated names with a list of names each server selects for itself. Currently, any -request to lookup and connect to a server will succeed, but the hooks +request to lookup and connect to a server will succeed up to the limit +of connections (if any) specified by a server, but the hooks are there to enforce permissions and deny connections, and/or request authentication for connection. -Most server names are crate-local, and are bound through library functions -called during the creation of server access objects. However, some names -of servers which may not be statically bound are stored in `xous-rs/names.rs`. -The intention is that this is a list of "public" services that should -be well-known and generally all processes are allowed to connect to -these. - -Later on, we may implement servers that handle sensitive information; -and also, user processes can start private servers that should be isolated -from others, and thus have restricted permissions. These names may not -appear in this list, or they may appear but also we'll have annotations -for permissions and security. +Server names are crate-local, and are bound through library functions +called during the creation of server access objects. In other words, +there is no global name space for servers.