-
Notifications
You must be signed in to change notification settings - Fork 302
/
dev-environment.md
243 lines (174 loc) · 8.85 KB
/
dev-environment.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
# OpenBMC Development Environment
**Document Purpose:** How to set up an OpenBMC development environment
**Audience:** Programmer familiar with Linux and BMCs
**Prerequisites:** Current Linux, Mac, or Windows system
## Overview
OpenBMC uses the [Yocto](https://www.yoctoproject.org/) Project as its
underlying building and distribution generation framework. The main OpenBMC
[README](https://github.com/openbmc/openbmc/blob/master/README.md) provides
information on getting up and going with Yocto and OpenBMC. There are mechanisms
to use this process to build your changes but it can be slow and cumbersome for
initial debug and validation of your software. This guide focuses on how to test
new changes quickly using the OpenBMC Software Development Kit (SDK) and
[QEMU](https://www.qemu.org/).
The SDK is a group of packages that are built during a BitBake operation.
BitBake is the tool used to build Yocto based distributions. The SDK provides
all required libraries and cross compilers to build OpenBMC applications. The
SDK is not used to build entire OpenBMC flash images, it provides a mechanism to
compile OpenBMC applications and libraries that you can then copy onto a running
system for testing.
QEMU is a software emulator that can be used to run OpenBMC images.
This doc walks through the recommended steps for setting up an OpenBMC
development environment and installing the needed SDK.
For testing purposes, this guide uses the Romulus system as the default because
this is the system tested for each CI job, which means it's the most stable.
## Install Linux Environment
If you are running Linux, and are ok with installing some additional packages,
then you can skip to step 3.
The recommended OpenBMC development environment is the latest Ubuntu LTS
release. Other versions of Linux may work but you are using that at your own
risk. If you have Windows or Mac OS then VirtualBox is the recommended
virtualization tool to run the development environment.
1. Install either [VirtualBox](https://www.virtualbox.org/wiki/Downloads) or
[VMware](https://www.vmware.com/products/workstation-player/workstation-player-evaluation.html)
onto your computer (Mac, Windows, Linux)
Both have free versions available for what you need. VirtualBox is what the
majority of core OpenBMC development is using. **Note:** If you want to use this
VM to BitBake a full OpenBMC image, you'll want to allocate as many resources as
possible. Ideal minimum resources are 8 threads, 16GB memory, 200GB hard drive.
Just using for SDK builds and QEMU should work fine with the normal defaults on
a VM.
2. Install the latest Ubuntu LTS release
The majority of OpenBMC development community uses Ubuntu. The qemu below is
built on [18.04](http://releases.ubuntu.com/18.04/) but whatever is most recent
_should_ work. The same goes for other Linux distributions like Fedora but
again, these are not tested nearly as much by the core OpenBMC team as Ubuntu.
**VirtualBox Tips** - You'll want copy/paste working between your VM and Host.
To do that, once you have your VM up and running:
- Devices -> Insert Guest Additions CD Image (install)
- Devices -> Shared Clipboard -> Bidirectional
- reboot (the VM)
3. Install required packages
Refer to
[Prerequisite](https://github.com/openbmc/openbmc/blob/master/README.md#1-prerequisite)
link.
**Note** - In Ubuntu, a "sudo apt-get update" will probably be needed before
installing the packages.
## Download and Install SDK
The OpenBMC Software Development Kit (SDK) contains a cross-toolchain and a set
libraries for working on OpenBMC applications. The SDK is installed on the
machine you will use to develop applications for OpenBMC and not on the BMC
itself.
Generally, SDKs for one BMC cannot be used for developing software for other
BMCs. This can be due to platform ABI, libc or kernel differences, or any other
number of choices made in the configuration of the firmware.
Romulus is the BMC platform used for the purpose of this walk-through.
To begin working with the SDK:
1. Download the latest SDK to your system. It's recommended that you create a
directory to store your SDK scripts and installation directories to keep your
workspace organised.
```
mkdir -p ~/sdk
cd ~/sdk
wget https://jenkins.openbmc.org/job/latest-master-sdk/label=docker-builder,target=romulus/lastSuccessfulBuild/artifact/deploy/sdk/oecore-x86_64-arm1176jzs-toolchain-nodistro.0.sh
chmod u+x oecore-x86_64-arm1176jzs-toolchain-nodistro.0.sh
```
2. Install the SDK
Choose an appropriate location and name. It's a good idea to include the date
and system supported by that SDK in the directory name. For example:
```
mkdir -p ~/sdk/romulus-`date +%F`
```
Run the following command to install the SDK. When command asks you to "Enter
target directory for SDK", enter the directory you created in the previous step.
```
./oecore-x86_64-arm1176jzs-toolchain-nodistro.0.sh
```
The installation script will indicate progress and give completion messages like
this:
```
SDK has been successfully set up and is ready to be used.
Each time you wish to use the SDK in a new shell session, you need to source
the environment setup script e.g. $ . /...path-to-sdk.../environment-setup-arm1176jzs-openbmc-linux-gnueabi
```
3. Source yourself into the SDK
Ensure no errors. The command to do this will be provided at the end of
installation. To make your shell use the new SDK environment, you must source
its `environment-setup` script which was created in the previous step. You may
wish to save the required command, for example, cut/paste the text above into a
README.
That's it, you now have a working development environment for OpenBMC!
## Download and Start QEMU Session
1. Download latest openbmc/qemu fork of QEMU application
```
wget https://jenkins.openbmc.org/job/latest-qemu-x86/lastSuccessfulBuild/artifact/qemu/build/qemu-system-arm
chmod u+x qemu-system-arm
```
2. Download the Romulus image.
```
wget https://jenkins.openbmc.org/job/latest-master/label=docker-builder,target=romulus/lastSuccessfulBuild/artifact/openbmc/build/tmp/deploy/images/romulus/obmc-phosphor-image-romulus.static.mtd
```
3. Start QEMU with downloaded Romulus image
**Note** - For REST, SSH and IPMI to work into your QEMU session, you must
connect up some host ports to the REST, SSH and IPMI ports in your QEMU
session. In this example, it just uses 2222, 2443, 2623. You can use whatever
you prefer.
```
./qemu-system-arm -m 256 -M romulus-bmc -nographic \
-drive file=./obmc-phosphor-image-romulus.static.mtd,format=raw,if=mtd \
-net nic \
-net user,hostfwd=:127.0.0.1:2222-:22,hostfwd=:127.0.0.1:2443-:443,hostfwd=udp:127.0.0.1:2623-:623,hostname=qemu
```
**Note** - By default, Jenkins and openbmc-test-automation use SSH and HTTPS
ports 22 and 443, respectively. For the IPMI port 623 is used. SSH connection to
use a user-defined port 2222 might not be successful. To use SSH port 22, HTTPS
port 443 and IPMI port 623:
```
./qemu-system-arm -m 256 -machine romulus-bmc -nographic \
-drive file=./obmc-phosphor-image-romulus.static.mtd,format=raw,if=mtd \
-net nic \
-net user,hostfwd=:127.0.0.1:22-:22,hostfwd=:127.0.0.1:443-:443,hostfwd=tcp:127.0.0.1:80-:80,hostfwd=tcp:127.0.0.1:2200-:2200,hostfwd=udp:127.0.0.1:623-:623,hostfwd=udp:127.0.0.1:664-:664,hostname=qemu
```
4. Wait for your QEMU-based BMC to boot
Login using default root/0penBmc login (Note the 0 is a zero).
5. Check the system state
You'll see a lot of services starting in the console, you can start running the
obmcutil tool to check the state of the OpenBMC state services. When you see the
following then you have successfully booted to "Ready" state.
```
root@openbmc:~# obmcutil state
CurrentBMCState : xyz.openbmc_project.State.BMC.BMCState.Ready
CurrentPowerState : xyz.openbmc_project.State.Chassis.PowerState.Off
CurrentHostState : xyz.openbmc_project.State.Host.HostState.Off
```
**Note** To exit (and kill) your QEMU session run: `ctrl+a x`
## Alternative yocto QEMU
yocto has tools for building and running qemu. These tools avoid some of the
configuration issues that come from downloading a prebuilt image, and modifying
binaries. Using yocto qemu also uses the
[TAP interface](https://www.kernel.org/doc/Documentation/networking/tuntap.txt)
which some find be more stable. This is particularly useful when debugging at
the application level.
- set up a bmc build environment
```
source setup romulus myBuild/build
```
- add the qemu x86 open embedded machine for testing
```
MACHINE ??= "qemux86"
```
- Make the changes to the build (ie devtool modify bmcweb, devtool add gdb)
```
devtool modify bmcweb myNewLocalbmcweb/
```
- build open bmc for the qemu x86 machine
```
MACHINE=qemux86 bitbake obmc-phosphor-image
```
- run qemu they way yocto provides
```
runqemu myBuild/build/tmp/deploy/images/qemux86/ nographic \
qemuparams="-m 2048"
```
- after that the all the a TAP network interface is added, and protocol like
ssh, scp, http work well.