From 2ca2ea61e08b07a94cd4c299db73af6a85d03aa8 Mon Sep 17 00:00:00 2001 From: Wojciech Rajtar Date: Tue, 4 Jul 2023 11:15:19 +0200 Subject: [PATCH 1/2] Review README.md and documentation --- README.md | 70 ++++++++++++++++++++--------------------- docs/Devices.md | 37 ++++++++-------------- docs/Image.md | 34 ++++++++++---------- docs/Kernel.md | 30 +++++++++--------- docs/Network.md | 9 +++--- docs/Python-packages.md | 14 ++++----- 6 files changed, 90 insertions(+), 104 deletions(-) diff --git a/README.md b/README.md index 62a10bb..822ec33 100644 --- a/README.md +++ b/README.md @@ -2,41 +2,39 @@ Copyright (c) 2022-2023 [Antmicro](https://www.antmicro.com) -This action enables users to run workflows that require certain Linux [devices](#devices) not available in the default GitHub runners. -It even provides the means to run entire custom kernels. +This action enables users to run workflows that require certain Linux [devices](#devices) not available in default GitHub runners and provides the means to run entire custom kernels. This is achieved by running an emulated Linux system inside [Renode](https://renode.io/). -Because each project has very different requirements, this action provides an environment that's as configurable as possible. ## Parameters ### Tests configuration -- [`renode-run`](#running-your-commands-in-an-emulated-linux-system) - A command, list or [YAML Task](#tasks) with commands to run in Renode. -- [`shared-dirs`](#shared-directories) - Shared directory paths. The contents of these directories will be mounted in Renode. -- [`python-packages`](#python-packages) - Python packages from PyPI or a Git repository that will be sideloaded into the emulated Linux system. -- [`repos`](#git-repositories) - Git repositories that will be sideloaded into the emulated system. -- [`fail-fast`](#fail-fast) - Fail after first non-zero exit code instead of failing at the end. Default: `true` +- [`renode-run`](#running-your-commands-in-an-emulated-linux-system) - A single command, list of commands or a [YAML Task](#tasks) containing commands to be run in Renode +- [`shared-dirs`](#shared-directories) - Shared directory paths. Their contents will be mounted in Renode +- [`python-packages`](#python-packages) - Python packages from PyPI or a Git repository that will be sideloaded into the emulated Linux system +- [`repos`](#git-repositories) - Git repositories that will be sideloaded into the emulated system +- [`fail-fast`](#fail-fast) - Fail after first non-zero exit code instead of failing at the end. Default: `true`. ### OS configuration - [`rootfs-size`](#rootfs-size) - Set the size of the rootfs image. Default: `auto` - [`image-type`](#image) - `native` or `docker`. Read about the differences in the [image section](#image) -- [`image`](#image) - URL of the path to a `tar.xz` archive with a Linux rootfs for the specified architecture or a Docker image identifier. If not specified, the action will use the default one. See releases for examples. +- [`image`](#image) - URL path to a Linux rootfs `tar.xz` archive for the specified architecture or a Docker image identifier. If not specified, the action will use the default one. See releases for examples - [`tasks`](#tasks) - Allows you to change the way the system is initialized. See [Tasks](#tasks) for more details. ### Board and devices configuration -- [`network`](#network) - Enable access to the Internet in the emulated Linux system? Default: `true` -- [`devices`](#devices) - List of devices to add to the emulated system. If not specified, the action will not add any devices. -- [`kernel`](#kernel) - URL or path to the `tar.xz` archive containing the compiled embedded Linux kernel and initramfs. If not specified, the action will use the default kernel. See releases for examples. +- [`network`](#network) - Enable Internet access in the emulated Linux system. Default: `true` +- [`devices`](#devices) - List of devices to add to the emulated system. If not specified, the action will not add any devices +- [`kernel`](#kernel) - URL or path to the `tar.xz` archive containing the compiled embedded Linux kernel and initramfs. If not specified, the action will use the default kernel. See releases for examples - [`arch`](#emulation) - Processor architecture - [`board`](#board) - A specific board name, or `default` for architecture default, or `custom` for a custom board - [`resc`](#board) - Custom Renode script -- [`repl`](#board) - Custom Renode platform description +- [`repl`](#board) - Custom Renode platform description. ## Running your commands in an emulated Linux system -This is the simplest example of running your commands in the emulated Linux system. The default image will boot and log itself into a basic shell session. +This is the simplest example of how you can run your commands in the emulated Linux system. The default image will boot and log itself into a basic shell session. ```yaml - uses: antmicro/renode-linux-runner-action@v1 @@ -62,7 +60,7 @@ If you want to run more than one command, you can use a multiline string. For ex tty ``` -the result is: +you get the following result: ```raw # ls /dev | grep tty | head -n 3 @@ -73,7 +71,7 @@ tty1 /dev/ttySIF0 ``` -You can also run shell scripts, but you have to load them into the emulated system first using the [shared directories feature](#shared-directories) or by [sideloading Git repositories](#git-repositories). +You can also run shell scripts, but you need to load them into the emulated system first using the [shared directories feature](#shared-directories) or by [sideloading Git repositories](#git-repositories). ```yaml - uses: antmicro/renode-linux-runner-action@v1 @@ -94,7 +92,7 @@ You can also set additional test parameters with [Task files](#tasks). For examp - wget example.org ``` -This test will complete successfully because the network will be disabled in the emulated system and `wget` will return a non-zero exit code. +This test will complete successfully because the network is disabled in the emulated system and `wget` will return a non-zero exit code. ### Special cases @@ -102,7 +100,7 @@ If the action detects that one of your commands has failed, it will also fail wi ### Limitations -To keep the system image minimal, there is no standard `bash` shell, but a `busybox ash` shell instead. If you need `bash`, you can provide your own custom image. More on this in the [Image section](#image). +To keep the system image minimal, there is no standard `bash` shell, but a `busybox ash` shell instead. If you need `bash`, you can provide your own custom image. More on this in the ['Image' section of the documentation](#image). ## Examples @@ -110,7 +108,7 @@ The [release](.github/workflows/release.yml) workflow contains an example usage ## Emulation -The Linux emulation runs on the RISC-V/HiFive Unleashed single core platform in [Renode 1.13.3](https://github.com/renode/renode). This emulated system has some basics like 8GB of RAM and a network connection configured. +The Linux emulation runs on the RISC-V HiFive Unleashed single core platform in [Renode 1.13.3](https://github.com/renode/renode). Basic specs like 8GB of RAM and a network connection are configured in the emulated system. ### Architecture @@ -128,7 +126,7 @@ Available architectures: - riscv64 - arm32 (armv7) -We are working on `arm64` support. +We are working on adding `arm64` support. ## Shared directories @@ -148,7 +146,7 @@ In the following example, files from the `project-files` directory will be extra ## Devices -The action allows you to add additional devices that are available in a given kernel configuration. For example, if you want to add a stub Video4Linux device you can specify: +The action allows you to add additional devices available in a given kernel configuration. For example, if you want to add a stub Video4Linux device, you can specify: ```yaml - uses: antmicro/renode-linux-runner-action@v1 @@ -164,7 +162,7 @@ More about available devices and syntax to customize them can be found [in the ' ## Python packages -This action offers sideloading Python packages that you want to use in the emulated system. You can select any package from PyPI or from a Git repository. +This action lets you sideload Python packages that you want to use in the emulated system. You can select any package from PyPI or from a Git repository. For example: @@ -228,7 +226,7 @@ If you need additional software, you can mount your own filesystem. More informa ## Rootfs size -The size of the mounted rootfs can be specified with the `rootfs-size` parameter. The parameter accepts the sizes in bytes (i.e. `1000000000`), kilobytes (i.e. `50000K`), megabytes (i.e. `512M`) or gigabytes (i.e. `1G`). The default `rootfs-size` value is `auto`; with this setting the size is calculated automatically. +The size of the mounted rootfs can be specified with the `rootfs-size` parameter. The parameter accepts sizes in bytes (e.g. `1000000000`), kilobytes (e.g. `50000K`), megabytes (e.g. `512M`) or gigabytes (e.g. `1G`). The default `rootfs-size` value is `auto`; with this setting the size is calculated automatically. ```yaml - uses: antmicro/renode-linux-runner-action@v1 @@ -240,7 +238,7 @@ The size of the mounted rootfs can be specified with the `rootfs-size` parameter ## Tasks -Sometimes, after replacing the initramfs or board configuration, you may need to change the default commands that the action executes on each run. You can use Tasks for that. All the commands that the action executes are stored in the Task files in `action/tasks/*.yml`. If you want to change any of these, you can pass your own Task through the `tasks` action argument. If your Task has the same name as one of the default ones, it will replace it. +Sometimes, after replacing initramfs or changing the board configuration, you may need to change the default commands that the action executes on each run. You can use Tasks for that. All the commands that the action executes are stored in the Task files in `action/tasks/*.yml`. If you want to change any of these, you can pass your own Task through the `tasks` action argument. If your Task has the same name as one of the default ones, it will replace it. For example: @@ -261,13 +259,13 @@ For example: A Task file is a YAML file with the following fields: - `name`: the only mandatory field; it is used to resolve dependencies between Tasks. -- `shell`: the name of the shell on which the commands will be executed. The action has three available shells (`host`, `target`, `renode`). -- `requires`: the array of tasks that must be executed before this task. This list is empty by default. -- `before`: the array of tasks that must be executed after this task, but these tasks do not have to exist. This list is empty by default. +- `shell`: the name of the shell in which the commands will be executed. The action has three available shells (`host`, `target`, `renode`). +- `requires`: an array of tasks that must be executed before this task. This list is empty by default. +- `before`: an array of tasks that will be executed after this task. This list is empty by default and the tasks included in the array do not need to exist. - `echo`: Boolean parameter. If true, the output from the shell will be printed. Default: `false` - `timeout`: Default timeout for each command. Commands can override this setting. Default: `null`, meaning no timeout for your commands. - `fail-fast`: Boolean parameter. If true, the action will return the error from the first failed command and stop. Otherwise, the action will fail at the end of the task. Default: `true` -- `sleep`: The action will wait for the specified time in seconds before proceeding to the next task. Default: `0` +- `sleep`: The action will wait for the specified time (in seconds) before proceeding to the next task. Default: `0` - `command`: List of commands or `Command` objects to execute. Default: empty - `vars`: Dictionary of variables. [Read more about it here](#variables). Default: empty @@ -294,34 +292,34 @@ vars: ### Command syntax -For a list of commands you can just use a list of strings, but if you want more powerful customization, you can use a `Command` object with the following fields: +For a list of commands you can just use a list of strings, but if you want more customization, you can use a `Command` object containing the following fields: -- `command`: The shell command to be run. +- `command`: A shell command to be run. - `expect`: A string the action will wait for from the command's output. -- `timeout`: Timeout in seconds for the command. By default, the timeout is inherited from the task. +- `timeout`: Command timeout (in seconds). By default, the timeout is inherited from the task. - `echo`: Boolean parameter. If true, the output from the shell is printed. By default this parameter is inherited from the task. - `check-exit-code`: Boolean parameter. If true, the shell will check whether the command failed or not. Default: `true` ### Variables -You can define a list of variables and use it later with `${{VAR_NAME}}`. In addition, some predefined global variables are available: +You can define a list of variables and use it later with `${{VAR_NAME}}`. In addition, predefined global variables are available: - `${{BOARD}}`: name of the selected board - `${{NOW}}`: current date and time in the format `%Y-%m-%d %H:%M:%S` ### Shell initialization -All Tasks that refer to a particular shell have an additional hidden dependency. They require the Task that has the same name as the shell (for example, `renode`). These Tasks are used to configure the shell. However, you can replace these Tasks by simply providing your own version with the same name. +Any Task that refers to a particular shell will have an additional hidden, shell-specific dependency. They require the Task that has the same name as the shell (for example, `renode`). These Tasks are used to configure the shell. However, you can replace these Tasks by simply providing your own version with the same name. ## Kernel -It is possible to replace the Linux image on which the tests are run and mount a custom [file system image](#image). More information on how to do it can be found [in the 'Kernel' section of the docs](docs/Kernel.md). +It is possible to replace a Linux image on which the tests are run and mount a custom [file system image](#image). You can find further instructions on the topic [in the 'Kernel' section of the docs](docs/Kernel.md). ## Board -The action allows you to select your own board and choose its configuration. You can select a board from the list (remember that you also need to select the matching processor architecture). Here are the available boards: +The action allows you to select your own board and choose its configuration. You can select a board from a list (remember that you also need to select a matching processor architecture). Available boards are: - [riscv64 - hifive_unleashed](action/device/hifive_unleashed/init.resc) - [arm32 - zynq_7000](action/device/zynq_7000/init.resc) -You can also choose the default board: `default` or your own board: `custom`. In the latter case, you have to provide your own resc and repl files, which will configure the emulation. Configuration files can be selected using [`resc`](https://renode.readthedocs.io/en/latest/introduction/using.html#resc-scripts) and [`repl`](https://renode.readthedocs.io/en/latest/advanced/platform_description_format.html) parameters. You can read more about these files in the [Renode documentation](https://renode.readthedocs.io/en/latest/index.html). +You can also choose the default board: `default` or your own board: `custom`. In the latter case, you need to provide your own resc and repl files, which will configure the emulation. You can select the configuration files using [`resc`](https://renode.readthedocs.io/en/latest/introduction/using.html#resc-scripts) and [`repl`](https://renode.readthedocs.io/en/latest/advanced/platform_description_format.html) parameters. You can read more about these files in the [Renode documentation](https://renode.readthedocs.io/en/latest/index.html). diff --git a/docs/Devices.md b/docs/Devices.md index a9fbf15..e88369e 100644 --- a/docs/Devices.md +++ b/docs/Devices.md @@ -1,22 +1,22 @@ # Devices -This action offers several additional devices in the default images, which are not available in the GitHub runners, but are also not enabled by default. To enable a device simply add its name to the `devices` parameter along with optional parameters. +This action adds several devices not available in GitHub runners to the default images. These devices are not enabled by default. To enable a device simply add its name to the `devices` parameter along with optional parameters. > **Warnings** -> Adding devices may not work properly with your own kernel. If you want to use your own kernel, check that you have added the correct drivers. +> Adding devices may not work properly with your own kernel. If you want to use your own kernel, make sure you have added the correct drivers. -## YAML style passing devices +## Adding device configs using YAML -You can pass device configurations for inclusion with a simple YAML file. If you do not want to pass any parameters to the device, simply put its name on the next line. +You can add device configurations with YAML. If you do not want to pass any parameters to the device, just add its name. ### Available devices -- [`vivid`](https://www.kernel.org/doc/html/latest/admin-guide/media/vivid.html) - virtual device emulating a Video4Linux device -- [`gpio`](https://docs.kernel.org/admin-guide/gpio/gpio-mockup.html) - virtual device emulating GPIO lines. Optional parameters: - - left-bound: GPIO line numbers will start from this number - - right-bound: GPIO line numbers will end 1 before this number (for example, `gpio 0 64` will add 64 lines from 0 to 63) -- [`i2c`](https://www.kernel.org/doc/html/v5.10/i2c/i2c-stub.html) - virtual device emulating `I2C` bus. Optional parameter: - - chip-addr: 7 bit address 0x03 to 0x77 of the chip that simulates the EEPROM device and provides read and write commands to it. +- [`vivid`](https://www.kernel.org/doc/html/latest/admin-guide/media/vivid.html) - a virtual device emulating a Video4Linux device +- [`gpio`](https://docs.kernel.org/admin-guide/gpio/gpio-mockup.html) - a virtual device emulating GPIO lines. Optional parameters: + - `left-bound`: GPIO line numbers will start with this number + - `right-bound`: GPIO line numbers will end one number before this number (for example, `gpio 0 64` will add 64 lines from 0 to 63) +- [`i2c`](https://www.kernel.org/doc/html/v5.10/i2c/i2c-stub.html) - a virtual device emulating an `I2C` bus. Optional parameter: + - `chip-addr`: SMBus address between 0x03 and 0x77 to emulate a chip at. ### Example @@ -31,9 +31,9 @@ You can pass device configurations for inclusion with a simple YAML file. If you vivid ``` -## Passing devices by multiline string +## Adding devices using multiline strings -Devices can also be written out simply as individual lines in a multiline string. Then all the parameters have to be listed one by one (without their names). +You can also add devices as individual lines in a multiline string. Then you need to list all parameters one by one (without parameter names). For example: @@ -45,15 +45,4 @@ For example: gpio 16 32 i2c 0x1C vivid -``` - -### Old devices syntax - -```yaml -- uses: antmicro/renode-linux-runner-action@v1 - with: - devices: | - device1 param1 param2 param3 ... - device2 param1 param2 param3 ... - ... -``` +``` \ No newline at end of file diff --git a/docs/Image.md b/docs/Image.md index 6a529b7..5d4912b 100644 --- a/docs/Image.md +++ b/docs/Image.md @@ -1,21 +1,21 @@ # Image -This section details how to work with `image` packages that are compatible with this action. You can treat these images like containers: they provide the userspace software you need, compiled on the specified processor architecture, but have nothing to do with device drivers, the kernel, or the bootloader. +This section describes the workflow for `image` packages compatible with this action. You can treat these images like containers as they provide you with userspace software compiled for a specified processor architecture, independent from device drivers, the kernel, or the bootloader. ## Image type -There are two types of images that are compatible with this action: +There are two types of images compatible with this action: -* native: all files are placed in the `.tar.xz` archive +* native: all files are located in a `.tar.xz` archive * docker: docker container ### Native images -A native image is just an archive with a full Linux rootfs. You can add any files you want. The only requirement is a `/bin/sh` and binaries compiled for the specified architecture. +A native image is an archive with a full Linux rootfs. You can add any files you want. The only requirement is a `/bin/sh` and binaries compiled for a specified architecture. ### Docker images -The `docker` image type is a standard Docker image. The action will repack the latest layer into the standard .tar.xz archive and everything will continue as in the native image. The Docker images are downloaded from DockerHub. This is an example of using the `docker` image type: +The `docker` image type is a standard Docker image. The action will repack the latest layer into the standard `.tar.xz` archive and everything will continue as in the native image. The Docker images are downloaded from DockerHub. Here is an example of using the `docker` image type: ```yaml - uses: antmicro/renode-linux-runner-action@v1 @@ -41,34 +41,34 @@ Currently, the following `image` configurations are provided: * image-arm32-default.tar.xz -This images contains the following software: +These images contain the following software: * Full busybox 1.36.0 with ash shell -* Python 3.11.3 +* Python 3.11.2 * pip 22.3.1 * v4l2-utils 1.22.1 * libgpiod tools 1.6.3 * git 2.39.3 -* curl 8.1.2 +* curl 7.88.1 ## Required native image components -Your custom `image` package should include the required file system directory structure; to find out more please read [this](https://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard): +Your custom `image` package should include the required file system directory structure. To learn more, read [the Filesystem Hierarchy Standard Wikipedia entry](https://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard): Additionally you will need: -* shell executable available from `/bin/sh` -* If you want to use [`python-packages`](./Python-packages.md) you need `pip` available in your $PATH. +* a shell executable available from `/bin/sh` +* `pip` available in your $PATH if you want to use [`python-packages`](./Python-packages.md). ## Create your own native image -You can create the `image` package using any method you like, but we recommend using `buildroot`. It provides a lot of configuration options and will produce the file structure that this action requires. +You can create an `image` package using any method you like, but we recommend using `buildroot`. It provides many configuration options and will produce the file structure required by this action. -First, you may want to download the default `image` package configuration and modify it. The configuration is stored in the `image/` directory. +To start, you can download the default `image` package configuration and modify it. The configuration is stored in the `image/` directory. -### Adding the applications +### Adding applications -If you want to add applications that we do not currently offer in our build, take a look at the `configs/riscv64_defconfig` file. There you can add the additional applications offered by `buildroot`. You may also want to add specific package configurations or custom patches for them. See the `buildroot` documentation for more. +If you want to add applications that we do not currently offer in our build, take a look at the `configs/riscv64_defconfig` file. There you can add additional applications offered by `buildroot`. You may also want to add specific package configurations or custom patches for them. See the `buildroot` documentation for more. ### Preparing the archive @@ -78,7 +78,7 @@ Download the latest `buildroot` from [GitHub](https://github.com/buildroot/build make BR2_EXTERNAL=path/to/configuration name_defconfig ``` -and start compiling: +Then start compiling: ```sh make -j$(nproc) @@ -86,7 +86,7 @@ make -j$(nproc) This will take some time. -Eventually, you should have a `rootfs.tar` in the `buildroot/output/images` directory. Create the `xz` archive with `xz -z rootfs.tar'. +Eventually, you should end up with a `rootfs.tar` in the `buildroot/output/images` directory. Create an `xz` archive with `xz -z rootfs.tar`. ### Use your image diff --git a/docs/Kernel.md b/docs/Kernel.md index cf94a3a..decfc1e 100644 --- a/docs/Kernel.md +++ b/docs/Kernel.md @@ -5,9 +5,9 @@ This section describes in detail how to build `kernel` packages that will be compatible with this action. -First, it is worth mentioning that what we call the `kernel` package is actually a `tar.xz` archive containing `initramfs` and firmware for the emulated system. +Firstly, it is worth mentioning that what we call the `kernel` package is actually a `tar.xz` archive containing `initramfs` and firmware for the emulated system. -## Default images available +## Available default images We currently provide the following `kernel` configurations: @@ -19,37 +19,35 @@ We currently provide the following `kernel` configurations: * kernel-arm32-zynq_7000.tar.xz -This packages contains drivers essential for selected boards, but we have also added some other drivers: +The packages contain a Busybox with essential commands, drivers essential for these boards, and other drivers: * `vivid` for Video4Linux * `i2c-stub` * `gpio-mockup` -There is also a Busybox with essential commands. - ## Required image components Your custom `kernel` package should include: -* The file `vmlinux` or `Image`: the compiled kernel for the selected architecture with the bootloader and firmware if vmlinux is provided -* `fw_payload.elf`: (for `Image` kernel) the bootloader and firmware for the board -* `rootfs.cpio`: a packed `initramfs` compiled for the selected architecture -* `.dtb` file: the device tree binary file for the specified board with the `.dtb` file extension. +* A `vmlinux` or `Image` file - a compiled kernel for the selected architecture, and a bootloader and firmware for `vmlinux` kernels +* `fw_payload.elf` - a bootloader and firmware for `Image` kernels +* `rootfs.cpio` - a packaged `initramfs` compiled for the selected architecture +* `.dtb` file - a device tree binary file for the specified board. `rootfs.cpio` should contain: -* `/init`, an executable script that redirects output to `ttyS0` device and starts an interactive shell session. +* `/init`, an executable script that redirects output to the `ttyS0` device and starts an interactive shell session. * basic programs like: `sh`, `mount`, `chroot`, `dmesg`, `date`. -* If you want to use networking, you should provide the `ip` command and network stack. +* the `ip` command and a network stack, should you want to use networking. ## Create your own custom kernel package -You can build the `kernel` package using any method you like, but we recommend using `buildroot`. It provides a lot of configuration options and will produce the file structure that this action requires. -First, you may want to download the default `kernel` package configuration and modify it. The configuration is stored in the `kernel/` directory. +You can build the `kernel` package using any method you like, but we recommend using `buildroot`. It provides many configuration options and will produce the file structure that this action requires. +To start, you can download the default `kernel` package configuration and modify it. The configuration is stored in the `kernel/` directory. ### Adding Devices and Modifying Other Components -If you want to add devices that we currently do not offer in our build, take a look at the `configs/linux.config.fragment` file. You can add the additional drivers there. You may also want to change the kernel version in `configs/board_defconfig` or add/delete some kernel patches in `patches/linux`. +If you want to add devices that we currently do not offer in our build, take a look at the `configs/linux.config.fragment` file. You can add the necessary drivers there. You may also want to change the kernel version in `configs/board_defconfig` or add/delete kernel patches in `patches/linux`. ### Preparing the archive @@ -59,7 +57,7 @@ Download the latest `buildroot` from [GitHub](https://github.com/buildroot/build make BR2_EXTERNAL=path/to/configuration board_name_defconfig ``` -and start compiling: +Start compiling: ```sh make -j$(nproc) @@ -67,7 +65,7 @@ make -j$(nproc) This will take some time. -Eventually, you should have some files in the `buildroot/output/images` directory. Create the new `tar.xz` archive with [required files](#required-image-components). The resulting archive is ready to use with the action. +You should end up with files in the `buildroot/output/images` directory. Create a new `tar.xz` archive with the [required files](#required-image-components). The resulting archive is ready for use with the action. ### Use your kernel diff --git a/docs/Network.md b/docs/Network.md index ea670fb..72a2bca 100644 --- a/docs/Network.md +++ b/docs/Network.md @@ -1,10 +1,10 @@ # Network -The emulated Linux system can access the Internet. This allows testing applications that require an Internet connection in addition to access to specific drivers. If an Internet connection is not needed it can also be disabled. +The emulated Linux can access the Internet. This allows you to test applications that require an Internet connection in addition to access to specific drivers. If an Internet connection is not needed, it can be disabled. ## How it works -The Renode emulator creates a [TAP](https://www.kernel.org/doc/html/latest/networking/tuntap.html) device on the host OS. Then, both the tap device and the emulated Ethernet module are connected to the virtual switch. +The Renode emulator creates a [TAP](https://www.kernel.org/doc/html/latest/networking/tuntap.html) device on the host OS. Then both the tap device and the emulated Ethernet module are connected to a virtual switch. Network configuration: @@ -14,7 +14,8 @@ Network configuration: ## Disable network -If you don't need the Internet or don't have the proper permissions, you can disable the entire configuration with the `network: false` flag. You can continue to use options such as installing external Python packages, sharing directories or sideloading Git repositories. +Should you not need an Internet connection or not have the proper permissions, you can disable the entire configuration with the `network: false` flag. +You can continue to use options such as installing external Python packages, sharing directories or sideloading Git repositories. ```yaml - uses: antmicro/renode-linux-runner-action@v1 @@ -26,4 +27,4 @@ If you don't need the Internet or don't have the proper permissions, you can dis ## Known issues -Sometimes when cloning Git repositories the emulated system using an HTTPS connection, the download fails due to certificate errors or buffer overflows. If you have an idea how we can solve this problem, feel free to suggest it to us. +Cloning Git repositories for the emulated system using an HTTPS connection sometimes fails due to certificate errors or buffer overflows. We are open for suggestions on solving this problem. diff --git a/docs/Python-packages.md b/docs/Python-packages.md index e478a91..466783e 100644 --- a/docs/Python-packages.md +++ b/docs/Python-packages.md @@ -1,12 +1,12 @@ -# Python packages sideloading +# Sideloading python packages -You can use the `python-packages` parameter to add the Python packages you require to test your software. This is the recommended option, as downloading packages manually in the emulated system is possible, but can sometimes fail. +You can use the `python-packages` parameter to add the Python packages you require to test your software. This is the recommended option, as downloading packages manually in the emulated system is possible but can sometimes fail. ## Available options The `python-packages` parameter accepts any packages from the PyPI repository and from public Git repositories. For packages from PyPI you can select additional requirements like minimum or exact version (see examples below), and for packages from Git repositories you can select a specific commit, branch or tag. -There is no need to manually add dependencies. The action will resolve them and install all required packages by itself. +There is no need to manually add dependencies. The action will resolve them and install all required packages. Examples: @@ -23,12 +23,12 @@ Examples: ## Collecting requirements -All dependencies for the appropriate architecture (e.g. riscv64) are resolved and downloaded automatically. If the packages contain binaries which are not precompiled, their sources will be downloaded. +All dependencies for a respective architecture (e.g. riscv64) are resolved and downloaded automatically. If packages contain non-precompiled binaries, their sources will be downloaded. -The action creates an empty virtual environment where it tries to install packages in [`--dry-run`](https://pip.pypa.io/en/stable/cli/pip_install/#cmdoption-dry-run) mode, and then collects the requirements of what additional dependencies were needed. The whole thing is based on the [`--report`](https://pip.pypa.io/en/stable/reference/installation-report/) functionality, which in the stable version was added in `pip 23.0`. From the report you can read exactly what packages were needed and in what versions. +The action creates an empty virtual environment where it tries to install packages in [`--dry-run`](https://pip.pypa.io/en/stable/cli/pip_install/#cmdoption-dry-run) mode, and collects information about required dependencies. This feature is based on the [`--report`](https://pip.pypa.io/en/stable/reference/installation-report/) functionality added in `pip 23.0` (stable). The report details what packages and versions are needed. -The action then downloads all the needed packages from the repositories, preferring the binary versions, and adds the saved files to the registry, which it will use later when sideloading. +The action then downloads all the necessary packages from their repositories, preferring binary versions, and adds the saved files to the registry, for later use when sideloading. ## Sideloading -After booting the emulated Linux and mounting the disks, it's time to install the Python packages. The only thing the action does is specify all the downloaded files as argument. Dependency downloading is disabled and must remain so, otherwise `pip` will try to download them from the Internet, even though the required package is provided as one of the arguments. +After booting the emulated Linux and mounting the disks, you can install the Python packages. The action specifies all the downloaded files as argument. Dependency downloading is disabled and must remain so, otherwise `pip` will try to download them from the Internet, even though the required packages are provided as arguments. From ad32a041246c5e0356e6beef4a9f17850db19b68 Mon Sep 17 00:00:00 2001 From: Wojciech Rajtar Date: Tue, 4 Jul 2023 11:48:17 +0200 Subject: [PATCH 2/2] Fix wording --- docs/Devices.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Devices.md b/docs/Devices.md index e88369e..6912f69 100644 --- a/docs/Devices.md +++ b/docs/Devices.md @@ -1,6 +1,6 @@ # Devices -This action adds several devices not available in GitHub runners to the default images. These devices are not enabled by default. To enable a device simply add its name to the `devices` parameter along with optional parameters. +The action's default images contain several devices not available in GitHub runners. These devices are not enabled by default. To enable a device simply add its name to the `devices` parameter along with optional parameters. > **Warnings** > Adding devices may not work properly with your own kernel. If you want to use your own kernel, make sure you have added the correct drivers.