Skip to content

Commit 8e42cdc

Browse files
mgieldamgielda
committed
Add link to Robot framework, not everyone is familiar with it.
1 parent 9167965 commit 8e42cdc

File tree

1 file changed

+67
-67
lines changed

1 file changed

+67
-67
lines changed

‎README.md‎

Lines changed: 67 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -1,67 +1,67 @@
1-
# Renode issue reproduction template
2-
3-
This repository is meant to help report issues in (and provide contributions to) the open source [Renode simulation framework](https://renode.io).
4-
5-
It has a GitHub Actions CI set up for you so that you only need to provide the minimum amount of data which reproduces the issue (= makes the CI fail).
6-
7-
Fork this repo and [adapt the template to build a test case which shows the failure](#usage-to-report-bugs), and if you have an idea how to [provide a fix](#providing-fixes), implement it in this repo to showcase the desired solution and outcome, all nicely automated.
8-
9-
## Important files in this repo
10-
11-
* `.github/workflows` - the GH Actions plumbing; touch it only if you want to make some fundamental changes
12-
* `artifacts` - any files you want the CI to store for demonstration (e.g. logs) should end up here during the CI job
13-
* `build.sh` - a stub of a potential build script for your [test software](#providing-test-software)
14-
* `requirements.txt` - add any Python requirements here, if needed
15-
* `test.resc` - Renode script file, you will most likely be changing this one
16-
* `test.robot` - Robot test file, most likely also requiring adaptations
17-
18-
## Usage to report bugs
19-
20-
Adapt the `.resc` and `.robot` files until you get the CI to fail (with the dreaded red cross showing up) in a way that you know should not happen, e.g. the simulated binary should be printing something to UART but apparently doesn't.
21-
22-
Report an issue in https://github.com/renode/renode and link to your clone, with any additional explanations needed.
23-
24-
Files in the `artifacts/` directory will automatically be saved as build artifacts so if you want to share e.g. logs, make sure they end up there after the CI executes.
25-
26-
## Providing fixes
27-
28-
Sometimes you may already know what the fix should be - this repository is an easy way to get your fix included in mainline Renode!
29-
30-
To do that, implement changes in this repo which make the previously failing CI green again. One way to do that may involve providing standalone `.cs` files with the fixed model code and loading them in runtime to override the original implementations.
31-
32-
If you report an issue with such a fix already in place using this repository - we can then easily verify this on our end and help you prepare a PR.
33-
34-
### Overriding existing or adding new peripheral models in runtime
35-
36-
Loading new `.cs` files in runtime is as easy as executing `include @my_file.cs` in the `.resc` script or `ExecuteCommand include @my_file.cs` in the `.robot` file. Please note that names of the dynamically added classes should not overlap with existing ones, so if you e.g., fix the `ABC_UART` class that is referenced in the `abc.repl` platform you should create the `ABC_UART_Fixed` class and update the `.repl` file to reference `ABC_UART_Fixed` instead of the original `ABC_UART`.
37-
38-
It might happen that during the dynamic compilation you see compilation errors about unknown types. In such case you should use the `EnsureTypeIsLoaded` command. See the example below for details.
39-
40-
```
41-
# in case your implementation references types available in Renode
42-
# but not recognized by the dynamic compiler use the `EnsureTypeIsLoaded` command;
43-
# this step is only needed if you encounter unreferenced types errors during execution of the `include` command
44-
EnsureTypeIsLoaded "Antmicro.Renode.NameOfTheUnknownType"
45-
46-
# load your fixed implementation of the model
47-
include @ABC_UART_Fixed.cs
48-
49-
# make sure that abc.repl references the ABC_UART_Fixed class instead of ABC_UART
50-
mach create
51-
machine LoadPlatformDescription @abc.repl
52-
53-
[...]
54-
```
55-
56-
## Providing test software
57-
58-
If you can reproduce your problem with one of our demo binaries hosted at dl.antmicro.com or in the [Zephyr Dashboard](https://zephyr-dashboard.renode.io/), feel free to use that.
59-
60-
If you need your specific software to replicate the issue, please try to create the minimum failing binary (preferably in ELF form; for formats without debug symbols, remember to set the Program Counter after loading them).
61-
62-
You can just commit your binary into the repository and use it in the `.resc` script, especially in situations when due to confidentiality you can only share the binary.
63-
64-
If you can share the sources, please include them e.g. in a `src/` directory - and if you have the time to do so, also adapt `build.sh` to build it.
65-
Otherwise you can just commit a binary you compiled yourself corresponding to the sources.
66-
67-
If you can't share your binary or a minimal test case based on it, you can always adapt the CI to pull it from some secret storage with authentication, but that of course may need more work.
1+
# Renode issue reproduction template
2+
3+
This repository is meant to help report issues in (and provide contributions to) the open source [Renode simulation framework](https://renode.io).
4+
5+
It has a GitHub Actions CI set up for you so that you only need to provide the minimum amount of data which reproduces the issue (= makes the CI fail).
6+
7+
Fork this repo and [adapt the template to build a test case which shows the failure](#usage-to-report-bugs), and if you have an idea how to [provide a fix](#providing-fixes), implement it in this repo to showcase the desired solution and outcome, all nicely automated.
8+
9+
## Important files in this repo
10+
11+
* `.github/workflows` - the GH Actions plumbing; touch it only if you want to make some fundamental changes
12+
* `artifacts` - any files you want the CI to store for demonstration (e.g. logs) should end up here during the CI job
13+
* `build.sh` - a stub of a potential build script for your [test software](#providing-test-software)
14+
* `requirements.txt` - add any Python requirements here, if needed
15+
* `test.resc` - Renode script file, you will most likely be changing this one
16+
* `test.robot` - [Robot](https://robotframework.org/) test file, most likely also requiring adaptations
17+
18+
## Usage to report bugs
19+
20+
Adapt the `.resc` and `.robot` files until you get the CI to fail (with the dreaded red cross showing up) in a way that you know should not happen, e.g. the simulated binary should be printing something to UART but apparently doesn't.
21+
22+
Report an issue in https://github.com/renode/renode and link to your clone, with any additional explanations needed.
23+
24+
Files in the `artifacts/` directory will automatically be saved as build artifacts so if you want to share e.g. logs, make sure they end up there after the CI executes.
25+
26+
## Providing fixes
27+
28+
Sometimes you may already know what the fix should be - this repository is an easy way to get your fix included in mainline Renode!
29+
30+
To do that, implement changes in this repo which make the previously failing CI green again. One way to do that may involve providing standalone `.cs` files with the fixed model code and loading them in runtime to override the original implementations.
31+
32+
If you report an issue with such a fix already in place using this repository - we can then easily verify this on our end and help you prepare a PR.
33+
34+
### Overriding existing or adding new peripheral models in runtime
35+
36+
Loading new `.cs` files in runtime is as easy as executing `include @my_file.cs` in the `.resc` script or `ExecuteCommand include @my_file.cs` in the `.robot` file. Please note that names of the dynamically added classes should not overlap with existing ones, so if you e.g., fix the `ABC_UART` class that is referenced in the `abc.repl` platform you should create the `ABC_UART_Fixed` class and update the `.repl` file to reference `ABC_UART_Fixed` instead of the original `ABC_UART`.
37+
38+
It might happen that during the dynamic compilation you see compilation errors about unknown types. In such case you should use the `EnsureTypeIsLoaded` command. See the example below for details.
39+
40+
```
41+
# in case your implementation references types available in Renode
42+
# but not recognized by the dynamic compiler use the `EnsureTypeIsLoaded` command;
43+
# this step is only needed if you encounter unreferenced types errors during execution of the `include` command
44+
EnsureTypeIsLoaded "Antmicro.Renode.NameOfTheUnknownType"
45+
46+
# load your fixed implementation of the model
47+
include @ABC_UART_Fixed.cs
48+
49+
# make sure that abc.repl references the ABC_UART_Fixed class instead of ABC_UART
50+
mach create
51+
machine LoadPlatformDescription @abc.repl
52+
53+
[...]
54+
```
55+
56+
## Providing test software
57+
58+
If you can reproduce your problem with one of our demo binaries hosted at dl.antmicro.com or in the [Zephyr Dashboard](https://zephyr-dashboard.renode.io/), feel free to use that.
59+
60+
If you need your specific software to replicate the issue, please try to create the minimum failing binary (preferably in ELF form; for formats without debug symbols, remember to set the Program Counter after loading them).
61+
62+
You can just commit your binary into the repository and use it in the `.resc` script, especially in situations when due to confidentiality you can only share the binary.
63+
64+
If you can share the sources, please include them e.g. in a `src/` directory - and if you have the time to do so, also adapt `build.sh` to build it.
65+
Otherwise you can just commit a binary you compiled yourself corresponding to the sources.
66+
67+
If you can't share your binary or a minimal test case based on it, you can always adapt the CI to pull it from some secret storage with authentication, but that of course may need more work.

0 commit comments

Comments
 (0)