mirror of
https://github.com/saymrwulf/xous-core.git
synced 2026-11-17 08:40:52 +00:00
update documentation
This commit is contained in:
parent
2b5ba61552
commit
b5630b74ce
2 changed files with 60 additions and 26 deletions
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in a new issue