https://github.com/ockam-network/ockam/tree/develop/documentation/use-cases/run-ockam-on-riscv Skip to content Sign up * Why GitHub? + Features - + Mobile - + Actions - + Codespaces - + Packages - + Security - + Code review - + Issues - + Integrations - + GitHub Sponsors - + Customer stories - * Team * Enterprise * Explore + Explore GitHub - + Learn and contribute + Topics - + Collections - + Trending - + Learning Lab - + Open source guides - + Connect with others + The ReadME Project - + Events - + Community forum - + GitHub Education - + GitHub Stars program - * Marketplace * Pricing + Plans - + Compare plans - + Contact Sales - + Education - [ ] * # In this repository All GitHub | Jump to | * No suggested jump to results * # In this repository All GitHub | Jump to | * # In this organization All GitHub | Jump to | * # In this repository All GitHub | Jump to | Sign in Sign up {{ message }} ockam-network / ockam Public * Notifications * Star 1.5k * Fork 154 * * Code * Issues 202 * Pull requests 23 * Discussions * Actions * Security * Insights More * Code * Issues * Pull requests * Discussions * Actions * Security * Insights develop Switch branches/tags [ ] Branches Tags Could not load branches Nothing to show Loading {{ refName }} default View all branches Could not load tags Nothing to show {{ refName }} default Loading View all tags ockam/documentation/use-cases/run-ockam-on-riscv/ Go to file ockam/documentation/use-cases/run-ockam-on-riscv/ Latest commit @mrinalwadhwa mrinalwadhwa docs: improve risc-v guide ... 1f5d0b8 Nov 4, 2021 docs: improve risc-v guide 1f5d0b8 Git stats * History Files Permalink Failed to load latest commit information. Type Name Latest commit message Commit time . . README.md docs: improve risc-v guide Nov 5, 2021 [ ] How to run Ockam on RISC-V Linux What is RISC-V? About the RISC-V ISA Rust on RISC-V Rust on RISC-V with cargo cross Hello Ockam Rust on RISC-V with OS toolchains Rust on RISC-V with the official toolchain Testing with qemu and Debian Testing with qemu and buildroot README.md How to run Ockam on RISC-V Linux In this hands-on guide, we'll show how to cross compile a Rust example of Ockam for RISC-V Linux systems. We'll also see how to test RISC-V Linux programs using qemu. Before we dive in, let's start with a ~2 minute demo of how to run Ockam's end-to-end encryption example on Microchip's PolarFire SoC Icicle kit. ockam_riscv_linux_microchip_polarfire.mp4 Please unmute to listen to the explanation of the demo What is RISC-V? RISC-V is a free, open CPU instruction set architecture (ISA) that is revolutionizing hardware. The open source nature of the ISA has allowed global innovation and creativity in much the same way Open Source revolutionized software. Since its first publication from UC Berkeley in 2011, adoption of RISC-V has seen incredible growth. Organizations like RISC-V International collaborate with dozens of companies, academic institutions, and passionate individuals to propel the ecosystem forward. Open architectures such as RISC-V provide transparency down to the deepest levels of a system. For systems that require strong security and safety guarantees, an open ISA provides the foundation of a completely understood supply chain. RISC-V is also extensible: additional instructions can be added to perform new operations. This ability is being used to add many features to the ISA, including cryptographic extensions. These extensions enable the development of specialized processors such as Secure Enclaves and Trusted Execution Environments. About the RISC-V ISA RISC-V cores come in many shapes and sizes, because the ISA is so flexible and extensible. There are 32-bit, 64-bit and even 128-bit versions of the core integer instructions. * rv32 is the 32-bit configuration suitable for microcontrollers and other small, low power systems. * rv64 is the 64-bit general purpose, server class configuration. RISC-V Linux projects target the RV64. * rv128 is a mostly theoretical 128-bit configuration. RISC-V cores are also configurable using what are called instruction set variants. Variants add additional instructions to the core ISA. Several variants have been officially standardized, and more are on the way. Variants are referenced by a single letter code such as I, M and C. The most important RISC-V variants are: * I - The base integer instructions. All RISC-V cores implement this. * M - Multiplication instructions. Most cores implement this, but some very small microcontrollers do not. * A - Atomic instructions. These instructions enable multi-core systems to have consistent views of memory. * F - Floating point instructions. Often omitted on microcontroller configurations. * D - Double floating point instructions. Often omitted on microcontroller configurations. * C - Compressed instructions. Similar to ARM's Thumb instructions. Reduces code size. Sometimes omitted. * G - Short hand for the set of IMAFD variants. RISC-V cores are referred to by their bit-width and set of supported variants. For example, a common class of microcontroller configurations is rv32imc which is a 32-bit processor with a multiplier and compressed instructions. The RISC-V configuration targeted by Linux distributions is typically rv64gc, although it is possible to run Linux on other configurations. Rust on RISC-V Rust supports several RISC-V targets. Rust targets are split into several tiers, which have different guarantees with respect to support and stability. * riscv64-unknown-linux-gnu is a "Tier 2 With Host Tools" target that has support for std running on Linux. * riscv64gc-unknown-none-elf and riscv64imac-unknown-none-elf are Tier 2 targets that can be used in bare metal projects. * riscv32i, riscv32imc and riscv32imac -unknown-none-elf are the 32-bit Tier 2 targets that can be used in bare metal projects. * riscv32imc-esp-espidf is a Tier 3 target that supports ESP RISC-V chips like the esp32-c3. Rust programs targeting RISC-V can be built with or without the std library. Building no_std applications is a complex topic, and requires details about the underlying hardware being targeted. Additionally, an allocator is often needed if the application requires a heap. This guide focuses on std projects for RISC-V running Linux. Ockam support for no_std is an ongoing effort with initial support for several ARM boards. In the future, Ockam no_std support will be extended to the RISC-V ecosystem. Cross compiling for a different processor requires the presence of a toolchain and libraries for that target. There are a variety of ways to cross compile to RISC-V: * Use cargo cross. This is the fastest and easiest way to get started. * Install cross compiler packages from your OS distribution. Debian for example, has many riscv64 tools. * Build and install the official riscv-gnu-toolchain. Rust on RISC-V with cargo cross First, install cross: cargo install cross Create a new Rust project: cargo new --bin ockam_rv Add the Ockam dependency to the project's Cargo.toml dependencies: [dependencies] ockam = "0" Now let's turn main.rs into an Ockam Node: use ockam::*; #[ockam::node] async fn main(mut ctx: Context) -> Result<()> { println!("Hello, Ockam!"); ctx.stop().await } cross takes the same arguments as cargo. To build the project, run: cross build --target riscv64gc-unknown-linux-gnu This will generate a RISC-V binary in the target/ riscv64gc-unknown-linux-gnu/debug/ directory! You can also run the project in an emulated environment with cross: cross run --target riscv64gc-unknown-linux-gnu You should see output similar to: Finished dev [unoptimized + debuginfo] target(s) in 0.04s Running `/linux-runner riscv64 /target/riscv64gc-unknown-linux-gnu/debug/ockam_rv` 2021-11-03T19:52:01.495439Z INFO ockam_node::node: Initializing ockam node Hello, Ockam! 2021-11-03T19:52:01.586869Z INFO ockam_node::context: Shutting down all workers In most cases, cross is sufficient for cross compiling to RISC-V Linux. However, it does require Docker or Podman. Hello Ockam Let's create an encrypted secure channel between Alice and Bob. When a message is sent through this channel it will be encrypted when it enters the channel and decrypted just before it exits the channel. For the purpose of our example, we'll create a local channel within one program. In our other examples, you'll see that it's just as easy to create end-to-end protected channels over multi-hop, multi-protocol transport routes: Replace the contents of src/main.rs with the following code: use ockam::{route, Context, Entity, Result, TrustEveryonePolicy, Vault}; #[ockam::node] async fn main(mut ctx: Context) -> Result<()> { // Create a Vault to safely store secret keys for Alice and Bob. let vault = Vault::create(&ctx).await?; // Create an Entity to represent Bob. let mut bob = Entity::create(&ctx, &vault).await?; // Create a secure channel listener for Bob that will wait for requests to // initiate an Authenticated Key Exchange. bob.create_secure_channel_listener("bob", TrustEveryonePolicy).await?; // Create an entity to represent Alice. let mut alice = Entity::create(&ctx, &vault).await?; // As Alice, connect to Bob's secure channel listener and perform an // Authenticated Key Exchange to establish an encrypted secure channel with Bob. let channel = alice.create_secure_channel("bob", TrustEveryonePolicy).await?; // Send a message, ** THROUGH ** the secure channel, // to the "app" worker on the other side. // // This message will automatically get encrypted when it enters the channel // and decrypted just before it exits the channel. ctx.send(route![channel, "app"], "Hello Ockam!".to_string()).await?; // Wait to receive a message for the "app" worker and print it. let message = ctx.receive::().await?; println!("App Received: {}", message); // should print "Hello Ockam!" // Stop all workers, stop the node, cleanup and return. ctx.stop().await } A lot happened when you ran this small example. It created a secure vault, spawned workers to represent entities, established a mutually authenticated channel and then routed a message through that channel. This involved running cryptographic protocols for generating keys, authenticating as an entity, performing an authenticated key exchange and exchanging messages with authenticated encryption. Rust on RISC-V with OS toolchains The process for installing cross-compiling tools differs between OSes and distributions. The primary requirement for building Rust executables for RISC-V is the presence of a RISC-V linker, such as GCC. * For Debian: apt-get install gcc-riscv64-linux-gnu * For MacOS: brew tap riscv/riscv && brew install --cc=gcc-10 riscv-tools In your ockam_rv project, create a .cargo/config.toml file. In this file, we specify that we're builing for RISC-V and also configure the location of the linker. [build] target = "riscv64gc-unknown-linux-gnu" [target.riscv64gc-unknown-linux-gnu] linker = "/path/to/your/riscv64-unknown-linux-gnu-gcc" Now when you run cargo build, your local cross-compiling toolchain will be used to link the program, which is available in target/ riscv64gc-unknown-linux-gnu/debug You can now test this binary in an emulated RISC-V environment, or hardware. It is important to remember that glibc versions can differ between Linux distribution versions. Ensure that your emulated environment has a glibc version equal to or greater than used by your build tools. Rust on RISC-V with the official toolchain If packages are not available for RISC-V development on your OS, you may need to clone and build the tools yourself. * Clone the git repo https://github.com/riscv-collab/ riscv-gnu-toolchain * Follow the instructions to install pre-requisites for your system. * Run ./configure --prefix=/opt/riscv - Change the prefix path as appropriate. * Run make linux The tools default to building for RV64GC, which is perfect for Rust on RISC-V Linux. When the build is done, you will have /opt/riscv/bin /riscv64-unknown-linux-gnu-gcc along with other tools and libraries. Configure your Cargo project to use this as the linker. Testing with qemu and Debian A great way to test RISC-V programs is by using qemu and Debian Quick Image Baker pre-baked images. * Go to https://people.debian.org/~gio/dqib/ and download Images for riscv64-virt * Uncompress the downloaded artifacts.zip file. * Execute ./run.sh to boot your RISC-V Linux system! From here, you can either copy binaries into your vm over the local network or mounted filesystem. Testing with qemu and buildroot Buildroot is also a great way to test RISC-V programs, especially in custom or constrained environments. * Download buildroot or clone from https://github.com/buildroot/ buildroot * Run make qemu_riscv64_virt_defconfig * Either run make to build the system or make menuconfig to tweak any settings. * The resulting system will be built in output/images/ * Run ./start-qemu.sh in the output/images directory. Like with Debian on qemu, you can copy your test binary over the network, or use any other facility that qemu provides. --------------------------------------------------------------------- Next: End-to-End Encryption with Rust * (c) 2021 GitHub, Inc. * Terms * Privacy * Security * Status * Docs * Contact GitHub * Pricing * API * Training * Blog * About You can't perform that action at this time. You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.