update documentation

This commit is contained in:
bunnie 2021-06-19 01:36:35 +08:00
parent 2b5ba61552
commit b5630b74ce
2 changed files with 60 additions and 26 deletions

View file

@ -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 a trust and complexity issue to allow for simultaneous stacking of trust domains
with live, full-content update of the underlying layers. 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 ### TextView
A `TextView` object is a heavy data structure that contains both a `xous::String` A `TextView` object is a heavy data structure that contains both a `xous::String`
@ -123,3 +135,28 @@ on top for rendering, and then rendering that.
`TextView` can both be directly rendered to a `Canvas`, or managed by secondary `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. 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

View file

@ -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 On boot, a trusted set of processes are started which form the
operating system. These must all claim names in the name space before operating system. These must all claim names in the name space before
any further processes are started, to prevent later processes from 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`, The exception to random SIDs are the `xous-name-server`,
`xous-log-server ` (note the trailing space), and `ticktimer-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. function in the `xous-names/src/lib.rs` file, with the following procedure.
1. It calls `register_name` with a preferred ASCII name string, 1. It calls `register_name` with a preferred ASCII name string,
limited to 64 characters. The convenience function wraps this in an `rkyv` limited to 64 characters. It also specifies how many connections the server
object and passes it as mutable-borrowed memory to the name 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 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 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 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 The current implementation is a hash map that matches randomly generated
names with a list of names each server selects for itself. Currently, any 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 are there to enforce permissions and deny connections, and/or request
authentication for connection. authentication for connection.
Most server names are crate-local, and are bound through library functions Server names are crate-local, and are bound through library functions
called during the creation of server access objects. However, some names called during the creation of server access objects. In other words,
of servers which may not be statically bound are stored in `xous-rs/names.rs`. there is no global name space for servers.
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.