diff options
Diffstat (limited to 'arch/riscv/boards/riscvemu/defaultenv-riscvemu/data')
27 files changed, 233 insertions, 0 deletions
diff --git a/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/00-init b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/00-init new file mode 100644 index 0000000000..1ff43142ba --- /dev/null +++ b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/00-init @@ -0,0 +1,12 @@ + +You are using Hush, barebox' default shell. You are currently using it +interactively, but it can execute scripts as part of the startup and boot +procedure as well. See for yourself: +``` + cat /env/init/90-tutorial-intro +``` +Look around as you like. When you are ready to continue the tutorial, +type `next` again. The `prev` command does the inverse and shows previous +tutorial steps. The `help` command will show help usage text, +e.g. `help next`. + diff --git a/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/01-interactive b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/01-interactive new file mode 100644 index 0000000000..8b285cd9f4 --- /dev/null +++ b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/01-interactive @@ -0,0 +1,7 @@ + +The interactive shell, its commands and the nodes in the virtual +file system they operate on enable quick UNIX-like prototyping +and debugging. Let's give it a try, shall we? +Type `of_dump` to list the open firmware (OF) device tree barebox +used to discover the hardware and `next` to continue the tutorial. + diff --git a/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/02-ofdump b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/02-ofdump new file mode 100644 index 0000000000..3271f734b2 --- /dev/null +++ b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/02-ofdump @@ -0,0 +1,6 @@ + +That's a lot of output, so let's restrict ourselves to just part +of the tree: +``` + of_dump /soc/virtio@40010000 +``` diff --git a/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/03-devinfo b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/03-devinfo new file mode 100644 index 0000000000..74bc9aa88a --- /dev/null +++ b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/03-devinfo @@ -0,0 +1,5 @@ + +This node tells barebox enough information to instantiate a device and +to try match it with existing drivers. Type `devinfo` to see the tree of +devices known to barebox. + diff --git a/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/04-cs0 b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/04-cs0 new file mode 100644 index 0000000000..fdb878fa93 --- /dev/null +++ b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/04-cs0 @@ -0,0 +1,11 @@ + +In this tree, you will find 40010000.virtio@40010000.of, the +device corresponding to the device tree node we've just seen. +Devices can have child devices themselves. This device's +grandchild is `cs0`, the virtual console device that prints +you this very text. + +See for yourself: +``` + echo -a /dev/cs0 Append this text to virtio console +``` diff --git a/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/05-drvinfo b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/05-drvinfo new file mode 100644 index 0000000000..068bf303d8 --- /dev/null +++ b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/05-drvinfo @@ -0,0 +1,4 @@ + +Let's look at more devices. Type `drvinfo` to see what drivers are +available and what devices they were successfully matched with. + diff --git a/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/06-devinfo-dev b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/06-devinfo-dev new file mode 100644 index 0000000000..f706915ba2 --- /dev/null +++ b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/06-devinfo-dev @@ -0,0 +1,6 @@ + +Let's pick another device out of the list: HTIF. We can display some extra +info with `devinfo`. (Use the tab completion to avoid writing it all out!) +``` +devinfo 40008000.htif.of +``` diff --git a/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/07-mw b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/07-mw new file mode 100644 index 0000000000..4278f8f391 --- /dev/null +++ b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/07-mw @@ -0,0 +1,9 @@ + +We see that the device has a memory mapped I/O region of 8 bytes that +can be used for communication. Poking 0x010100000000002e in little- +endian into that region should print a period '.'. +Let's do that quad-word memory write (`mw -q`) 80 times by having a shell +local variable keep count: +``` +i=0; while [ $i -lt 80 ]; do mw -q 0x40008000 0x010100000000002e; let i=$i+1; done +``` diff --git a/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/08-devfs b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/08-devfs new file mode 100644 index 0000000000..b117e4bb16 --- /dev/null +++ b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/08-devfs @@ -0,0 +1,8 @@ + +`mw` is complemented by `md` for memory display. There are further commands +like `mm` (memory modify), `memcpy` and `memcmp` (copy/compare ranges). +These commands operate on `/dev/mem` by default, but any seekable device +or file can be used instead. Let's see what device files we got here: +``` +ls /dev +``` diff --git a/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/09-partitions b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/09-partitions new file mode 100644 index 0000000000..552ab2ab1e --- /dev/null +++ b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/09-partitions @@ -0,0 +1,9 @@ + +The `mtdram0` looks interesting. That's the 64K SRAM at the start of the +address space. The virtual machine places the boot "rom" there as well +as the flattened (compiled) device tree (FDT). barebox can be informed +about partitioning and will create extra devices for each partition. +This allows you to reference them from commands easily: +``` +of_dump -f /dev/mtdram0.fdt +``` diff --git a/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/10-environment b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/10-environment new file mode 100644 index 0000000000..d1a6f85119 --- /dev/null +++ b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/10-environment @@ -0,0 +1,8 @@ + +Not all of the 64K is used, so the barebox board support here uses +the unused mtd-ram space for saving modified environment and state. +The barebox environment is a file system which contains scripts, variables +and data: +``` +ls -R /env +``` diff --git a/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/11-env-data b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/11-env-data new file mode 100644 index 0000000000..81e3f47ee7 --- /dev/null +++ b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/11-env-data @@ -0,0 +1,12 @@ + +The environment you see here is the built-in environment barebox was +compiled with. It contains default values for non-volatile variables, +(init) scripts and data. It's generated from directories on the host +system specified during build and stored as an archive within +barebox. This environment may also be compressed allowing shipping +larger files and even binaries. For example, this barebox binary +has the option CONFIG_DEFAULT_ENVIRONMENT_GENERIC_NEW_IKCONFIG=y, +which ships a copy of the used barebox configuration. See for yourself: +``` +cat /env/data/config +``` diff --git a/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/12-dmesg b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/12-dmesg new file mode 100644 index 0000000000..61cdd2adaf --- /dev/null +++ b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/12-dmesg @@ -0,0 +1,9 @@ + +In the field, you will probably want to depend exclusively on the built-in +environment, but it can be very handy to persist environment changes during +development. You may recall that barebox told us at first boot that the +environment was never written? If you don't, no problem, log messages are, +you guessed it, logged: +``` +dmesg +``` diff --git a/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/13-env-bin b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/13-env-bin new file mode 100644 index 0000000000..34b7ab554b --- /dev/null +++ b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/13-env-bin @@ -0,0 +1,11 @@ + +Let's modify the environment to add a new script (Remember +`help` can show you the usage, e.g. `help mw`): +``` +cd /env/bin +echo -o putc '#!/bin/sh' +echo -a putc 'mw -l 0x40008000 $1' +echo -a putc 'mw -l 0x40008004 0x01010000' +cd / +putc 0x40 # Print an @ character +``` diff --git a/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/14-env-init b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/14-env-init new file mode 100644 index 0000000000..184a4f571f --- /dev/null +++ b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/14-env-init @@ -0,0 +1,8 @@ + +We could have added the last script anywhere in `/env`. But `/env/bin` is +already in the executable search `PATH`, so you don't have to write out +the full path when invoking the script. Another special directory is +`/env/init`. Anything there will be sourced on shell startup. +Let's poke the HTIF a bit every time we start: Open a new file with +`edit /env/init/99-percent` and type into it `putc 0x40`. + diff --git a/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/15-magicvar b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/15-magicvar new file mode 100644 index 0000000000..ec2912da9f --- /dev/null +++ b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/15-magicvar @@ -0,0 +1,10 @@ + +As init scripts only run on initialization, we'll have to do a reset to +see them in action. But first, we'll want to save our tutorial progress. +This happens via $global.variables. Many parts of barebox monitor reads +and writes to such variables to make information available to the shell. + +The `next` command also does it. How would you know? +``` +magicvar +``` diff --git a/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/16-env-nv b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/16-env-nv new file mode 100644 index 0000000000..3440e01947 --- /dev/null +++ b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/16-env-nv @@ -0,0 +1,12 @@ + +Now that you know that $global.tutorial.step holds the next step, you +will want to initialize it on the next reset. We could write an init shell +script for that, but there is something much more convenient: + +On startup, barebox needs to assign initial values for each +$global.variable; if a suitably named non-volatile $nv.variable already +exists, it will be used as initial value. Let's see what global variables +we got (leading asterisk '*' means it was initialized from NV): +``` +global +``` diff --git a/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/17-env-saveenv b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/17-env-saveenv new file mode 100644 index 0000000000..f929838138 --- /dev/null +++ b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/17-env-saveenv @@ -0,0 +1,7 @@ + +Now that we have written a normal script and an init script, add a +nv variable to the mix, save the environment and reset to see them +all in action: +``` +nv tutorial.step=$global.tutorial.step; saveenv; reset +``` diff --git a/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/17-env-usage b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/17-env-usage new file mode 100644 index 0000000000..1f4ff37f86 --- /dev/null +++ b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/17-env-usage @@ -0,0 +1,5 @@ + +Welcome back! You have successfully saved the environment. Make sure +to reset your environment with `saveenv -z` when you are done. You wouldn't +want to chase ghosts, because you changed an init script and forgot about it. :) + diff --git a/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/18-mnt b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/18-mnt new file mode 100644 index 0000000000..3122e6ffa4 --- /dev/null +++ b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/18-mnt @@ -0,0 +1,11 @@ + +We now have seen `/dev`, which holds the devfs, and `/env` which holds the +active environment. `/tmp` is as you have guessed it a directory where temporary +files can be placed. `/pstore` is short for persistent storage, a Linux +mechanism to store and retrieve error records even after a kernel panic. + +This leaves `/mnt`. Let's take a peek at it as well at our active mounts: +``` +mount +ls /mnt +``` diff --git a/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/19-automount b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/19-automount new file mode 100644 index 0000000000..4d4787a9a8 --- /dev/null +++ b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/19-automount @@ -0,0 +1,9 @@ + +Strangely, nothing inside `/mnt` is seen in the `mount` output. Why you +ask? Because these are automounts that are deferred until first access. +So when you `bootm /mnt/nfs/boot/Image.gz` the first time, barebox will +bring up the network and mount the network file system (provided you do +have network). We can list what automounts there are: +``` +automount -l +``` diff --git a/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/20-mount-fs b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/20-mount-fs new file mode 100644 index 0000000000..cc5e64c66c --- /dev/null +++ b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/20-mount-fs @@ -0,0 +1,11 @@ + +`/mnt/virtioblk0` is an interesting one. Block device partitions +automatically get automount entries created. On first access, +barebox will determine what file system is located in the partition +and mount it. Thus you can just use `/mnt/virtioblk0/DOOM1.WAD` in +your script and not incur the overhead of mounting unless it's accessed: +``` +mount +ll /mnt/virtioblk0/DOOM1.WAD +mount +``` diff --git a/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/21-state b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/21-state new file mode 100644 index 0000000000..1a71204cf5 --- /dev/null +++ b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/21-state @@ -0,0 +1,11 @@ + +You'll note most file systems in barebox are read-only. While those that aren't +could be used with `saveenv` to store a packed environment for Linux use, that's +murky waters: atomicity, limiting scope, authentication and journal handling +complicate things. barebox state is the mechanism how barebox stores variables +(and only variables) in a power-fail safe manner that's also accessible to Linux. + +Check the `state` device: +``` +devinfo state +``` diff --git a/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/22-device-params b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/22-device-params new file mode 100644 index 0000000000..3f8d31f171 --- /dev/null +++ b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/22-device-params @@ -0,0 +1,11 @@ + +The state driver parses the device tree to learn the state layout +and how it's (redundantly) placed. The information it learns are +registered with the device as device parameters. Device Parameters +make it easy to interact with the shell. For example, the MAC address +of a network adapter is a device parameter. We already saw some other +device parameters before. Those of the global and nv device: +``` +devinfo global +devinfo nv +``` diff --git a/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/23-device-param-types b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/23-device-param-types new file mode 100644 index 0000000000..36a311d011 --- /dev/null +++ b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/23-device-param-types @@ -0,0 +1,8 @@ + +Many device parameters are simple strings, some have specific types +and run actions on read/write or accept only specific values. +`devinfo` will show you what type a variable has and writing an +invalid value will give you an error: +``` +global.tutorial.step=non-existent +``` diff --git a/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/24-boot b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/24-boot new file mode 100644 index 0000000000..90c2266973 --- /dev/null +++ b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/24-boot @@ -0,0 +1,12 @@ + +You should now know enough about barebox' architecture, that +we could talk about barebox' actual function without it +seeming too magical: Booting. + +We still need to add that part to the tutorial though, but you +can check out `help boot`, `help bootm` as well as the barebox +documentation linked below. Also give the graphical mode a +try! + +Tutorial to be continued.. + diff --git a/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/99-end b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/99-end new file mode 100644 index 0000000000..4744f2b3ee --- /dev/null +++ b/arch/riscv/boards/riscvemu/defaultenv-riscvemu/data/tutorial/99-end @@ -0,0 +1 @@ +End of tutorial reached! |