From c89dd686cc5db0dc5e06a8eacefd7c1e9e68c0e6 Mon Sep 17 00:00:00 2001 From: Brad Campbell Date: Fri, 20 Jul 2018 15:42:35 -0400 Subject: [PATCH] doc: general updates --- doc/Lifetimes.md | 4 ++-- doc/Memory_Layout.md | 6 +++--- doc/README.md | 3 +-- doc/Startup.md | 12 +++++------ doc/Userland.md | 49 ++++++++++++++++++++++---------------------- 5 files changed, 35 insertions(+), 39 deletions(-) diff --git a/doc/Lifetimes.md b/doc/Lifetimes.md index 2e9a14c878..a0fabc8be2 100644 --- a/doc/Lifetimes.md +++ b/doc/Lifetimes.md @@ -34,7 +34,7 @@ lifetime of that reference. For example: ```rust struct Foo<'a> { - bar: &'a Bar + bar: &'a Bar } ``` @@ -47,7 +47,7 @@ forever, regardless of how long the containing type (e.g. `Foo`) lives: ```rust struct Foo { - bar: &'static Bar + bar: &'static Bar } ``` diff --git a/doc/Memory_Layout.md b/doc/Memory_Layout.md index 3d8c7c0132..b6cf401a8f 100644 --- a/doc/Memory_Layout.md +++ b/doc/Memory_Layout.md @@ -2,7 +2,7 @@ Memory Layout ============= This document describes how the memory in Tock is structured and used for the -kernel, applications, and supporting state. +kernel, applications, and supporting state. @@ -59,7 +59,7 @@ valid process is set to all 0x00 or 0xFF. ## RAM -The RAM holds the data currently being used by both the kernel and processes. +The RAM holds the data currently being used by both the kernel and processes. ### Kernel RAM The kernel RAM contains three major regions: @@ -106,4 +106,4 @@ others. The structure of its flash and RAM is as follows. | Address Range | Length (bytes) | Content | Description | |-----------------------|----------------|--------------------|---------------------------------------------------------------------------------------------------| -| 0x20000000-0x2000FFFF | 64k | Kernel and app RAM | The kernel links with all of the RAM, and then allocates a buffer internally for application use. | \ No newline at end of file +| 0x20000000-0x2000FFFF | 64k | Kernel and app RAM | The kernel links with all of the RAM, and then allocates a buffer internally for application use. | diff --git a/doc/README.md b/doc/README.md index 18cb6be44c..02b3d72c71 100644 --- a/doc/README.md +++ b/doc/README.md @@ -41,5 +41,4 @@ Tock Guides ### Courses and Tutorials - **[Courses](courses)** - Workshops on multiple aspects of Tock. -- **[Tutorials](tutorials)** - Tutorials that walk through specific features of - Tock. +- **[Tutorials](tutorials)** - Tutorials that walk through specific features of Tock. diff --git a/doc/Startup.md b/doc/Startup.md index 34588427d7..dddc9e1d8f 100644 --- a/doc/Startup.md +++ b/doc/Startup.md @@ -130,11 +130,9 @@ An example version of this loop is in `kernel/src/process.rs` as the process from the starting address in flash and with a given amount of memory remaining. If the header is validated, it tries to load the process into memory and initialize all of the bookkeeping in the kernel associated with the process. -This can fail if the process needs more memory than is available on the chip. As -a part of this load process, the kernel can also perform PIC fixups for the -process if it was requested in the TBF header. If the process is successfully -loaded the kernel importantly notes the address of the application's entry -function which is called when the process is started. +This can fail if the process needs more memory than is available on the chip. If +the process is successfully loaded the kernel importantly notes the address of +the application's entry function which is called when the process is started. The load process loop ends when the kernel runs out of statically allocated memory to store processes in, available RAM for processes, or there is an @@ -142,5 +140,5 @@ invalid TBF header in flash. ## Scheduler Execution -The final thing that the reset handler must do is call `kernel::main()`. This -starts the Tock scheduler and the main operation of the kernel. +The final thing that the reset handler must do is call `kernel.kernel_loop()`. +This starts the Tock scheduler and the main operation of the kernel. diff --git a/doc/Userland.md b/doc/Userland.md index 4d8088d6ee..2b32407486 100644 --- a/doc/Userland.md +++ b/doc/Userland.md @@ -28,17 +28,16 @@ Applications in Tock are the user-level code meant to accomplish some type of task for the end user. Applications are distinguished from kernel code which handles device drivers, chip-specific details, and general operating system tasks. Unlike many existing embedded operating systems, in Tock applications -are not built as one with the kernel. Instead they are entirely separate code +are not compiled with the kernel. Instead they are entirely separate code that interact with the kernel and each other through [system calls](https://en.wikipedia.org/wiki/System_call). Since applications are not a part of the kernel, they may be written in any -language that can be compiled into code capable of running on ARM Cortex-M -processors. While the Tock kernel is written in Rust, applications are commonly -written in C. Additionally, Tock supports running multiple applications -concurrently. Co-operatively multiprogramming is the default, but applications -may also be time sliced. Applications may talk to each other via Inter-Process -Communication (IPC) through system calls. +language that can be compiled into code capable of running on a microcontroller. +Tock supports running multiple applications concurrently. Co-operatively +multiprogramming is the default, but applications may also be time sliced. +Applications may talk to each other via Inter-Process Communication (IPC) +through system calls. Applications do not have compile-time knowledge of the address at which they will be installed and loaded. In the current design of Tock, applications must @@ -49,9 +48,9 @@ of PIC for Tock apps is not a fundamental choice, future versions of the system may support run-time relocatable code. Applications are unprivileged code. They may not access all portions of memory -and may, in fact, fault if they attempt to access memory outside of their -boundaries (similarly to segmentation faults in Linux code). In order to -interact with hardware, applications must make calls to the kernel. +and will fault if they attempt to access memory outside of their boundaries +(similarly to segmentation faults in Linux code). To interact with hardware, +applications must make calls to the kernel. ## System Calls @@ -96,30 +95,30 @@ timer fires. Specific state that you want the callback to act upon can be passed as the pointer `userdata`. After the application has started the timer, calls `yield`, and the timer fires, the callback function will be called. -It is important to note that `yield` must be called in order for events to be -serviced in the current implementation of Tock. Callbacks to the application -will be queued when they occur but the application will not receive them until -it yields. This is not fundamental to Tock, and future version may service -callbacks on any system call or when performing application time slicing. After -receiving and running the callback, application code will continue after the -`yield`. Tock automatically calls `yield` continuously for applications that -return from execution (for example, an application that returns from `main`). +It is important to note that `yield` must be called for events to be serviced in +the current implementation of Tock. Callbacks to the application will be queued +when they occur but the application will not receive them until it yields. This +is not fundamental to Tock, and future version may service callbacks on any +system call or when performing application time slicing. After receiving and +running the callback, application code will continue after the `yield`. +Applications which are "finished" (i.e. have returned from `main()`) should call +`yield` in a loop to avoid being scheduled by the kernel. ## Inter-Process Communication IPC allows for multiple applications to communicate directly through shared buffers. IPC in Tock is implemented with a service-client model. Each app can -support one service and the service is identified by the `PACKAGE_NAME` variable -set in its Makefile. An app can communicate with multiple services and will get -a unique handle for each discovered service. Clients and services communicate -through shared buffers. Each client can share some of its own application memory -with the service and then notify the service to instruct it to parse the shared -buffer. +support one service and the service is identified by its package name which is +included in the Tock Binary Format Header for the app. An app can communicate +with multiple services and will get a unique handle for each discovered service. +Clients and services communicate through shared buffers. Each client can share +some of its own application memory with the service and then notify the service +to instruct it to parse the shared buffer. ### Services -Services are named by the `PACKAGE_NAME` variable in the application Makefile. +Services are named by the package name included in the app's TBF header. To register a service, an app can call `ipc_register_svc()` to setup a callback. This callback will be called whenever a client calls notify on that service.