github/sparrow-kata-full
1
0
Fork 0
mirror of https://github.com/AmbiML/sparrow-kata-full.git synced 2025-04-27 10:31:31 +00:00
Code Issues Projects Releases Wiki Activity

Merge "docs: Add in an overview of component construction."

Browse Source 
GitOrigin-RevId: a44fb57b60906de7d2549082e2de980f83fd85bb
This commit is contained in:
June Tate-Gans 2022-08-16 16:24:38 +00:00 committed by Sam Leffler
parent 0b528c2a59
commit f75b87d6b4
1 changed files with 80 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

80
docs/Component_Model.md Normal file
View File

@ -0,0 +1,80 @@
# KataOS System Component Model
This document lays out how we expect most components to be constructed in the
KataOS / CAmkES world. Note that we say "most" here, because not everything can
be so dogmatic.
In general, most of our components are divided into three crates: interface,
component, and manager. These crates each provide slightly different interfaces
into the C bindings that are constructed by the build system.
Typically, the source tree is organized like this:
```
system/
├ components/
│ ├ SecurityCoordinator/
│ │ ├ Cargo.toml
│ │ ├ SecurityCoordinator.camkes
│ │ ├ kata-security-component/
│ │ ├ kata-security-coordinator/
│ │ └ kata-security-interface/
│ ┆
│
├ interfaces/
│ ├ SecurityCoordinatorInterface.camkes
│ ┆
│
└ system.camkes
```
`system.camkes` is the toplevel CAmkES Assembly, that defines which components
exist in the entire system, and which components speak to which other
components.
The CAmkES interfaces for each component are defined in the `interfaces/`
directory, named after its specific component
(`SecurityCoordinatorInterface.camkes` for this particular instance). These
simply define the interface of verbs other components can call out to, and helps
to define the client-side C interface for the component.
The crates that make up the code for each component, however, exist in the
`components/` directory, named after their component. Typically this is a
crate-of-crates configuration, and includes another camkes file defining the
implementation of the component, and thus defining the server-side C interface.
## Interface
The interface crate defines the native Rust client APIs for a given component.
This helps to isolate clients from the underlying C and IPC mechanics,
effectively creating a mirror of the CAmkES interface in Rust. This is due to
the fact that CAmkES does not (at the moment -- we'll address that later) create
Rust source code from its assembly descriptions.
In CAmkES, you explicitly define which components a component will speak to, and
CAmkES generates stub C bindings for you that then cross the seL4 IPC boundary
(as defined in the CAmkES interface description in the interface directory).
Note that the RPC connections are not visible to the client or server, and the
interface method name defines the C function that an implementation must use.
The top-level functions defined here simply wrap the CAmkES stubs to call across
to the component, effectively creating a client-side interface, and wrapping up
the unsafe entry points.
Note that this wrapping of unsafe entry points into safe Rust calls does not
mean we've swept the tree for unsafe issues! We hope to investigate this in the
future.
## Component
The component crate defines the C to Rust interconnect for the server-side of
the component, or rather, it's implementation.
Inside this crate is a set of top-level functions, named from their CAmkES
IDL specifications.
## Manager
This crate contains the actual full Rust implementation of the component, and
typically includes the impl for the trait defined in the Component crate, though
this varies significantly.