[squash] partially address review feedback

Signed-off-by: Gerwin Klein <[email protected]>

libsel4camkes/README.md

@@ -6,7 +6,7 @@
 
 # libsel4camkes
 
-This is a library that contain a collection of user-friendly abstractions to
+This is a library that contains a collection of user-friendly abstractions to
 the CAmkES runtime environment, as well some backend functions for the CAmkES
 environment to bootstrap and configure the runtime environment.
 

libsel4camkes/docs/allocator.md

@@ -1,13 +1,13 @@
 <!--
      Copyright 2021, Data61, CSIRO (ABN 41 687 119 230)
 
-     SPDX-License-Identifier: BSD-2-Clause
+     SPDX-License-Identifier: CC-BY-SA-4.0
 -->
 
-# Allocator 
+# Allocator
 
-The allocator in libsel4camkes can be used to allocate seL4 capability objects
-from a managed pool. The `camkes_provide` function is mostly used in the by the
+The allocator in `libsel4camkes` can be used to allocate seL4 capability objects
+from a managed pool. The `camkes_provide` function is mostly used by the
 CAmkES backend to setup the pool on behalf of the user. In `simple` or
 'dynamic' configurations of CAmkES, other allocators (`vka`, `vspace`, etc)
 would be preferred instead.
@@ -21,14 +21,14 @@ users to specify some objects to be created and provided to the pool
 automatically.
 
 So far, only TCBs, Endpoints, Notifications, and Untypes can be allocated.
