Skip to content

Commit 247161a

Browse files
artur-rsartur-rs
authored
Merge pull request #4 from zarhus/basic-docs
Add basic docs.
2 parents 6d2bd82 + 8a37b05 commit 247161a

15 files changed

+1414
-2
lines changed

‎docs/getting-started/building.md

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
# Building Zarhus OS
2+
3+
<!--
4+
TODO: scalable way to build different images (e.g. with WebKit or without
5+
WebKit support) for different platforms.
6+
-->
7+
8+
This guide will demonstrate how to build a Zarhus OS image from zero!
9+
10+
## Prerequisites
11+
12+
* Linux PC (tested on `Fedora 40`)
13+
* [docker](https://docs.docker.com/engine/install/fedora/) installed
14+
* [kas-container
15+
3.0.2](https://raw.githubusercontent.com/siemens/kas/3.0.2/kas-container)
16+
script downloaded and available in
17+
[PATH](https://en.wikipedia.org/wiki/PATH_(variable)).
18+
19+
```bash
20+
mkdir ~/.local/bin
21+
wget -O ~/.local/bin/kas-container https://raw.githubusercontent.com/siemens/kas/3.0.2/kas-container
22+
chmod +x ~/.local/bin/kas-container
23+
```
24+
25+
!!! note
26+
27+
You may need to add `~/.local/bin` into your
28+
[PATH](https://en.wikipedia.org/wiki/PATH_(variable)). You can do so for
29+
example by adding `export PATH=$PATH:~/.local/bin` to your `.bashrc` and
30+
`source` it.
31+
32+
* `meta-zarhus` repository cloned:
33+
34+
```bash
35+
mkdir yocto
36+
cd yocto
37+
git clone https://github.com/zarhus/meta-zarhus.git
38+
```
39+
40+
* [`bmaptool`](https://docs.yoctoproject.org/dev-manual/bmaptool.html)
41+
installed:
42+
43+
```bash
44+
sudo dnf install bmap-tools
45+
```
46+
47+
!!! note
48+
49+
You can also use `bmaptool` [from
50+
GitHub](https://github.com/yoctoproject/bmaptool) if it is not available in
51+
your distro.
52+
53+
## Build
54+
55+
From `yocto` directory run:
56+
57+
```shell
58+
$ SHELL=/bin/bash kas-container build meta-zarhus/kas-IMAGE_TYPE.yml
59+
```
60+
61+
!!! note
62+
63+
Replace `IMAGE_TYPE` with either `debug` or `prod`.
64+
65+
Image build takes time, so be patient and after the build finishes you should see
66+
something similar to this (the exact tasks numbers may differ):
67+
68+
```shell
69+
Initialising tasks: 100% |###########################################################################################| Time: 0:00:01
70+
Sstate summary: Wanted 2 Found 0 Missed 2 Current 931 (0% match, 99% complete)
71+
NOTE: Executing Tasks
72+
NOTE: Tasks Summary: Attempted 2532 tasks of which 2524 didn't need to be rerun and all succeeded.
73+
```
74+
75+
# Verification
76+
77+
The build should finish without errors or warnings.
78+
79+
After the build has finished - feel free to explore
80+
`yocto/build/tmp/deploy/images/MACHINE_NAME/` directory for built images.
81+
82+
!!! note
83+
84+
Replace `MACHINE_NAME` with the name of the machine you have built your
85+
image for.
86+
87+
You should find an image with filename ending with `.rootfs.wic.gz` and a binary
88+
map for the image in format with filename ending with `.rootfs.wic.bmap`. These
89+
files will be needed for [flashing process](./flashing.md).

‎docs/getting-started/flashing.md

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
# Flashing Zarhus OS
2+
3+
There are many ways an OS can be flashed and booted on embedded platform, but
4+
the most common one is using an SD card. This guide will describe SD card
5+
flashing only, because all other ways to flash the image are highly
6+
target-specific and are described [per-target](../supported-targets/targets.md).
7+
8+
## Flashing SD card
9+
10+
This section demonstrates how to flash a Zarhus OS image on the SD card.
11+
12+
### Prerequisites
13+
14+
* Linux PC (tested on `Fedora 40`);
15+
* [bmaptool](https://docs.yoctoproject.org/dev-manual/bmaptool.html)
16+
installed:
17+
18+
```bash
19+
sudo apt install bmap-tools
20+
```
21+
22+
* Zarhus OS image built according to [build guide](./building.md).
23+
24+
!!! note
25+
26+
You can also use `bmaptool` [from
27+
GitHub](https://github.com/yoctoproject/bmaptool) if it is not available in
28+
your distro.
29+
30+
### Flashing
31+
32+
Find out your device name:
33+
34+
```shell
35+
$ lsblk
36+
(...)
37+
sdx 8:16 1 14.8G 0 disk
38+
├─sdx1 8:17 1 3.5M 0 part
39+
├─sdx2 8:18 1 256K 0 part
40+
├─sdx3 8:19 1 192K 0 part
41+
(...)
42+
```
43+
44+
!!! warning
45+
46+
In this case the device name is `/dev/sdx` **but be aware, in next steps
47+
replace `/dev/sdx` with the right device name on your platform or else you
48+
can damage your system!**
49+
50+
From the directory you ran your image build, run command:
51+
52+
```shell
53+
$ cd build/tmp/deploy/images/MACHINE_NAME
54+
$ sudo umount /dev/sdx*
55+
$ sudo bmaptool copy IMAGE_NAME-IMAGE_TYPE-MACHINE_NAME.rootfs.wic.gz /dev/sdx
56+
```
57+
58+
!!! note
59+
60+
Replace `MACHINE_NAME` with the name of the machine you have built the image
61+
for, `IMAGE_TYPE` with `debug` or `prod` and `IMAGE_NAME` with the name of
62+
the image you have built.
63+
64+
You should see output similar to this:
65+
66+
```shell
67+
bmaptool: info: block map format version 2.0
68+
bmaptool: info: 85971 blocks of size 4096 (335.8 MiB), mapped 42910 blocks (167.6 MiB or 49.9%)
69+
bmaptool: info: copying image 'zarhus-base-image-debug-zarhus-machine-cm3.rootfs.wic.gz' to block device '/dev/sdx' using bmap file 'zarhus-base-image-debug-zarhus-machine-cm3.rootfs.wic.bmap'
70+
bmaptool: info: 100% copied
71+
bmaptool: info: synchronizing '/dev/sdx'
72+
bmaptool: info: copying time: 11.1s, copying speed 15.1 MiB/sec
73+
```
74+
75+
## Verification
76+
77+
After the SD card has been flashed with your image, the partitions (at least
78+
`rootfs` partition) should be mountable. So, you can mount a partition and
79+
explore the Zarhus OS without even booting it! Here is example block storage
80+
layout after flashing [Zarhus Rockchip OS
81+
image](https://github.com/zarhus/meta-zarhus-bsp-rockchip/blob/main/wic/sdimage-rockchip.wks):
82+
83+
```bash
84+
$ lsblk
85+
(...)
86+
sdx 8:16 1 14.8G 0 disk
87+
├─sdx1 8:17 1 3.5M 0 part
88+
├─sdx2 8:18 1 256K 0 part
89+
├─sdx3 8:19 1 192K 0 part
90+
├─sdx4 8:20 1 32K 0 part
91+
├─sdx5 8:21 1 32K 0 part
92+
├─sdx6 8:22 1 4M 0 part
93+
├─sdx7 8:23 1 4M 0 part
94+
├─sdx8 8:24 1 4M 0 part
95+
└─sdx9 8:25 1 320.7M 0 part
96+
(...)
97+
```
98+
99+
!!! note
100+
101+
Your SD card may get another file name in your system, here `sdx` is shown
102+
as an example.
103+
104+
Mounting `rootfs`:
105+
106+
```bash
107+
$ sudo mount /dev/sdx9 /mnt
108+
$ ls /mnt
109+
bin boot dev etc home lib lost+found media mnt proc root run sbin srv sys tmp usr var
110+
$ lsblk
111+
(...)
112+
sdx 8:16 1 14.8G 0 disk
113+
├─sdx1 8:17 1 3.5M 0 part
114+
├─sdx2 8:18 1 256K 0 part
115+
├─sdx3 8:19 1 192K 0 part
116+
├─sdx4 8:20 1 32K 0 part
117+
├─sdx5 8:21 1 32K 0 part
118+
├─sdx6 8:22 1 4M 0 part
119+
├─sdx7 8:23 1 4M 0 part
120+
├─sdx8 8:24 1 4M 0 part
121+
└─sdx9 8:25 1 320.7M 0 part /mnt
122+
(...)
123+
```
124+
125+
For further image verification checkout [verification guide](./verification.md).

0 commit comments

Comments
 (0)