Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jonlamb-gh/renode-run
A custom Cargo runner that runs Rust firmware in the renode emulator
https://github.com/jonlamb-gh/renode-run
cargo-runner embedded-rust renode simulation
Last synced: 2 months ago
JSON representation
A custom Cargo runner that runs Rust firmware in the renode emulator
- Host: GitHub
- URL: https://github.com/jonlamb-gh/renode-run
- Owner: jonlamb-gh
- License: apache-2.0
- Created: 2023-03-15T11:13:22.000Z (almost 2 years ago)
- Default Branch: master
- Last Pushed: 2024-03-26T15:54:29.000Z (10 months ago)
- Last Synced: 2024-10-07T04:48:51.036Z (3 months ago)
- Topics: cargo-runner, embedded-rust, renode, simulation
- Language: Rust
- Homepage:
- Size: 38.1 KB
- Stars: 6
- Watchers: 2
- Forks: 0
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- License: LICENSE-APACHE
Awesome Lists containing this project
README
# renode-run ![ci] [![crates.io]](https://crates.io/crates/renode-run)
A custom Cargo runner that runs Rust firmware in the [renode] emulator.
## Features
* Acts as a Cargo runner, integrating into `cargo run`.
* Exposes all of [renode]'s scripting facilities and CLI as configuration in your `Cargo.toml`.
* Provides configuration for the environment, allowing you to perform environment variable
substitution on nearly everything.
## Installation
To install `renode-run`, use `cargo install renode-run`.
## Setup
**NOTE** Requires [renode] to be installed on the host system.
### 1. Set the Cargo runner
Set `renode-run` as your Cargo runner (`.cargo/config.toml`).
``` toml
[target.'cfg(all(target_arch = "arm", target_os = "none"))']
runner = "renode-run"
```
### 2. Run
You can now run your firmware using `cargo run`.
## Configuration
### `[package.metadata.renode]` options
**NOTE** Many of these can be overridden by CLI options. Nearly every field supports environment variable substitution.
Fields pertaining the `resc` script generation:
- **name**: The name field used in the generated `resc` script.
If not present, the name of the crate is used or a default name is provided.
- **description**: The description field used in the generated `resc` script.
If not present, the description of the crate is used or a default description is provided.
- **machine-name**: The machine's name.
- **init-commands**: An array of commands ran after the machine is created and before variables are declared.
- **variables**: An array of variable declarations.
`renode-run` will automatically insert `$bin = @target//` as provided by Cargo.
- **platform-description**: A single platform description.
Can be one of:
* a renode-provided `repl` file (starts with `@`)
* a local `repl` file (doesn't start with `@`)
* a local `repl` file that is to be imported and generated into the output directory (starts with `<`).
This is handy when you want to perform environment substitution on the contents of a `repl` file.
* a literal string
- **platform-descriptions**: An array of platform descriptions.
Each entry can be one of:
* a renode-provided `repl` file (starts with `@`)
* a local `repl` file (doesn't start with `@`)
* a local `repl` file that is to be imported and generated into the output directory (starts with `<`).
This is handy when you want to perform environment substitution on the contents of a `repl` file.
* a literal string
- **reset**: The reset macro definition. The default is `sysbus LoadELF $bin`.
- **start**: The start command definition. The default is `start`.
- **pre-start-commands**: An array of commands ran immediately before the `start` command.
- **post-start-commands**: An array of commands ran immediately after the `start` command.
Fields pertaining the behavior of `renode-run`:
- **environment-variables**: An array of environment variables and values to set for both the `renode-run` and `renode` environment.
- **renode**: The path to the `renode` binary to use. Defaults to using the system's `$PATH`.
- **omit-start**: Don't generate a `start` command. Defaults to `false`.
- **omit-out-dir-path**: Don't add the output directory to renode's path.
- **resc-file-name**: The name of the generated `resc` script. Defaults to `emulate.resc`.
- **use-relative-paths**: TBD
- **disable-envsub**: TBD
- **using-sysbus**: TBD
Fields pertaining the invocation of `renode` itself:
- **plain**: Adds `--plain` to the list of arguments given to `renode`.
- **port**: Adds `--port ` to the list of arguments given to `renode`.
- **disable-xwt**: Adds `--disable-xwt` to the list of arguments given to `renode`.
- **hide-monitor**: Adds `--hide-monitor` to the list of arguments given to `renode`.
- **hide-log**: Adds `--hide-log` to the list of arguments given to `renode`.
- **hide-analyzers**: Adds `--hide-analyzers` to the list of arguments given to `renode`.
- **console**: Adds `--console` to the list of arguments given to `renode`.
- **keep-temporary-files**: Adds `--keep-temporary-files` to the list of arguments given to `renode`.
## Example
```toml
[package.metadata.renode]
name = 'my-script'
description = 'my renode script - ${FOOKEY} works'
machine-name = 'my-machine'
using-sysbus = true
renode = '${HOME}/repos/forks/renode/renode'
environment-variables = [
['FOOKEY', 'FOOVAL'],
["MYENV", "MYVAL"],
]
init-commands = [
'logLevel -1 i2c2',
]
variables = [
'$tap?="renode-tap0"',
# Set random board UNIQUE ID
'''
python "import _random"
python "rand = _random.Random()"
$id1 = `python "print rand.getrandbits(32)"`
$id2 = `python "print rand.getrandbits(32)"`
$id3 = `python "print rand.getrandbits(32)"`
''',
]
platform-descriptions = [
'@platforms/boards/stm32f4_discovery-kit.repl',
'path/to/dev_board.repl',
'< ${SOMETHING}/other_dev_board.repl',
'''
phy3: Network.EthernetPhysicalLayer @ ethernet 3
Id1: 0x0000
Id2: 0x0000
''',
'''
wss: Python.PythonPeripheral @ sysbus 0x50070000
size: 0x10
initable: true
filename: "${ORIGIN}/sensor_models/wss.py"
''',
]
pre-start-commands = [
'''
emulation CreateSwitch "switch"
connector Connect sysbus.ethernet switch
emulation CreateTap $tap "tap"
connector Connect host.tap switch
''',
'''
logFile @/tmp/logfile.log true
logLevel 3 file
''',
'emulation LogEthernetTraffic',
'machine StartGdbServer 3333',
'''
sysbus.usart3 AddLineHook "PANIC" "Antmicro.Renode.Logging.Logger.Log(LogLevel.Error, line)"
sysbus.usart3 AddLineHook "test result: ok" "Antmicro.Renode.Emulator.Exit()"
''',
]
reset = '''
sysbus LoadELF $bin
sysbus WriteDoubleWord 0x1FFF7A10 $id1
sysbus WriteDoubleWord 0x1FFF7A14 $id2
sysbus WriteDoubleWord 0x1FFF7A18 $id3
'''
```
## License
Licensed under either of
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
at your option.
### Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
licensed as above, without any additional terms or conditions.
[ci]: https://github.com/jonlamb-gh/renode-run/workflows/CI/badge.svg
[crates.io]: https://img.shields.io/crates/v/renode-run.svg
[renode]: https://renode.io/