Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/betrusted-io/betrusted-ec

Betrusted embedded controller (UP5K)
https://github.com/betrusted-io/betrusted-ec

Last synced: 3 months ago
JSON representation

Betrusted embedded controller (UP5K)

Lists

README 

        
# Betrusted Embedded Controller



The embedded controller (EC) is a UP5K FPGA responsible for secondary

power management functions, and for intermediating between the trusted

comms port on the SoC and the untrusted wifi stack.



From the strict security model, the EC is in the untrusted domain, and

the core SoC must be robust against arbitrary remote exploits in the EC.



Compiled documentation: https://ci.betrusted.io/betrusted-ec/doc/[latest register set], https://ci.betrusted.io/betrusted-ec/rustdoc/betrusted_pac/[latest rust API documentation]



## Getting Started



### Building the CPU

1. Ensure you have a toolchain installed, including a compiler, Python 3.5+, `nextpnr-ice40`, and `yosys`.  These can all be obtained by downloading the https://github.com/im-tomu/fomu-toolchain/releases/tag/v1.5.6[Fomu toolchain] and adding it to your `PATH`. Note that the latest release of the toolchain does not work because the synthesis adds extra logic, causing the design to not fit.

1. Install the https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack/releases[xpack riscv toolchain]

1. Check out this repo with `git clone --recurse-submodules `. It will consume ~800MiB of disk space (sorry!).

1. Run `./betrusted_ec.py --revision=pvt` (or `python3 ./betrusted_ec.py --revision=pvt`) to build the "PVT" version of the EC

1. Run `cargo xtask copy-precursors` to copy your newly built CPU to the staging area for firmware images

1. (Optional) Run `cargo xtask docs` to create an HTML document tree of all the CPU registers



### Building the firmware binaries

1. Ensure that you have a toolchain installed, including a gcc compiler and Rust. gcc is necessary to handle the FFI bindings.

1. Run `cargo xtask hw-image` to build the burnable ROM image artifacts



### Updating the EC

When using the USB method, you either must trigger the update by bumping the semantic version

of the gateware and the firmware, or you need to rebuild `xous.img` with the custom argument

`--feature=dbg-ecupdate` to unlock the `shellchat` `ecup` command which allows you to force an

update, even if it is a downgrade. Once that is set up:



1. Copy the resulting `ec_fw.bin` file to a location where you can run the https://github.com/betrusted-io/xous-core/blob/main/tools/usb_update.py[usb_update.py]

2. Plug in the device to the host that can run the script

3. Execute `usb_update.py -e path-to/ec_fw.bin`



Alternatively:



2. Run `cargo xtask push  [idfile]` to push the files to a Raspberry Pi with a debug hat for burning. `idfile` is the ssh ID file if you use one.

2. On the Raspberry Pi, run `config_up5k.sh` from the `betrusted-scripts` repo as explained below.



## Debugging Notes

Serial output from the EC can be viewed over the debugging cable via

the Precursor debug HAT. See https://github.com/betrusted-io/betrusted-wiki/wiki/Updating-Your-Device#installing-the-cable[instructions on installing the cable].



The EC UART port is selected by running the `betrusted-scripts/uart_up5k.sh` script.



You will need some terminal program to interact with the EC. One such program

is `screen`, for example, on a Raspberry Pi 3B+ you could run

`sudo screen -fn /dev/ttyS0 115200` and access the EC UART after switching

to the UART port.



Note that varying generations and releases of Raspberry

Pi put the UART on either `ttyS0` or `AMA0`, and you may need to run

`raspi-config` to enable serial ports first.



## WF200 firmware

The EC image is intimately linked to the WF200 firmware image that is

presumed to be burned into the FLASH memory. Please consult `hal_wf200.rs`

for `WFX_FIRMWARE_OFFSET` and `WFX_FIRMWARE_SIZE`. In particular, when

updating the firmware, the `WFX_FIRMWARE_SIZE` parameter should also be

updated.



If you must update the bindings, you will need to be able to run `bindgen`.

Install it by doing something like this:



```

sudo apt install llvm-dev libclang-dev clang

sudo apt install gcc-multilib

cargo install bindgen-cli

```



## Updating ##



To update the repo to the upstream version, including all dependencies, run:



```sh

git pull

git submodule update --recursive

```



## Using lxbuildenv.py Environment ##



`lxbuildenv` is a Python module.  It sets up the build environment and ensures you have the correct dependencies.  To use it, start your program off with:



```python

#!/usr/bin/env python3

import lxbuildenv

```



*`lxbuildenv.py` has some very surprising behaviors* that you should be aware of:



