Documentation (#263)

* documentation: add patchelf dependency to README.md

* documentation: fix 404 when linking to `INIT_COMPARTMENT` macro

* documentation: update usage of `IA2_COMPARTMENT`, which replaced `INIT_COMPARTMENT`

* fix documentation for assigning a protection key

Co-authored-by: Stephen Crane <[email protected]>

---------

Co-authored-by: Stephen Crane <[email protected]>

README.md

@@ -11,7 +11,7 @@ Ubuntu 20.04 is used for testing. Other Linux distributions may or may not work.
 ```
 sudo apt install -y libusb-1.0-0-dev libclang-dev llvm-dev \
             ninja-build zlib1g-dev python3-pip cmake \
-            libavformat-dev libavutil-dev pcregrep
+            libavformat-dev libavutil-dev pcregrep patchelf
 pip install lit
 rustup install nightly
 ```
@@ -41,9 +41,16 @@ ninja check-ia2
 
 ### Defining compartments
 
-First invoke the [`INIT_RUNTIME`](https://github.com/immunant/IA2-Phase2/blob/main/include/ia2.h) macro once in any binary or shared library to define the number of protection keys that need to be allocated. The argument passed to `INIT_RUNTIME` must be a number between 1 and 15. Then the [`INIT_COMPARTMENT`](https://github.com/immunant/IA2-Phase2/blob/main/include/ia2.h) macro is used to define trusted compartments at the shared object level. This can be the main executable ELF or any dynamically-linked shared libraries. Memory belonging to a trusted compartment is assigned one of the [15 protection keys](https://man7.org/linux/man-pages/man7/pkeys.7.html) and can only be accessed by the shared object itself. Objects that don't explicitly define a compartment are treated as untrusted by default.
+First invoke the [`INIT_RUNTIME`](https://github.com/immunant/IA2-Phase2/blob/5cdb743d3a42e8df8e4d8cf61fb3551656001c73/libia2/include/ia2.h#L204) macro once in any binary or shared library to define the number of protection keys that need to be allocated. The argument passed to `INIT_RUNTIME` must be a number between 1 and 15. Then the [`IA2_COMPARTMENT`](https://github.com/immunant/IA2-Phase2/blob/4a3a0c8d2a2b1881e0e41c89db070db3da187f9e/libia2/include/ia2_compartment_init.inc#L3) `#define` is used to define trusted compartments at the shared object level. This can be the main executable ELF or any dynamically-linked shared libraries. Memory belonging to a trusted compartment is assigned one of the [15 protection keys](https://man7.org/linux/man-pages/man7/pkeys.7.html) and can only be accessed by the shared object itself. Objects that don't explicitly define a compartment are treated as untrusted by default.
 
-To assign a protection key to a trusted compartment insert `INIT_COMPARTMENT(n)` with an argument between 1-15 specifying the index of the protection key. This argument must differ from the other trusted compartments. Trusted compartments must also be aligned and padded properly by using the `padding.ld` script in `libia2/`. In CMake this is done automatically for executables built with `define_test` while libraries built with `define_shared_lib` must add `LINK_OPTS "-Wl,-T${libia2_BINARY_DIR}/padding.ld"`. To use in manual builds just include `-Wl,-T/path/to/padding.ld` in the final compilation step. Manual builds also require disabling lazy binding with `-Wl,-z,now`.
+To assign a protection key to a trusted compartment, insert `#define IA2_COMPARTMENT n` with an argument between 1-15 specifying the index of the protection key, and include `ia2_compartment_init.inc`:
+
+```c
+#define IA2_COMPARTMENT 1
+#include <ia2_compartment_init.inc>
+```
+
+This argument must differ from the other trusted compartments. Trusted compartments must also be aligned and padded properly by using the `padding.ld` script in `libia2/`. In CMake this is done automatically for executables built with `define_test` while libraries built with `define_shared_lib` must add `LINK_OPTS "-Wl,-T${libia2_BINARY_DIR}/padding.ld"`. To use in manual builds just include `-Wl,-T/path/to/padding.ld` in the final compilation step. Manual builds also require disabling lazy binding with `-Wl,-z,now`.
 
 ### Wrapping calls
 
@@ -67,7 +74,7 @@ We provide a CMake rule to wrap a library or the main executable. This rule buil
 +target_link_libraries(my_prog PRIVATE my_wrapper_target)
 ```
 
-Wrapped libraries are treated as untrusted by default. If the library being wrapped defined a trusted compartment, `COMPARTMENT_PKEY n` must be specified in define_ia2_wrapper. Here `n` is the argument used in `INIT_COMPARTMENT` to define the compartment. If the caller is an untrusted compartment, set `CALLER_PKEY UNTRUSTED`. To create a wrapper for the main binary (i.e. if shared libraries call it directly) the `WRAP_MAIN` option must be specified.
+Wrapped libraries are treated as untrusted by default. If the library being wrapped defined a trusted compartment, `COMPARTMENT_PKEY n` must be specified in define_ia2_wrapper. Here `n` is the argument used in `IA2_COMPARTMENT` to define the compartment. If the caller is an untrusted compartment, set `CALLER_PKEY UNTRUSTED`. To create a wrapper for the main binary (i.e. if shared libraries call it directly) the `WRAP_MAIN` option must be specified.
 
 #### Manual usage
 

docs/usage.md

@@ -79,14 +79,14 @@ gcc -shared libbar_shim.c -Wl,-z,now -Wl,--version-script,libbar_shim.c.syms \
 ```
 
 We now modify the main binary's source to initialize our runtime using
-`INIT_RUNTIME` and assign it a protection key with `INIT_COMPARTMENT`.
+`INIT_RUNTIME` and assign it a protection key with `IA2_COMPARTMENT`.
 `INIT_RUNTIME` must be invoked once in the main binary. To assign a protection
-key to another shared object, only `INIT_COMPARTMENT` must be added to one of
+key to another shared object, only `IA2_COMPARTMENT` must be added to one of
 the object's source files.
 
 ```
 // main.c
-// This header defines INIT_RUNTIME and INIT_COMPARTMENT
+// This header defines INIT_RUNTIME and IA2_COMPARTMENT
 #include <ia2.h>
 
 // Initialize the runtime and allocate 1 protection key.