bootlin / training-materials Goto Github PK

Bootlin embedded Linux and kernel training materials

Home Page: https://bootlin.com/training/

License: Other

Makefile 1.02% TeX 94.04% C 3.30% Shell 0.22% HTML 0.34% C++ 0.78% Python 0.05% Dockerfile 0.04% BitBake 0.21%

training-materials's Introduction

How to compile these materials
==============================

First, you may install the packages needed to compile the materials
(example on Ubuntu 22.04):

sudo apt install --no-install-recommends git-core inkscape \
texlive-latex-base texlive-latex-extra texlive-font-utils dia \
python3-pygments texlive-fonts-recommended \
texlive-fonts-extra make texlive-xetex texlive-extra-utils \
fonts-inconsolata fonts-liberation \
xfonts-scalable lmodern texlive-science texlive-plain-generic \
texlive-lang-french ghostscript

Then, run 'make help' to see what available targets are.

For example:

make full-linux-kernel-slides.pdf
make full-linux-kernel-labs.pdf

Compiling issues
================

 * If the materials stop compiling after upgrading your distro,
   you may have to run "make clean" to get the materials to
   compile again.

   Example case: https://tex.stackexchange.com/questions/352017/miktex-and-beamer-error-beamerendinputifotherversion

Labs formatting guidelines
==========================

 * To create a new lab, the chapter must start with a 'subchapter'
   command, as in:

\subchapter{Bootloader – U-Boot}{Objectives: Set up serial
  communication, compile and install the X-Loader and U-Boot
  bootloaders, use basic U-Boot commands, set up TFTP communication
  with the development workstation.}

 * You can use \section{} and \subsection{} to create sections in your
   lab document.

 * To add some fixed-sized font text (function names, file or
   directory paths, commands) inside a paragraph of normal text, use
   the \code macro as follows:

Blabla. Look in the \code{/usr/bin} directory. Blabla.

   Note that the \code{} macro doesn't require escaping of $ or _
   signs:

You can look for the \code{platform_device_register()} function in the
\code{$HOME/linux/blabla.c} file.

   This macro *MUST* be used instead of {\tt }, because \code{}
   provides proper line wrapping on dashes, slashes and so on, which
   helps in keeping the line of text within the width of the page.

   Note that this macro cannot be used in section titles or chapter
   titles. In this case {\tt } needs to be used (and inside {\tt },
   the _ or $ signs have to be escaped).

 * To add some fixed-size font text as a complete paragraph, use the
   'verbatim' environment:

In order to build the kernel run:

