1# Getting Started of QEMU (macOS) 2 3The 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. 4 5## 1 Install dependency libraries 6 7### 1.1 Install Python and SCons 8 9Download the latest Python installer from the [official Python website](https://www.python.org/downloads/). Click on the installer and follow the steps to install. 10 11Then install SCons with 12 13```shell 14python3 -m pip install scons 15``` 16 17### 1.2 Use Homebrew to install QEMU 18 19First install Homebrew with 20 21```shell 22/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" 23``` 24 25Then use Homebrew to install QEMU 26 27```shell 28brew install qemu 29``` 30 31### 1.3 Install compiler toolchain 32 33Download 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) 34 35 36 37Move the file to an appropriate location. The following steps assume the file is moved to the home directory 38 39Decompress the file 40 41```shell 42tar xf ~/gcc-arm-11.2-2022.02-darwin-x86_64-arm-none-eabi.tar.xz 43``` 44 45Add the following line to `~/.bash_profile` 46 47```shell 48export PATH="$PATH:~/gcc-arm-11.2-2022.02-darwin-x86_64-arm-none-eabi/bin" 49``` 50 51Run the following command. This is only needed once after `~/.bash_profile` is modified 52 53```shell 54source ~/.bash_profile 55``` 56 57Check the installed tools can be detected 58 59``` 60$ arm-none-eabi-gcc --version 61arm-none-eabi-gcc (GNU Toolchain for the Arm Architecture 11.2-2022.02 (arm-11.14)) 11.2.1 20220111 62Copyright (C) 2021 Free Software Foundation, Inc. 63This is free software; see the source for copying conditions. There is NO 64warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 65``` 66 67## 2 Get RT-Thread source code 68 69Download RT-Thread Source Code : `git clone https://github.com/RT-Thread/rt-thread.git` 70 71## 3 Build QEMU Project 72 73### 3.1 Move into QEMU folder 74 75``` 76cd rt-thread/bsp/qemu-vexpress-a9/ 77``` 78 79### 3.2 Install Env and Configure BSP 80 81Type following the command under `bsp/qemu-vexpress-a9` folder: 82 83``` 84scons --menuconfig 85``` 86 87The 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: 88 89 90 91You 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. 92 93### 3.3 Acquire software packages 94 95``` 96source ~/.env/env.sh 97scons --menuconfig 98pkgs --update 99``` 100 101The `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. 102 103Then use `scons --menuconfig` command to enter menuconfig, and you could select the online packages at this time. 104 105 106 107For example, select the system packages, POSIX extension functions, xxtension string functions `<strings.h>` 108 109 110 111Exit and save the configuration. 112 113 114 115If 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): 116 117 118 119### 3.4 Compile the QEMU project 120 121Run 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. 122 123## 4 Introduction of QEMU BSP Catalogue 124 125The 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. 126 127 128 129The main files and directories of `qemu-vexpress-a9` BSP are described as follows: 130 131| Fles/Directories | Description | 132| ---------------- | ------------------------------------------- | 133| applications | User application code directory | 134| drivers | The underlying driver provided by RT-Thread | 135| qemu.bat | Script files running on Windows platform | 136| qemu.sh | Script files running on Linux platform | 137| qemu-dbg.bat | Debugging script files on Windows platform | 138| qemu-dbg.sh | Debugging script files on Linux platform | 139| README.md | Description document of BSP | 140| rtconfig.h | A header file of BSP | 141 142## 5 Run the QEMU project 143 144### 5.1 Use the *./qemu.sh* Command to Run the Project 145 146After 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: 147 148 149 150### 5.2 Run the Finsh Console 151 152RT-Thread supports Finsh, and users can use command operations in command line mode. 153 154Type `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. 155 156 157 158For 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. 159 160 161 162### 5.3 Run the File System 163 164Type `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. 165 166> 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) 167 168 169 170The 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: 171 172 173 174- ls: Display the file and directory information 175- cd: Switch to the specified directory 176- rm: Delete files or directories 177- echo: Writes the specified content to the target file 178- cat: Displays the details of a file 179- mkdir: Create folders 180 181Please enter `help` to see more commands. 182
