Skip to content

Copy edit uVisor documents #411

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Mar 8, 2017
Merged

Copy edit uVisor documents #411

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 6 additions & 21 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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:

Expand Down
140 changes: 66 additions & 74 deletions README.md
View file
Open in desktop

Large diffs are not rendered by default.

16 changes: 8 additions & 8 deletions docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)
53 changes: 18 additions & 35 deletions docs/api/API.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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>
Expand All @@ -46,6 +39,7 @@ UVISOR_BOX_CONFIG(box_name
</table>

Example:

```C
#include "uvisor-lib/uvisor-lib.h"

Expand Down Expand Up @@ -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.

---

Expand Down Expand Up @@ -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.

---

Expand All @@ -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>
Expand All @@ -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).

Expand Down Expand Up @@ -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.

---

Expand Down Expand Up @@ -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

Expand All @@ -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>
Expand Down Expand Up @@ -486,7 +469,7 @@ int vIRQ_GetLevel(void)
## Type definitions

```C
typedef uint32_t UvisroBoxAcl; /* Permssion mask */
typedef uint32_t UvisroBoxAcl; /* Permission mask */
```

---
Expand All @@ -511,4 +494,4 @@ typedef struct
| `FAULT_BUS` | 6 |
| `FAULT_USAGE` | 7 |
| `FAULT_HARD` | 8 |
| `FAULT_DEBUG` | 9 |
| `FAULT_DEBUG` | 9 |
Loading