\begin{verbatim}
make blabla_defconfig
make
\end{verbatim}

   Here as well, it does not require escaping of $ or _ signs.

 * To add URLs, use the \url{https://foobar.com} macro. This will
   create a clickable link in the resulting PDF file.

 * If needed, you can locally reduce the size of a
   \begin{verbatim}...\end{verbatim} environment by doing:

\small
\begin{verbatim}
...
\end{verbatim}
\normalsize

   This must be used parsimoniously because changing the font size all
   the time is not very pretty. But since the verbatim environment
   does not do line wrapping, it may sometimes be necessary.

   Note that in addition to \small, you can also use other sizes, see
   https://en.wikibooks.org/wiki/LaTeX/Fonts#Built-in_sizes .

Slides formatting guidelines
============================

  * A new training should start with a file containing the setup of the
    various variables needed such as authors and a slide created using the
    titleframe macro. This new file should be created in the common/ directory
    with the name <training-name>-title.tex

  * Every new chapter should be split in order to allow its possible use in
    other trainings as well. Each new file should contain only one subsection
    and should be named <training-name>-<section-name>-<subsection-name>.tex.
    New sections should be in a separate file named
    <training-name>-<section-name>-title.tex. All the aggregation would be done
    by the Makefile

Syntax Highlighting
===================

The LaTeX package minted is included to have a nice syntax
highlighting and advanced code formatting features. It uses pygments
as backend, so in order to use it, one needs to install the
debian/Ubuntu package python-pygments.

A basic example for C code is:

\begin{minted}{c}
....
\end{minted}

Of course, it can take a lot of options that you can find in the
minted's documentation present at:
http://mirrors.ctan.org/macros/latex/contrib/minted/minted.pdf

Emacs usage in LaTeX
====================

Install the AUCTex package which contains an improved Emacs
environment for editing LaTeX documents:

sudo apt install auctex

In your ~/.emacs.el file, add the following lines:

(load "auctex.el" nil t t)
(require 'latex)
(add-to-list 'LaTeX-verbatim-macros-with-braces "code")
(add-to-list 'LaTeX-verbatim-macros-with-braces "url")

The important point here is that this tells Emacs to consider the
\code{} and \url{} macros as a verbatim macro, so that even if special
characters such as $, _ or % are not escaped inside these macros,
Emacs text colorization will not go crazy.

Nice keyboard shortcuts with AUCTex:

 * C-c RET to insert a macro, or embed the selected text into a
   macro. Very useful to quickly place a few words inside a \code{}
   macro

 * C-c C-e to insert an environment, such as verbatim, or embed the
   selected text into such an environment.

Diagrams
========

The recommended program to do diagrams is Dia:

 apt install dia

When saving a file, please make sure to unselect the "Compressed saved
files" option, so that the .dia files are raw XML files, and not
gzipped compressed files. Having raw XML files is much better for
version control, and will allow, to some extent, merging .dia diagrams
after conflicts.

The fonts to be used are "Latin Modern Sans" for normal text and
"Inconsolata" for the code/paths.

Here are some suggested color couples you can use for the border and
background of boxes and other elements. Using similar colors for all
diagrams will make our training documents much more coherent and nice
to look at.

 * Blue boxes
    borders:    #5CACFF
    background: #ADD8E6

 * Yellowish boxes
    borders:    #D9CB2F
    background: #FFF8A8

 * Grey boxes
    borders:    #868686
    background: #E5E5E5

 * Brownish boxes
    borders:    #A34804
    background: #FFD192

 * Purple boxes
    borders:    #2F004A
    background: #EFB9FF

 * Green boxes
    borders:    #6A8954
    background: #C5E387

 * Red/pink boxes
    borders:    #CC1F1A
    background: #FFACAC

If you want to easily add all these colors to Dia, add the following
fragment to ~/.dia/persistence (or replace the existing
role="color-menu" XML tag):

------------------8<-----------------8<-----------------------------
<dia:list role="color-menu">
 <dia:attribute name="listvalue">
  <dia:string>##5CACFF
#ADD8E6
#D9CB2F
#FFF8A8
#868686
#E5E5E5
#A34804
#FFD192
#2F004A
#EFB9FF
#6A8954
#C5E387
#CC1F1A
#FFACAC#</dia:string>
 </dia:attribute>
</dia:list>
------------------8<-----------------8<-----------------------------

training-materials's People

Contributors

Stargazers

Watchers

Forkers

mattthias younglhome andrewmk pkol mypopydev mullife martxel chapayghub mirceacaprioru veeraiyan guileschool fanfansfan yang0000qi laymer clivelau1990 lxhuster inspiration602 dkruces texierp mazelinux lmtan91 jensamberg dmarinescu bernarcio mylenej pofenghsieh damiankaczkowski faressalem robocon2011 alexjustgo bobdeng1974 lambogini1992 kelamrani aeo123 coderitter rpeve johandroid tsengwen blackantchen jeonghunlee dovanhuong itsnayabsd phoenixtreeember psvtrajan alpha-source padhikari kayzh3r hexiaolong2008 jpsgoncalves moxfun andyshrk eiknujedoc l-n-x jadonk yetkinakyz bobafwata suvinh mohammadvatandoost loongson-gfx wuweidong0107 larixsoft yuanzjls ly7799 angrypapa maozhou2002 ncs1 mbrown9764 duxincun kaksonen cladmi rich88888888 zombydogs qb-syn ostosh maolala channgo2203 shanliwa1 peng1ei erlend-aasland meerd v4l2-isp marek-gaw qsjiang0930 0xff07 joyxu hexcolors60 usapp-stack xiangxd zmaika caroid shuangquanjun benetti-engineering-sas smartree xiaoruiguo zgaoooo yoshigion mzgsxs gg9 zg55 starblue

training-materials's Issues

Boot time: add a section about reducing Boot time on a system built by Yocto

Ideally, we should have two sections: one for systems built by Buildroot, one for systems built by Yocto.

kernel: Old bibliography

All the proposed books are pretty old, there should be at least a disclaimer or perhaps newer books to reference.

kernel: Join the two slides talking about in-kernel/user API (in)stability

Boot time labs: use Buildroot out of tree building

Rather than making copies of Buildroot sources, use instead out of tree building to compile multiple rootfs and toolchains from the same sources, while keeping the ability to switch between them without having to rebuild everything.

kernel: move config file excerpt right after first config slide

full-yocto-stm32-labs.pdf - Setup & Download Yocto section problems

Setup:
Go to $HOME/yocto-labs/ directory
Directory does not exist, we just created / were told that it is yocto-stm32-labs
I renamed it to yocto-labs...

Download Yocto:
As setup.

git am $HOME/yocto-labs/bootlin-lab-data/0001-u-boot-update-config.patch
fails to apply:

~/yocto-stm32-labs/meta-st-stm32mp$ git am $HOME/yocto-stm32-labs/bootlin-lab-data/0001-u-boot-update-config.patch
Applying: u-boot: update config
.git/rebase-apply/patch:57: trailing whitespace.
-- 
error: patch failed: recipes-bsp/u-boot/u-boot-stm32mp-common_2018.11.inc:24
error: recipes-bsp/u-boot/u-boot-stm32mp-common_2018.11.inc: patch does not apply
.git/rebase-apply/patch:59: new blank line at EOF.
+
Patch failed at 0001 u-boot: update config
Use 'git am --show-current-patch' to see the failed patch
When you have resolved this problem, run "git am --continue".
If you prefer to skip this patch, run "git am --skip" instead.
To restore the original branch and stop patching, run "git am --abort".

kernel: Use a single board for explaining the bootstrap with device tree

Use a single board instead of the Crystalfontz + Marvell combo.

kernel: remove linux kernel size slides

kernel: Rework the energy saving chapter

[Grogory's idea]
Too much time spent explaining system-wide features?

Embedded Linux: reduce time spent explaining UNIX system administration

This was suggested by at least one participant and this makes sense...

The idea is to reduce the time spent in explaining the UNIX packages, administrator rights, sudo access, frustrating people expecting more embedded Linux specific topics.

Anyway, our lab instructions are explicit enough to let participants install packages, configure their environment.
I'm suggesting to reduce, not completely eliminate.

kernel: DMA chapter?

Should it be developed and moved in the standard slide deck? (currently an "if time" topic)

Issue with SVG diagrams with Courier 10 Pitch font

I've just realized that some SVG diagrams have lost their text because of the Courier 10 Pitch font, at least on Ubuntu 20.04.
An example is common/strace-c-output.svg
I tried to install the font again on my system, in $HOME/.fonts, but it didn't help.
LibreOffice can use this font, but not inkscape.
A consequence is that the generated documents have diagrams without text.

kernel: Mention device tree overlays

This is covered more widely in the Embedded Linux training but could potentially be covered in the Linux kernel training as well.

yocto: SERIAL_CONSOLE is deprecated, use SERIAL_CONSOLES

slides/yocto-bsp/yocto-bsp.tex shows an example machine config that defines SERIAL_CONSOLE, which is deprecated and should be replaced with SERIAL_CONSOLES.

We should find another machine config that uses SERIAL_CONSOLES and is also simple and short enough to fit in a slide.

kernel: change oops example to something easier to debug

Current example ends up in an assembly memcpy routine. This is difficult to explain. Instead of that, try to end up in a C routine to be able to get back to the C code from the oops location.

boot-time: broken kernel boot graph

The lab in which a kernel boot graph is generated is currently broken.
The information needed by scripts/bootgraph.pl is no longer available in the dmesg output.
Because of this, this part of the kernel optimization lab is no longer available.
An idea is to test with a more recent kernel.

kernel: remove smbus explanations

[Michael's idea]
Would it work with the nunchuk? If not, why do we tell people to prefer using smbus helpers?

kernel: Talk about licenses once for all at the beginning of the training

kernel: add lab to setup the board

For on-site courses, the board setup is already done by Bootlin trainers, before the training course.

For on-line courses in which we want the participants to do the labs by themselves, they need to prepare their boards. Therefore, we should have a "board setup" lab that goes through the process of reflashing the board with the appropriate U-Boot version/configuration. This must be added to our lab instructions.

kernel: Simplify quizz questions

Avoid misleading questions, simplify some of them, drop useless ones to have a shorter yet more useful quiz.
Examples:

do not talk about ABI in one question API in the other
do not use open answers such as ARCH/CROSS_COMPILE
drop the I2C question
drop the scanner/printer questions

kernel: Create a proper DT chapter

[Michael's idea]

The idea would be to cover more extensively the device tree in the embedded Linux training, and possibly share the slides with the kernel training.

embedded-linux-labs add footnote description of UBI issue when using U-Boot + MMC

First, thank you guys so much for putting together these embedded linux slides and labs and making them freely available. They have been a tremendous help in better understanding all the nuances of the embedded linux development ecosystem.

In the latest embedded-linux-lab.pdf (7/22/21) when talking about using UBIFS and UBI images on p. 28, you say:

"Also remove the SD card, to resume to the former way of booting. That’s important because
there is currently an issue with U-Boot compiled from the MMC configuration, which causes
UBI incompatibilities between U-Boot and Linux."

Would you please consider adding a footnote here to provide some additional information about this issue similar to footnote 13 in which you give an excellent description about needing to use the trimffs option with nand write to prevent running into ECC issues when writing the UBI images. My confusion with the existing information is whether or not this is a quirk of the particular hardware platform, a particular version of u-boot, or if this is a general issue with trying to pass a ubifs to linux when u-boot is using an environment located in mmc.

The first few times I tried to work through this section I glanced right over the line that mentioned removing the SD card and I kept getting strange ubi read errors related to bad ecc values when booting my kernel ubi_io_read: error -74 (ECC error). I dug through the config and .dts files for both u-boot and the kernel looking for anything related to NAND, ECC, and/or UBI trying to diagnose the issue, but I was unable to locate the source of the problem.

kernel: move the portability examples later

Add a slide to explain the endianness handling: where and why

kernel: Improve DT slides with an explanation of aliases + gpio hogs + examples of buttons, leds, etc

Boot time: add details about Yocto tools for reducing size

Share Yocto Projects resources for reducing space and therefore boot-time:
https://docs.yoctoproject.org/dev-manual/common-tasks.html#building-a-tiny-system

Some of the scripts, such as ksize.py, also apply outside of the scope of the Yocto project.

kernel: introduce the concept of stable at the beginning

Embedded Linux on SAMA5D3: stop using SAM-BA

The use of SAM-BA is a significant source of problems for people doing labs remotely. This could be a learning opportunity, but this is only relevant in the context of Microchip boards.

Instead, I propose to instruct people to prepare an MMC/SD card and compile U-Boot for booting from MMC from the start. This is much more generic and we already do this in the STM32 and QEMU labs. If we want to keep the flash labs, we will still be able to flash U-Boot on NAND flash using U-Boot on MMC.

What do you think?

cannot compile u-boot for vexpress_ca9x4_defconfig

I have followed all the instructions as per this slides : https://bootlin.com/doc/training/embedded-linux-qemu/embedded-linux-qemu-labs.pdf to build the cross-compiler, but after that while building u-boot, I am getting this error, can anyone help me share the cross-compiler .config file such that I can tally, as I think the problem is with compiler only, but I have followed all the instructions while building compiler.
Here is my u-boot building error, I have also followed all steps for making the u-boot, but it is not working !

{standard input}: Assembler messages:
{standard input}:43: Error: selected processor does not support `dsb sy' in ARM mode
{standard input}:47: Error: selected processor does not support `isb sy' in ARM mode
{standard input}:240: Error: selected processor does not support `dsb sy' in ARM mode
{standard input}:244: Error: selected processor does not support `isb sy' in ARM mode
{standard input}:367: Error: selected processor does not support `dsb sy' in ARM mode
{standard input}:459: Error: selected processor does not support `dsb sy' in ARM mode
{standard input}:463: Error: selected processor does not support `isb sy' in ARM mode
{standard input}:596: Error: selected processor does not support `dsb sy' in ARM mode
make[1]: *** [scripts/Makefile.build:279: arch/arm/cpu/armv7/cache_v7.o] Error 1
make: *** [Makefile:1727: arch/arm/cpu/armv7] Error 2

kernel: linux sources, clarify sources tree

Remove useless directories (certs/etc)
Present some subsystems that are present in drivers/.

kernel: Missing explanations about framework's "struct device *"

no latex-beamer in Ubuntu20.04, requires texlive-plain-generic

I wasnt able install dependency: latex-beamer in Ubuntu20.04.

In addition, I had to install texlive-plain-generic, it complains missing file: ulem.sty, otherwise.

yocto: update to SPDX license strings

The LICENSE strings have been modified in OE-core, so that license strings are obsolete now in our slides. They should use the SPDX license names.

Example of a change:
LICENSE = "GPLv2"
should be replaced by
LICENSE = "GPL-2.0-only"

This doesn't impact our labs yet (based on Dunfell), but the next release (3.5 Kirstone) will make our slides obsolete.
Keep this as a reminder.

kernel: Simplify the code about the legacy method for declaring devices

Perhaps this part should be made much smaller now that the device tree has been broadly accepted. We could still have a couple of slides about "how it was done before" but that is all.

kernel: Clarify use of the word module/driver/kerbnel/built-in

Sometimes modules is used to designate a driver. Rework that to be coherent. A module is a loadable module and a driver car be compiled as a module or built-in

boot-time: broken detection of accessed files

The "atime" based technique used to detect which files are accessed during the boot process doesn't work any more.
The files accessed during the boot process don't get an access time in 1970 any more, which allowed to distinguish them from other files.
That's probably because the root filesystem is mounted with the "relatime" mount option by default. How to change the rootfs mount options from the kernel command line?
Otherwise, any other (simple) idea for detecting files accessed at boot time? Or the ones not accessed at boot time?

kernel: Update the CrystalFontz example

[Michael's idea]
Either update the mainline code or use another board

kernel: Cover more debug tools (perf)

[Michael's idea]
https://wkz.github.io/ply/

BBB kernel configuration steps are unclear

I am using BBB and Linux kernel and driver development training. Steps in the material are unclear on how to config the kernel for BBB board! Is arch/arm/configs/omap2plus_defconfig the file that needs to used as .config? OR is there any target in kernel's make to pick corresponding target for am335x boards?

kernel: clarify the retrieval of private data for frameworks

Instead of presenting the links between all the structures and never show how to retrieve that effectively in the slides, add example with various framework interfaces to retrieve data (foo_get_privdata(), container_of, etc)

kernel: boot chain on on ARM64 (OPTEE, SMC, PSCI)

Should we talk about the interaction with the firmware? With ACPI?

online agendas: propose native Linux installs too, recommend Ubuntu

Our current agendas for online sessions, at least the embedded Linux one, says:
"For people interested in our optional practical labs, an installation of VirtualBox and about 30 GB of free disk space."

Shouldn't instead say?
"For people interested in our optional practical labs, Ubuntu 20.04 in a native installation or in a VirtualBox instance, with about 30 GB of free disk space."

A native installation is much better and it's good to propose the GNU/Linux distro and version that we officially support.
Would you agree with this change?