-Here's a following example of asking CAmkES to allocate these objects.
+Below is an example of asking CAmkES to allocate these objects.
 
 ```c
 assembly {
     composition {
         component Foo bar;
-    } 
-    
+    }
+
     configuration {
         bar.<object type>_pool = 12;
     }
@@ -37,8 +37,9 @@ assembly {
 
 In the example, CAmkES would allocate 12 objects of type 'object type'. Valid
 object types are:
-  - `tcb`
-  - `ep`
-  - `notification`
-  - `untypedX`, where X is a number indicating the size of the untyped, e.g.
-    `untyped12` would ask for untypes of size 2 to the power 12, or 4096
+
+- `tcb`
+- `ep`
+- `notification`
+- `untypedX`, where X is a number indicating the size of the untyped, e.g.
+  `untyped12` would ask for untypes of size 2 to the power 12, or 4096

libsel4camkes/docs/dataport.md

@@ -6,28 +6,29 @@
 
 # Dataport
 
-libsel4camkes provides some functions for interacting with CAmkES dataports.
+`libsel4camkes` provides some functions for interacting with CAmkES dataports.
 There are also some definitions intended for CAmKES internal use.
 
 ## Usage
 
 There are two functions for wrapping and unwrapping pointers that point to the
-dataport into and from a data format that can be shared between components. These are:
+dataport into and from a data format that can be shared between components.
+These are:
 
 ```c
 dataport_ptr_t dataport_wrap_ptr(void *ptr);
 
 void *dataport_unwrap_ptr(dataport_ptr_t ptr);
 ```
 
-Although components may share some memory between each with the use CAmkES
+Although components may share memory between each other using CAmkES
 dataports, the dataports may not be necessarily be mapped into the same virtual
 address in the components' address space. Thus, these functions are used to
-communicate pointers in the dataport by converting in a format that's
+communicate pointers in the dataport by converting them into a format that's
 understood by all components that have a shared dataport connection.
 
-There is also an addditional function that allows clients to perform cache
-maintaince operations on the dataports.
+There is an additional function that allows clients to perform cache
+maintenance operations on the dataports.
 
 ```c
 int camkes_dataport_flush_cache(size_t start_offset, size_t size,

libsel4camkes/docs/dma.md

@@ -1,16 +1,16 @@
 <!--
      Copyright 2021, Data61, CSIRO (ABN 41 687 119 230)
 
-     SPDX-License-Identifier: BSD-2-Clause
+     SPDX-License-Identifier: CC-BY-SA-4.0
 -->
 
 # DMA
 
-libsel4camkes provides some functions for interacting with a DMA pool that
-CAmkES allocates and manages. These functions are essentially an implementation
-of the `ps_dma_man_t` interface in `ps_io_ops_t`. It is preferred that the DMA
-requests go through the `ps_dma_man_t` interfaces instead of using these
-functions.
+`libsel4camkes` provides functions for interacting with a DMA pool that is
+allocated and managed by CAmkES. These functions are essentially an
+implementation of the `ps_dma_man_t` interface in `ps_io_ops_t`. It is preferred
+that the DMA requests go through the `ps_dma_man_t` interfaces instead of using
+these functions.
 
 ## Usage
 
@@ -23,7 +23,7 @@ assembly {
     composition {
         component Foo bar;
     }
-    
+
     configuration {
         bar.dma_pool = 0x4000;
     }

libsel4camkes/docs/error.md

@@ -1,20 +1,20 @@
 <!--
      Copyright 2021, Data61, CSIRO (ABN 41 687 119 230)
 
-     SPDX-License-Identifier: BSD-2-Clause
+     SPDX-License-Identifier: CC-BY-SA-4.0
 -->
 
 # Error
 
-libsel4camkes provides some functions for dealing with errors with the CAmkES
+`libsel4camkes` provides some functions for dealing with errors from the CAmkES
 runtime.
 
 ## Usage
 
-In rare occasions, the CAmkES runtime can fail on some operations. Upon
-failure, the CAmkES runtime will invoke an error handler to deal with the
-error. The default error handler will simply halt the system upon error. It is
-possible to install a custom error handler with the following function.
+In rare occasions, the CAmkES runtime can produce an error on some operations.
+When such an error occurs, the CAmkES runtime will invoke an error handler to
+deal with the error. The default error handler will simply halt the system. It
+is possible to install a custom error handler with the following function.
 
 ```c
 camkes_error_handler_t camkes_register_error_handler(camkes_error_handler_t handler);
@@ -28,9 +28,12 @@ typedef camkes_error_action_t (*camkes_error_handler_t)(camkes_error_t *);
 
 The error handler is given relevant information from the `camkes_error_t`
 struct and is expected to handle the error and return a `camkes_error_type_t`
-return code indicating the action to take. The actions that can be taken are:
-    - to discard the transaction
-    - ignore the error
-    - exit with failure
+return code indicating the action to take. The actions that can be taken are to:
 
-See the [header](https://github.com/seL4/camkes-tool/blob/master/libsel4camkes/include/camkes/error.h) for more information.
+- discard the transaction
+- ignore the error
+- exit with failure
+
+See the
+[header](https://github.com/seL4/camkes-tool/blob/master/libsel4camkes/include/camkes/error.h)
+for more information.

libsel4camkes/docs/fault.md

@@ -1,29 +1,29 @@
 <!--
      Copyright 2021, Data61, CSIRO (ABN 41 687 119 230)
 
-     SPDX-License-Identifier: BSD-2-Clause
+     SPDX-License-Identifier: CC-BY-SA-4.0
 -->
 
 # Fault
 
-libsel4camkes provides some functions for examining faults that are generated
-by the applications.
+`libsel4camkes` provides functions for examining faults that are generated
+by applications.
 
 ## Usage
 
-When an application triggers a fault, the seL4 kernel will invoke the
-applications, or more specifically, the thread's fault handler. The fault
-handler is then given information about the fault and is expected to resolve
-the situation. CAmkES will register a default fault handler on a debug build
-that will call a function to show information about the fault. This function is:
+When an application triggers a fault, the seL4 kernel will invoke the the
+faulting thread's fault handler. The fault handler is then given information
+about the fault and is expected to resolve the situation. CAmkES will register a
+default fault handler on a debug build that will call a function to show
+information about the fault. This function is:
 
 ```c
 void camkes_show_fault(seL4_MessageInfo_t info, seL4_CPtr thread_id,
                        const char *name, bool tcp_caps_available,
                        const camkes_memory_region_t *memory_map);
 ```
 
-The function takes the fault information written by the kernel into the
+The function takes the fault information that the kernel provides in the
 faulting thread's IPC buffer and displays it in a human readable format.
 
 Currently this function is expected to be called by a component's fault handler

libsel4camkes/docs/msgqueue.md

@@ -32,10 +32,10 @@ assembly {
     composition {
         component Foo bar;
         component Foo2 baz;
-        
+
         connection messagequeue_foo seL4Msgqueue(from baz.tx, to bar.rx);
     }
-    
+
     configuration {
         bar.rx_id = 1;
         baz.tx_id = 1;
@@ -60,7 +60,7 @@ int camkes_msgqueue_sender_init(int msgqueue_id, camkes_msgqueue_sender_t *sende
 int camkes_msgqueue_receiver_init(int msgqueue_id, camkes_msgqueue_receiver_t *receiver);
 ```
 
-The sender can then call the following function to send messages. 
+The sender can then call the following function to send messages.
 
 ```c
 int camkes_msgqueue_send(camkes_msgqueue_sender_t *sender, void *message, size_t message_size);

libsel4camkes/docs/ps_io_ops_t.md

@@ -3,7 +3,7 @@
 
      SPDX-License-Identifier: BSD-2-Clause
 -->
-  
+
 # `ps_io_ops_t`
 
 CAmkES provides an implementation of the `ps_io_ops_t` as part
@@ -86,7 +86,7 @@ are expected to register these capabilities in the `_ioport_regions` linker
 section. The CAmkES imlementation of the IOPort interface looks up these
 capabilities for requested IOPorts and then performs the correct seL4 IOPort
 invocation. Errors are returned for any IOPorts that the component does not
-have access to. 
+have access to.
 
 A feature may be added in the future for delegating IOPort calls to a different
 CAmkES component. This is required to support sharing of devices across

libsel4camkes/docs/virtqueue.md

@@ -31,10 +31,10 @@ assembly {
         component VirtQueueInit vq_init;
         component Foo bar;
         component Foo2 baz;
-        
+
         connection virtqueue_foo seL4VirtQueue(to vq_init.init, from bar.drv, from baz.dev);
     }
-    
+
     configuration {
         bar.drv_id = 1;
         baz.dev_id = 1;
@@ -65,9 +65,9 @@ There is also a version of these functions which can return the underlying
 notification object that is backing the notification part of the virtqueues.
 
 ```c
-int camkes_virtqueue_driver_init_with_recv(virtqueue_driver_t *driver, unsigned int camkes_virtqueue_id, 
+int camkes_virtqueue_driver_init_with_recv(virtqueue_driver_t *driver, unsigned int camkes_virtqueue_id,
                                            seL4_CPtr *recv_notification, seL4_CPtr *recv_badge);
-                                           
+
 int camkes_virtqueue_device_init_with_recv(virtqueue_device_t *device, unsigned int camkes_virtqueue_id,
                                            seL4_CPtr *recv_notification, seL4_CPtr *recv_badge);
 ```
@@ -98,7 +98,7 @@ It is then possible to gather each buffer in the used buffer ring and copy it in
 ```c
 int camkes_virtqueue_driver_gather_copy_buffer(virtqueue_driver_t *vq, virtqueue_ring_object *handle,
                                         void *buffer, size_t size);
-                                        
+
 int camkes_virtqueue_driver_gather_buffer(virtqueue_driver_t *vq, virtqueue_ring_object_t *handle,
                                           void **buffer, unsigned *size, vq_flags_t *flag);
 ```
@@ -120,10 +120,10 @@ The buffers can then be:
 ```c
 int camkes_virtqueue_device_gather_copy_buffer(virtqueue_device_t *vq, virtqueue_ring_object_t *handle,
                                                void *buffer, size_t size);
-                                               
+
 int camkes_virtqueue_device_scatter_copy_buffer(virtqueue_device_t *vq, virtqueue_ring_object_t *handle,
                                                 void *buffer, size_t size);
-                                                
+
 int camkes_virtqueue_device_gather_buffer(virtqueue_device_t *vq, virtqueue_ring_object_t *handle,
                                           void **buffer, unsigned *size, vq_flags_t *flag);
 ```