Skip to content

Commit dc653bc

Browse files
t0037799t0037799
committed
lab0
1 parent 7406a3c commit dc653bc

File tree

4 files changed

+325
-1
lines changed

4 files changed

+325
-1
lines changed

‎Makefile

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
.PHONY: all, en, clean
1+
.PHONY: all, en, tw, clean
22
en:
33
sphinx-build . _build/html/en
44

‎external_reference/index.rst

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
Exteral Reference
2+
=================
3+
These are all great websites you can refer to.
4+
5+
**Bare metal tutorials in C**
6+
7+
https://github.com/bztsrc/raspi3-tutorial
8+
9+
**Operating system tutorials in C**
10+
11+
https://github.com/s-matyukevich/raspberry-pi-os
12+
13+
**Operating system tutorials in rust**
14+
15+
https://github.com/rust-embedded/rust-raspi3-OS-tutorials
16+
17+
**Raspberry pi officical github**
18+
19+
https://github.com/raspberrypi/
20+
21+
**Embedded linux wiki page for Raspberry pi**
22+
23+
https://elinux.org/RPi_Hub

‎index.rst

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
.. nctuos documentation master file, created by
2+
sphinx-quickstart on Sat Nov 23 15:22:13 2019.
3+
You can adapt this file completely to your liking, but it should at least
4+
contain the root `toctree` directive.
5+
6+
NCTU, Operating System Design & Implementation, Spring 2020
7+
===========================================================
8+
`中文 </zh_TW>`__
9+
10+
This course aims to introduce the design and implementation of the operating system kernel.
11+
You'll learn both concept and implementation from a series of labs.
12+
13+
This course uses `Raspberry Pi 3 Model B+ <https://www.raspberrypi.org/products/raspberry-pi-3-model-b-plus/>`_ (rpi3 for short)
14+
as a hardware platform.
15+
Students can get their hands dirty on a **Real Machine** instead of an emulator.
16+
17+
Labs
18+
----
19+
There are 9 + 1 labs in this course.
20+
You'll learn the concept of **design** of kernel by **implementing** it yourself.
21+
22+
The main point of these labs is the design principle not programming languages.
23+
Hence, you are free to choose any programming languages such as ASM/C/C++/Rust.
24+
However, there are a lot of things which are language dependent and even compiler dependent.
25+
You need to manage them yourself.
26+
27+
We use ``aarch64-linux-gnu-`` toolchain and C to develop.
28+
If you choose other toolchain or programming languages, we might not help you.
29+
30+
There are 5 types of labels appear in each lab.
31+
32+
================== ===========================================================================================
33+
``required`` You're required to implement it by the description, they take up major of your scores.
34+
``elective`` You're supposed to choose some of them to get full credit.
35+
``question`` During the demo, you need to answer the question correctly to get full score.
36+
``bonus`` It's not required. You can still implement it and get a bonus.
37+
================== ===========================================================================================
38+
39+
.. toctree::
40+
:caption: Labs
41+
:hidden:
42+
43+
labs/lab0
44+
45+
Hardware
46+
---------
47+
Students who register this course will get a rpi3, a 5.1V 2.5A power supply, a USB-TTL cable, a micro SD card, and an SD card reader.
48+
49+
We don't expect every student to have experience in embedded system or microcontroller.
50+
So, the hardware information needed by labs will be provided.
51+
You can check them when you need them.
52+
53+
Disclaimer
54+
----------
55+
We're not kernel developers or experienced embedded developers.
56+
It's common we made mistakes in the description.
57+
If you find any of them, send an issue to the course github.
58+
59+
.. note::
60+
This documentation is not well self-contained, you can get more information from external references.
61+
62+
.. toctree::
63+
:caption: Hardware
64+
:hidden:
65+
66+
67+
68+
.. toctree::
69+
:caption: Miscs
70+
:hidden:
71+
72+
external_reference/index

‎labs/lab0.rst

