Merge pull request #411 from AnotherButler/AnotherButler

Copy edit uVisor documents

Author: AlessandroA

CONTRIBUTING.md

@@ -1,29 +1,14 @@
-ARM mbed OS is an Open Source project. We encourage you to pitch in, and we
-welcome contributions and [bug reports](../../issues).
+ARM mbed OS is an open source project. We welcome contributions and [bug reports](../../issues).
 
-* If you want to submit a bug report please make sure to follow our
-  [reporting guidelines](https://github.com/ARMmbed/mbed-os/blob/master/Reporting%20Bugs.md).
+- If you want to submit a bug report, please follow our [reporting guidelines](https://github.com/ARMmbed/mbed-os/blob/master/Reporting%20Bugs.md).
 
-* If you want to submit a patch, please read the
-  [contribution guide](https://github.com/ARMmbed/mbed-os/blob/master/Contributing%20to%20mbed.md).
-  Note that we have a
-  [Contributor Agreement](http://developer.mbed.org/contributor_agreement/)
-  that must be agreed to before contributions can be merged. To agree to the
-  contributor agreement, you need to have an mbed.com account and be logged in.
-  **We only accept [bug reports](../../issues) and pull requests [via GitHub](../../)**.
+- If you want to submit a patch, please read the [contribution guide](https://docs.mbed.com/docs/mbed-os-handbook/en/latest/cont/contributing/). Note that we have a [Contributor Agreement](http://developer.mbed.org/contributor_agreement/) that you must agree to before we can merge your contributions. To agree to the contributor agreement, you need to have a [developer.mbed.org](https://developer.mbed.org/account/signup/) account and be logged in. **We only accept [bug reports](../../issues) and pull requests [via GitHub](../../)**.
 
-* If you have a question about how to use mbed OS, please search the
-  [mbed forums](http://forums.mbed.com/c/mbed-os), and if you still need help,
-  post a new topic there.
+- If you have a question about how to use mbed OS, please search the [mbed forums](http://forums.mbed.com/c/mbed-os), and if you still need help, post a new topic there.
 
-* Before contributing an enhancement (new feature, new port etc) please start by
-  [discussing it on the forums](http://forums.mbed.com/c/mbed-os)
-  to avoid duplication of work - as we or others might work on a related feature already.
-  This will help streamline your pull request for getting it merged quickly.
+- Before contributing an enhancement (such as a new feature or port), please start by [discussing it on the forums](http://forums.mbed.com/c/mbed-os) to avoid duplication of work. This will help streamline your pull request for a quick merge.
 
-* If you work for an [mbed Partner company](http://www.mbed.com/en/partners/our-partners/),
-  you will have a partner manager assigned to you who can help you navigate the
-  process and get the best out of your partnership.
+- If you work for an [mbed Partner company](http://www.mbed.com/en/partners/our-partners/), the partner manager assigned to you can help you navigate the process and get the most out of your partnership.
 
 Thanks! :heart:
 

README.md

@@ -1,25 +1,25 @@
 # The uVisor Documentation
 
-The uVisor documentation is divided into two areas, depending on what your interest. These domains are described below. If you instead are interested in the general uVisor design philosophy, you can see our [high level introduction to mbed uVisor](https://github.com/ARMmbed/uvisor/raw/docs/uVisorSecurity-TechCon2016.pdf) or refer to the uVisor [GitHub documentation](../README.md).
+The uVisor documentation consists of two sections, API documentation and core documentation. You can find descriptions of these domains below. If you instead are interested in the general uVisor design philosophy, see the [high-level introduction to mbed uVisor](https://github.com/ARMmbed/uvisor/raw/docs/uVisorSecurity-TechCon2016.pdf) or refer to the uVisor [GitHub documentation](../README.md).
 
 ## API documentation
 
-These are the user-facing documents. They are the ideal starting point to know what you can do with uVisor, and how to setup an application to use the uVisor features.
+These user-facing documents show what you can do with uVisor and how to set up an application that uses the uVisor features.
 
 | I want to...                                          | Document                                                     |
 |-------------------------------------------------------|--------------------------------------------------------------|
-| Get a high level introduction to mbed uVisor          | [Practical real-time operating system security for the masses](https://github.com/ARMmbed/uvisor/raw/docs/uVisorSecurity-TechCon2016.pdf) |
-| Start using uVisor in mbed OS on a supported platform | [Quick-Start Guide for uVisor on mbed OS](api/QUICKSTART.md) |
+| See a high-level introduction to mbed uVisor          | [Practical real-time operating system security for the masses](https://github.com/ARMmbed/uvisor/raw/docs/uVisorSecurity-TechCon2016.pdf) |
+| Start using uVisor in mbed OS on a supported platform | [Getting started guide for uVisor on mbed OS](api/QUICKSTART.md) |
 | Read the uVisor API documentation in detail           | [The uVisor API documentation](api/API.md)                   |
 | Enable the uVisor debug messages                      | [Debugging uVisor on mbed OS](api/DEBUGGING.md)              |
 
 ## Core documentation
 
-These documents describe the uVisor internals more in details. They are useful if you need to contribute to uVisor, compile a specific uVisor version, or if you just want to know more about the uVisor core.
+These documents describe the uVisor internals in more detail. They are useful if you want to contribute to uVisor, compile a specific uVisor version or just know more about the uVisor core.
 
 | I want to...                     | Document                                                                                              |
 |----------------------------------|-------------------------------------------------------------------------------------------------------|
 | Understand uVisor integration    | [mbed uVisor integration in mbed OS](https://github.com/ARMmbed/uvisor/raw/docs/uvisor-rtos-docs.pdf) |
-| Port uVisor to my platform/OS    | [uVisor Porting Guide for mbed OS](core/PORTING.md)                                                   |
-| Test and experiment with uVisor  | [Developing with uVisor Locally on mbed OS](core/DEVELOPING_LOCALLY.md)                               |
-| Contribute to uVisor             | [Contributing to uVisor](../CONTRIBUTING.md)                                                          |
+| Port uVisor to my platform/OS    | [uVisor porting guide for mbed OS](core/PORTING.md)                                                   |
+| Test and experiment with uVisor  | [Developing with uVisor locally on mbed OS](core/DEVELOPING_LOCALLY.md)                               |
+| Contribute to uVisor             | [Contributing to uVisor](../CONTRIBUTING.md)   

docs/README.md

@@ -1,14 +1,7 @@
 # uVisor API documentation
 
-Here you can find detailed documentation for:
-
-1. [Configuration macros](#configuration-macros), to configure a secure box and protect data and peripherals.
-1. [Box Identity](#box-identity), to retrieve a box-specific ID or the namespace of the current or calling box.
-1. [Low level APIs](#low-level-apis), to access uVisor functions that are not available to unprivileged code (interrupts, restricted system registers).
-1. [Type definitions](#type-definitions).
-1. [Error codes](#error-codes).
-
 ## Configuration macros
+You can use configuration macros to configure a secure box and protect data and peripherals.
 
 ```C
 UVISOR_BOX_CONFIG(box_name
@@ -24,7 +17,7 @@ UVISOR_BOX_CONFIG(box_name
   </tr>
   <tr>
     <td>Type</td>
-    <td colspan="2">C/C++ pre-processor macro (pseudo-function)</td>
+    <td colspan="2">C/C++ preprocessor macro (pseudo-function)</td>
   </tr>
   <tr>
     <td rowspan="4">Parameters</td>
@@ -46,6 +39,7 @@ UVISOR_BOX_CONFIG(box_name
 </table>
 
 Example:
+
 ```C
 #include "uvisor-lib/uvisor-lib.h"
 
@@ -107,11 +101,7 @@ Example:
 UVISOR_SET_MODE(UVISOR_ENABLED);
 ```
 
-**Note:**
-
-1. This macro is only needed temporarily (uVisor disabled by default) and will be removed in the future.
-
-2. This macro must be used only once in the top level yotta executable.
+**Note:** This macro is only temporary (uVisor disabled by default) and will be removed in the future.
 
 ---
 
@@ -161,11 +151,7 @@ static const UvBoxAclItem g_background_acl[] = {
 UVISOR_SET_MODE_ACL(UVISOR_ENABLED, g_background_acl);
 ```
 
-**Note:**
-
-1. This macro is only needed temporarily (uVisor disabled by default) and will be removed in the future.
-
-2. This macro must be used only once in the top level yotta executable.
+**Note:** This macro is only temporary (uVisor disabled by default) and will be removed in the future.
 
 ---
 
@@ -178,15 +164,15 @@ UVISOR_BOX_NAMESPACE(static const char const namespace[])
     <td>Description</td>
     <td colspan="2"><p>Specify the namespace for a box.</p>
 
-      <p>The namespace of the box must be a null-terminated string no longer than <code>MAX_BOX_NAMESPACE_LENGTH</code> (including the terminating null). The namespace must also be stored in public flash. uVisor will verify that the namespace is null-terminated and stored in public flash at boot-time, and will halt if the namespace fails this verification.</p>
+      <p>The namespace of the box must be a null-terminated string no longer than <code>MAX_BOX_NAMESPACE_LENGTH</code> (including the terminating null). The namespace must also be stored in public flash. uVisor will verify that the namespace is null-terminated and stored in public flash at boot-time and will halt if the namespace fails this verification.</p>
 
       <p>For now, use a reverse domain name for the box namespace. If you don't have a reverse domain name, use a GUID string identifier. We currently don't verify that the namespace is globally unique, but we will perform this validation in the future.</p>
 
-      <p>Use of this configuration macro before <code>UVISOR_BOX_CONFIG</code> is required. If you do not wish to give your box a namespace, specify <code>NULL</code> as the namespace to create an anonymous box.</p>
+      <p>You must use this configuration macro before <code>UVISOR_BOX_CONFIG</code>. If you do not wish to give your box a namespace, specify <code>NULL</code> as the namespace to create an anonymous box.</p>
   </tr>
   <tr>
     <td>Type</td>
-    <td colspan="2">C/C++ pre-processor macro (pseudo-function)</td>
+    <td colspan="2">C/C++ preprocessor macro (pseudo-function)</td>
   </tr>
   <tr>
     <td rowspan="1">Parameters</td>
@@ -204,17 +190,16 @@ UVISOR_BOX_NAMESPACE("com.example.my-box-name");
 UVISOR_BOX_CONFIG(my_box_name, UVISOR_BOX_STACK_SIZE);
 ```
 
-## Box Identity
-
+## Box identity
 A box identity identifies a security domain uniquely and globally.
 
-The box identity API can be used to determine the source box of an inbound secure gateway call. This can be useful for implementing complex authorization logic between mutually distrustful security domains.
+You can use the box identity API to determine the source box of an inbound secure gateway call. This can be useful for implementing complex authorization logic between mutually distrustful security domains.
 
 uVisor provides the ability to retrieve the box ID of the current box (`uvisor_box_id_self`), or of the box that called the current box through an RPC gateway via the `box_id_caller` parameter of `rpc_fncall_waitfor`.
 
-The box ID number is not constant and can change between reboots. But, the box ID number can be used as a token to retrieve a constant string identifier, known as the box namespace.
+The box ID number is not constant and can change between reboots, but you can use it as a token to retrieve a constant string identifier, known as the box namespace.
 
-A box namespace is a static, box-specific string, that can help identify which box has which ID at run-time. In the future, the box namespace will be guaranteed to be globally unique.
+A box namespace is a static, box-specific string that can help identify which box has which ID at runtime. In the future, the box namespace will be globally unique.
 
 A full example using this API is available at [mbed-os-example-uvisor-number-store](https://github.com/ARMmbed/mbed-os-example-uvisor-number-store).
 
@@ -250,7 +235,7 @@ int rpc_fncall_waitfor(const TFN_Ptr fn_ptr_array[], size_t fn_count, int * box_
   </tr>
 </table>
 
-> When deciding which memory to provide for `rpc_fncall_waitfor` to use when writing `box_id_caller`, strongly prefer thread local storage when multiple threads in a box can handle incoming RPC.
+> When deciding which memory to provide for `rpc_fncall_waitfor` to use when writing `box_id_caller`, use thread local storage when multiple threads in a box can handle incoming RPC.
 
 ---
 
@@ -284,9 +269,7 @@ int uvisor_box_namespace(int box_id, char *box_namespace, size_t length)
 
 ## Low-level APIs
 
-Currently the following low level operations are permitted:
-
-1. Interrupt management.
+You can use low-level APIs to access uVisor functions that are not available to unprivileged code (interrupts, restricted system registers). The only permitted low-level operation is interrupt management.
 
 ### Interrupt management
 
@@ -297,15 +280,15 @@ void vIRQ_SetVector(uint32_t irqn, uint32_t vector)
 <table>
   <tr>
     <td>Description</td>
-    <td colspan="2">Set an ISR for IRQn</td>
+    <td colspan="2">Register an ISR to the currently active box</td>
   <tr>
     <td rowspan="2">Parameters</td>
     <td><pre>uint32_t irqn<code></td>
     <td>IRQn</td>
   </tr>
   <tr>
     <td><pre>uint32_t vector<code></td>
-    <td>Interrupt handler
+    <td>Interrupt handler; if 0 the IRQn slot is deregistered for the current
         box</td>
   </tr>
 </table>
@@ -486,7 +469,7 @@ int vIRQ_GetLevel(void)
 ## Type definitions
 
 ```C
-typedef uint32_t UvisroBoxAcl;    /* Permssion mask */
+typedef uint32_t UvisroBoxAcl;    /* Permission mask */
 ```
 
 ---
@@ -511,4 +494,4 @@ typedef struct
 | `FAULT_BUS`           | 6          |
 | `FAULT_USAGE`         | 7          |
 | `FAULT_HARD`          | 8          |
-| `FAULT_DEBUG`         | 9          |
+| `FAULT_DEBUG`         | 9          |