README.md 2.91 KB
Newer Older
rnd's avatar
rnd committed
1
# Rust support for the card10 CCCamp19 badge
Astro's avatar
Astro committed
2

Astro's avatar
Astro committed
3
4
5
6
7
8
9
10
11
12
13
## Prebuilt binaries

By courtesy of this Gitlab's CI system, and NixOS, we build `.elf`
files for you drop into the `apps/` directory of your card10 badge.

Because running ELF binaries requires a jailbroken base firmware
starting with v1.5, we build this one too. It includes this project's
Rust binaries.

https://git.card10.badge.events.ccc.de/astro/rust-card10/-/jobs

Danilo's avatar
Danilo committed
14
15
## Prerequisites

rnd's avatar
rnd committed
16
17
You need rust nightly and a working setup to compile the card10
firmware including the matching libc.
Danilo's avatar
Danilo committed
18

19
1) For instructions how to setup rust please see https://rustup.rs.
Danilo's avatar
Danilo committed
20

rnd's avatar
rnd committed
21
22
   Please ensure that you installed the latest rust nightly toolchain
   and add the `thumbv7em-none-eabi` target.
Danilo's avatar
Danilo committed
23

rnd's avatar
rnd committed
24
25
26
27
28
   ```shell
   rustup toolchain install nightly
   rustup update
   rustup target add thumbv7em-none-eabi --toolchain nightly
   ```
Astro's avatar
Astro committed
29

rnd's avatar
rnd committed
30
2) For instructions how to setup the card10 firmware check the dependency
31
   chapter in https://firmware.card10.badge.events.ccc.de/how-to-build.html.
Astro's avatar
Astro committed
32

rnd's avatar
rnd committed
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
3) Additionally you may need the packages for the llvm and libc i386
   dev headers.

4) Clone this repository with `--recursive` to get the submodules,
   otherwise update them afterwards:

   ```shell
   git submodule update --init --recursive
   ```

## Setup a Rust enabled firmware

To allow rust based apps on card10 you need a firmware which allows
to run custom elf binaries on the core. This requires a custom build
with `-Djailbreak_card10=true` as bootstrapping flag.

Assuming that you installed all required dependencies mentioned in
50
https://firmware.card10.badge.events.ccc.de/how-to-build.html this
rnd's avatar
rnd committed
51
should work as following:
52
53

```shell
rnd's avatar
rnd committed
54
55
56
cd c/
./bootstrap -Djailbreak_card10=true
ninja -C build/
57
```
Astro's avatar
Astro committed
58

rnd's avatar
rnd committed
59
60
61
62
And then copy `build/pycardium/pycardium_epicardium.bin` as
`card10.bin` onto your badge.

## Build and run Rust loadables
Astro's avatar
Astro committed
63
64

```shell
rnd's avatar
rnd committed
65
cargo +nightly build --release --target thumbv7-none-eabi
Astro's avatar
Astro committed
66
67
```

rnd's avatar
rnd committed
68
Then copy the resulting executable from the target directory 
Astro's avatar
Astro committed
69
`target/thumbv7em-none-eabi/release/example` into the
rnd's avatar
rnd committed
70
71
`apps` directory of your badge.

Astro's avatar
Astro committed
72
73
**Attention**: Its necessary to rename the executable to add the `elf`
extension (e.g `example` must be renamed as `example.elf`).
Astro's avatar
Astro committed
74

Astro's avatar
Astro committed
75
76
77
78
## Crates

| Crate    | Description                                               |
| ----     | ---                                                       |
Astro's avatar
Astro committed
79
| l0dable  | Helper crate for building l0dables                        |
Astro's avatar
Astro committed
80
| example  | l0dable example                                           |
Astro's avatar
Astro committed
81
| rkanoid  | Arkanoid clone                                            |
Astro's avatar
Astro committed
82

rnd's avatar
rnd committed
83
84
85

## Misc

Astro's avatar
Astro committed
86
### How to update the firmware bindings
rnd's avatar
rnd committed
87
88
89
90
91
92
93
94
95
96
97
98
99

1) Update the `c/` submodule to the latest firmware state.

2) Rebuild the firmware as described above.

3) Run the following script from the project root directory

   ```shell
   python c/epicardium/api/genapi.py -H c/epicardium/epicardium.h -c l0dable/src/client.c -s l0dable/src/server.c
   ```

4) Rebuild your app :)

Astro's avatar
Astro committed
100
101
102
## TODO

- [ ] alloc