1. In order to set environment variables such as `PYTHONHASHSEED`, `lxbuildenv` will actually re-exec the Python interpreter.  This will, among other things, cause the pid to change.  *This is why lxbuildenv should be imported first*.

1. The environment variable `PYTHONPATH` is replaced to include every directory under `deps/`.  If you rely on `PYTHONPATH` to be something else, this may surprise you.

1. `lxbuildenv` has several command line parameters that it can accept.  To display these, run your command with the `--lx-help` parameter.

1. The `deps/` directory includes its own `site.py` implementation, adapted from a Debian implementation.  This is because some distros force `/usr/share/python/site-packages/` to be first in the dependency list, which causes confusing dependency interactions.  If you're relying on site packages being in a certain order, this may cause problems.  You can try deleting `deps/site/` in order to disable this behavior.



In exchange for some deviation from other build environments, `lxbuildenv` gives you several benefits that come in handy for hardware projects:



1. Python dicts enumerate in constant order, giving some consistency to build results.

1. You will probably be modifying code in the dependencies.  By keeping them inside the project directory, this becomes much simpler.

1. Additionally, all dependencies remain under version control, which you would otherwise lose when installing dependencies as packages.

1. Hardware, moreso than software, depends on exact version numbers.  By using `git` to track dependency versions, this build becomes more reproducible.

1. It is cross-platform, and works anywhere Xilinx does.

1. The `lxbuildenv` environment doesn't rely on opaque environment variables, or otherwise have a special environment you enter.  Everything is documented behind `--help` flags.



## Working with Dependencies ##



Dependencies are managed through `git`, and managing their usage is largely an exercise

in working with `git`.



For example, if you would like to make a change to `litex`, go into `deps/litex` and checkout

a new branch and create a new upstream repo.  If you're working on Github, you would do

something like fork the repo to your own organization.



As an example, assume `sutajiokousagi` has forked upstream `litex`:



```sh

$ cd deps/litex

$ git checkout -b new-feature

$ git remote add kosagi [email protected]:sutajiokousagi/litex.git

$ cd -

```



Then, make changes to `deps/litex` as needed.



When you want to merge changes upstream, go into `deps/litex/` and push the branch to your remote:



```sh

$ cd deps/litex

$ git push kosagi new-feature

$ cd -

```



Then you can go and open a Pull Request on Github.



## Fetching Updates ##



Dependencies are designed to be independent, and you should update them as needed.  To update a particular

dependency, go into that dependency's subdirectory and run `git pull`.  You may also find it easier to

pull updates from a particular dependency and merge them.  For example, if you're working on the `new-feature`

branch of `litex` and want to pull changes from upstream, run:



```sh

$ cd deps/litex

$ git fetch origin

$ git merge master

$ cd -

```



This will merge all changes from upstream onto your own branch.



## PyCharm integration ##



To use PyCharm, open this directory as a `Project` by going to the *File* menu and selecting *Open...*.  Make sure you open the entire directory, and not just a single file in this directory.



When you first open this project, you'll see lots of red squiggly lines indicating errors.  PyCharm needs to know about the dependency structure in order to allow you to drill down into modules and auto-complete statements.



Open this directory in PyCharm and expand the `deps/` directory.  Then hold down `Shift` and select all subdirectories under `deps/`.  This will include `litedram`, `liteeth`, and so on.



Then, right-click and select `Mark directory as...` and select `Sources Root`.  The red squiggly lines should go away, and PyCharm should now be configured.



When running your module from within PyCharm, you may find it useful to set environment variables.  You can use the `--lx-print-env` command.  For example: `./betrusted-ec.py --lx-print-env > pycharm.env` to create a `.env`-compatible file.  There are several PyCharm plugins that can make use of this file.



## Visual Studio Code integration ##



Visual Studio Code needs to know where modules are.  These are specified in environment variables, which are automatically read from a .env file in your project root.  Create this file to enable `pylint` and debugging in Visual Studio Code:



```sh

$ python ./betrusted-ec.py --lx-print-env > .env

```



## Contribution Guidelines



[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-v2.0%20adopted-ff69b4.svg)](CODE_OF_CONDUCT.md)



Please see [CONTRIBUTING](CONTRIBUTING.md) for details on

how to make a contribution.



Please note that this project is released with a

[Contributor Code of Conduct](CODE_OF_CONDUCT.md).

By participating in this project you agree to abide its terms.



## License



Copyright © 2019



Licensed under the [CERN OHL v1.2](https://ohwr.org/project/licenses/wikis/cern-ohl-v1.2) [LICENSE](LICENSE)