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: latest register set, latest rust API documentation

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 [Fomu toolchain](https://github.com/im-tomu/fomu-toolchain/releases/latest) and adding it to your PATH.

2. Check out this repo with git clone --recurse-submodules <repo>.

3. Run ./betrusted-ec.py --revision=pvt (or python3 ./betrusted-ec.py --revision=pvt) to build the "PVT" version of the EC

4. Run cargo xtask hw-image to build the burnable ROM image

5. Run cargo xtask docs to update the HTML document tree

6. Run cargo xtask push <target> [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.

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

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:

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.

2. 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.

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

4. 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.

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

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

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

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

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

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:

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:

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

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:

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

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 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:

[](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.

Copyright © 2019

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