Lines changed: 229 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,229 @@
1+
=========================
2+
Lab 0: Environment Setup
3+
=========================
4+
5+
Introduction
6+
=============
7+
The first step of creating a masterpiece is preparing the tool.
8+
You're going to implement a 64-bit kernel on ARM CPU.
9+
Hence, you need a toolchain to help you finish the jobs.
10+
11+
In this lab, you'll set up the working environment for future development.
12+
13+
Goals of this lab
14+
=================
15+
16+
* Understand cross-platform development.
17+
18+
* Setup the working environment.
19+
20+
* Test your hardware.
21+
22+
.. note::
23+
This lab is an introductory lab, it won't be taken as part of your final grade.
24+
But you still need to do the ``required`` stuff, or you'll be in trouble in the next lab.
25+
26+
Cross-platform development
27+
==========================
28+
29+
Cross compiler
30+
---------------
31+
rpi3 uses ARM Cortex-A53 CPU.
32+
You need a cross-compiler either using C/C++/Rust.
33+
34+
``required`` Install the cross compiler on your host computer.
35+
36+
``question`` What's the RAM size of Raspberry Pi 3B+?
37+
38+
``question`` What's the cache size and level of Raspberry Pi 3B+?
39+
40+
.. note:: You're doing 64-bit programming, make sure you choose the right cross compiler.
41+
42+
Bare Metal Programming
43+
----------------------
44+
Some features and standard library of a programming language rely on operating system support.
45+
Hence you cannot naively use them.
46+
47+
Also, you should set the corresponding compiler flags to generate correct code.
48+
49+
Linker
50+
-------
51+
You might not notice the existence of linker.
52+
It's because the compiler uses the default linker script for you. (``ld --verbose`` to check the content)
53+
But in bare metal programming, you should set the memory layout yourself.
54+
55+
This is an incomplete linker script for you, you should extend it in the following lab.
56+
57+
.. code-block:: none
58+
:linenos:
59+
60+
SECTIONS
61+
{
62+
. = 0x80000;
63+
.text : { *(.text) }
64+
}
65+
66+
``question`` Explain each line of the above linker script.
67+
68+
QEMU
69+
-----------
70+
In cross-platform development,
71+
it's easier to validate on emulators first to get better control.
72+
You can use QEMU to test your code first before validating them on your real rpi3.
73+
74+
.. warning::
75+
Although QEMU provides a machine option for rpi3, it doesn't act the same as real rpi3.
76+
You should validate your code on rpi3, too.
77+
78+
``required`` Install ``qemu-system-aarch64`` as an emulator for rpi3.
79+
80+
From source code to kernel image
81+
=====================================
82+
83+
You have the basic knowledge of the toolchain for cross-platform development.
84+
Now, it's time to practice them.
85+
86+
From source code to object files
87+
--------------------------------
88+
89+
Source code is compiled or assembled to be object file by cross compiler.
90+
91+
.. code-block:: c
92+
93+
.section ".text"
94+
_start:
95+
wfe
96+
b _start
97+
98+
Assemble the assembly to object file by the following command.
99+
100+
.. code-block:: none
101+
102+
aarch64-linux-gnu-gcc -c a.S
103+
104+
From object files to ELF
105+
------------------------
106+
107+
Linker links object files to a ELF file
108+
It contains debugging information for debugger.
109+
It also could be load by QEMU and some bootloaders.
110+
111+
Save the provided linker script as linker.ld and run the following command to link the object file.
112+
113+
.. code-block:: none
114+
115+
aarch64-linux-gnu-ld -T linker.ld -o kernel8.elf a.o
116+
117+
118+
From elf to kernel image
119+
---------------------------
120+
121+
To run your code on real rpi3,
122+
you need to make the elf file a raw binary image.
123+
Also, the default name of it should be kernel8.img.
124+
You can use objcopy to translate elf to raw binary.
125+
126+
.. code-block:: none
127+
128+
aarch64-linux-gnu-objcopy -O binary kernel8.elf kernel8.img
129+
130+
Check on QEMU
131+
-------------
132+
133+
After building, you can use QEMU to see the dumped assembly.
134+
135+
.. code-block:: none
136+
137+
qemu-system-aarch64 -M raspi3 -kernel kernel8.img -display none -d in_asm
138+
139+
``required`` Build your first kernel image and check it by QEMU.
140+
141+
142+
Deploy to REAL rpi3
143+
===================
144+
145+
Flash bootable image to SD card
146+
--------------------------------
147+
To prepare a bootable image for rpi3, you have to prepare at least the following stuff.
148+
149+
* A FAT16/32 partition contains
150+
151+
* Firmware for GPU
152+
153+
* Kernel image
154+
155+
There are two ways to do it.
156+
157+
1.
158+
We already prepared a bootable image.
159+
You can use the following command to flash it to your sd card.
160+
161+
.. code-block:: none
162+
163+
dd if=nctuos.img of=/dev/sdb
164+
165+
.. warning:: /dev/sdb should be replaced by your sd card device, you can check it by `lsblk`
166+
167+
It's already partition and contains a FAT32 filesystem with firmware inside.
168+
You can mount the partition to check.
169+
170+
2.
171+
Partition the disk and prepare the booting firmware yourself.
172+
You can download the firmware from
173+
https://github.com/raspberrypi/firmware/tree/master/boot
174+
175+
bootcode.bin, fixup.dat and start.elf are essentials.
176+
More information about pi3's booting could be checked on official website
177+
https://www.raspberrypi.org/documentation/configuration/boot_folder.md
178+
https://www.raspberrypi.org/documentation/hardware/raspberrypi/bootmodes/README.md
179+
180+
Finally, put firmware and your kernel image into the FAT partition.
181+
182+
.. note::
183+
Besides using mkfs.fat -F 32 to FAT32 you should also set the partition type.
184+
185+
186+
``required`` Use either one of the methods to set up your sd card.
187+
188+
Interact with rpi3
189+
------------------
190+
Use the provided kernel8.img and connect TX, RX, GND to the corresponding pin on rpi3.
191+
After power on, you can read and write data from /dev/ttyUSB0 (Linux).
192+
You can use putty or screen with baud rate 115200 to interact with your rpi3.
193+
194+
.. code-block:: none
195+
196+
screen /dev/ttyUSB0 115200
197+
198+
199+
Debugging
200+
==========
201+
202+
Debug on QEMU
203+
-------------
204+
205+
Debugging on QEMU is a relatively easy way to validate your code.
206+
QEMU could show the content of memory and registers or expose them to debugger.
207+
You can use the following command waiting for gdb connection.
208+
209+
.. code-block:: none
210+
211+
qemu-system-aarch64 -M raspi3 -kernel kernel8.img -display none -S -s
212+
213+
Then you can use the following command in gdb to load debugging information and connect to QEMU.
214+
215+
.. code-block:: none
216+
217+
file kernel8.elf
218+
target remote :1234
219+
220+
.. note::
221+
Your gdb should also be cross-platform gdb.
222+
223+
224+
Debug on real rpi3
225+
-------------------
226+
227+
If you'd like to debug on real rpi3, you could either use print log or using JTAG.
228+
We don't provide JTAG in this course, you can try it if you have one.
229+
https://metebalci.com/blog/bare-metal-raspberry-pi-3b-jtag/

0 commit comments

Comments
 (0)