Bayou: Difference between revisions

From coreboot
Jump to navigation Jump to search
No edit summary
 
(3 intermediate revisions by the same user not shown)
Line 4: Line 4:
[[Image:Bayou-screenshot-timeout.jpg|thumb|right|The timeout message. If the key isn't pressed, then the menu is displayed.]]
[[Image:Bayou-screenshot-timeout.jpg|thumb|right|The timeout message. If the key isn't pressed, then the menu is displayed.]]


'''Bayou''' is the working name for a coreboot [[Payloads|payload]] that can choose, load and run other payloads from a LAR archive on the ROM.
'''Bayou''' is the working name for a coreboot [[Payloads|payload]] that can choose, load and run other payloads from a CBFS on the ROM.


== Building ==
== Building ==


First, get and build [[libpayload]]:
First, get coreboot and configure it to fit your needs


  $ '''git clone http://review.coreboot.org/p/coreboot'''
  $ '''git clone http://review.coreboot.org/p/coreboot'''
  $ '''cd payloads/libpayload'''
  $ '''cd coreboot'''
  $ '''make menuconfig'''
  $ '''make menuconfig'''
$ '''make'''


Then, get and build Bayou itself:
Then:
* Go to the [[Payloads|Payload]] section in "make menuconfig"
* Choose Bayou as your main payload through the "Add a payload" option
* Choose all the payloads that you want in your configuration from the "Secondary payloads" submenu


$ '''cd ../bayou'''
Now, you'll need to create a '''bayou.xml''' file containing the menu entries you like.
$ '''mkdir build'''
Start by copying and then editing the sample file '''bayou.xml.example''' inside '''payloads/bayou'''.
$ '''cd build'''
$ '''ln -s ../../libpayload/ ./'''
$ '''cd ../'''
 
Now, you'll need to create a '''bayou.xml''' file containing the menu entries you like. Start by copying and then editing the sample file '''bayou.xml.example''' (and copying all required payloads in the current directory).


$ '''cd payloads/bayou'''
  $ '''cp bayou.xml.example bayou.xml'''
  $ '''cp bayou.xml.example bayou.xml'''


Then actually build Bayou:
Then go back to the coreboot root directory and build it:


  $ '''make'''
  $ '''make'''


The file '''bayou.elf''' is your finale Bayou payload file, which you can use for coreboot.
The file '''bayou.elf''' is your finale Bayou payload file, which the build system will include in your coreboot image.


== Why "Bayou"? ==
== Why "Bayou"? ==


We need a little bit of originality in the names of our payloads, as Peter discusses [http://www.coreboot.org/pipermail/coreboot/2008-April/033219.html here].  In the grand tradition of [http://en.wikipedia.org/wiki/El_Torito_%28CD-ROM_standard%29 El Torito], we decided to name the project after the restaurant where we ate lunch and debated the payload chooser during the coreboot summit 2008 in Denver: [http://denver.citysearch.com/profile/1823003/denver_co/bayou_bob_s_seafood_southern_cookin.html Bayou Bob's]. The word ''bayou'' is French in origin, but it famously describes slow or stagnant streams and swamps in the southern United States (see also [http://en.wikipedia.org/wiki/Bayou Bayou at wikipedia].  The name in no way describes the project itself, which should neither be slow nor swampy.
We need a little bit of originality in the names of our payloads, as Peter discusses [http://www.coreboot.org/pipermail/coreboot/2008-April/033219.html here].  In the grand tradition of [http://en.wikipedia.org/wiki/El_Torito_%28CD-ROM_standard%29 El Torito], we decided to name the project after the restaurant where we ate lunch and debated the payload chooser during the coreboot summit 2008 in Denver: [http://bayoubobs.com/contact Bayou Bob's]. The word ''bayou'' is French in origin, but it famously describes slow or stagnant streams and swamps in the southern United States (see also [http://en.wikipedia.org/wiki/Bayou Bayou at wikipedia].  The name in no way describes the project itself, which should neither be slow nor swampy.


== Usage Models ==
== Usage Models ==
Line 43: Line 41:
=== Graphical chooser ===
=== Graphical chooser ===


This usage model presents a menu to the user containing the descriptive names of all the payloads in the LAR.  The user selects an item from the list, and Bayou loads and runs the payload.  If the payload is responsible enough to be able to exit cleanly (as all libpayload payloads should be able to do) and return control to Bayou, then the user can select a different payload.
This usage model presents a menu to the user containing the descriptive names of all the payloads in the CBFS.  The user selects an item from the list, and Bayou loads and runs the payload.  If the payload is responsible enough to be able to exit cleanly (as all libpayload payloads should be able to do) and return control to Bayou, then the user can select a different payload.


=== Chaining ===
=== Chaining ===
Line 51: Line 49:
== Architecture ==
== Architecture ==


The architecture of Bayou is rather simple.  It is a [[libpayload]] based application with code for reading and loading payloads from a LAR and a front end user interface.  The Bayou code itself lives below 640k so that it can stay resident when loading payloads that would typically locate themselves at 1Mb or higher.  Payloads that want to work cleanly with Bayou should not write to memory below 640k unless it is a "final" payload (i.e. something that will not return to Bayou, such as the Linux kernel).  Bayou will read, load and execute payloads encoded in the [[SELF|Simple Executable Loader Format]], decompressing them if needed (with lzma).
The architecture of Bayou is rather simple.  It is a [[libpayload]] based application with code for reading and loading payloads from a CBFS and a front end user interface.  The Bayou code itself lives below 640k (0x19000) so that it can stay resident when loading payloads that would typically locate themselves at 1Mb or higher.  Payloads that want to work cleanly with Bayou should not write to memory below 640k unless it is a "final" payload (i.e. something that will not return to Bayou, such as the Linux kernel).  Bayou will read, load and execute payloads encoded in the [[SELF|Simple Executable Loader Format]].


== Behavior ==
== Behavior ==
Line 66: Line 64:
== Configuration ==
== Configuration ==


The ROM image with LAR + coreboot v3 is very dynamic in nature.  New blobs of data can be added at any time during the build process or during runtime.  This means that the Bayou configuration cannot be static - it must be able to grow and change with the LAR.
The ROM image is very dynamic in nature.  New blobs of data can be added at any time during the build process or during runtime.  This is why Bayou was designed to easily detect and use the payloads added to the CBFS through cbfstool and update its configuration without needing to touch the payloads.


=== Bayou Payload Table ===
=== Bayou Payload Table ===


The payload table describes which payloads to manage, both in chooser and in chained mode.  The table is stored as a LAR file with the name '''bayou_payload_table'''.  The table is organized like follows:
The payload table describes which payloads to manage, both in chooser and in chained mode.  The table is stored as a raw file inside the CBFS with the name '''bayou_payload_table'''.  The table is organized like follows:


{| border="1"
{| border="1"
Line 118: Line 116:
| nlen  || 4 bytes || Length of the payload name, in bytes.  This should be 0 for master chain items.
| nlen  || 4 bytes || Length of the payload name, in bytes.  This should be 0 for master chain items.
|-  
|-  
| name  || 'nlen' bytes || Specifies the name of the LAR file for the payload associated with this entry.  Only valid for sub-chain items and chooser items.
| name  || 'nlen' bytes || Specifies the name of the CBFS file for the payload associated with this entry.  Only valid for sub-chain items and chooser items.
|}
|}


Line 143: Line 141:
  PAYLOAD_PARAM(desc,"Display information about the system");
  PAYLOAD_PARAM(desc,"Display information about the system");


== Changes to coreboot ==
== BPTBuilder ==


In order to support Bayou, some drastic changes need to be made to coreboot and associated projects. The following is a short synopsis of these changes.
BPTBuilder is an utility used to parse the '''bayou.xml''' modified by the use and convert it into a binary file that is easily understood by the Bayou payload itself.
The resulting binary file ('''bayou_payload_table''' a.k.a. bpt) is loaded into the CBFS by the build system.


=== Coreboot ===
This is the structure of the file:


* Coreboot needs to be modified to understand and load the [[SELF]] format.
{| border="1"
* The LAR design needs to be modified so that coreboot can identify and boot the "default" payload. Captain Obvious says: call it '''payload/default''' (or normal, or whatever). No evil bit in LAR required to find it.
|- bgcolor="#6699ff"
!Struct
!Description
|-
| bpt_config || This is the global conffiguration of Bayou as described above
|-
| bpt_pentry || This is the a payload entry, which can represent both a simple '''Chooser''' configuration or be the beginning of a '''Chain''' one. This is followed by more structs of the same type, one for each payload.
|}


=== LAR ===
== Changes to coreboot ==
 
* The LAR utility must be modified to build LAR images with SELF payloads.
* The LAR utility needs to be modified to allow the user to specify a long descriptive name to be included in the NAME segment.
* A rewrite of the frontend of the LAR utility may be needed to fully support all the features.


Instead of modifying LAR and putting even more features into it, how about creating an '''elf2self''' (and back) tool, and just add those files into lar?
In order to better support Bayou, some changes need to be made to coreboot and associated projects.  The following are a few of the changes that would help.
Sure, it's another build step, but it's "one tool for one job", allows for interesting development, adoption of SELF beyond coreboot, ... - and we really already have enough build steps that this additional one won't hurt either.


=== Buildrom ===
=== Payloads ===


* Buildrom must be adapted to build multiple payloads during the same run.
* Making sure that every payload usable with Bayou does not reboot before returning.


=== Libpayload ===
=== Libpayload ===


* Add generic LAR walking code ('''done''').
* Add generic CBFS walking code.
* Ensure that libpayload based payloads can cleanly return control to the master payload.
* Modify the build system to allow the configuration system to modify the payload entry point.
* Modify the build system to allow the configuration system to modify the payload entry point.

Latest revision as of 12:13, 30 July 2016

The chooser menu with two options.
The same chooser menu showing the PAYLOAD_PARAM data passed by coreinfo.
The same chooser menu over serial.
The timeout message. If the key isn't pressed, then the menu is displayed.

Bayou is the working name for a coreboot payload that can choose, load and run other payloads from a CBFS on the ROM.

Building

First, get coreboot and configure it to fit your needs 

$ git clone http://review.coreboot.org/p/coreboot
$ cd coreboot
$ make menuconfig

Then:

  • Go to the Payload section in "make menuconfig"
  • Choose Bayou as your main payload through the "Add a payload" option
  • Choose all the payloads that you want in your configuration from the "Secondary payloads" submenu

Now, you'll need to create a bayou.xml file containing the menu entries you like. Start by copying and then editing the sample file bayou.xml.example inside payloads/bayou. 

$ cd payloads/bayou
$ cp bayou.xml.example bayou.xml

Then go back to the coreboot root directory and build it: 

$ make

The file bayou.elf is your finale Bayou payload file, which the build system will include in your coreboot image.

Why "Bayou"?

We need a little bit of originality in the names of our payloads, as Peter discusses here. In the grand tradition of El Torito, we decided to name the project after the restaurant where we ate lunch and debated the payload chooser during the coreboot summit 2008 in Denver: Bayou Bob's. The word bayou is French in origin, but it famously describes slow or stagnant streams and swamps in the southern United States (see also Bayou at wikipedia. The name in no way describes the project itself, which should neither be slow nor swampy.

Usage Models

The following are the two usage models for the payload:

Graphical chooser

This usage model presents a menu to the user containing the descriptive names of all the payloads in the CBFS. The user selects an item from the list, and Bayou loads and runs the payload. If the payload is responsible enough to be able to exit cleanly (as all libpayload payloads should be able to do) and return control to Bayou, then the user can select a different payload.

Chaining

Chaining is a non-interactive usage model wherein Bayou will load and execute a series of payloads in order. The payloads must be able to return control to Bayou cleanly (except the "final" payload which isn't expected to return). This will loosely imitate a traditional BIOS in that one could define a "BIOS setup screen" payload that ran before FILO or other kernel bootloader.

Architecture

The architecture of Bayou is rather simple. It is a libpayload based application with code for reading and loading payloads from a CBFS and a front end user interface. The Bayou code itself lives below 640k (0x19000) so that it can stay resident when loading payloads that would typically locate themselves at 1Mb or higher. Payloads that want to work cleanly with Bayou should not write to memory below 640k unless it is a "final" payload (i.e. something that will not return to Bayou, such as the Linux kernel). Bayou will read, load and execute payloads encoded in the Simple Executable Loader Format.

Behavior

When Bayou starts, it will find and read the Bayou Payload Table (BPT) (see below). There are three different paths that can be followed, depending on the value of the timeout field:

  • If the timeout field is greater then 0 but not 0xFF, then Bayou will display a countdown message on the screen. If the user presses F1, then the chooser menu will be displayed. If the user does not press a key in the alloted time then Bayou will automatically start the item in the payload table that is marked as 'default'.
Please press F1 for the menu.  Timeout in (3) seconds...
  • If the timeout field is zero, then the default item will be chosen immediately without a timeout.
  • If the timeout field is 0xFF. then the chooser menu will be shown immediately without a timeout.

When the menu is displayed, it will list all top level items in the Bayou Payload Table, both chooser and chain items. When a chain item is selected from the menu (or as the 'default' item), then each of the sub-items listed in the payload table will be executed in order. Each sub-payload item is expected to return control to Bayou, except the last one. If a payload fails to return control, then the rest of the chain will not be executed.

Configuration

The ROM image is very dynamic in nature. New blobs of data can be added at any time during the build process or during runtime. This is why Bayou was designed to easily detect and use the payloads added to the CBFS through cbfstool and update its configuration without needing to touch the payloads.

Bayou Payload Table

The payload table describes which payloads to manage, both in chooser and in chained mode. The table is stored as a raw file inside the CBFS with the name bayou_payload_table. The table is organized like follows:

Global configuration
Payload tables

The global configuration header controls general Bayou behavior:

Field Size Description
ID 4 bytes An identifier that indicates the file is a Bayou Payload Table. the value will be 'BPT0' or in hex: 0x305405042 (in little endian)
Timeout 1 bytes if the value of this field is 0, then the default item in the payload list will be executed immediately. If this value is 254 (0xFF), then the chooser menu will be displayed immediately. Any value between 1 and 254 indicates the amount of time (in seconds) that the system should wait.
Padding 11 bytes Unused space padding out to 16 byte alignment. This may be used in the future

Following the configuration header is the list of payloads. There are three types of possible items in the list:

  • A chooser item is displayed in a list of other items on a menu. Each chooser item is associated with a single payload.
  • A master chain item describes a chain of items that are to be executed one after another. Master chain items specify a title and may be displayed on the chooser menu.
  • A number of sub chain items are tied to a master chain item and point to the specific payloads to be executed in the chain.
Field Size Description
index 1 byte An index number for the entry - sub items will use this as the value of its 'parent' field
parent 1 byte For sub chain items this lists the index of the master chain item that the payload is attached to. Chooser and master chain items are always at the toplevel and should have a parent of '0'
type 1 byte Specifies the type of the entry. Possible values are 0x01 - chooser item, 0x02 - master chain item, 0x03 sub-chain item
flags 1 byte This bit field describes various flags that modify the item. Possible values are bit 0 - default item (executed after timeout), bit 1 - do not show in chooser menu
title 64 bytes This is a name displayed by the chooser for the item. It is required for master chain items, but not for chooser items. If not NULL, this will replace any names specified by the payload. This should be null for sub chain items
nlen 4 bytes Length of the payload name, in bytes. This should be 0 for master chain items.
name 'nlen' bytes Specifies the name of the CBFS file for the payload associated with this entry. Only valid for sub-chain items and chooser items.

Payload Parameters

There are several parameters that the payload can set to control the behavior of Bayou. These are passed in through the PARAMS section in the SELF:

Parameter Description
name This is the short name of the payload, which is displayed in the log and in the chooser menu if 'listname' is not defined
listname This is the name shown in the chooser menu
desc This is a verbose description of the application that will be displayed in the "help" section in the chooser menu

The following is an example of macros a typical payload would use to set the above values: 

PAYLOAD_PARAM(name,"coreinfo");
PAYLOAD_PARAM(listname,"System Information");
PAYLOAD_PARAM(desc,"Display information about the system");

BPTBuilder

BPTBuilder is an utility used to parse the bayou.xml modified by the use and convert it into a binary file that is easily understood by the Bayou payload itself. The resulting binary file (bayou_payload_table a.k.a. bpt) is loaded into the CBFS by the build system.

This is the structure of the file:

Struct Description
bpt_config This is the global conffiguration of Bayou as described above
bpt_pentry This is the a payload entry, which can represent both a simple Chooser configuration or be the beginning of a Chain one. This is followed by more structs of the same type, one for each payload.

Changes to coreboot

In order to better support Bayou, some changes need to be made to coreboot and associated projects. The following are a few of the changes that would help.

Payloads

  • Making sure that every payload usable with Bayou does not reboot before returning.

Libpayload

  • Add generic CBFS walking code.
  • Modify the build system to allow the configuration system to modify the payload entry point.
Retrieved from "https://www.coreboot.org/index.php?title=Bayou&oldid=20052"