README.md
1# QEMU Arm Virt for Standard System Tutorial
2
3## 1. Overview
4
5The `arm_virt/linux` directory contains code that has been verified on the QEMU Arm Virt platform for adapting to Linux kernel. The code includes the driver and board configurations.
6
7The Arm Virt platform is a `qemu-system-arm` target device that simulates a general-purpose board running on the Arm architecture.
8The board whose **machine** is **virt** in QEMU is configurable. For example, you can select the core type and quantity, memory size, and security extensions when configuring the board.
9
10This tutorial guides you through the configuration of a board based on the Cortex-A7 architecture, with one CPU, extended secure features, Generic Interrupt Controller versions 2 (GICv2), and 1 GB memory.
11The system memory is hardcoded to 1024 MB.
12
13## 2. Setting Up the Environment
14
15For details, see [Environment Setup](https://gitee.com/openharmony/docs/blob/HEAD/en/device-dev/quick-start/quickstart-standard.md)
16
17## 3. Obtaining the Source Code
18
19For details, see [Source Code Acquisition](https://gitee.com/openharmony/docs/blob/HEAD/en/device-dev/get-code/sourcecode-acquire.md).
20
21## 4. Building the Source Code
22
23In the root directory of the obtained source code, run the following command:
24
25```
26./build.sh --product-name qemu-arm-linux-min --ccache --jobs 4
27./build.sh --product-name qemu-arm-linux-headless --ccache --jobs 4
28```
29
30After this command is executed, the image files for standard system are generated in out/qemu-arm-linux/packages/phone/images/ directory.
31qemu-arm-linux-min means product with minimum set of components.
32qemu-arm-linux-headless add application framework related components based on qemu-arm-linux-min.
33
34## 5. Running an Image in QEMU
35
36a) If `qemu-system-arm` has not been installed, install it. For details, see [Qemu Installation](https://gitee.com/openharmony/device_qemu/blob/HEAD/README.md).
37
38Note: The introduced functions have been tested on the target machine of virt-5.1, but are not available for all QEMU versions. Therefore, you must ensure that the qemu-system-arm version is 5.1 or later.
39
40
41b) Run the images.
42
43After the source code is built, run the `./vendor/ohemu/qemu_arm_linux_min/qemu_run.sh` or `./vendor/ohemu/qemu_arm_linux_headless/qemu_run.sh` command, the images built in step 4 will be started.
44
45c) Exit QEMU.
46
47Press `Ctrl-A + x` to exit the QEMU virtual environment.
48
49
README_zh.md
1# Qemu ARM Virt 标准系统教程
2
3## 1. 简介
4
5`arm_virt/linux` 子目录包含部分Qemu ARM虚拟化平台验证的Linux kernel的适配代码，含驱动配置、板端配置等。
6
7ARM 虚拟化平台是一个 `qemu-system-arm` 的目标设备，通过它来模拟一个通用的、基于ARM架构的单板。
8Qemu中machine为 **virt** 的单板就是这种可配置的，例如：选择核的类型、核的个数、内存的大小和安全特性等，单板设备的配置。
9
10这次模拟的配置是：Cortex-A7架构，1个CPU，带安全扩展，GICv2，1G内存。
11提示: 系统内存硬编码为1024MB。
12
13## 2. 环境搭建
14
15参考链接: [环境搭建](https://gitee.com/openharmony/docs/blob/HEAD/zh-cn/device-dev/quick-start/quickstart-standard.md)
16
17## 3. 获取源码
18
19参考链接: [代码获取](https://gitee.com/openharmony/docs/blob/HEAD/zh-cn/device-dev/get-code/sourcecode-acquire.md)
20
21## 4. 源码构建
22
23在已经获取的源码根目录，请输入：
24
25```
26./build.sh --product-name qemu-arm-linux-min --ccache --jobs 4
27./build.sh --product-name qemu-arm-linux-headless --ccache --jobs 4
28```
29
30在构建完成之后，对应的镜像文件在out/qemu-arm-linux/packages/phone/images/目录下。
31qemu-arm-linux-min表示部件最小集合的产品。
32qemu-arm-linux-headless表示在最小集合基础上，支持无屏幕的用户程序框架部件集合的产品。
33
34
35## 5. 在Qemu中运行镜像
36
37a) 如果没有安装 `qemu-system-arm` ，安装请参考链接 [Qemu installation](https://gitee.com/openharmony/device_qemu/blob/HEAD/README_zh.md)
38
39提示：当前引入的功能在virt-5.1的目标machine已经完成测试，不保证所有的Qemu版本都能够运行成功，因此需要保证你的qemu-system-arm
40版本尽可能在5.1及以上。
41
42b) 运行镜像
43
44执行`./vendor/ohemu/qemu_arm_linux_min/qemu_run.sh`或`./vendor/ohemu/qemu_arm_linux_headless/qemu_run.sh`即可运行步骤4生成的镜像。
45
46c) 退出qemu环境
47
48按下`Ctrl-A + x`可退出qemu虚拟环境。
49
50### 5.1 qemu_run.sh使用说明
51
52```C
53Usage: qemu-run [OPTION]...
54Run a OHOS image in qemu according to the options.
55 -e, --exec image_path images path, including: zImage-dtb, ramdisk.img, system.img, vendor.img, userdata.img
56 -g, --gdb enable gdb for kernel.
57 -n, --network auto setup network for qemu (sudo required).
58 -i, --instance id start qemu images with specified instance id (from 01 to 99).
59 it will also setup network when running in multiple instance mode.
60 -f force override instance image with a new copy.
61 -h, --help print this help info.
62
63 If no image_path specified, it will find OHOS image in current working directory; then try .
64
65 When setting up network, it will create br0 on the host PC with the following information:
66 IP address: 192.168.100.1
67 netmask: 255.255.255.0
68
69 The default qemu device MAC address is [00:22:33:44:55:66], default serial number is [0023456789].
70 When running in multiple instances mode, the MAC address and serial number will increase with specified instance ID as follow:
71 MAC address: {instanceID}:22:33:44:55:66
72 Serial number: {instanceID}23456789
73```
74
75qemu_run.sh默认会启动当前工作目录或out/qemu-arm-linux/packages/phone/images目录下的系统镜像。
76
77默认的qemu虚拟机没有网络连接。如果需要使能网络连接，可以添加-n选项。此选项会完成以下几个事物：
78
79- 主机侧创建虚拟网桥
80
81 主机侧会创建br0的网桥，用于与qemu ram虚拟机设备进行网络通信。
82
83 br0默认IP地址为192.168.100.1，子网掩码为255.255.255.0。
84
85 由于主机侧创建虚拟网桥需要管理员权限，因此，需要通过sudo命令执行qemu_run.sh。
86
87
88- 虚拟机侧创建虚拟网卡
89
90 启动qemu arm虚拟机时会为虚拟机设备创建一个网卡，该网卡的默认MAC地址是12:22:33:44:55:66，在虚拟机的网络接口名称是eth0。
91
92 虚拟机启动后，可以通过ifconfig eth0 192.168.100.2给虚拟机设置上IP地址（其它IP地址都可以，只要在同一个网段内）。
93
94 通过此设置，主机就可以和虚拟机进行网络通信。可以使用hdc与虚拟机交互。
95
96正常的OHOS设备都有一个唯一的设备序列号，该序列号会用于各个业务进行设备唯一标识。使用qemu虚拟机启动时，默认的序列号是0123456789。
97
98### 5.2 qemu_run.sh多实例运行
99
100有时需要运行多个qemu arm虚拟机实例，用于验证分布式组网场景。此时，可以在调用qemu_run.sh时传入-i指定不同实例号。每个不同实例号运行多虚拟机设备都有不同的MAC地址和SN号，以此来模拟多个虚拟设备。MAC地址和SN号的分配规则如下：
101
102 MAC address: {instanceID}:22:33:44:55:66
103 Serial number: {instanceID}23456789
104
105instanceID的取值格式为两个数字字符：范围为01到99。
106
107当镜像输出目录中已存在该instanceID的实例时，默认不重新拷贝镜像。若要重新拷贝镜像可在调用qemu_run.sh时传入-f选项将原镜像覆盖。
108