From f75b87d6b49d3e4cfea7b893a9c92c274f3b3e83 Mon Sep 17 00:00:00 2001
From: June Tate-Gans <jtgans@google.com>
Date: Tue, 16 Aug 2022 16:24:38 +0000
Subject: [PATCH] Merge "docs: Add in an overview of component construction."

GitOrigin-RevId: a44fb57b60906de7d2549082e2de980f83fd85bb
---
 docs/Component_Model.md | 80 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 80 insertions(+)
 create mode 100644 docs/Component_Model.md

diff --git a/docs/Component_Model.md b/docs/Component_Model.md
new file mode 100644
index 0000000..2ef05cc
--- /dev/null
+++ b/docs/Component_Model.md
@@ -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.