import RT-Thread@9217865c without bsp, libcpu and components/net

This commit is contained in:
Zihao Yu 2023-05-20 16:23:33 +08:00
commit e2376a3709
1414 changed files with 390370 additions and 0 deletions

Binary file not shown.

After

Width:  |  Height:  |  Size: 79 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 76 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 89 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 54 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 115 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 37 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 174 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 63 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 1.9 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 2.1 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 20 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 18 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 21 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 33 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 20 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 21 KiB

View file

@ -0,0 +1,36 @@
# Keil MDK Installation
Before running the RT-Thread operating system, we need to install MDK-ARM 5.24 (either official or evaluation version, version 5.14 and above), this version is also a relatively new version. This version can provide relatively complete debugging functions. Here, we are using evaluation version 5.24 of 16k compiled code limit. If you want to remove the 16k compiled code limit, please purchase the official MDK-ARM.
Firstly, download the MDK-ARM evaluation version from the official website of www.keil.com:
[http://www.keil.com/download/](http://www.keil.com/download/)
When downloading, you need to fill in some basic information, please fill in the corresponding complete information, and then start downloading. After it is downloaded, double-click the mouse to start the installation, you will see the software installation as shown:
![First Step](./figures/1.png)
This is the MDK-ARM installation instructions, click “Next>>” to enter the next step, as shown.
![Second Step](./figures/2.png)
Click "√" in the box next to "I agree to all the terms of the preceding License Agreement" and click "Next >>" to proceed to the next step of installation, as shown:
![Third Step](./figures/3.png)
Click "Browse..." to select the installation directory of MDK-ARM or directly input installation path in the "Destination Folder" box. Here, we default to "C:/Keil_v5", then click "Next>>" to proceed to the next step of installation, as shown:
![Fourth Step](./figures/4.png)
Input your name after "First Name", input your last name after "Last Name", input your company name after "Company Name", input your email address after "E-mail", and then click "Next>> " for the installation. Wait for a while for the installation to finish and you will see the following:
![Fifth Step](./figures/12.png)
The default selection does not need to be changed, just click “Next” to enter the next step as shown.
![MDK-ARM Installment Complete](./figures/13.png)
Here, you can click "Finish" to complete the installation of the entire MDK-ARM software.
With a useful took like MDK-ARM, you can start the RT-Thread operating system easily and explore real-time operating systems.
>Note: There is a charge for Official version of MDK-ARM. If you want to be able to compile larger binaries, please purchase the official version of MDK-ARM. RT-Thread operating system also supports GNU GCC compiler by Free Software Foundation which is an open source compiler. For more information on how to use GNU related tools, please refer to the related documentation on RT-Thread website.

View file

@ -0,0 +1,150 @@
# Start Guide: Simulate STM32F103 on Keil Simulator
Because of its particularity, the embedded operating system is often closely related to the hardware platform, and specific embedded operating systems can only run on specific hardware. For those who might not have an RT-Thread compatible hardware module, or want to test out their ideas, a complete RT-Thread system can be developed in the simulation environment MDK-ARM.
MDK-ARM (Microcontroller Development Kit - ARM) is a complete integrated development environment (IDE) from ARM. It includes an efficient C/C++ compiler for ARM chips (ARM7, ARM9, Cortex-M series, Cortex-R series, etc.), a project wizard and project management for various ARM devices and evaluation boards and a simulator for simulating hardware platforms in software. It supports debuggers connected to simulators debugging the target board, such as the commonly available ST-Link, J-Link, etc. The simulator software in MDK-ARM uses a complete software simulation to interpret and execute machine instructions from ARM and implement some peripheral logic to form a complete virtual hardware environment, enabling users to execute the corresponding target program on the computer without using a real hardware platform.
Because of its full STM32F103 software simulation environment, the MDK-ARM integrated development environment gives us the opportunity to run object code directly on the computer without using a real hardware environment. This simulator platform can completely virtualize the various operating modes and peripherals of the ARM Cortex-M3, such as exceptions, interrupts, clock timers, serial ports, etc., which is almost identical to the real hardware environment. RT-Thread can run on both the simulated environment and on real hardware.
What will follow is a demonstration of RT-Thread running on a simulated STM32F103 microcontroller through MDK-ARM.
## Preparation
MDK development environment: MDK-ARM 5.24 (official or evaluation version, version 5.14 and above) needs to be installed. This version is a relatively new version, which can provide relatively complete debugging functions. An installation guide can be found here: [Keil MDK Installation](./keil-installation/keil-installation.md).
## First acquaintance with RT-Thread
To see the code size of RT-Thread we first need to get an example of RT-Thread that is suited for this environment, which can be obtained from the following link:
[RT-Thread Simulator Sample](./rtthread_simulator_v0.1.0.zip)
This example is a zip file, unzip it. The directory structure after decompression is as shown below:
![rtthread_simulator_v0.1.0 Code Directory ](./figures/7.png)
Descriptions of the file types contained in each directory are shown in the following table:
Directory Name | Description
--- | ---
applications| RT-Thread application.
rt-thread | Source file for RT-Thread.
- components| Respective component directories of RT-Thread.
- include | Header file for RT-Thread kernel.
- libcpu | Porting code for various types of chips, including porting files of STM32.
- src | Source file for RT-Thread kernel.
- tools | Script file of RT-Thread commanding building tool.
drivers | Driver of RT-Thread, implementations of bottom driver of different platforms.
Libraries | ST's STM32 firmware library file.
kernel-sample-0.1.0 | Kernel sample for RT-Thread.
In the directory, there is a file with the name "project.uvprojx", which is an MDK5 project file in the sample referenced in this manual. Double-click "project.uvprojx" icon to open the project file:
![Open the project](./figures/5.png)
Under the "Project" column on the left side of the main window of the project, you can see the file list of the project. These files are stored in the following groups, respectively:
| Directory Group | Description |
| :-------------- | ------------------------------------------------------------ |
| Applications | The corresponding directory is rtthread_simulator_v0.1.0/applications, used to store user application code. |
| Drivers | The corresponding directory is rtthread_simulator_v0.1.0/drivers, used to store the bottom driver code for RT-Thread. |
| STM32_HAL | The corresponding directory is rtthread_simulator_v0.1.0/Libraries/CMSIS/Device/ST/STM32F1xx, used to store the firmware library files of STM32. |
| kernel-sample | The corresponding directory is rtthread_simulator_v0.1.0/kernel-sample-0.1.0, used to store kernel samples of RT-Thread. |
| Kernel | The corresponding directory is rtthread_simulator_v0.1.0/src, used to store RT-Thread kernel core code. |
| CORTEX-M3 | The corresponding directory is rtthread_simulator_v0.1.0/rt-thread/libcpu, used to store ARM Cortex-M3 porting code. |
| DeviceDrivers | The corresponding directory is rtthread_simulator_v0.1.0/rt-thread/components/drivers, used to store driver framework source code of RT-Thread. |
| finsh | The corresponding directory is rtthread_simulator_v0.1.0/rt-thread/components/finsh, used to store command line of RT-Thread finsh command line component. |
Now click the button from the toolbar on the top the window, ![img](./figures/compile.jpg), to compile the project as shown:
![compiling](./figures/9.png)
The result of the compilation is displayed in the "Build Output" bar at the bottom of the window. If nothing else, it will say "0 Error(s), * Warning(s)." on the last line, that is, there are no errors or warnings.
After compiling RT-Thread/STM32, we can simulate running RT-Thread through the MDK-ARM simulator. Click ![img](./figures/debug.jpg) at the top right of the window or directly hit Ctrl+F5 to enter the simulation interface and hit F5 to start, then click the button in the toolbar shown in the screen shot or select “View→Serial Windows→UART#1” in the menu bar to open the serial port 1 window. You can see that the output of the serial port only shows the logo of RT-Thread. This is because the user code is empty and the result of its simulation is as shown:
![simulate RT-Thread1](./figures/10.png)
>We can output all the commands supported by the current system by inputting the Tab key or `help + enter` , as shown in the following figure.
![simulate RT-Thread2](./figures/6.png)
## User Entry Code
The above startup code is related to the RT-Thread system, so how do users add initialization code for their own applications? RT-Thread uses main function as the user code entry, all you need to do is just add your own code to the main function.
```c
int main(void)
{
/* user app entry */
return 0;
}
```
>Note: In order to complete the initialization for the system functions before entering the main program, you can use the `$sub$$` and `$super$$` function identifiers to call another sample before entering the main program, this was, users can ignore the initialization operations before the main() function. See [ARM® Compiler v5.06 for µVision® armlink User Guide](http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.dui0377g/pge1362065967698.html) for details.
## Example of a Marquee
For technical engineers working on electronics, marquee is probably the simplest example, the equivalent of Hello World in every programming language programmers learn. So we will start with a marquee in the following example, to make it periodically update (turn on or off) the LED.
Under UART#1, input msh command: led and then click Enter to run it, as shown:
![run led](./figures/11.png)
**Example of a Marquee**
```c
/*
* Manifest of programs: Marquee sample
*
* marquee is probably the simplest example, it is like the first program
* Hello World in every programming language that programmers learned. So we will start with a marquee in the following example, start a thread to make it periodically
* update (turn on or off) the LED.
*/
int led(void)
{
rt_uint8_t count;
rt_pin_mode(LED_PIN, PIN_MODE_OUTPUT);
for(count = 0 ; count < 10 ;count++)
{
rt_pin_write(LED_PIN, PIN_HIGH);
rt_kprintf("led on, count : %d\r\n", count);
rt_thread_mdelay(500);
rt_pin_write(LED_PIN, PIN_LOW);
rt_kprintf("led off\r\n");
rt_thread_mdelay(500);
}
return 0;
}
MSH_CMD_EXPORT(led, RT-Thread first led sample);
```
## Other Examples
Additional kernel examples can be found in the kernel-sample-0.1.0 directory.
![more kernel samples](./figures/14.png)
## Frequently Asked Question
* Compilation error occurred as following:
```
rt-thread\src\kservice.c(823): error: #929: incorrect use of vaarg fieldwidth = aarg(args, int);
rt-thread\src\kservice.c(842): error: #929: incorrect use of vaarg precision = aarg(args, int);
………
```
Cause: This type of problem is usually caused by installation of ADS, when ADS and keil coexist, the header file of va_start points to the ADS folder.
Solution:
- Delete ADS environment variables
- Uninstall ADS and Keil, restart the computer, reload Keil

Binary file not shown.

After

Width:  |  Height:  |  Size: 31 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 14 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 45 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 197 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 39 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 48 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 183 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 269 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 63 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 78 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 169 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 269 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 318 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 312 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 131 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 297 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 416 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 224 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 14 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 33 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 20 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 24 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 36 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 10 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 15 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 20 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 128 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 55 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 6.9 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 16 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 77 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 18 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 12 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 57 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 123 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 90 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 123 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 11 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 87 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 73 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 85 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 26 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 4.1 KiB

View file

@ -0,0 +1,146 @@
# Getting Started of QEMU (Windows)
The development of embedded software is inseparable from the development board. Without physical development boards, similar virtual machines like QEMU can be used to simulate the development board. QEMU is a virtual machine that supports cross-platform virtualization. It can virtualize many development boards. To facilitate the experience of RT-Thread without a development board, RT-Thread provides a board-level support package (BSP) for QEMU-simulated **ARM vexpress A9** development board.
## Preparations
- [Download RT-Thread Source Code](https://github.com/RT-Thread/rt-thread)
- Download Env Tool
- [Install Git on your PC](https://www.git-scm.com/download/)
## Instructions for the Env tool
When using Env tools, you need to enter the corresponding BSP directory in the Env terminal.
### Configuration
```
menuconfig
```
Type the `menuconfig` command in the Env terminal to enter the configuration interface, and then configure the BSP:
![menuconfig command](figures/win-menuconfig.png)
![enter the configuration interface](figures/env_menu.png)
You can use the keyboard `↑` key and `↓` key to look up and down menu items, use the `Enter` key to enter the selected directory, use the `Space` key to select or cancel bool variables, and use the `Esc` key to exit the current directory.
### Acquisition of software packages
```
pkgs --update
```
If a package is selected in menuconfig, download the package using the `pkgs --update` command (Git needs to be installed)
### Compile
```
scons
```
Compile using the `scons` command.
### Generate IDE's Project Files
```
scons --target=xxx
```
If you use the MDK or IAR IDE for development, you need to regenerate project files to make the configuration work after the configuration is completed. The command is `scons --target=xxx`, as shown below, which is the generation of IAR project, MDK4 project and MDK5 project.
```c
scons --target=iar
scons --target=mdk4
scons --target=mdk5
```
## Introduction of QEMU BSP Catalogue
The board-level support package (BSP) provided by RT-Thread simulates ARM vexpress A9 development board is located in the `qemu-vexpress-a9` folder under the BSP directory of RT-Thread source code. This BSP implements LCD, keyboard, mouse, SD card, Ethernet card, serial port and other related drivers. The contents of the folder are shown in the following figure.
![qemu-vexpress-a9 folder](figures/qemubsp.png)
The main files and directories of `qemu-vexpress-a9` BSP are described as follows:
| Fles/Directories | Description |
| ---------------- | ------------------------------------------- |
| .vscode | configuration file of vscode |
| applications | User application code directory |
| drivers | The underlying driver provided by RT-Thread |
| qemu.bat | Script files running on Windows platform |
| qemu.sh | Script files running on Linux platform |
| qemu-dbg.bat | Debugging script files on Windows platform |
| qemu-dbg.sh | Debugging script files on Linux platform |
| README.md | Description document of BSP |
| rtconfig.h | A header file of BSP |
## Compile and Run
### Step 1. Use the *scons* Command to Compile the Project
Open the Env folder and double-click the `env.exe` file to open the Env console:
![Env folder](figures/env.png)
Switch to the QEMU BSP directory and enter the `scons` command to compile the project. If the compilation is correct, the `rtthread.elf` file will be generated in the BSP directory, which is a target file required for QEMU to run.
![compile the project](figures/scons.png)
### Step 2. Use the *qemu.bat* Command to Run the Project
After compiling, type `qemu.bat` to start the virtual machine and BSP project. `qemu.bat` is a Windows batch file. This file is located in the BSP folder, mainly including the execution instructions of QEMU. The first run of the project will create a blank `sd.bin` file under the BSP folder, which is a virtual SD card with a size of 64M. The Env command interface displays the initialization information and version number information printed during the start-up of RT-Thread system, and the QEMU virtual machine is also running. As shown in the following picture:
![run the project](figures/qemu.bat.png)
![QEMU virtual machine](figures/qemu.png)
### Run the Finsh Console
RT-Thread supports Finsh, and users can use command operations in command line mode.
Type `help` or press `Tab` to view all supported commands. As shown in the figure below, commands are on the left and command descriptions are on the right.
![view all supported commands](figures/finsh-cmd.png)
For example, by entering the `list_thread` command, you can see the currently running threads, thread status and stack size; by entering the `list_timer`, you can see the status of the timers.
![threads and timers](figures/finsh-thread.png)
### Run the File System
Type `list_device` to view all devices registered in the system. You can see the virtual SD card "sd0" device as shown in the following picture. Next, we can format the SD card using the `mkfs sd0` command, which will format the SD card into a FatFS file system. FatFs is a Microsoft fat-compatible file system developed for small embedded devices. It is written in ANSI C, uses abstract hardware I/O layer and provides continuous maintenance, so it has good portability.
For more information on FatFS, click on the link: [http://elm-chan.org/fsw/ff/00index_e.html](http://elm-chan.org/fsw/ff/00index_e.html)
![format the SD card ](figures/mkfs-sd0.png)
The file system will not be loaded immediately after the first formatting of the SD card, and the file system will be loaded correctly only after the second boot. So exit the virtual machine, and then restart the virtual machine and project by entering `qemu.bat` on the Env command line interface. Entering `ls` command, you can see that the `Directory` directory has been added, the file system has been loaded, and then you can experience the file system with other commands provided by RT-Thread:
![commands of file system](figures/echo-cat.png)
- ls: Display file and directory information
- cd: Switch to the specified directory
- rm: Delete files or directories
- echo: Writes the specified content to the target file
- cat: Displays the details of a file
- mkdir: Create folders
Please enter `help` to see more commands.
## More Functions
Open the Env tool in the BSP directory and enter the `menuconfig` command:
![menuconfig](figures/menuconfig.png)
You can configure more functions in the configuration interface. After the configuration is completed, save the configuration first, and then exit the configuration interface:
![menuconfig interface](figures/menuconfig_menu.png)
1. If you choose a package, you need to use the command `pkgs --update` to download the package.
2. Compile with `scons`.
3. Then enter `qemu.bat` to run.
4. Use `help` to view all commands of the BSP. And then use the commands.

View file

@ -0,0 +1,203 @@
# Getting Started of QEMU (Ubuntu)
The development of embedded software is inseparable from the development board. Without physical development boards, similar virtual machines like QEMU can be used to simulate the development board. QEMU is a virtual machine that supports cross-platform virtualization. It can virtualize many development boards. To facilitate the experience of RT-Thread without a development board, RT-Thread provides a board-level support package (BSP) for QEMU-simulated **ARM vexpress A9** development board.
## 1 Install dependency libraries
We need to type commands as following in the terminal:
```shell
sudo apt install gcc
sudo apt install python3
sudo apt install python3-pip
sudo apt install gcc-arm-none-eabi
sudo apt install gdb-arm-none-eabi
sudo apt install binutils-arm-none-eabi
sudo apt install scons
sudo apt install libncurses5-dev
sudo apt install qemu
sudo apt install qemu-system-arm
sudo apt install git
```
## 2 Get RT-Thread source code
Download RT-Thread Source Code : `git clone https://github.com/RT-Thread/rt-thread.git`
You can directly ignore the following steps, this is used for setting GCC compiler manually. Usually, you don't need to set this.
> - Install the compiler. If the compiler version installed with `apt-get` command is too old, it will cause compilation errors. You can download and install the new version using the following command in turn. The download link and the decompression folder name will vary according to the download version. The following Compression Packet will unzip to the `/opt` folder.
>
> - `wget https://armkeil.blob.core.windows.net/developer/Files/downloads/gnu-rm/6-2016q4/gcc-arm-none-eabi-6_2-2016q4-20161216-linux.tar.bz2`
> - `cd /opt`
> - `sudo tar xf ~/gcc-arm-none-eabi-6_2-2016q4-20161216-linux.tar.bz2`
>
>
> - After the compiler is installed, it is necessary to modify the `rtconfig.py` file under `rt-thread/bsp/qemu-vexpress-a9` BSP, modify the corresponding path to the bin directory corresponding to the compiler decompressed into the opt directory. Referring to the following figure, the directory name varies according to the downloaded version of the compiler:
>
> ![edit EXEC_PATH in rtconfig.py](figures/ubuntu-rtconfig-py.png)
>
## 3 Build QEMU Project
### 3.1 Move into QEMU folder
```
cd rt-thread/bsp/qemu-vexpress-a9/
```
### 3.2 Configure the environment of Env tool
#### 3.2.1 Remap python command
We need to remap `python` command as python3 by default.
Using `whereis` command to identify your python3's version:
![python3-version](figures/python3-version.png)
For instance, as you can see, in my computer, the python3's version is python 3.9. You need to identify python3's version in your computer. Then, we remap the `python` command as python3 by default:
```shell
sudo rm -rf /usr/bin/python3
sudo rm -rf /usr/bin/python
sudo ln -s /usr/bin/python3.9 /usr/bin/python3
sudo ln -s /usr/bin/python3.9 /usr/bin/python
```
### 3.3 Install Env and Configure BSP
Type following the command under `bsp/qemu-vexpress-a9` folder:
```
scons --menuconfig
```
The Env tool will be installed and initialized after using the `scons --menuconfig` command. Then it will enter the configuration interface, and you could configure the BSP:
![install env tool](figures/ubuntu-menuconfig.png)
![enter the configuration interface](figures/ubuntu-env-menu.png)
You can use the keyboard `↑` key and `↓` key to look up and down menu items, use the `Enter` key to enter the selected directory, use the `Space` key to select or cancel bool variables, and press `Esc Esc` to exit the current directory.
> Notice: Please make sure that the terminal size is larger than 80x24 character size.
### 3.4 Configure the QEMU BSP and acquisition of software packages
```
source ~/.env/env.sh
scons --menuconfig
pkgs --update
```
The `env.sh` file is a file that needs to be executed. It configures the environment variables so that we can update the package with the pkgs command and execute it with the `source ~/.env/env.sh` command.
Then use `scons --menuconfig` command to enter menuconfig, and you could select the online packages by this time.
![commands of acquisition of pkgs](figures/ubuntu-pkg-menuconfig.png)
![add pkg menu](figures/ubuntu-pkgs-add-to-menu.png)
For example, select the kernel sample package: semphore sample.
![select a package](figures/ubuntu-select-pkg.png)
Exit and save the configuration.
![save the configuration](figures/ubuntu-save.png)
If you have selected an online package, you can download the package to the packages folder in the BSP directory using the `pkgs --update` command (Git needs to be installed):
![download the package](figures/ubuntu-update-pkg.png)
#### 4.1 Tips
Before you use the `pkgs` command, you need to type command `source ~/.env/env.sh`. This is a annoying work. We can attach this command as a new line at the end of `~/.bashrc`, which can let you to to use `pkgs` command directly.
### 3.5 Compile the QEMU project
```
scons
```
Using the `scons` command to compile the BSP.
![compile the BSP](figures/ubuntu-scons.png)
## 4 Introduction of QEMU BSP Catalogue
The board-level support package (BSP) provided by RT-Thread simulates ARM vexpress A9 development board is located in the `qemu-vexpress-a9` folder under the `bsp` directory of RT-Thread source code. This BSP implements LCD, keyboard, mouse, SD card, Ethernet card, serial port and other related drivers. The contents of the folder are shown in the following figure.
![qemu-vexpress-a9 folder](figures/ubuntu-qemu-bsp.png)
The main files and directories of `qemu-vexpress-a9` BSP are described as follows:
| Fles/Directories | Description |
| ---------------- | ------------------------------------------- |
| applications | User application code directory |
| drivers | The underlying driver provided by RT-Thread |
| qemu.bat | Script files running on Windows platform |
| qemu.sh | Script files running on Linux platform |
| qemu-dbg.bat | Debugging script files on Windows platform |
| qemu-dbg.sh | Debugging script files on Linux platform |
| README.md | Description document of BSP |
| rtconfig.h | A header file of BSP |
## 5 Compile and Run
### 5.1 Use the *scons* Command to Compile the Project
Switch to the QEMU BSP directory and enter the `scons` command to compile the project. If the compilation is correct, the `rtthread.elf` file will be generated in the BSP directory, which is a target file required for QEMU to run.
![compile the project](figures/ubuntu-scons.png)
### 5.2 Use the *./qemu.sh* Command to Run the Project
After compiling, type `./qemu.sh` to start the virtual machine and BSP project. `qemu.sh` is a Linux batch file. This file is located in the BSP folder, mainly including the execution instructions of QEMU. The first run of the project will create a blank `sd.bin` file under the BSP folder, which is a virtual SD card with a size of 64M. The Env command interface displays the initialization information and version number information printed during the start-up of RT-Thread system, and the QEMU virtual machine is also running. As shown in the following picture:
![run the project](figures/ubuntu-qume-sh.png)
### 5.3 Run the Finsh Console
RT-Thread supports Finsh, and users can use command operations in command line mode.
Type `help` or press `Tab` to view all supported commands. As shown in the figure below, commands are on the left and command descriptions are on the right.
![view all supported commands](figures/ubuntu-msh-help.png)
For example, by entering the `list_thread` command, you can see the currently running threads, thread status and stack size; by entering the `list_timer`, you can see the status of the timers.
![threads and timers](figures/ubuntu-thread-timer.png)
### 5.4 Run the File System
Type `list_device` to view all devices registered in the system. You can see the virtual SD card "sd0" device as shown in the following picture. Next, we can format the SD card using the `mkfs sd0` command, which will format the SD card into a FatFS file system. FatFs is a Microsoft fat-compatible file system developed for small embedded devices. It is written in ANSI C, uses abstract hardware I/O layer and provides continuous maintenance, so it has good portability.
> For more information on FatFS, click on the link: [http://elm-chan.org/fsw/ff/00index_e.html](http://elm-chan.org/fsw/ff/00index_e.html)
![format the SD card](figures/ubuntu-mkfs-sd0.png)
The file system will not be loaded immediately after the first formatting of the SD card, and the file system will be loaded correctly only after the second boot. So exit the virtual machine, and then restart the virtual machine and project by entering `./qemu.sh` on the command line interface. Entering `ls` command, you can see that the `Directory` directory has been added, the file system has been loaded, and then you can experience the file system with other commands provided by RT-Thread:
![commands of file system](figures/ubuntu-filesys.png)
- ls: Display the file and directory information
- cd: Switch to the specified directory
- rm: Delete files or directories
- echo: Writes the specified content to the target file
- cat: Displays the details of a file
- mkdir: Create folders
Please enter `help` to see more commands.
## 6 More Functions
You can configure more functions in the menuconfig's configuration interface. use `scons --menuconfig` to config the BSP. After the configuration is completed, save the configuration first, and then exit the configuration interface, then:
1. If you choose a package, you need to use the command `pkgs --update` to download the package.
2. Compile with `scons`.
3. Then enter `./qemu.sh` to run QEMU.
4. Use `help` to view all commands of the BSP. And then use the commands.

View file

@ -0,0 +1,181 @@
# Getting Started of QEMU (macOS)
The development of embedded software is inseparable from the development board. Without physical development boards, similar virtual machines like QEMU can be used to simulate the development board. QEMU is a virtual machine that supports cross-platform virtualization. It can virtualize many development boards. To facilitate the experience of RT-Thread without a development board, RT-Thread provides a board-level support package (BSP) for QEMU-simulated **ARM vexpress A9** development board. This document details the steps to run RT-Thread with QEMU on a macOS machine with an Intel processor.
## 1 Install dependency libraries
### 1.1 Install Python and SCons
Download the latest Python installer from the [official Python website](https://www.python.org/downloads/). Click on the installer and follow the steps to install.
Then install SCons with
```shell
python3 -m pip install scons
```
### 1.2 Use Homebrew to install QEMU
First install Homebrew with
```shell
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```
Then use Homebrew to install QEMU
```shell
brew install qemu
```
### 1.3 Install compiler toolchain
Download the latest ARM GNU toolchain from [armDeveloper website](https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/downloads). Download the `.tar.xz` file under macOS (x86_64) hosted cross toolchains, AArch32 bare-metal target (arm-none-eabi)
![gcc-arm-11.2-2022.02-darwin-x86_64-arm-none-eabi.tar.xz](figures/gnu-arm.png)
Move the file to an appropriate location. The following steps assume the file is moved to the home directory
Decompress the file
```shell
tar xf ~/gcc-arm-11.2-2022.02-darwin-x86_64-arm-none-eabi.tar.xz
```
Add the following line to `~/.bash_profile`
```shell
export PATH="$PATH:~/gcc-arm-11.2-2022.02-darwin-x86_64-arm-none-eabi/bin"
```
Run the following command. This is only needed once after `~/.bash_profile` is modified
```shell
source ~/.bash_profile
```
Check the installed tools can be detected
```
$ arm-none-eabi-gcc --version
arm-none-eabi-gcc (GNU Toolchain for the Arm Architecture 11.2-2022.02 (arm-11.14)) 11.2.1 20220111
Copyright (C) 2021 Free Software Foundation, Inc.
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
```
## 2 Get RT-Thread source code
Download RT-Thread Source Code : `git clone https://github.com/RT-Thread/rt-thread.git`
## 3 Build QEMU Project
### 3.1 Move into QEMU folder
```
cd rt-thread/bsp/qemu-vexpress-a9/
```
### 3.2 Install Env and Configure BSP
Type following the command under `bsp/qemu-vexpress-a9` folder:
```
scons --menuconfig
```
The Env tool will be installed and initialized after using the `scons --menuconfig` command. Then it will enter the configuration interface, and you could configure the BSP:
![enter the configuration interface](figures/macos-env-menu.png)
You can use the keyboard `↑` key and `↓` key to look up and down menu items, use the `Enter` key to enter the selected directory, use the `Space` key to select or cancel bool variables, and press `Esc Esc` to exit the current directory.
### 3.3 Acquire software packages
```
source ~/.env/env.sh
scons --menuconfig
pkgs --update
```
The `env.sh` file configures the environment variables so that you can update the package with the `pkgs` command. You need to run `source ~/.env/env.sh` every time before you use the `pkgs` command in a new terminal. To avoid doing this you can add this command to the end of `~/.bash_profile`, which can let you to use `pkgs` command directly.
Then use `scons --menuconfig` command to enter menuconfig, and you could select the online packages at this time.
![add pkg menu](figures/macos-pkgs-add-to-menu.png)
For example, select the system packages, POSIX extension functions, xxtension string functions `<strings.h>`
![select a package](figures/macos-select-pkg.png)
Exit and save the configuration.
![save the configuration](figures/macos-save.png)
If you have selected an online package, you can download the package to the packages folder in the BSP directory using the `pkgs --update` command (Git needs to be installed):
![download the package](figures/macos-update-pkg.png)
### 3.4 Compile the QEMU project
Run the `scons` command to compile the BSP. If the compilation is successful, the `rtthread.elf` file will be generated in the BSP directory, which is a target file required for QEMU to run.
## 4 Introduction of QEMU BSP Catalogue
The board-level support package (BSP) provided by RT-Thread simulates ARM vexpress A9 development board is located in the `qemu-vexpress-a9` folder under the `bsp` directory of RT-Thread source code. This BSP implements LCD, keyboard, mouse, SD card, Ethernet card, serial port and other related drivers. The contents of the folder are shown in the following figure.
![qemu-vexpress-a9 folder](figures/macos-qemu-bsp.png)
The main files and directories of `qemu-vexpress-a9` BSP are described as follows:
| Fles/Directories | Description |
| ---------------- | ------------------------------------------- |
| applications | User application code directory |
| drivers | The underlying driver provided by RT-Thread |
| qemu.bat | Script files running on Windows platform |
| qemu.sh | Script files running on Linux platform |
| qemu-dbg.bat | Debugging script files on Windows platform |
| qemu-dbg.sh | Debugging script files on Linux platform |
| README.md | Description document of BSP |
| rtconfig.h | A header file of BSP |
## 5 Run the QEMU project
### 5.1 Use the *./qemu.sh* Command to Run the Project
After compiling, type `./qemu.sh` to start the virtual machine and BSP project. This file is located in the BSP folder, mainly including the execution instructions of QEMU. The first run of the project will create a blank `sd.bin` file under the BSP folder, which is a virtual SD card with a size of 64M. The Env command interface displays the initialization information and version number information printed during the start-up of RT-Thread system, and the QEMU virtual machine is also running. As shown in the following picture:
![run the project](figures/macos-qemu-sh.png)
### 5.2 Run the Finsh Console
RT-Thread supports Finsh, and users can use command operations in command line mode.
Type `help` or press `Tab` to view all supported commands. As shown in the figure below, commands are on the left and command descriptions are on the right.
![view all supported commands](figures/macos-msh-help.png)
For example, by entering the `list_thread` command, you can see the currently running threads, thread status and stack size; by entering the `list_timer`, you can see the status of the timers.
![threads and timers](figures/macos-thread-timer.png)
### 5.3 Run the File System
Type `list_device` to view all devices registered in the system. You can see the virtual SD card "sd0" device as shown in the following picture. Next, we can format the SD card using the `mkfs sd0` command, which will format the SD card into a FatFS file system. FatFs is a Microsoft fat-compatible file system developed for small embedded devices. It is written in ANSI C, uses abstract hardware I/O layer and provides continuous maintenance, so it has good portability.
> For more information on FatFS, click on the link: [http://elm-chan.org/fsw/ff/00index_e.html](http://elm-chan.org/fsw/ff/00index_e.html)
![format the SD card](figures/macos-mkfs-sd0.png)
The file system will not be loaded immediately after the first formatting of the SD card, and the file system will be loaded correctly only after the second boot. So exit the virtual machine, and then restart the virtual machine and project by entering `./qemu_nographic.sh` on the command line interface. Entering `ls` command, you can see that the `Directory` directory has been added, the file system has been loaded, and then you can experience the file system with other commands provided by RT-Thread:
![commands of file system](figures/macos-filesys.png)
- ls: Display the file and directory information
- cd: Switch to the specified directory
- rm: Delete files or directories
- echo: Writes the specified content to the target file
- cat: Displays the details of a file
- mkdir: Create folders
Please enter `help` to see more commands.

Binary file not shown.