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