diff --git a/doc/courses/2017-11-SenSys/README.md b/doc/courses/2017-11-SenSys/README.md deleted file mode 100644 index f37f91d62d..0000000000 --- a/doc/courses/2017-11-SenSys/README.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -location: Delft, Netherlands -date: November 5, 2017 ---- - -# Tock OS Training @ SenSys 2017 - ---- -**NOTE** - -This course was primarily designed in November of 2017, but has been updated -through May 2018. It is a useful introduction to Tock but is no longer updated -as Tock evolves in preparation for new courses that will be used. -For example, this course uses Tock version 1.2, and current Tock -development is on version 2.x. To follow this course, please checkout -the commit below to use Tock at a point where the tutorial is known to -be working. - -```bash -$ git checkout 1203437bff05667bb0636dc9ab69e1daca13c2a2 -``` ---- - -This course introduces you to Tock, a secure embedded operating system for -sensor networks and the Internet of Things. Tock is the first operating system -to allow multiple untrusted applications to run concurrently on a -microcontroller-based computer. The Tock kernel is written in Rust, a -memory-safe systems language that does not rely on a garbage collector. -Userspace applications are run in single-threaded processes that can be written -in any language. A paper describing Tock's goals, design, and implementation was -published at the SOSP'17 conference and is available -[here](https://www.amitlevy.com/papers/tock-sosp2017.pdf). - -In this course, you will learn the basic Tock system architecture, how to write -a userspace process in C, Tock's system call interface, and fill in code for a -small kernel extension written in Rust. The course assumes experience -programming embedded devices and fluency in C. It assumes no knowledge of Rust, -although knowing Rust will allow you to be more creative in the Rust programming -part of the course. diff --git a/doc/courses/2018-11-SenSys/README.md b/doc/courses/2018-11-SenSys/README.md deleted file mode 100644 index 96d5292056..0000000000 --- a/doc/courses/2018-11-SenSys/README.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -location: Shenzhen, China -date: November 4, 2018 ---- - -# Tock OS Training @ SenSys 2018 - ---- -**NOTE** - -This course was primarily designed in October of 2018. It is a useful -introduction to Tock but is no longer updated. For example, this course -uses Tock version 1.2, and current Tock development is on version 2.x. - ---- - -This course introduces you to Tock, a secure embedded operating system for -sensor networks and the Internet of Things. Tock is the first operating system -to allow multiple untrusted applications to run concurrently on a -microcontroller-based computer. The Tock kernel is written in Rust, a -memory-safe systems language that does not rely on a garbage collector. -Userspace applications are run in single-threaded processes that can be written -in any language. A paper describing Tock's goals, design, and implementation was -published at the SOSP'17 conference and is available -[here](https://www.amitlevy.com/papers/tock-sosp2017.pdf). - -In this course, we will look at some of the high-level services provided by Tock. -We will start with an understanding of the OS and its programming environment. -Then we'll look at how a process management application can help afford remote -debugging, diagnosing and fixing a resource-intensive app over the network. -The last part of the tutorial is a bit more free-form, inviting attendees to -further explore the networking and application features of Tock or to dig into -the kernel a bit and explore how to enhance and extend the kernel. - -This course assumes some experience programming embedded devices and fluency in C. -It assumes no knowledge of Rust, although knowing Rust will allow you to be -more creative during the kernel exploration at the end. - -## Preparation - -We will go over setting up a development environment during the course and help -out with possible problems you run into. However, because the WiFi is likely to -be slow, we **strongly urge you to set up the following dependencies ahead of -time, preferably by downloading the provided VM image**. - -First, you will need a laptop running Linux or OS X. Linux in a VM will work -just fine, see below for a pre-made image with all the dependencies. We strongly -recommend you use the pre-made image unless you have set up and tested your -installation before the course. - -### Virtual Machine - -If you're comfortable working inside a Debian virtual machine, you can download -an image with all of the dependencies already installed -[here](http://www.scs.stanford.edu/~alevy/Tock.ova) - - * VirtualBox users: [File → Import Appliance...](https://docs.oracle.com/cd/E26217_01/E26796/html/qs-import-vm.html), - * VMWare users: [File → Open...](https://pubs.vmware.com/workstation-9/index.jsp?topic=%2Fcom.vmware.ws.using.doc%2FGUID-DDCBE9C0-0EC9-4D09-8042-18436DA62F7A.html) - -The VM account is "user" with password "user". Feel free to customize it with -whichever editors, window managers, etc. you like before the training starts. - -> If the Host OS is Linux, you may need to add your user to the `vboxusers` -> group on your machine in order to connect the hardware boards to the virtual -> machine. - -### Manual Installation - -If you would prefer not to use the virtual machine, -[there are directions for manual installation of dependencies](manual_installation.md). - -### Testing - -To test if your environment is working, go to the `tock/boards/imix` directory -and type `make program`. This should compile the kernel for the default board, -Imix, and try to program it over a USB serial connection. It may need to compile -several supporting libraries first (so may take 30 seconds or so the first -time). You should see output like this: - -``` -$ make - Compiling tock-registers v0.2.0 (file:///Users/bradjc/git/tock/libraries/tock-register-interface) - Compiling tock-cells v0.1.0 (file:///Users/bradjc/git/tock/libraries/tock-cells) - Compiling enum_primitive v0.1.0 (file:///Users/bradjc/git/tock/libraries/enum_primitive) - Compiling imix v0.1.0 (file:///Users/bradjc/git/tock/boards/imix) - Compiling kernel v0.1.0 (file:///Users/bradjc/git/tock/kernel) - Compiling cortexm v0.1.0 (file:///Users/bradjc/git/tock/arch/cortex-m) - Compiling capsules v0.1.0 (file:///Users/bradjc/git/tock/capsules) - Compiling cortexm4 v0.1.0 (file:///Users/bradjc/git/tock/arch/cortex-m4) - Compiling sam4l v0.1.0 (file:///Users/bradjc/git/tock/chips/sam4l) - Finished release [optimized + debuginfo] target(s) in 23.89s - text data bss dec hex filename - 148192 5988 34968 189148 2e2dc target/thumbv7em-none-eabi/release/imix -tockloader flash --address 0x10000 target/thumbv7em-none-eabi/release/imix.bin -No device name specified. Using default "tock" -No serial ports found. Is the board connected? - -make: *** [program] Error 1 -``` - -That is, since you don't yet have a board plugged in it can't program it. But -the above output indicates that it can compile correctly and invoke `tockloader` -to program a board. - -## Agenda - -The training is divided into three sections, each starting with a short -presentation to introduce some concepts, followed by a practical exercise. - -1. [Environment Setup](environment.md): Get familiar with the Tock tools - and getting a board setup. - -2. [Userland programming](application.md): write a basic sensing application in C. - -3. [Deliver for the Client](client.md): Help an important client get a - new board setup. - -4. [Free-form Experimentation](freeform.md): Open-ended exploration with - support from the Tock team. - diff --git a/doc/courses/2018-11-SenSys/application.md b/doc/courses/2018-11-SenSys/application.md deleted file mode 100644 index df429ab0c2..0000000000 --- a/doc/courses/2018-11-SenSys/application.md +++ /dev/null @@ -1,206 +0,0 @@ -# Write an environment sensing Bluetooth Low Energy application ---- - -## Course Agenda - -- [Introduction](README.md) -- Part 1: [Getting started with Tock](environment.md) -- **Part 2: [Application Basics](application.md)** -- Part 3: [Client Delivery](client.md) -- Part 4: [Free-form Play](freeform.md) - ---- - -## 1. Presentation: Process overview, relocation model and system call API - -In this section, we're going to learn about processes (a.k.a applications) in -Tock, and build our own applications in C. - -## 2. Check your understanding - -1. How does a process perform a blocking operation? Can you draw the flow of - operations when a process calls `delay_ms(1000)`? - -2. How would you write an IPC service to print to the console? Which functions - would the client need to call? - -## 3. Get a C application running on your board - -You'll find the outline of a C application in the directory -`docs/courses/sensys/exercises/app`. - -Take a look at the code in `main.c`. So far, this application merely prints -"Hello, World!". - -The code uses the standard C library routine `printf` to compose a message -using a format string and print it to the console. Let's break down what the -code layers are here: - -1. `printf` is provided by the C standard library (implemented by - [newlib](https://sourceware.org/newlib/)). It takes the format string and - arguments, and generates an output string from them. To actually write the - string to standard out, `printf` calls `_write`. - -2. `_write` (in `userland/libtock/sys.c`) is a wrapper for actually writing to - output streams (in this case, standard out a.k.a. the console). It calls - the Tock-specific console writing function `putnstr`. - -3. `putnstr`(in `userland/libtock/console.c`) buffers data to be written, calls - `putnstr_async`, and acts as a synchronous wrapper, yielding until the - operation is complete. - -4. `putnstr_async` (in `userland/libtock/console.c`) finally performs the - actual system calls, calling to `allow`, `subscribe`, and `command` to - enable the kernel to access the buffer, request a callback when the write is - complete, and begin the write operation respectively. - - -The application could accomplish all of this by invoking Tock system calls -directly, but using libraries makes for a much cleaner interface and allows -users to not need to know the inner workings of the OS. - - -### Loading an application - -Okay, let's build and load this simple program. - -1. Erase all other applications from the development board: - - $ tockloader erase-apps - -2. Build this application: - - $ make - -3. Load the application (Note: `tockloader install` automatically searches the - current working directory and its subdirectories for Tock binaries.) - - $ tockloader install - -4. Check that it worked: - - $ tockloader listen - -The output should look something like: - -``` -$ tockloader listen -No device name specified. Using default "tock" -Using "/dev/cu.usbserial-c098e5130012 - Hail IoT Module - TockOS" - -Listening for serial output. -Hello, World! -``` - -## 4. Creating your own application - -Now that you've got a basic app working, modify it so that it continuously -prints out `Hello World` twice per second. You'll want to use the user -library's timer facilities to manage this: - -### Timer - -You'll find the interface for timers in `userland/libtock/timer.h`. The -function you'll find useful today is: - -```c -#include -void delay_ms(uint32_t ms); -``` - -This function sleeps until the specified number of milliseconds have passed, and -then returns. So we call this function "synchronous": no further code will run -until the delay is complete. - -## 5. Write an app that periodically samples the on-board sensors - -Now that we have the ability to write applications, let's do something a little -more complex. The development board you are using has several sensors on it. -These sensors include a light sensor, a humidity sensor, and a temperature -sensor. Each sensing medium can be accessed separately via the Tock user -library. We'll just be using the light, temperature, and humidity measurements -for today's tutorial. - -#### Light - -The interface in `userland/libtock/ambient_light.h` is used to measure ambient -light conditions in [lux](https://en.wikipedia.org/wiki/Lux). imix uses the -[ISL29035](https://www.intersil.com/en/products/optoelectronics/ambient-light-sensors/light-to-digital-sensors/ISL29035.html) -sensor, but the userland library is abstracted from the details of particular -sensors. It contains the function: - -```c -#include -int ambient_light_read_intensity_sync(int* lux); -``` - -Note that the light reading is written to the location passed as an -argument, and the function returns non-zero in the case of an error. - -#### Temperature - -The interface in `userland/libtock/temperature.h` is used to measure ambient -temperature in degrees Celsius, times 100. imix uses the -[SI7021](https://www.silabs.com/products/sensors/humidity-sensors/Pages/si7013-20-21.aspx) -sensor. It contains the function: - -```c -#include -int temperature_read_sync(int* temperature); -``` - -Again, this function returns non-zero in the case of an error. - -#### Humidity - -The interface in `userland/libtock/humidity.h` is used to measure the ambient -[relative humidity](https://en.wikipedia.org/wiki/Relative_humidity) in -percent, times 100. It contains the function: - -```c -#include -int humidity_read_sync (unsigned* humi); -``` - -Again, this function returns non-zero in the case of an error. - -### Read sensors in a Tock application - -Using the example program you're working on, write an application that reads -all of the sensors on your development board and reports their readings over -the serial port. - -As a bonus, experiment with toggling an LED when readings are above or below a -certain threshold: - -#### LED - -The interface in `userland/libtock/led.h` is used to control lights on Tock boards. On the Hail -board, there are three LEDs which can be controlled: Red, Blue, and Green. The -functions in the LED module are: - -```c -#include -int led_count(void); -``` - -Which returns the number of LEDs available on the board. - -```c -int led_on(int led_num); -``` - -Which turns an LED on, accessed by its number. - -```c -int led_off(int led_num); -``` - -Which turns an LED off, accessed by its number. - -```c -int led_toggle(int led_num); -``` - -Which toggles the state of an LED, accessed by its number. - diff --git a/doc/courses/2018-11-SenSys/client.md b/doc/courses/2018-11-SenSys/client.md deleted file mode 100644 index ce54a84a27..0000000000 --- a/doc/courses/2018-11-SenSys/client.md +++ /dev/null @@ -1,202 +0,0 @@ -Part 3: Keep the client happy -============================= - ---- - -## Course Agenda - -- [Introduction](README.md) -- Part 1: [Getting started with Tock](environment.md) -- Part 2: [Application Basics](application.md) -- **Part 3: [Client Delivery](client.md)** -- Part 4: [Free-form Play](freeform.md) - ---- - -You, an engineer newly added to a top-secret project in your organization, -have been directed to commission a new imix node for your most important client. -The directions you receive are terse, but helpful: - -``` -On Sunday, Nov 4, 2018, Director Hines wrote: - -Welcome to the team, need you to get started right away. The client needs -an imix setup with their two apps -- ASAP. Make sure it is working, -we need to keep this client happy. - -- DH -``` - -Hmm, ok, not a lot to go on, but luckily in orientation you learned how -to flash a kernel and apps on to the imix board, so you are all set for -your first assignment. - -There were some other apps in `libtock-c/examples` so you go looking there first. -And sure enough there is a folder called "important-client"! And even better, -it has two apps inside of it! "Alright!" you are thinking, "My first day -is shaping up to go pretty smoothly." - -After installing those two apps, which are a little mysterious still, you -decide that it would also be a good idea to install an app you are more -familiar with: the "blink" app. After doing all of that, you run `tockloader -list` and see the following: - -``` -$ tockloader list - -No device name specified. Using default "tock" -Using "/dev/ttyUSB1 - imix IoT Module - TockOS" - -[App 0] - Name: app2 - Enabled: True - Sticky: False - Total Size in Flash: 16384 bytes - - -[App 1] - Name: app1 - Enabled: True - Sticky: False - Total Size in Flash: 8192 bytes - - -[App 2] - Name: blink - Enabled: True - Sticky: False - Total Size in Flash: 2048 bytes - - -Finished in 1.959 seconds -``` - ---- -> ### Checkpoint -> -> Make sure you have these apps installed correctly and `tockloader list` -> produces similar output as shown here. ---- - -Great! Now you check that the LED is blinking, and sure enough, no problems -there. The blink app was just for testing, so you `tockloader uninstall blink` -to remove that. So far, so good, Tock! -But, before you prepare to head home after a -successful day, you start to wonder if maybe this was a little too easy. Also, -if you get this wrong, it's not going to look good as the new person on the team. - -Looking in the folders for the two applications, you notice a brief description -of the apps, and a URL. Ok, maybe you can check if everything is working. -After trying things for a little bit, everything seems to be in order. You -tell the director the board is ready and head home a little early—you did -just successfully complete your first project for a major client after all. - - -## Back at Work the Next Day - -Expecting a more challenging project after how well things went yesterday, you are -instead greeted by this email: - -``` -On Monday, Nov 5, 2018, Director Hines wrote: - -I know you are new, but what did you do?? I've been getting calls all morning -from the client, the imix board you gave them ran out battery already!! Are you -sure you set up the board correctly? Fix it, and get it back to me later today. - -- DH -``` - -Well, that's not good. You already removed the blink app, so it can't be that. -What you need is some way to inspect the board and see if something looks like -it is going awry. You first try: - -``` -$ tockloader listen -``` - -to see if any debugging information is being printed. A little, but nothing -helpful. Before trying to look around the code, you decided to try sending the -board a plea for help: - -``` -help -``` - -and, surprisingly, it responded! - -``` -Welcome to the process console. -Valid commands are: help status list stop start -``` - -Ok! Maybe the process console can help. Try the `status` command: - -``` -Total processes: 2 -Active processes: 2 -Timeslice expirations: 4277 -``` - -It seems this tool is actually able to inspect the current system and the active -processes! But hmmm, it seems there are a lot of "timeslice expirations". From -orientation, you remember that processes are allocated only a certain quantum -of time to execute, and if they exceed that the kernel forces a context switch -back to the kernel. If that is happening a lot, then the board is likely unable -to go to sleep! That could explain why the battery is draining so fast! - -But which process is at fault? Perhaps we should try another command. -Maybe `list`: - -``` - PID Name Quanta Syscalls Dropped Callbacks State - 00 app2 0 336 0 Yielded - 01 app1 8556 1439951 0 Running - - -``` - -Ok! Now we have the status of individual applications. And aha! We can clearly -see the faulty application. From our testing we know that one app detects -button presses and one app is transmitting sensor data. Let's see if we can -disable the faulty app somehow and see which data packets we are still getting. -Going back to the help command, the `stop` command seems promising: - -``` -stop -``` - -Then checking back on the status webpage we now know what functionality we -have to fix. - - -## Time to Fix the App - -After debugging, we now know three things about the issue: - -- The name of the faulty app. -- What that app is supposed to do. -- That it is functionally correct but is for some reason consuming excess CPU cycles. - -Using this information, dig into the the faulty app. - -### A Quick Fix - -To get the director off your back, you should be able to introduce a simple fix -that will reduce wakeups by -[waiting a bit](https://github.com/tock/libtock-c/blob/21234c671eee0ae491faa5d23f35f3762b25c522/libtock/timer.h#L76) -between samples. - -### A Better Way - -While the quick fix will slow the number of wakeups, you know that you can do -better than polling for something like a button press! Tock supports -asynchronous operations allowing user processes to _subscribe_ to interrupts. - -Looking at the [button interface](https://github.com/tock/libtock-c/blob/master/libtock/button.h), -it looks like we'll first have to enable interrupts and then sign up to listen to them. - -Once this energy-optimal patch is in place, it'll be time to kick off a -triumphant e-mail to the director, and then off to celebrate with some -[baijiu](https://en.wikipedia.org/wiki/Baijiu)! - diff --git a/doc/courses/2018-11-SenSys/environment.md b/doc/courses/2018-11-SenSys/environment.md deleted file mode 100644 index b128818d27..0000000000 --- a/doc/courses/2018-11-SenSys/environment.md +++ /dev/null @@ -1,256 +0,0 @@ -# Tock OS Course Part 1: Getting your environment set up - -> While we're getting set up and started, please make sure you have -> completed all of the [tutorial pre-requisites](README.md#preparation). -> You can download a -> [virtual machine image](README.md#virtual-machine) with all the pre-requisites -> already installed. - ---- - -## Course Agenda - -- [Introduction](README.md) -- **Part 1: [Getting started with Tock](environment.md)** -- Part 2: [Application Basics](application.md) -- Part 3: [Client Delivery](client.md) -- Part 4: [Free-form Play](freeform.md) - ---- - -The goal of this part of the course is to make sure you have a working -development environment for Tock. - -During this portion of the course you will: - -- Get a high-level overview of how Tock works. -- Learn how to compile and flash the kernel onto an Imix board. - -## 1. Presentation: Tock's goals, architecture and components - - - -A key contribution of Tock is that it uses Rust's borrow checker as a -language sandbox for isolation and a cooperative scheduling model for -concurrency in the kernel. As a result, for the kernel isolation is -(more or less) free in terms of resource consumption at the expense of -preemptive scheduling (so a malicious component could block the system by, -e.g., spinning in an infinite loop). - -Tock includes three architectural components: - - - A small trusted _core kernel_, written in Rust, that implements a hardware - abstraction layer (HAL), scheduler, and platform-specific configuration. - - _Capsules_, which are compiled with the kernel and use Rust's type and - module systems for safety. - - _Processes_, which use the memory protection unit (MPU) for protection at runtime. - -Read the Tock documentation for more details on its -[design](https://github.com/tock/tock/blob/master/doc/Design.md). - -[_Presentation slides are available here._](presentation/presentation.pdf) - -## 2. Check your understanding - -1. What kinds of binaries exist on a Tock board? Hint: There are three, and - only two can be programmed using `tockloader`. - -2. What are the differences between capsules and processes? What performance - and memory overhead does each entail? Why would you choose to write - something as a process instead of a capsule and vice versa? - -3. Clearly, the core kernel should never enter an infinite loop. But is it - acceptable for a process to spin? What about a capsule? - -## 3. Compile and program the kernel - -### Make sure your Tock repository is up to date - - $ git pull - -### Build the kernel - -To build the kernel, just type make in `boards/imix/`. - - $ cd boards/imix/ - $ make - -If this is the first time you are trying to make the kernel, the build system -will use cargo and rustup to install various Tock dependencies. - -Kernels must be compiled from within the desired board's folder. For example, to -compile for Hail instead you must first run `cd boards/hail/`. - -### Connect to an imix board - -> #### One-Time Fixups -> -> * On Linux, you might need to give your user access to the imix's serial port. -> If you are using the VM, this is already done for you. -> You can do this by adding a udev rule: -> -> $ sudo bash -c "echo 'ATTRS{idVendor}==\"0403\", ATTRS{idProduct}==\"6015\", MODE=\"0666\"' > /etc/udev/rules.d/99-imix" -> -> Afterwards, detach and re-attach the imix to reload the rule. -> -> * With the virtual machine, you might need to attach the USB device to the -> VM. To do so, after plugging in imix, select in the VirtualBox/VMWare menu bar: -> -> Devices -> USB Devices -> imix IoT Module - TockOS -> -> If this generates an error, often unplugging/replugging fixes it. You can also -> create a rule in the VM USB settings which will auto-attach the imix to the VM. - -To connect your development machine to the imix, connect them with a micro-USB -cable. Any cable will do, but notice that there are two USB ports on the imix. -Make sure you connect to the micro-USB port labeled 'debug' on the imix. The -imix should come with `blink` and `c_hello` installed, which will blink the -status LED and print `Hello World` on boot respectively. - -The imix board should appear as a regular serial device (e.g. -`/dev/tty.usbserial-c098e5130006` on my Mac and `/dev/ttyUSB0` on my Linux box). -While you can connect with any standard serial program (set to 115200 baud), -tockloader makes this easier. Tockloader can read attributes from connected -serial devices, and will automatically find your connected imix. Simply run: - - $ tockloader listen - No device name specified. Using default "tock" - Using "/dev/ttyUSB0 - Imix - TockOS" - - Listening for serial output. - Initialization complete. Entering main loop - Hello World! - -### Flash the kernel - -Now that the imix board is connected and you have verified that the kernel -compiles, we can flash the imix board with the latest Tock kernel: - - $ cd boards/imix/ - $ make program - -This command will compile the kernel if needed, and then use `tockloader` to -flash it onto the imix. When the flash command succeeds, the `blink` and -`c_hello` apps should still be running and the LED will be blinking. -You now have the bleeding-edge Tock kernel running on your imix board! - -### Clear out the applications and re-flash the test app. - -Lets check what's on the board right now: - - $ tockloader list - ... - [App 0] - Name: blink - Enabled: True - Sticky: False - Total Size in Flash: 2048 bytes - - [App 1] - Name: c_hello - Enabled: True - Sticky: False - Total Size in Flash: 1024 bytes - - -As you can see, the old apps are still installed on the board. -This also nicely demonstrates that user applications are isolated from the -kernel: it is possible to update one independently of the other. -We can remove apps with the following command: - - $ tockloader uninstall - -Following the prompt, if you remove the `blink` app, the LED will stop -blinking, however the console will still print `Hello World`. - -Now let's try adding a more interesting app: - - $ cd libtock-c/examples/sensors/ - $ make program - -The `sensors` app will automatically discover all available sensors, -sample them once a second, and print the results. - - Listening for serial output. - Starting process console - Initialization complete. Entering main loop - [Sensors] Starting Sensors App. - Hello World! - [Sensors] All available sensors on the platform will be sampled. - ISL29035: Light Intensity: 453 - Temperature: 24 deg C - Humidity: 63% - - ISL29035: Light Intensity: 453 - Temperature: 24 deg C - Humidity: 63% - - -## 4. (Optional) Familiarize yourself with `tockloader` commands -The `tockloader` tool is a useful and versatile tool for managing and installing -applications on Tock. It supports a number of commands, and a more complete -list can be found in the tockloader repository, located at -[github.com/tock/tockloader](https://github.com/tock/tockloader#usage). -Below is a list of the more useful and important commands for programming and -querying a board. - -### `tockloader install` -This is the main tockloader command, used to load Tock applications onto a -board. -By default, `tockloader install` adds the new application, but does not erase -any others, replacing any already existing application with the same name. -Use the `--no-replace` flag to install multiple copies of the same app. -In order to install an app, navigate to the correct directory, make the program, -then issue the install command: - - $ cd libtock-c/examples/blink - $ make - $ tockloader install - -> *Tip:* You can add the `--make` flag to have tockloader automatically -> run make before installing, i.e. `tockloader install --make` - -> *Tip:* You can add the `--erase` flag to have tockloader automatically -> remove other applications when installing a new one. - -### `tockloader uninstall [application name(s)]` -Removes one or more applications from the board by name. - -### `tockloader erase-apps` -Removes all applications from the board. - -### `tockloader list` -Prints basic information about the apps currently loaded onto the board. - -### `tockloader info` -Shows all properties of the board, including information about currently -loaded applications, their sizes and versions, and any set attributes. - -### `tockloader listen` -This command prints output from Tock apps to the terminal. It listens via UART, -and will print out anything written to stdout/stderr from a board. - -> *Tip:* As a long-running command, `listen` interacts with other tockloader -> sessions. You can leave a terminal window open and listening. If another -> tockloader process needs access to the board (e.g. to install an app update), -> tockloader will automatically pause and resume listening. - -### `tockloader flash` -Loads binaries onto hardware platforms that are running a compatible bootloader. -This is used by the Tock Make system when kernel binaries are programmed to the -board with `make program`. - -## 5. (Optional) Explore other Tock example applications - -Other applications can be found in the `libtock-c/examples/` directory. Try -loading them on your imix and then try modifying them. By default, `tockloader -install` adds the new application, but does not erase any others. Be aware, not -all applications will work well together if they need the same resources (Tock -is in active development to add virtualization to all resources to remove this -issue!). - -**Note:** By default, the imix platform is limited to only running four -concurrent processes at once. Tockloader is (currently) unaware of this -limitation, and will allow to you to load additional apps. However the kernel -will only load the first four apps. One option for the free-form section at the -end of the tutorial will be to explore this limitation and allow more apps. diff --git a/doc/courses/2018-11-SenSys/exercises/app/.gitignore b/doc/courses/2018-11-SenSys/exercises/app/.gitignore deleted file mode 100644 index a8f4f83715..0000000000 --- a/doc/courses/2018-11-SenSys/exercises/app/.gitignore +++ /dev/null @@ -1,5 +0,0 @@ -# Licensed under the Apache License, Version 2.0 or the MIT License. -# SPDX-License-Identifier: Apache-2.0 OR MIT -# Copyright Tock Contributors 2023. - -build diff --git a/doc/courses/2018-11-SenSys/exercises/app/Makefile b/doc/courses/2018-11-SenSys/exercises/app/Makefile deleted file mode 100644 index 987e659f10..0000000000 --- a/doc/courses/2018-11-SenSys/exercises/app/Makefile +++ /dev/null @@ -1,17 +0,0 @@ -# Licensed under the Apache License, Version 2.0 or the MIT License. -# SPDX-License-Identifier: Apache-2.0 OR MIT -# Copyright Tock Contributors 2022. - -# Makefile for user application - -# Specify this directory relative to the current application. -TOCK_USERLAND_BASE_DIR = ../../../../../userland - -# Which files to compile. -C_SRCS := $(wildcard *.c) - -PACKAGE_NAME = tock-course-app - -# Include userland master makefile. Contains rules and flags for actually -# building the application. -include $(TOCK_USERLAND_BASE_DIR)/AppMakefile.mk diff --git a/doc/courses/2018-11-SenSys/exercises/app/main.c b/doc/courses/2018-11-SenSys/exercises/app/main.c deleted file mode 100644 index 76600c3c91..0000000000 --- a/doc/courses/2018-11-SenSys/exercises/app/main.c +++ /dev/null @@ -1,12 +0,0 @@ -// Licensed under the Apache License, Version 2.0 or the MIT License. -// SPDX-License-Identifier: Apache-2.0 OR MIT -// Copyright Tock Contributors 2023. - -#include -#include - -int main (void) { - printf("Hello, World!\n"); - - return 0; -} diff --git a/doc/courses/2018-11-SenSys/exercises/app/solutions/ble-ess.c b/doc/courses/2018-11-SenSys/exercises/app/solutions/ble-ess.c deleted file mode 100644 index a2653e7af9..0000000000 --- a/doc/courses/2018-11-SenSys/exercises/app/solutions/ble-ess.c +++ /dev/null @@ -1,84 +0,0 @@ -// Licensed under the Apache License, Version 2.0 or the MIT License. -// SPDX-License-Identifier: Apache-2.0 OR MIT -// Copyright Tock Contributors 2023. - -#include -#include - -#include -#include -#include -#include -#include -#include -#include - -int _svc_num = 0; - -char buf[64] __attribute__((aligned(64))); - -typedef enum { - SENSOR_TEMPERATURE = 0, - SENSOR_IRRADIANCE = 1, - SENSOR_HUMIDITY = 2, -} sensor_type_e; - -typedef struct { - int type; // sensor type - int value; // sensor reading -} sensor_update_t; - -static void ipc_callback(__attribute__ ((unused)) int pid, - __attribute__ ((unused)) int len, - __attribute__ ((unused)) int arg2, - void* ud) { - *(bool*)ud = true; - printf("Updated BLE characteristic.\n"); -} - -int main(void) -{ - _svc_num = ipc_discover("org.tockos.services.ble-ess"); - if (_svc_num < 0) { - printf("No BLE ESS service installed.\n"); - return -1; - } - - printf("Found BLE ESS service (%i)\n", _svc_num); - - delay_ms(1500); - - sensor_update_t *update = (sensor_update_t*) buf; - bool cond; - ipc_register_client_cb(_svc_num, ipc_callback, &cond); - ipc_share(_svc_num, buf, 64); - - while (true) { - int lux; - ambient_light_read_intensity_sync(&lux); - update->type = SENSOR_IRRADIANCE; - update->value = lux; - ipc_notify_svc(_svc_num); - cond = false; - yield_for(&cond); - - int temp; - temperature_read_sync(&temp); - update->type = SENSOR_TEMPERATURE; - update->value = temp; - ipc_notify_svc(_svc_num); - cond = false; - yield_for(&cond); - - unsigned humi; - humidity_read_sync(&humi); - update->type = SENSOR_HUMIDITY; - update->value = humi; - ipc_notify_svc(_svc_num); - cond = false; - yield_for(&cond); - - delay_ms(1000); - } -} - diff --git a/doc/courses/2018-11-SenSys/exercises/app/solutions/repeat-hello.c b/doc/courses/2018-11-SenSys/exercises/app/solutions/repeat-hello.c deleted file mode 100644 index 73f922a588..0000000000 --- a/doc/courses/2018-11-SenSys/exercises/app/solutions/repeat-hello.c +++ /dev/null @@ -1,16 +0,0 @@ -// Licensed under the Apache License, Version 2.0 or the MIT License. -// SPDX-License-Identifier: Apache-2.0 OR MIT -// Copyright Tock Contributors 2023. - -#include -#include - -#include - -int main (void) { - while (true) { - printf("Hello, World!\n"); - delay_ms(500); - } -} - diff --git a/doc/courses/2018-11-SenSys/exercises/app/solutions/sensors.c b/doc/courses/2018-11-SenSys/exercises/app/solutions/sensors.c deleted file mode 100644 index b1d7fb7a09..0000000000 --- a/doc/courses/2018-11-SenSys/exercises/app/solutions/sensors.c +++ /dev/null @@ -1,40 +0,0 @@ -// Licensed under the Apache License, Version 2.0 or the MIT License. -// SPDX-License-Identifier: Apache-2.0 OR MIT -// Copyright Tock Contributors 2023. - -#include -#include - -#include -#include -#include -#include -#include - -int main (void) { - while (1) { - int lux; - ambient_light_read_intensity_sync(&lux); - printf("Light: %d lux\n", lux); - - /* Turn on the red LED in low light conditions */ - if (lux < 30) { - led_on(0); - } - else { - led_off(0); - } - - int temp; - temperature_read_sync(&temp); - printf("Temperature: %d degrees C\n", temp/100); - - unsigned humi; - humidity_read_sync(&humi); - printf("Relative humidity: %u%%\n", humi/100); - - printf("\n"); - delay_ms(2000); - } -} - diff --git a/doc/courses/2018-11-SenSys/freeform.md b/doc/courses/2018-11-SenSys/freeform.md deleted file mode 100644 index 2452517756..0000000000 --- a/doc/courses/2018-11-SenSys/freeform.md +++ /dev/null @@ -1,45 +0,0 @@ -# Free-form Experimentation ---- - -## Course Agenda - -- [Introduction](README.md) -- Part 1: [Getting started with Tock](environment.md) -- Part 2: [Application Basics](application.md) -- Part 3: [Client Delivery](client.md) -- **Part 4: [Free-form Play](freeform.md)** - ---- - -These are seedling ideas, feel free to try one of these or anything else that -strikes your fancy! - -## Kernel Hacking - - - Understanding board configuration: - - Look into the four-process limitation, where does it come from, can we add more processes, how? - - How are pins mapped and buses configured? Could we do something like tie the LED to be a SPI status indicator? - - - Add a new capsule to the kernel (write it, include it in the crate, - initialize it in a boot sequence). - - Can you send 802.15.4 packets directly from the within the kernel? - -## Userland Hacking - - - What other sensors and interfaces are available? - - Write a thermal alarm app? - - Write a light-change triggering motion detector app? - - Understand how the timer interface works and virtual timers? - - - Execution model - - What happens when there are multiple concurrent interrupts? - - How do blocking calls and callbacks interplay? - -## End-to-End Comprehension - - - What happens when your app returns from main? When will it run again (if at all)? - - - Can you diagram what happens when a process makes a blocking system call - (context switch, interrupt setup, wait_for, interrupt handling, kernel - thread, resuming process)? - diff --git a/doc/courses/2018-11-SenSys/img/architecture.png b/doc/courses/2018-11-SenSys/img/architecture.png deleted file mode 100644 index 5cce5a1cda..0000000000 Binary files a/doc/courses/2018-11-SenSys/img/architecture.png and /dev/null differ diff --git a/doc/courses/2018-11-SenSys/manual_installation.md b/doc/courses/2018-11-SenSys/manual_installation.md deleted file mode 100644 index 4442ae3e3f..0000000000 --- a/doc/courses/2018-11-SenSys/manual_installation.md +++ /dev/null @@ -1,46 +0,0 @@ -## Manual Installation - -If you choose to install manually, you will need the following software: - -1. Command line utilities: curl, make, git - -1. Python 3 and pip3 - -1. A local clone of the Tock repository - - $ git clone https://github.com/tock/tock.git - -1. A local clone of the Tock applications repository (for apps written in C) - - $ git clone https://github.com/tock/libtock-c.git - -1. [rustup](http://rustup.rs/). This tool helps manage installations of the - Rust compiler and related tools. - - $ curl https://sh.rustup.rs -sSf | sh - -1. [arm-none-eabi toolchain](https://developer.arm.com/open-source/gnu-toolchain/gnu-rm/downloads) (version >= 5.2) - - OS-specific installation instructions can be found - [here](https://github.com/tock/tock/blob/master/doc/Getting_Started.md#arm-none-eabi-toolchain) - -1. [tockloader](https://github.com/tock/tockloader) - - $ pip3 install -U --user tockloader - - > Note: On MacOS, you may need to add `tockloader` to your path. If you - > cannot run it after installation, run the following: - - $ export PATH=$HOME/Library/Python/3.6/bin/:$PATH - - > Similarly, on Linux distributions, this will typically install to - > `$HOME/.local/bin`, and you may need to add that to your `$PATH` if not - > already present: - - $ PATH=$HOME/.local/bin:$PATH - - -### Testing - -To verify you have everything installed correctly, -[hop back over to the testing directions in the main README](README.md#testing). diff --git a/doc/courses/2018-11-SenSys/presentation/Makefile b/doc/courses/2018-11-SenSys/presentation/Makefile deleted file mode 100644 index ca03775ef8..0000000000 --- a/doc/courses/2018-11-SenSys/presentation/Makefile +++ /dev/null @@ -1,8 +0,0 @@ -# Licensed under the Apache License, Version 2.0 or the MIT License. -# SPDX-License-Identifier: Apache-2.0 OR MIT -# Copyright Tock Contributors 2022. - -all: presentation.pdf - -presentation.pdf: slides.md - pandoc -s --pdf-engine xelatex -t beamer $< -o $@ diff --git a/doc/courses/2018-11-SenSys/presentation/architecture.pdf b/doc/courses/2018-11-SenSys/presentation/architecture.pdf deleted file mode 100644 index ce6aca54cd..0000000000 Binary files a/doc/courses/2018-11-SenSys/presentation/architecture.pdf and /dev/null differ diff --git a/doc/courses/2018-11-SenSys/presentation/execution.pdf b/doc/courses/2018-11-SenSys/presentation/execution.pdf deleted file mode 100644 index 00d66b3c7a..0000000000 Binary files a/doc/courses/2018-11-SenSys/presentation/execution.pdf and /dev/null differ diff --git a/doc/courses/2018-11-SenSys/presentation/imix.png b/doc/courses/2018-11-SenSys/presentation/imix.png deleted file mode 100644 index ef3ca4620e..0000000000 Binary files a/doc/courses/2018-11-SenSys/presentation/imix.png and /dev/null differ diff --git a/doc/courses/2018-11-SenSys/presentation/slides.md b/doc/courses/2018-11-SenSys/presentation/slides.md deleted file mode 100644 index f7e8810f1c..0000000000 --- a/doc/courses/2018-11-SenSys/presentation/slides.md +++ /dev/null @@ -1,349 +0,0 @@ ---- -title: Tock Embedded OS Tutorial -date: SenSys 2018 -header-includes: - - \beamertemplatenavigationsymbolsempty - - \usepackage{pifont} - - \newcommand{\cmark}{\color{green}\ding{51}} - - \newcommand{\xmark}{\color{red}\ding{55}} - - \setbeamerfont{note page}{family*=pplx,size=\large} - - \usefonttheme{professionalfonts} - - \setmainfont{Source Sans Pro} - - \setsansfont{Source Sans Pro} ---- - -## Tock - -A secure operating system for microcontrollers - - * Kernel components in Rust - - * Type-safe API for safe driver development - - * Hardware isolated processes for application code - -## Microcontrollers - -System-on-a-chip with integrated flash, SRAM, CPU and a bunch of hardware -controllers. - -Typically: - - * Communication: UART, SPI, I2C, USB, CAN... - - * External I/O: GPIO, external interrupt, ADC, DAC - - * Timers: RTC, countdown timers - -Maybe... - - * Radio (Bluetooth, 15.4) - - * Cryptographic accelerators - - * Other specialized hardware... - -## Low Resource - - * 10's of µA average power draw - - * 10's of kBs of RAM - - * Moderate clock speeds - -## Use cases - - * Security applications (e.g. authentication keys) - - * Sensor networks - - * Programmable wearables - - * PC/phone peripherals - - * Home/industrial automation - - * Flight control - -## Two types of components: capsules and processes - -![](architecture.pdf) - -## Two types of scheduling: cooperative and preemptive - -![](execution.pdf) - -## Agenda Today - -| | | -|-------------+-------------| -| 09:30-10:40 | Intro to Tock, Development Environment & Hardware | -| 10:40-11:00 | Coffee break | -| 11:00-12:00 | Hardware setup and installing apps | -| 12:00-13:30 | Lunch | -| 13:30-15:20 | Find and fix a real world bug | -| 15:20-15:40 | Coffee break | -| 15:40-17:30 | Choose your own adventure | - -# Part 1: Hardware, tools, and development environment - -* * * - -![](imix.png) - -## imix - - - Atmel SAM4L, Cortex-M4, 64 kB RAM, 256 kB flash - - - Nordic NRF51 Bluetooth SoC - - - 802.15.4 radio (6lowpan) - - - Temperature, humidity, and light sensors - - - 2 USBs (target USB + FTDI serial USB) - - - 2 LEDs, 1 "user" button - -## Binaries on-board in flash - - - `0x00000`: **Bootloader**: Interact with Tockloader; load code - - - `0x10000`: **Kernel** - - - `0x40000`: **Processes**: Packed back-to-back - -## Tools - - * `make` - - * Rust/Cargo (Rust code → Cortex-M) - - * `arm-none-eabi` (C → Cortex-M) - - * `tockloader` to interact with imix and the bootloader - -## Tools: `tockloader` - -Write a binary to a particular address in flash - -```bash -$ tockloader flash --address 0x10000 \ - target/thumbv7em-none-eabi/release/imix.bin -``` - -Program a process in Tock Binary Format[^footnote]: - -```bash -$ tockloader install myapp.tab -``` - -Restart the board and connect to the debug console: - -```bash -$ tockloader listen -``` - -[^footnote]: TBFs are relocatable process binaries prefixed with headers like - the package name. `.tab` is a tarball of TBFs for different architectures as - well as a metadata file for `tockloader`. - -## Check your understanding - -Turn to the person next to you: - - 1. What kinds of binaries exist on a Tock board? - _Hint: There are three, and only two can be programmed using `tockloader`._ - - 2. What steps would you follow to program a process onto imix? What about - to replace the kernel? - -## Answers - - 1. The three binaries are the serial bootloader, the kernel, and a series of - processes. The bootloader can be used to load the kernel and processes, but - cannot replace itself. - - 2. Use `tockloader`: - - * `tockloader install app.tab` - - * `tockloader flash --address 0x10000 imix-kernel.bin` - -## Hands-on: Set-up development environment - - 3. Compile and program the kernel - - 4. (Optional) Familiarize yourself with `tockloader` commands - - * `uninstall` - - * `list` - - * `erase-apps` - - 5. (Optional) Add some other apps from the repo, like `blink` and `sensors` - - - - Head to to get started! - - \tiny ([https://github.com/tock/tock/blob/tutorial-sensys-2018/doc/courses/sensys/environment.md](https://github.com/tock/tock/blob/tutorial-sensys-2018/doc/courses/sensys/environment.md)) - -# Part 2: User space programming - -## System calls - -Tock supports five syscalls that applications use to interact with the kernel. - -| **Call** | **Target** | **Description** | -|:----------|:----------:|----------------------------------| -| command | Capsule | Invoke an operation on a capsule | -| allow | Capsule | Share memory with a capsule | -| subscribe | Capsule | Register an upcall | -| memop | Core | Modify memory break | -| yield | Core | Block until next upcall is ready | - -## C System Calls: `command` & `allow` - -```c -// Start an operation -int command(u32 driver, u32 command, int arg1, int arg2); - -// Share memory with the kernel -int allow(u32 driver, u32 allow, void* ptr, size_t size); -``` - -## C System Calls: `subscribe` - -```c -// Callback function type -typedef void (sub_cb)(int, int, int, void* userdata); - -// Register a callback with the kernel -int subscribe(u32 driver, - u32 subscribe, - sub_cb cb, - void* userdata); -``` - -## C System Calls: `yield` & `yield_for` - -```c -// Block until next callback -void yield(void); - -// Block until a specific callback -void yield_for(bool *cond) { - while (!*cond) { - yield(); - } -} -``` - - - -## Example: printing to the debug console - -```c -#define DRIVER_NUM_CONSOLE 0x0001 - -bool done = false; - -static void putstr_cb(int x, int y, int z, void* ud) { - done = true; -} - -int putnstr(const char *str, size_t len) { - allow(DRIVER_NUM_CONSOLE, 1, str, len); - subscribe(DRIVER_NUM_CONSOLE, 1, putstr_cb, NULL); - command(DRIVER_NUM_CONSOLE, 1, len, 0); - yield_for(&done); - - return Ok(()); -} -``` - -## Hands-on: Write a simple application - - 3. Get an application running on imix - - 4. [Print "Hello World" every second](https://github.com/tock/tock/blob/tutorial-sensys-2018/doc/courses/sensys/exercises/app/solutions/repeat-hello.c) - - 5. [Extend your app to sample on-board sensors](https://github.com/tock/tock/blob/tutorial-sensys-2018/doc/courses/sensys/exercises/app/solutions/sensors.c) - - - Head to to get started! - - \tiny ([https://github.com/tock/tock/blob/tutorial-sensys-2018/doc/courses/sensys/application.md](https://github.com/tock/tock/blob/tutorial-sensys-2018/doc/courses/sensys/application.md#2-check-your-understanding)) - -# Part 3: Deliver for the Client - -## Debugging in a Multi-app Setting - - * Multiprogramming -> multiple things can go wrong - - * Multiprogramming _enables_ better debugging facilities - - - Monitor individual application state - - - Disable only faulty applications - - - Replace only parts of the system - -## The Process Console on imix - -Keeps track of system calls and timeslice expirations for each process. - -Provides basic debugging facilities over UART: - - * `status` - - * `list` - - * `stop [app_name]` - - * `start [app_name]` - -## Our task - - * Fix a "deployed" with two mysteriously named processes: - - `app1` & `app2` - - * Networked over UDP/6LoWPAN - - - One sends button presses - - - Another sends periodic temperature, humidty and light data - - * Functional, but seem to be draining battery! - -_Find and fix the problem!_ - -## Stay in touch! - - - - - - - -\medskip - -\hrule - diff --git a/doc/courses/README.md b/doc/courses/README.md deleted file mode 100644 index e1e8a699a3..0000000000 --- a/doc/courses/README.md +++ /dev/null @@ -1,30 +0,0 @@ -Tock courses -================== - ---- -**NOTE** - -These courses all use Tock version 1 (e.g., 1.2, 1.3). -Tock development is currently on version 2. -The major difference between the two versions is the -system call ABI/API. If you are interested in writing applications on Tock, -the changes appear very small, as userspace libraries hide the differences. -The differences between version 1 and version 2 are most significant if you -want to write system call drivers for kernel services. - -We hope to write a course for version 2 soon. Until then, the -[Tock book](https://book.tockos.org/) is a good place to start. It has -been updated to Tock v2. - ---- - - -Courses are a great way to start learning Tock. They take you to the entire -process of getting started, writing an application, and adding a capsule to the -kernel. There are currently three different courses available, corresponding to -the three conferences we've given workshops at: - -- **[RustConf](rustconf)** - For the user familiar with Rust. -- **[Sensys](2018-11-SenSys)** - For the user familiar with embedded networked sensor systems. -- **[SOSP](sosp)** - For the user familiar with operating systems. - diff --git a/doc/courses/rustconf/README.md b/doc/courses/rustconf/README.md deleted file mode 100644 index 3eaec2fc90..0000000000 --- a/doc/courses/rustconf/README.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -location: Portland, OR, USA -date: August 19th 2017 ---- - -# Tock OS Training @ RustConf 2017 - ---- -**NOTE** - -This course was primarily designed in the summer of 2017. It focuses on -presenting Tock to a Rust (rather than research) audience. It is no longer -updated. For example, this course uses Tock version 1.2, and current Tock -development is on version 2.x. - ---- - - -Put Rust to practice in low-level embedded systems. This training will introduce -cover programming for Tock, a secure embedded operating system for sensor -networks and the Internet of Things, written in Rust. You will learn to write -kernel extensions, the basics of porting Tock to a new platform, and how to -write power- and memory-efficient applications. We will also give an overview of -the system architecture. - -This tutorial assumes basic knowledge of Rust, including ownership, borrowing, -traits, and lifetimes. While not required, it is most appropriate for people who -are familiar with the material covered in the Advanced Rust training, and -attending the morning Intermediate Rust training is highly encouraged. - -## Pre-requisites - -We will go over setting up a development environment during the training. -However, because the WiFi might not provide the fastest Internet connection in -the world, it would be useful to set up the following dependencies ahead of -time: - -1. A laptop running Linux or OS X. Linux in a VM will work just fine, see below - for a pre-made image with all the dependencies. - -2. Command line utilities: wget, make, cmake, git - -4. Python 3 and pip - -5. A local clone of the Tock repository - - $ git clone https://github.com/tock/tock.git - -6. [rustup](http://rustup.rs/). - - $ curl https://sh.rustup.rs -sSf | sh - -8. [arm-none-eabi toolchain](https://developer.arm.com/open-source/gnu-toolchain/gnu-rm/downloads) (version >= 5.2) - - > Note that you can install the version packaged by your Linux distribution, - > but make sure you install the newlib port as well. For instance, on Debian or - > Ubuntu, install both gcc-arm-none-eabi and libnewlib-arm-none-eabi. - -9. [tockloader](https://github.com/tock/tockloader) - - $ pip3 install -U --user tockloader - - > Note: On MacOS, you may need to add `tockloader` to your path. If you - > cannot run it after installation, run the following: - - $ export PATH=$HOME/Library/Python/3.6/bin/:$PATH - - > Similarly, on Linux distributions, this will typically install to - > `$HOME/.local/bin`, and you may need to add that to your `$PATH` if not - > already present: - - $ PATH=$HOME/.local/bin:$PATH - -### Virtual Machine - -If you're comfortable working inside a Debian virtual machine, you can download -an image with all of the dependencies already installed -[here](https://www.dropbox.com/s/5km04herxa9h05w/Tock.ova?dl=0) -(VirtualBox users: -[File → Import Appliance...](https://docs.oracle.com/cd/E26217_01/E26796/html/qs-import-vm.html), -VMWare users: -[File → Open...](https://pubs.vmware.com/workstation-9/index.jsp?topic=%2Fcom.vmware.ws.using.doc%2FGUID-DDCBE9C0-0EC9-4D09-8042-18436DA62F7A.html) -). -The VM account is "user" with password "user". -Feel free to customize it with whichever editors, window managers, etc you like -before the training starts. - -> #### Heads Up! -> There's a small error in the VM configuration. You'll need to manually -> `source ~/.profile` when you open a new terminal to set up all the needed -> paths. - -## Agenda - -The training is divided into three sections, each starting with a short -presentation to introduce some concepts, followed by a practical exercise. - -1. [Getting your environment set up](environment.md) (~1 hour) - -2. [Add a new capsule to the kernel](capsule.md) (~2 hours) - -3. [Write an environment sensing Bluetooth Low Energy - application](application.md) (~1 hour) - diff --git a/doc/courses/rustconf/application.md b/doc/courses/rustconf/application.md deleted file mode 100644 index b10bd3ee69..0000000000 --- a/doc/courses/rustconf/application.md +++ /dev/null @@ -1,353 +0,0 @@ -# Write an environment sensing Bluetooth Low Energy application - -## 1. Presentation: Process overview, relocation model and system call API - -In this section, we're going to learn about processes (a.k.a applications) in -Tock, and build our own applications in Rust. - -## 2. Check your understanding - -1. How does a process perform a blocking operation? Can you draw the flow of - operations when a process calls `delay_ms(1000)`? - -2. What is a Grant? How do processes interact with grants? Hint: Think about - memory exhaustion. - -## 3. Get a Rust application running on Hail - -First, clone the tock-rust-template repository. - - $ git clone https://github.com/tock/tock-rust-template.git - -This is the base for Tock applications written in Rust. Your code goes in the -`src` folder in `main.rs`. The `Cargo` files are Rust build -configurations. The `thumbv7em-tock-eabi.json` and `layout.ld` files are code -compilation configurations. The Makefile uses `cargo` to create ELF files, and -several scripts in `tools/` to build Tock binaries, with all built output going -in the directory `target/thumb7em-tock-eabi/release/`. - -First, lets look at the application code. `main()` is the function called when -the app is started. The base functionality of it creates a Tock console object -and then prints a message through it via the `write!` macro. The -[`alloc`](https://doc.rust-lang.org/beta/alloc/) crate is used to make the -`write_fmt` function inside of `write!` work. Note that `write!` returns a -`Result`, which we call unwrap on to handle. - -We also use the [Tock crate](https://github.com/tock/libtock-rs) -which contains the Rust library for interacting with a Tock kernel. Two pieces -of Tock functionality which we will explain here are the Console and Timer -modules that the Tock crate exports. - -#### Console - -`tock::console::Console` is used to send messages over the USB connection on a -Hail (technically it sends serial data through a UART to an FTDI UART-to-USB -chip, but same difference). Its functions are: - - pub fn new() -> Console - - Creates, initializes, and returns a new Console struct. - - pub fn write(&mut self, string: String) - - Writes a string object to the Console. - -`Console` also implements `fmt::write`, which enables the `write!` macro to -work. We recommend using -[`write!`](https://doc.rust-lang.org/1.5.0/std/macro.write!.html) for this -tutorial, as it allows you to use [format -options](https://doc.rust-lang.org/1.5.0/std/fmt/) while printing. - -#### Timer - -`tock::timer` is used to trigger events at a specific number of seconds in the -future. It has several functions, only one of which will be used today: - - pub fn delay_ms(ms: u32) - - Sleeps until the specified number of milliseconds have passed, at which - point this function will return. Note that this is synchronous, and no - further code will run until the delay is complete. - -### Loading a Rust application - -Now, lets build and load the base template application in `src/main.rs`. - -1. Erase all other applications from the Hail. - - tockloader erase-apps - -2. Build this Rust application. - - make - -3. Load the Rust application. (note: `tockloader install` automatically - searches subdirectories for Tock binaries) - - tockloader install - -4. Check that it worked. - - tockloader listen - -The expected output should look like: - -``` -$ tockloader listen -No device name specified. Using default "tock" -Using "/dev/cu.usbserial-c098e5130012 - Hail IoT Module - TockOS" - -Listening for serial output. -Tock App -``` - -### Creating your own Rust application - -Now that you've got a basic Rust app working, modify it so that it continuously -prints out `Hello World` twice per second. Note the Tock function `delay_ms` as -explained above, as well as the Rust -[loop](https://doc.rust-lang.org/1.6.0/book/loops.html) instruction. - - -## 4. Write an app that periodically samples the on-board sensors - -Now that we have the ability to write Tock applications in Rust, lets do -something a little more complex. The Hail board you are using has several -sensors on it [as shown here](https://github.com/tock/tock/blob/master/boards/hail/media/hail_reva_noheaders_labeled.png). -These sensors include a light sensor, a humidity and temperature sensor, and an -acceleration and magnetic field sensor (marked as accelerometer in the -picture). Each sensing medium can be accessed separately through the Tock -crate, each within the `sensors` module. - -#### Light - -`tock::sensors::AmbientLightSensor` is used to measure ambient light conditions -in [lux](https://en.wikipedia.org/wiki/Lux). Specifically, it uses the sensor -[ISL29035](https://www.intersil.com/en/products/optoelectronics/ambient-light-sensors/light-to-digital-sensors/ISL29035.html). -It has the function: - - pub fn read(&mut self) -> Reading - - Where a Reading in this case is implemented as the type `AmbientLight`, - which is capable of being cast into an `i32` or printed in a message. - -#### Temperature - -`tock::sensors::TemperatureSensor` is used to measure ambient temperature in degrees -Celsius. It uses the [SI7021](https://www.silabs.com/products/sensors/humidity-sensors/Pages/si7013-20-21.aspx) -sensor. It has the function: - - pub fn read(&mut self) -> Reading - - Where a Reading in this case is implemented as the type `Temperature`, which - is capable of being cast into an `i32` or printed in a message. - -#### Humidity - -`tock::sensors::HumiditySensor` is used to measure the ambient -[relative humidity](https://en.wikipedia.org/wiki/Relative_humidity) in -percent. It has the function: - - pub fn read(&mut self) -> Reading - - Where a Reading in this case is implemented as the type `Humdity`, which - is capable of being cast into an `i32` or printed in a message. - -#### Nindedof - -`tock::sensors::Ninedof` is used to read acceleration or magnetic field -strength from the -[FXOS8700CQ](http://www.nxp.com/products/sensors/6-axis-sensors/digital-sensor-3d-accelerometer-2g-4g-8g-plus-3d-magnetometer:FXOS8700CQ). -Note that Hail's hardware implementation of the Ninedof does not include the -traditional rotational sensor. It has the functions: - - pub unsafe fn new() -> Ninedof - - Which creates a new Ninedof struct on which the following functions may be - called. Note that this function is `unsafe` and must be called within an - unsafe block. - - pub fn read_acceleration(&mut self) -> NinedofReading - - Which reads acceleration in [g's](https://en.wikipedia.org/wiki/G-force) in - the x, y, and z orientations. - - pub fn read_magnetometer(&mut self) -> NinedofReading - - Which reads magnetic field strength in - [microTeslas](https://en.wikipedia.org/wiki/Tesla_(unit)) in the x, y, and z - orientations. - -It also has the NinedofReading struct: - - pub struct NinedofReading { - pub x: i32, - pub y: i32, - pub z: i32 - } - - Which has `fmt:Display` implemented for it and thus can be directly printed. - - -### Read sensors in a Tock application - -Using the tock-rust-template, write an application that reads all of the -sensors on Hail and reports their readings over serial. As a bonus, experiment -with turning on/or off an LED when readings are above or below a certain -threshold. - -#### LED - -`tock::led` is used to control lights on Tock boards. On the Hail board, there -are three LEDs: Red, Blue, and Green which can be controlled. The functions in -the LED module are: - - pub fn count() -> isize - - Which returns the number of LEDs available on a board. - - pub fn on(led_num: u32) - - Which turns an LED on, accessed by its number. - - pub fn off(led_num: u32) - - Which turns an LED off, accessed by its number. - - pub fn toggle(led_num: u32) - - Which changes the state of an LED, accessed by its number. - -[Sample Solution](https://gist.github.com/alevy/73d0a1e5c8784df066c86dc5da9d3107). - - -## 5. Extend your app to report through the `ble-env-sense` service - -Finally, lets explore accessing the Bluetooth Low-Energy (BLE) capabilities of -the hardware. The Hail board has an -[nRF51822](https://www.nordicsemi.com/eng/Products/Bluetooth-low-energy/nRF51822) -radio which provides BLE communications. Given that and the sensors available, -we can use Tock to provide the BLE -[Environmental Sensing Service](https://www.bluetooth.com/specifications/assigned-numbers/environmental-sensing-service-characteristics) -(ESS). - -Currently, the Tock libraries for Rust do not support directly -interacting with the BLE radio. However, we can still access BLE by loading an -additional process on the board as a service and sending it commands over -Tock's inter-process communication (IPC) method. - -### Loading the BLE ESS Service - -The BLE ESS service can be found in the main Tock repository under -`userland/examples/services/ble-env-sense`. It accepts commands over IPC and -updates the BLE ESS service, which is broadcasts through the BLE radio. - -Before we load the service though, you should chose modify its name so that -you'll be able to tell your Hail apart from everyone else's (be sure to pick -something short but reasonably unique). On Line 32, change the adv_name to a -string of your choice. For example: - -``` - .adv_name = "AmitHail", -``` - -Once you've changed the name, we can load the service onto the Hail. - -``` -$ tockloader erase-apps -$ cd userland/examples/services/ble-env-sense/ -$ make program -$ tockloader listen -... -[BLE] Environmental Sensing IPC Service -... -``` - -### Using the BLE ESS Service from a Rust application - -Now that we've got the service loaded, we can build our own application to use -it in the tock-rust-template repository. - -**IMPORTANT** - -For this section only, the `layout.ld` file needs to be modified. On Line 18, -the FLASH ORIGIN needs to be changed to `0x00040038`. This places the Rust -application after the BLE ESS service in memory (and will not be necessary soon -when we get Rust applications compiling as position independent code). It -should look like this: - -``` - FLASH (rx) : ORIGIN = 0x00040038, LENGTH = PROG_LENGTH -``` - -#### IPC to the BLE ESS Service - -`tock::ipc::ble_ess` allows for data to be sent to the BLE ESS service via -Tock's inter-process communication mechanism. It has one function: - - pub fn connect() -> Result - - This connects to the BLE ESS service over IPC, returning a - [Result](https://doc.rust-lang.org/std/result/) with a BleEss struct. - -The BleEss struct itself has one function: - - pub fn set_reading(&mut self, sensor: ReadingType, data: I) -> Result<(), ()> - - Which takes a ReadingType and a measurement, and updates it in the - Environmental Sensing Service. - -The `tock::ipc::ble_ess` also has the ReadingType enum: - - pub enum ReadingType { - Temperature = 0, - Humidity = 1, - Light = 2 - } - - Note that the ESS does not accept acceleration or magnetic field strength - measurements. - - -Now that you've got the IPC library, you should be able to write an app that -sends data over BLE. To get you started, here are what the first couple lines -will probably look like: - -``` -#![feature(alloc)] -#![no_std] - -extern crate alloc; -extern crate tock; - -use alloc::fmt::Write; -use tock::console::Console; -use tock::ipc::ble_ess::{self, ReadingType}; -use tock::sensors::{AmbientLightSensor, TemperatureSensor, HumiditySensor, Nindedof}; - -#[inline(never)] -fn main() { - let mut console = Console::new(); - write!(&mut console, "Starting BLE ESS\n").unwrap(); - - let mut ess = match ble_ess::connect() { - Ok(ess) => ess, - _ => { - write!(&mut console, "BLE IPC Service not installed\n").unwrap(); - return - } - }; - write!(&mut console, "Found BLE IPC Service\n").unwrap(); - ... -``` - -To test that everything is working, you can connect to your Hail with a -smartphone. We recommend the nRF Connect app -[[Android](https://play.google.com/store/apps/details?id=no.nordicsemi.android.mcp&hl=en) - | [iOS](https://itunes.apple.com/us/app/nrf-connect/id1054362403?mt=8)]. -The BLE address of the Hail is labeled on its bottom, however iOS devices -cannot access the address of a BLE device. However, you should be able to see -the unique name that you chose earlier. - -[Sample Solution](https://gist.github.com/alevy/a274981a29ffc00230aa16101ee0b89f). - diff --git a/doc/courses/rustconf/architecture.png b/doc/courses/rustconf/architecture.png deleted file mode 100644 index 5cce5a1cda..0000000000 Binary files a/doc/courses/rustconf/architecture.png and /dev/null differ diff --git a/doc/courses/rustconf/capsule.md b/doc/courses/rustconf/capsule.md deleted file mode 100644 index da22382a36..0000000000 --- a/doc/courses/rustconf/capsule.md +++ /dev/null @@ -1,457 +0,0 @@ -### Tock OS Course Part 2: Adding a New Capsule to the Kernel - -The goal of this part of the course is to make you comfortable with the -Tock kernel and writing code for it. By the end of this part, you'll have -written a new capsule that reads a 9DOF (nine degrees of freedom, consisting -of a 3-axis accelerometer, magnetometer, and gyroscope) sensor and outputs -its readings over the serial port. - -During this you will: - -1. Learn how Tock uses Rust's memory safety to provide isolation for free -2. Read the Tock boot sequence, seeing how Tock uses static allocation -3. Learn about Tock's event-driven programming -4. Write a new capsule that reads a 9DOF sensor and prints it over serial - -#### 1. Listen to presentation on Tock's kernel and capsules - -This part of the course will start with a member of the Tock development -team presenting its core software architecture. This will explain how a -Tock platform has a small amount of trusted (can use `unsafe`) code, but -the bulk of the kernel code is in *capsules*, which cannot violate Rust's -safety guarantees. It'll also explain how RAM constraints lead the Tock -kernel to rely on static allocation and use a purely event-driven execution -model. - -This presentation will give you the intellectual framework to understand -why capsules work as they do, and understand what you'll be doing in the rest -of this part of the course. - -#### 2. Check your understanding - -1. What is a `VolatileCell`? Can you find some uses of `VolatileCell`, and do you understand why they are needed? Hint: look inside `chips/sam4l/src`. -2. What is a `TakeCell`? When is a `TakeCell` preferable to a standard `Cell`? - -#### 3. Read the Tock boot sequence (20m) - -Open `boards/hail/src/main.rs` in your favorite editor. This file defines the -Hail platform: how it boots, what capsules it uses, and what system calls it -supports for userland applications. - -##### 3.1 How is everything organized? - -Find the declaration of `struct Hail` (it's pretty early in the file). -This declares the structure representing the platform. It has many fields, -all of which are capsules. These are the capsules that make up the Hail -platform. For the most part, these map directly to hardware peripherals, -but there are exceptions such as `IPC` (inter-process communication). - -Recall the discussion about how everything in the kernel is statically -allocated? We can see that here. Every field in `struct Hail` is a reference to -an object with a static lifetime. - -The capsules themselves take a lifetime as a parameter, which is currently -always `` `static``. The implementations of these capsules, however, do not -rely on this assumption. - -The boot process is primarily the construction of this `Hail` structure. Once -everything is set up, the board will pass the constructed `hail` to -`kernel::main` and we're off to the races. - -##### 3.2 How do things get started? - -The method `reset_handler` is invoked when the chip resets (i.e., boots). -It's pretty long because Hail has a lot of drivers that need to be created -and initialized, and many of them depend on other, lower layer abstractions -that need to be created and initialized as well. - -Take a look at the first few lines of the `reset_handler`. The boot sequence -initializes memory (copies initialized variables into RAM, clears the BSS), -sets up the system clocks, and configures the GPIO pins. - -##### 3.3 How do capsules get created? - -The next lines of `reset_handler` create and initialize the system console, -which is what turns calls to `print!` into bytes sent to the USB serial port: - -```rust -let console = static_init!( - Console, - Console::new(&usart::USART0, - 115200, - &mut console::WRITE_BUF, - kernel::Container::create())); -hil::uart::UART::set_client(&usart::USART0, console); -``` - -Eventually, once all of the capsules have been created, we will populate -a Hail structure with them: - -```rust -let hail = Hail { - console: console, - gpio: gpio, - ... -``` - -The `static_init!` macro is simply an easy way to allocate a static -variable with a call to `new`. The first parameter is the type, the second -is the expression to produce an instance of the type. This call creates -a `Console` that uses serial port 0 (`USART0`) at 115200 bits per second. - -> ##### A brief aside on buffers: -> -> Notice that you have to pass a write buffer to the console for it to use: -> this buffer has to have a `` `static`` lifetime. This is because low-level -> hardware drivers, especially those that use DMA, require `` `static`` buffers. -> Since Tock doesn't promise when a DMA operation will complete, and you -> need to be able to promise that the buffer outlives the operation, the -> one lifetime that is assured to be alive at the end of an operation is -> `` `static``. So that other code which has buffers -> without a `` `static`` lifetime, such as userspace processes, can use the -> `Console`, it copies them into its own internal `` `static`` buffer before -> passing it to the serial port. So the buffer passing architecture looks like -> this: -> -> ![Console/UART buffer lifetimes](console.png) -> -> It's a little weird that Console's `new` method takes in a reference to -> itself. This is an ergonomics tradeoff. The Console needs a mutable static -> buffer to use internally, which the Console capsule declares. However writing -> global statics is unsafe. To avoid the unsafe operation in the Console -> capsule itself, we make it the responsibility of the instantiator to give the -> Console a buffer to use, without burdening the instantiator with sizing the -> buffer. - -The final parameter, the `Container`, is for handling system calls: -you don't need to worry about it for now. - -##### 3.4 Let's make a Hail! - -The code continues on, creating all of the other capsules that are needed -by the hail platform. By the time we get down to around line 360, we've -created all of the capsules we need, and it's time to create the actual -hail platform structure (`let hail = Hail {` ...). - -##### 3.5 Capsule _initialization_ - -Up to this point we have been creating numerous structures and setting some -static configuration options and mappings, but nothing dynamic has occurred -(said another way, all methods invoked by `static_init!` must be `const fn`, -however Tock's `static_init!` macro predates stabilization of `const fn`'s. -A future iteration could possibly leverage these and obviate the need for the -macro). - -Some capsules require _initialization_, some code that must be executed -before they can be used. For example, a few lines after creating the hail -struct, we initialize the console: - -```rust -hail.console.initialize(); -``` - -This method is responsible for actually writing the hardware registers that -configure the associated UART peripheral for use as a text console -(8 data bits, 1 stop bit, no parity bit, no hardware flow control). - -##### 3.6 Inter-capsule dependencies - -Just after initializing the console capsule, we find this line: - -```rust -kernel::debug::assign_console_driver(Some(hail.console), kc); -``` - -This configures the kernel's `debug!` macro to print messages to this console -we've just created. The `debug!` mechanism can be very helpful during -development and testing. Today we're going to use it to print output from the -capsule you create. - -Let's try it out really quick: - -```diff ---- a/boards/hail/src/main.rs -+++ b/boards/hail/src/main.rs -@@ -10,7 +10,7 @@ - extern crate capsules; - extern crate cortexm4; - extern crate compiler_builtins; --#[macro_use(static_init)] -+#[macro_use(debug, static_init)] - extern crate kernel; - extern crate sam4l; - -@@ -388,6 +388,8 @@ pub unsafe fn reset_handler() { - capsules::console::App::default()); - kernel::debug::assign_console_driver(Some(hail.console), kc); - -+ debug!("Testing 1, 2, 3..."); -+ - hail.nrf51822.initialize(); -``` - -Compile and flash the kernel (`make program`) then look at the output -(`tockloader listen`). - - - What happens if you put the `debug!` before `assign_console_driver`? - - What happens if you put `hail.console.initialize()` after - `assign_console_driver`? - -As you can see, sometimes there are dependencies between capsules, and board -authors must take care during initialization to ensure correctness. - -> **Note:** The `debug!` implementation is _asynchronous_. It copies messages -> into a buffer and the console prints them via DMA as the UART peripheral is -> available, interleaved with other console users (i.e. processes). You -> shouldn't need to worry about the mechanics of this for now. - - -##### 3.7 Loading processes - -Once the platform is all set up, the board is responsible for loading processes -into memory: - -```rust -kernel::process::load_processes(&_sapps as *const u8, - &mut APP_MEMORY, - &mut PROCESSES, - FAULT_RESPONSE); -``` - -A Tock process is represented by a `kernel::Process` struct. In principle, a -platform could load processes by any means. In practice, all existing platforms -write an array of Tock Binary Format (TBF) entries to flash. The kernel provides -the `load_processes` helper function that takes in a flash address and begins -iteratively parsing TBF entries and making `Process`es. - -##### 3.8 Starting the kernel - -Finally, the board passes a reference to the current platform, the chip the -platform is built on (used for interrupt and power handling), the processes to -run, and an IPC server instance to the main loop of the kernel: - -```rust -kernel::main(&hail, &mut chip, &mut PROCESSES, &hail.ipc); -``` - -From here, Tock is initialized, the kernel event loop takes over, and the -system enters steady state operation. - -#### 4. Create a "Hello World" capsule - -Now that you've seen how Tock initializes and uses capsules, you're going to -write a new one. At the end of this section, your capsule will sample the -accelerometer from the 9dof sensor once a second and print the results as -serial output. But you'll start with something simpler: printing "Hello World" -to the debug console once on boot. - -To begin, because you're going to be modifying the boot sequence of Hail, -make a branch of the Tock repository. This will keep your master -branch clean. - -```bash -# Possibly undo any changes from exploring debug! above: -$ git reset --hard -$ git checkout -b rustconf -``` - -Next, create a new module in `boards/hail/src` and import it from -`boards/hail/src/main.rs`. In your new module, make a new `struct` for your -capsule (e.g. called `Accelerate`), a `new` function to construct it and a `start` method. - -Eventually, the `start` method will kick off the state machine for periodic -accelerometer readings, but for now, you'll just print "Hello World" to the -debug console and return: - -```rust -debug!("Hello World"); -``` - -Finally, initialize this new capsule in the `main.rs` boot sequence. You'll -want to use the `static_init!` macro to make sure it's initialized in static -memory. `static_init!` is already imported, and has the following signature: - -```rust -static_init!($T:ty, :expr -> $T) -> &'static T -``` - -That is, the first parameter is the type of the thing you want to allocate and -the second parameter is an expression constructing it. The result is a -reference to the constructed value with `'static` lifetime. - -Compile and program your new kernel: - -```bash -$ make program -$ tockloader listen -No device name specified. Using default "tock" Using "/dev/ttyUSB0 - Hail IoT Module - TockOS" -Listening for serial output. -TOCK_DEBUG(0): /home/alevy/hack/helena/rustconf/tock/boards/hail/src/accelerate.rs:18: Hello World -``` - -[Sample Solution](https://gist.github.com/alevy/56b0566e2d1a6ba582b7d4c09968ddc9) - -#### 5. Extend your capsule to print "Hello World" every second - -In order for your capsule to keep track of time, it will need to depend on -another capsule that implements the Alarm interface. We'll have to do something -similar for reading the accelerometer, so this is good practice. - -The Alarm HIL includes several traits, `Alarm`, `Client`, and `Frequency`, -all in the `kernel::hil::time` module. You'll use the `set_alarm` and `now` -methods from the `Alarm` trait to set an alarm for a particular value of the -clock. The `Alarm` trait also has an associated type that implements the -`Frequency` trait which lets us call its `frequency` method to get the clock -frequency. - -Modify your capsule to have a field of the type `&'a Alarm` and to accept an -`&'a Alarm` in the `new` function. - -Your capsule will also need to implement the `Client` trait so it can -receive alarm events. The `Client` trait has a single method: - -```rust -fn fired(&self) -``` - -Your capsule should now set an alarm in the `start` method, print the debug -message and set an alarm again when the alarm fires. - -Finally, you'll need to modify the capsule initialization to pass in an alarm -implementation. Since lots of other capsules use the alarm, you should use a -virtual alarm. You can make a new one like this: - -```rust -let my_virtual_alarm = static_init!( - VirtualMuxAlarm<'static, sam4l::ast::Ast>, - VirtualMuxAlarm::new(mux_alarm)); -``` - -and you have to make sure to set your capsule as the client of the virtual alarm after initializing it: - -```rust -my_virtual_alarm.set_client(my_capsule); -``` - -Compile and program your new kernel: - -```bash -$ make program -$ tockloader listen -No device name specified. Using default "tock" Using "/dev/ttyUSB0 - Hail IoT Module - TockOS" -Listening for serial output. -TOCK_DEBUG(0): /home/alevy/hack/helena/rustconf/tock/boards/hail/src/accelerate.rs:31: Hello World -TOCK_DEBUG(0): /home/alevy/hack/helena/rustconf/tock/boards/hail/src/accelerate.rs:31: Hello World -TOCK_DEBUG(0): /home/alevy/hack/helena/rustconf/tock/boards/hail/src/accelerate.rs:31: Hello World -TOCK_DEBUG(0): /home/alevy/hack/helena/rustconf/tock/boards/hail/src/accelerate.rs:31: Hello World -``` - -[Sample Solution](https://gist.github.com/alevy/73fca7b0dddcb5449088cebcbfc035f1) - -#### 6. Extend your capsule to sample the accelerometer once a second - -The steps for reading an accelerometer from your capsule are similar to using -the alarm. You'll use a capsule that implements the NineDof (nine degrees of -freedom) HIL, which includes the `NineDof` and `NineDofClient` traits, both in -`kernel::hil::sensors`. - -The `NineDof` trait includes the method `read_accelerometer` which initiates an -accelerometer reading. The `NineDofClient` trait has a single method for receiving readings: - -```rust -fn callback(&self, x: usize, y: usize, z: usize); -``` - -However, unlike the alarm, there is no virtualization layer for the `NineDof` -HIL (yet!) and there is already a driver used in Hail that exposes the 9dof -sensor to userland. Fortunately, we can just remove it for our purposes. - -Remove the `ninedof` field from the `Hail` struct definition: - -```rust -ninedof: &'static capsules::ninedof::NineDof<'static>, -``` - -and initialization: - -```rust -ninedof: ninedof, -``` - -Remove `ninedof` from the system call lookup table in `with_driver`: - -```rust -11 => f(Some(self.ninedof)), // Comment this out -``` - -And, finally, remove the initialization of `ninedof` from the boot sequence: - -```rust -let ninedof = static_init!( - capsules::ninedof::NineDof<'static>, - capsules::ninedof::NineDof::new(fxos8700, kernel::Container::create())); -hil::ninedof::NineDof::set_client(fxos8700, ninedof); -``` - -Follow the same steps you did for adding an alarm to your capsule for the 9dof -sensor capsule: - - 1. Add a `&'a NineDof` field. - - 2. Accept one in the `new` function. - - 3. Implement the `NineDofClient` trait. - -Now, modify the Hail boot sequence passing in the `fxos8700` capsule, which -implements the `NineDof` trait, to your capsule (it should already be -initialized). Make sure to set your capsule as its client: - -```rust -{ - use hil::ninedof::NineDof; - fxos8700.set_client(my_capsule); -} -``` - -Finally, implement logic to initiate a accelerometer reading every second and -report the results. - -![Structure of `rustconf` capsule](rustconf.png) - -Compile and program your kernel: - -```bash -$ make program -$ tockloader listen -No device name specified. Using default "tock" Using "/dev/ttyUSB0 - Hail IoT Module - TockOS" -Listening for serial output. -TOCK_DEBUG(0): /home/alevy/hack/helena/rustconf/tock/boards/hail/src/accelerate.rs:31: 982 33 166 -TOCK_DEBUG(0): /home/alevy/hack/helena/rustconf/tock/boards/hail/src/accelerate.rs:31: 988 31 158 -``` - -[Sample solution](https://gist.github.com/alevy/798d11dbfa5409e0aa56d870b4b7afcf) - -#### 7. Some further questions and directions to explore - -Your capsule used the fxos8700 and virtual alarm. Take a look at the -code behind each of these services: - -1. Is the 9DOF sensor on-chip or a separate chip connected over a bus? - -2. What happens if you request two 9DOF sensors (e.g., accelerometer and magnetometer) - - back-to-back? -3. Is there a limit on how many virtual alarms can be created? - -4. How many virtual alarms does the Hail boot sequence create? - -#### 8. **Extra credit**: Write a virtualization capsule for 9dof (∞) - -Remember how you had to remove the userspace facing `ninedof` driver from Hail -in order to use the accelerometer in your capsule? That was a bummer... - -If you have extra time, try writing a virtualization capsule for the `NineDof` -HIL that will allow multiple clients to use it. This is a fairly open ended -task, but you might find inspiration in the `virtua_alarm` and `virtual_i2c` -capsules. - diff --git a/doc/courses/rustconf/console.png b/doc/courses/rustconf/console.png deleted file mode 100644 index 2d26a02e73..0000000000 Binary files a/doc/courses/rustconf/console.png and /dev/null differ diff --git a/doc/courses/rustconf/console.svg b/doc/courses/rustconf/console.svg deleted file mode 100644 index db102e6f59..0000000000 --- a/doc/courses/rustconf/console.svg +++ /dev/null @@ -1,379 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - image/svg+xml - - - - - - - - - - Application - - - app buffer - - - - Console - UART - - - - static buffer - - - - static buffer - - TakeCell - - copy - - - take - replace - - diff --git a/doc/courses/rustconf/environment.md b/doc/courses/rustconf/environment.md deleted file mode 100644 index f73677830c..0000000000 --- a/doc/courses/rustconf/environment.md +++ /dev/null @@ -1,203 +0,0 @@ -# Tock OS Course Part 1: Getting your environment set up - -> While we're getting set up and started, please make sure you have -> completed all of the [tutorial pre-requisites](./#pre-requisites). -> If you prefer, you can download a -> [virtual machine image](./#virtual-machine) with all the pre-requisites -> already installed. - -The goal of this part of the course is to make sure you have a working -development environment for Tock. - -During this you will: - -- Get a high-level overview of how Tock works. -- Learn how to compile and flash the kernel onto a Hail board. - -## 1. Presentation: Tock's goals, architecture and components - -The key contribution of Tock is that it uses Rust's borrow checker as a -language sandbox for isolation and a cooperative scheduling model for -concurrency in the kernel. As a result, isolation is (more or less) free in -terms of resource consumption at the expense of preemptive scheduling (so a -malicious component could block the system by, e.g., spinning in an infinite -loop). This is accomplished by the following architecture: - -![Tock architecture](architecture.png) - -Tock includes three architectural components: - - - A small trusted kernel, written in Rust, that implements a hardware - abstraction layer (HAL), scheduler, and platform-specific configuration. - - _Capsules_, which are compiled with the kernel and use Rust's type and - module systems for safety. - - _Processes_, which use the MPU for protection at runtime. - -Read the Tock documentation for more details on its -[design](https://www.tockos.org/documentation/design). - -[_Presentation slides are availble here._](presentation/presentation.pdf) - -## 2. Check your understanding - -1. What kinds of binaries exist on a Tock board? Hint: There are three, and - only two can be programmed using `tockloader`. - -2. What are the differences between capsules and processes? What performance - and memory overhead does each entail? Why would you choose to write - something as a process instead of a capsule and vice versa? - -3. Clearly, the kernel should never enter an infinite loop. But is it - acceptable for a process to spin? What about a capsule? - -## 3. Compile and flash the kernel - -### Build the kernel - -To build the kernel, just type make in the root directory, or in boards/hail/. - - $ cd boards/hail/ - $ make - -If this is the first time you are trying to make the kernel, cargo and rustup -will now go ahead and install all the requirements of Tock. - -If you're not in a board folder, -the root Makefile selects a board and architecture to build the kernel for and -routes all calls to that board's specific Makefile. It's set up with -`TOCK_BOARD ?= hail`, so it compiles for the Hail board by default. To change -this default, just change the `TOCK_BOARD` environment variable. For example, -to compile for the imix instead, `export TOCK_BOARD=imix` or `cd boards/imix/`. - -### Connect to a Hail board - -> On Linux, you might need to give your user access to the Hail's serial port. You can do this by adding a udev rule in: -> `/etc/udev/rules.d/99-hail` containing the rule: `ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6015", MODE="0666"`. -> Detaching and re-attaching Hail should do the trick. - -To connect your development machine to the Hail, connect them with a micro-USB -cable. Any cable will do. Hail should come with the Tock kernel and the Hail -test app pre-loaded. When you plug in Hail, the blue LED should blink slowly -(about once per second). Pressing the User Button—just to the right of the USB -plug—should turn on the green LED. - -The Hail board should appear as a regular serial device (e.g. -/dev/tty.usbserial-c098e5130006 on my machine). While you can connect with any -standard serial program (set to 115200 baud), tockloader makes this easier. -Tockloader can read attributes from connected serial devices, and will -automatically find your connected Hail. Simply run: - - $ tockloader listen - No device name specified. Using default "tock" - Using "/dev/ttyUSB0 - Hail IoT Module - TockOS" - - Listening for serial output. - - [Hail] Test App! - [Hail] Samples all sensors. - [Hail] Transmits name over BLE. - [Hail] Button controls LED. - [Hail Sensor Reading] - Temperature: 3174 1/100 degrees C - Humidity: 3915 0.01% - Light: 15 - Acceleration: 987 - ... - -### Flash the kernel - -Now that the Hail board is connected and you have verified that the kernel -compiles, we can flash the Hail board with the latest Tock kernel: - - $ make program - -This command will compile the kernel if needed, and then use `tockloader` to -flash it onto the Hail. When the flash command succeeds, the Hail test app -should no longer be working (i.e. the blue LED will not be blinking). Instead, -the red LED will be blinking furiously, a sign that the kernel has panicked. - -Don't panic! This is because... - -### Clear out the applications and re-flash the test app. - -...the Tock Binary Format (TBF) was recently changed, and is incompatible with the -app pre-loaded on the Hail board. To fix this, clear it out and re-flash it. - - $ tockloader list - ... - [App 0] - Name: hail - Total Size in Flash: 65536 bytes - ... - -As you can see, the old Hail test app is still installed on the board. This -also nicely demonstrates that user applications are nicely isolated from the -kernel: it is possible to update one independently of the other. Remove it with -the following command: - - $ tockloader erase-apps - -The red LED should no longer blink. Compile and re-flash the Hail test app: - - $ cd userland/examples/tests/hail/ - $ make program - -You now have the bleeding-edge Tock kernel running on your Hail board! - -## 4. (Optional) Familiarize yourself with `tockloader` commands -The `tockloader` tool is a useful and versatile tool for managing and installing -applications on Tock. It supports a number of commands, and a more complete -list can be found in the tockloader repository, located at -https://github.com/tock/tockloader. Below is a list of the more useful -and important commands for programming and querying a board. - -### `tockloader install` -This is the main tockloader command, used to load Tock applications onto a -board. Use the `--no-replace` flag to install multiple copies of the same app. -In order to install an app, navigate to the correct directory, make the program, -then issue the install command: - - $ cd tock/userland/examples/blink - $ make - $ tockloader install - -> *Tip:* You can add the `--make` flag to have tockloader automatically -> run make before installing, i.e. `tockloader install --make` - -### `tockloader uninstall [application name(s)]` -Removes one or more applications from the board by name. - -### `tockloader erase-apps` -Removes all applications from the board. - -### `tockloader list` -Prints basic information about the apps currently loaded onto the board. - -### `tockloader info` -Shows all properties of the board, including information about currently -loaded applications, their sizes and versions, and any set attributes. - -### `tockloader listen` -This command prints output from Tock apps to the terminal. It listens via UART, -and will print out anything written to stdout/stderr from a board. - -> *Tip:* As a long-running command, `listen` interacts with other tockloader -> sessions. You can leave a terminal window open and listening. If another -> tockloader process needs access to the board (e.g. to install an app update), -> tockloader will automatically pause and resume listening. - -### `tockloader flash` -Loads binaries onto hardware platforms that are running a compatible bootloader. -This is used by the Tock Make system when kernel binaries are programmed to the -board with `make program`. - -## 5. (Optional) Explore other Tock example applications - -Other applications can be found in the `userland/examples/` directory. Try -loading them on your Hail and then try modifying them. By default, -`tockloader install` adds the new application, but does not erase any others. -Not all applications will work well together if they need the same resources. - -> *Tip:* You can add the `--erase` flag to have tockloader automatically -> remove other applications when installing a new one. - diff --git a/doc/courses/rustconf/goals.txt b/doc/courses/rustconf/goals.txt deleted file mode 100644 index b42d2f205c..0000000000 --- a/doc/courses/rustconf/goals.txt +++ /dev/null @@ -1,18 +0,0 @@ -At the end of the RustConf tutorial, attendees should be able to: - -1) Set up a Hail board, compile Tock, install Tock, compile applications, - and install applications. - -2) Add a new capsule to the kernel (write it, include it in the crate, - initialize it in a boot sequence). - -3) Write a system call interface to a capsule. - -4) Write a new chip driver for a hardware controller. - - Maybe not, but understanding unsafe use here is important. - - If not, maybe _modify_ a controller driver - -5) Write down/diagram what happens when a process makes a blocking - system call (context switch, interrupt setup, wait_for, interrupt - handling, kernel thread, resuming process). - diff --git a/doc/courses/rustconf/presentation/architecture.pdf b/doc/courses/rustconf/presentation/architecture.pdf deleted file mode 100644 index ce6aca54cd..0000000000 Binary files a/doc/courses/rustconf/presentation/architecture.pdf and /dev/null differ diff --git a/doc/courses/rustconf/presentation/execution.pdf b/doc/courses/rustconf/presentation/execution.pdf deleted file mode 100644 index 00d66b3c7a..0000000000 Binary files a/doc/courses/rustconf/presentation/execution.pdf and /dev/null differ diff --git a/doc/courses/rustconf/presentation/hail.png b/doc/courses/rustconf/presentation/hail.png deleted file mode 100644 index 28a460c69f..0000000000 Binary files a/doc/courses/rustconf/presentation/hail.png and /dev/null differ diff --git a/doc/courses/rustconf/presentation/ipc.pdf b/doc/courses/rustconf/presentation/ipc.pdf deleted file mode 100644 index 051a9bf7e9..0000000000 Binary files a/doc/courses/rustconf/presentation/ipc.pdf and /dev/null differ diff --git a/doc/courses/rustconf/presentation/ipc.svg b/doc/courses/rustconf/presentation/ipc.svg deleted file mode 100644 index debff98570..0000000000 --- a/doc/courses/rustconf/presentation/ipc.svg +++ /dev/null @@ -1,206 +0,0 @@ - - - - - - - - - - - - - - - - - - - - image/svg+xml - - - - - - - - BLE ESSService - - My App - - - allow - - notify - - Kernel - - diff --git a/doc/courses/rustconf/presentation/presentation.pdf b/doc/courses/rustconf/presentation/presentation.pdf deleted file mode 100644 index 85bfe6a5cf..0000000000 Binary files a/doc/courses/rustconf/presentation/presentation.pdf and /dev/null differ diff --git a/doc/courses/rustconf/presentation/process_layout.png b/doc/courses/rustconf/presentation/process_layout.png deleted file mode 100644 index 85932c0c5f..0000000000 Binary files a/doc/courses/rustconf/presentation/process_layout.png and /dev/null differ diff --git a/doc/courses/rustconf/presentation/rng.pdf b/doc/courses/rustconf/presentation/rng.pdf deleted file mode 100644 index fe868b82e3..0000000000 Binary files a/doc/courses/rustconf/presentation/rng.pdf and /dev/null differ diff --git a/doc/courses/rustconf/presentation/rng.svg b/doc/courses/rustconf/presentation/rng.svg deleted file mode 100644 index a90d47a578..0000000000 --- a/doc/courses/rustconf/presentation/rng.svg +++ /dev/null @@ -1,4 +0,0 @@ - - - - diff --git a/doc/courses/rustconf/presentation/slides.md b/doc/courses/rustconf/presentation/slides.md deleted file mode 100644 index b33504539b..0000000000 --- a/doc/courses/rustconf/presentation/slides.md +++ /dev/null @@ -1,475 +0,0 @@ ---- -title: Tock Embedded OS Training -date: RustConf 2017 -header-includes: - - \beamertemplatenavigationsymbolsempty - - \usepackage{pifont} - - \newcommand{\cmark}{\color{green}\ding{51}} - - \newcommand{\xmark}{\color{red}\ding{55}} ---- - -> Please make sure you have completed all of the tutorial pre-requisites. If -> you prefer, you can download a virtual machine image with all the -> pre-requisites already installed. - - - - - -## Tock is a... - - 1. Secure - - 2. Embedded - - 3. Operating System - - 4. for Low Resource - - 5. Microcontrollers - -## Secure - -![](snakeoil.jpg) - -## ~~_Secure_~~ Safe - -### Tock has isolation primitives that allow you to build secure systems. - -## Embedded - -### Definition A - -> Kernel, applications and hardware are tightly integrated. - -### Definition B - -> You'll likely be writing the kernel. - -## Operating System - -Tock itself provides services to components in the system: - - * Scheduling - - * Communication - - * Hardware multiplexing - -## Low Resource - - * 10s uA average power draw - - * 10s of kBs of RAM - - * Moderate clock speeds - -## Microcontrollers - -System-on-a-chip with integrated flash, SRAM, CPU and a bunch of hardware -controllers. - -Typically: - - * Communication: UART, SPI, I2C, USB, CAN... - - * External I/O: GPIO, external interrupt, ADC, DAC - - * Timers: RTC, countdown timers - -Maybe... - - * Radio (Bluetooth, 15.4) - - * Cryptographic accelerators - - * Other specialized hardware... - -## Two types of components: capsules and processes - -![](architecture.pdf) - -## Two types of scheduling: cooperative and preemptive - -![](execution.pdf) - -## Agenda Today - - 1. Intro to hardware, tools and development environment - - 2. Add functionality to the Tock kernel - - 3. Write an end-to-end Bluetooth Low Energy environment sensing application. - -# Part 1: Hardware, tools and development environment - -## Hail - -![](hail.png) - -## Binaries on-board - -### Bootloader - -### Kernel - -### Processes - -## Tools - - * `make` (just instrumenting `cargo`) - - * Rust (nightly for `asm!`, compiling `core`, etc) - - * `arm-none-eabi` GCC/LD to link binaries - - * `tockloader` to interact with Hail and the bootloader - -## Tools: `tockloader` - -Write a binary to a particular address in flash - -```bash -$ tockloader flash --address 0x1000 \ - target/thumbv7em-none-eabi/release/hail.bin -``` - -Program a process in Tock Binary Format[^footnote]: - -```bash -$ tockloader install myapp.tab -``` - -Restart the board and connect to the debug console: - -```bash -$ tockloader listen -``` - -[^footnote]: TBFs are relocatable process binaries prefixed with headers like - the package name. `.tab` is a tarball of TBFs for different architectures as - well as a metadata file for `tockloader`. - -## Check your understanding - - 1. What kinds of binaries exist on a Tock board? Hint: There are three, and - only two can be programmed using `tockloader`. - - 2. Can you point to the chip on the Hail that runs the Tock kernel? How about - the processes? - - 3. What steps would you follow to program a processes onto Hail? What about - to replace the kernel? - -## Hands-on: Set-up development environment - - 1. Compile and flash the kernel - - 2. Compile and program `ble-env-sense` service - - 3. (Optional) Add some other apps from the repo, like `blink` and `sensors` - - 4. (Optional) Familiarize yourself with `tockloader` commands - - * `uninstall` - - * `list` - - * `erase-apps` - -# Part 2: The kernel - -## Trusted Computing Base (`unsafe` allowed) - - * Hardware Abstraction Layer - - * Board configuration - - * Event & Process scheduler - - * Rust `core` library - - * Core Tock primitives - -``` -kernel/ -chips/ -``` - -## Capsules (`unsafe` not allowed) - - * Virtualization - - * Peripheral drivers - - * Communication protocols (IP, USB, etc) - - * Application logic - -``` -capsules/ -``` - -## Constraints - -### Small isolation units - -Breaking a monolithic component into smaller ones should have low/no cost - -### Avoid memory exhaustion in the kernel - -No heap. Everything is allocated statically. - -### Low communication overhead - -Communicating between components as cheap as an internal function call. Ideally -inlined. - -## Event-driven execution model - -```rust -pub fn main(platform: &P, chip: &mut C, - processes: &mut [Process]) { - loop { - chip.service_pending_interrupts(); - for (i, p) in processes.iter_mut().enumerate() { - sched::do_process(platform, chip, process); - } - - if !chip.has_pending_interrupts() { - chip.prepare_for_sleep(); - support::wfi(); - } - } -} -``` - -## Event-driven execution model - -```rust -fn service_pending_interrupts(&mut self) { - while let Some(interrupt) = get_interrupt() { - match interrupt { - ASTALARM => ast::AST.handle_interrupt(), - USART0 => usart::USART0.handle_interrupt(), - USART1 => usart::USART1.handle_interrupt(), - USART2 => usart::USART2.handle_interrupt(), - ... - } - } -} -``` - -## Event-driven execution model - -```rust -impl Ast { - pub fn handle_interrupt(&self) { - self.clear_alarm(); - self.callback.get().map(|cb| { cb.fired(); }); - } -} -impl time::Client for MuxAlarm { - fn fired(&self) { - for cur in self.virtual_alarms.iter() { - if cur.should_fire() { - cur.armed.set(false); - self.enabled.set(self.enabled.get() - 1); - cur.fired(); - } - } - } -} -``` - -* * * - -![Capsules reference each other directly, assisting inlining](rng.pdf) - -## The mutable aliases problem - -```rust -enum NumOrPointer { - Num(u32), - Pointer(&mut u32) -} - -// n.b. will not compile -let external : &mut NumOrPointer; -match external { - Pointer(internal) => { - // This would violate safety and - // write to memory at 0xdeadbeef - *external = Num(0xdeadbeef); - *internal = 12345; // Kaboom - }, - ... -} -``` - -## Interior mutability to the rescue - -| Type | Copy-only | Mutual exclusion | Opt. | Mem Opt. | -|----------------|:---------:|:----------------:|:---------:|:--------:| -| `Cell` | \cmark{} | \xmark{} | \cmark{} | \cmark{} | -| `VolatileCell` | \cmark{} | \xmark{} | \xmark{} | \cmark{} | -| `TakeCell` | \xmark{} | \cmark{} | \xmark{} | \cmark{} | -| `MapCell` | \xmark{} | \cmark{} | \cmark{} | \xmark{} | - - -* * * - -```rust -pub struct Fxos8700cq<`a> { - i2c: &`a I2CDevice, - state: Cell, - buffer: TakeCell<`static, [u8]>, - callback: - Cell>, -} - -impl<`a> I2CClient for Fxos8700cq<`a> { - fn cmd_complete(&self, buf: &`static mut [u8]) { ... } -} - -impl<`a> hil::ninedof::NineDof for Fxos8700cq<`a> { - fn read_accelerometer(&self) -> ReturnCode { ... } -} - -pub trait NineDofClient { - fn callback(&self, x: usize, y: usize, z: usize); -} -``` - -## Check your understanding - - 1. What is a `VolatileCell`? Can you find some uses of `VolatileCell`, and do - you understand why they are needed? Hint: look inside `chips/sam4l/src`. - - 2. What is a `TakeCell`? When is a `TakeCell` preferable to a standard - `Cell`? - -## Hands-on: Write and add a capsule to the kernel - - 1. Read the Hail boot sequence in `boards/hail/src/main.rs` - - 2. [Write a new capsule that prints "Hello World" to the debug - console.](https://gist.github.com/alevy/56b0566e2d1a6ba582b7d4c09968ddc9) - - 3. [Extend your capsule to print "Hello World" every second](https://gist.github.com/alevy/798d11dbfa5409e0aa56d870b4b7afcf) - - 4. [Extend your capsule to read and report the accelerometer](https://gist.github.com/alevy/73fca7b0dddcb5449088cebcbfc035f1#file-boot_sequence.rs) - - 5. Extra Credit: Write a 9dof virtualization capsule. - -# Part 3: User space - -## System calls - -| **Call** | **Target** | **Description** | -|:----------|:----------:|----------------------------------| -| command | Capsule | Invoke an operation on a capsule | -| allow | Capsule | Share memory with a capsule | -| subscribe | Capsule | Register an upcall | -| memop | Core | Modify memory break | -| yield | Core | Bloc until next upcall is ready | - -## Rust System calls: `command` & `allow` - -```rust -pub unsafe fn command(major: u32, minor: u32, - arg: isize) -> isize; - -pub unsafe fn allow(major: u32, minor: u32, - slice: &[u8]) -> isize; -``` - -## Rust System calls: `subscribe` - -```rust -type ExternFn = - extern fn (usize, usize, usize, *const usize); - -pub unsafe fn subscribe(major: u32, minor: u32, - cb: ExternFn, ud: *const usize) -> isize { -``` - -## Rust System calls: `yieldk` & `yieldk_for` - -```rust -pub fn yieldk(); - -pub fn yieldk_for bool>(cond: F) { - while !cond() { yieldk(); } -} -``` - -## Example: printing to the debug console - -```rust -pub fn write(string: Box<[u8]>) { - let done: Cell = Cell::new(false); - syscalls::allow(DRIVER_NUM, 1, string); - syscalls::subscribe(DRIVER_NUM, 1, callback, - &done as *const _ as usiz); - syscalls::command(DRIVER_NUM, 1, string.len()); - yieldk_for(|| done.get()) -} - -extern fn callback(_: usize, _: usize, _: usize, - ud: *const usize) { - let done: &Cell = unsafe { - mem::transmute(ud) - }; - done.set(true); -} -``` - -## Inter Process Communication (IPC) - -![](ipc.pdf) - -## Current Rust userland - -### Supported drivers - - * Debug console - - * Timer - - * Sensors: - - * Accelerometer & magnetometer - - * Ambient light - - * Temperature - - * IPC - -### Caveats - - * No global variables allowed! - - * Fixed code offset - - * Blocking library calls only - -## Check your understanding - -1. How does a process perform a blocking operation? Can you draw the flow of - operations when a process calls `delay_ms(1000)`? - -2. What is a Grant? How do processes interact with grants? Hint: Think about - memory exhaustion. - -## Hands-on: Write a BLE environment sensing application - - 1. Get a Rust application running on Hail - - 2. [Periodically sample on-board - sensors](https://gist.github.com/alevy/73d0a1e5c8784df066c86dc5da9d3107) - - 3. [Extend your app to report through the `ble-env-sense` - service](https://gist.github.com/alevy/a274981a29ffc00230aa16101ee0b89f) - diff --git a/doc/courses/rustconf/presentation/snakeoil.jpg b/doc/courses/rustconf/presentation/snakeoil.jpg deleted file mode 100644 index e77953731c..0000000000 Binary files a/doc/courses/rustconf/presentation/snakeoil.jpg and /dev/null differ diff --git a/doc/courses/rustconf/rustconf.png b/doc/courses/rustconf/rustconf.png deleted file mode 100644 index a923dc013e..0000000000 Binary files a/doc/courses/rustconf/rustconf.png and /dev/null differ diff --git a/doc/courses/rustconf/rustconf.svg b/doc/courses/rustconf/rustconf.svg deleted file mode 100644 index 5efe7ffbb4..0000000000 --- a/doc/courses/rustconf/rustconf.svg +++ /dev/null @@ -1,300 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - image/svg+xml - - - - - - - - - rustconf - alarm - - fxos8700 - - - - - set - fired - read - callback - - diff --git a/doc/courses/sosp/README.md b/doc/courses/sosp/README.md deleted file mode 100644 index 1575adcf9b..0000000000 --- a/doc/courses/sosp/README.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -location: Shanghai, China -date: October 28th ---- - -# Tock OS Training @ SOSP 2017 - ---- -**NOTE** - -This course was primarily designed in the summer of 2017. It focuses on -presenting Tock to an operating systems research audience. It is no longer -updated. For example, this course uses Tock version 1.2, and current Tock -development is on version 2.x. - ---- - - -This course introduces you to Tock, a secure embedded operating system for sensor -networks and the Internet of Things. Tock is the first operating system to -allow multiple untrusted applications to run concurrently on a microcontroller-based -computer. The Tock kernel is written in Rust, a memory-safe systems language that -does not rely on a garbage collector. Userspace applications are run in -single-threaded processes that can be written in any language. A paper -describing Tock's goals, design, and implementation will be presented at the -conference on Monday and is available [here](https://www.amitlevy.com/papers/tock-sosp2017.pdf). - -This course is based on TockOS as it was in October, 2017. It serves as a useful -introduction to Tock, but it is not updated as Tock evolves. To view this -tutorial in the context it was originally designed for, please checkout the -correct commit hash: - -```bash -$ git checkout 3c12437d23b83db896a5a8e218a3dc14468ce2df -``` - -This commit includes a working version of this tutorial.