Bayou - Revision history

GNUtoo at 17:23, 16 February 2013

2013-02-16T17:23:46Z

XVilka: Fixed downloading from Subversion to Git

2012-06-01T11:02:16Z

Fixed downloading from Subversion to Git

Stepan: svn paths

2009-10-30T18:34:04Z

svn paths

Uwe: Add proper build instructions for Bayou.

2008-12-21T23:04:06Z

Add proper build instructions for Bayou.

Stepan: add download link so people can test bayou

2008-09-11T15:51:40Z

add download link so people can test bayou

Uwe: Small fixes.

2008-07-08T19:33:11Z

Small fixes.

JCrouse: Add screenshots

2008-06-20T22:50:48Z

Add screenshots

JCrouse: Change the size of the timeout to 1 byte - 254 seconds is a long time to wait

2008-06-19T16:14:31Z

Change the size of the timeout to 1 byte - 254 seconds is a long time to wait

JCrouse: /* Bayou Payload Table */ Millisecond granularity

2008-06-19T16:04:15Z

‎Bayou Payload Table: Millisecond granularity

JCrouse: Add behavior and cleanups

2008-06-16T17:34:21Z

Add behavior and cleanups

← Older revision		Revision as of 17:23, 16 February 2013
Line 18:		Line 18:

	$ '''cd ../bayou'''		$ '''cd ../bayou'''
		+	$ '''mkdir build'''
		+	$ '''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).		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).

@@ Line 10: / Line 10: @@
 First, get and build [[libpayload]]:
-  $ '''svn co svn://coreboot.org/coreboot/trunk/payloads/libpayload'''
+  $ '''git clone http://review.coreboot.org/p/coreboot'''
-  $ '''cd libpayload'''
+  $ '''cd payloads/libpayload'''
   $ '''make menuconfig'''
   $ '''make'''
@@ Line 17: / Line 17: @@
 Then, get and build Bayou itself:
-  $ '''cd ..'''
+  $ '''cd ../bayou'''
- $ '''svn co svn://coreboot.org/coreboot/trunk/payloads/bayou'''
- $ '''cd bayou'''
 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).

@@ Line 10: / Line 10: @@
 First, get and build [[libpayload]]:
-  $ '''svn co svn://coreboot.org/repos/trunk/payloads/libpayload'''
+  $ '''svn co svn://coreboot.org/coreboot/trunk/payloads/libpayload'''
   $ '''cd libpayload'''
   $ '''make menuconfig'''
@@ Line 18: / Line 18: @@
   $ '''cd ..'''
-  $ '''svn co svn://coreboot.org/repos/trunk/payloads/bayou'''
+  $ '''svn co svn://coreboot.org/coreboot/trunk/payloads/bayou'''
   $ '''cd bayou'''

@@ Line 1: / Line 1: @@
-'''Bayou''' is the working name for a coreboot payload that can chose, load and run other payloads from a LAR archive on the ROM.
+[[Image:Bayou-screenshot-menu.jpg|thumb|right|The chooser menu with two options.]]
-== Screenshots ==
+'''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.
-<gallery widths="200" perrow="4">
+== Building ==
-Image:Bayou-screenshot-menu.jpg|The chooser menu with two options.
-Image:Bayou-screenshot-info.jpg|The same chooser menu showing the PAYLOAD_PARAM data passed by coreinfo.
-Image:Bayou-screenshot-serial.jpg|The same chooser menu over serial.
-Image:Bayou-screenshot-timeout.jpg|The timeout message. If the key isn't pressed, then the menu is displayed.
-</gallery>
-== Download ==
+First, get and build [[libpayload]]:
-The current version of Bayou is '''0.3'''. You can get it [http://coreboot.org/~jcrouse/bayou_0.3.tar.gz here].
+ $ '''svn co svn://coreboot.org/repos/trunk/payloads/libpayload'''
 == Why "Bayou"? ==

@@ Line 9: / Line 9: @@
 Image:Bayou-screenshot-timeout.jpg|The timeout message. If the key isn't pressed, then the menu is displayed.
 </gallery>
 == Why "Bayou"? ==

@@ Line 3: / Line 3: @@
 == Screenshots ==
-[[Image:Bayou-screenshot-menu.jpg|400px|The chooser menu with two options]]
+<gallery widths="200" perrow="4">
-[[Image:Bayou-screenshot-info.jpg|400px|The same chooser menu showing the PAYLOAD_PARAM data passed by coreinfo]]<br>
+Image:Bayou-screenshot-menu.jpg|The chooser menu with two options.
-[[Image:Bayou-screenshot-serial.jpg|400px|The same chooser menu over serial]]
+Image:Bayou-screenshot-info.jpg|The same chooser menu showing the PAYLOAD_PARAM data passed by coreinfo.
-[[Image:Bayou-screenshot-timeout.jpg|400px|The timeout message.  If the key isn't pressed, then the menu is displayed]]
+Image:Bayou-screenshot-serial.jpg|The same chooser menu over serial.
 == 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 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://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.
 == Usage Models ==
@@ Line 17: / Line 19: @@
 === 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.
 === 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 LAR and an front end user interface.  The
+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).
-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).
 == Behavior ==
-When Bayou starts, it will find and read the Bayou Payload Table (see below).  There are three different paths that can be followed, depending on the value of the 'timeout' field:
+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'.
+* 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 BPT, both chooser and chain items. When a chain item is selected from the menu (or as the 'default' item), then each
+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.
-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 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
+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.
 cannot be static - it must be able to grow and change with the LAR.
 === 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
+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:
 follows:
 {| border="1"
@@ Line 77: / Line 74: @@
 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 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
+* 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.
 {| border="1"
@@ Line 103: / Line 100: @@
 == 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:
+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:
 {| border="1"
@@ Line 124: / Line 121: @@
 == Changes to coreboot ==
-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.
 === Coreboot ===
 * Coreboot needs to be modified to understand and load the [[SELF]] format
-* 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.
+* Coreboot needs to be modified to understand and load the [[SELF]] format.
 === LAR ===
-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?
+* The LAR utility must be modified to build LAR images with SELF payloads.
-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.
+* The LAR utility needs to be modified to allow the user to specify a long descriptive name to be included in the NAME segment.
 === Buildrom ===
 * Buildrom must be adapted to build multiple payloads during the same run
 === Libpayload ===
-* Add generic LAR walking code '''Done'''
-* Ensure that libpayload based payloads can cleanly return control to the master payload
+* Add generic LAR walking code ('''done''').
-* Modify the build system to allow the configuration system to modify the payload entry point
+* Ensure that libpayload based payloads can cleanly return control to the master payload.

← Older revision		Revision as of 22:50, 20 June 2008
Line 1:		Line 1:
	'''Bayou''' is the working name for a coreboot payload that can chose, load and run other payloads from a LAR archive on the ROM.		'''Bayou''' is the working name for a coreboot payload that can chose, load and run other payloads from a LAR archive on the ROM.
		+
		+	== Screenshots ==
		+
		+	[[Image:Bayou-screenshot-menu.jpg\|400px\|The chooser menu with two options]]
		+	[[Image:Bayou-screenshot-info.jpg\|400px\|The same chooser menu showing the PAYLOAD_PARAM data passed by coreinfo]]<br>
		+	[[Image:Bayou-screenshot-serial.jpg\|400px\|The same chooser menu over serial]]
		+	[[Image:Bayou-screenshot-timeout.jpg\|400px\|The timeout message. If the key isn't pressed, then the menu is displayed]]

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

@@ Line 26: / Line 26: @@
 When Bayou starts, it will find and read the Bayou Payload Table (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 0xFFFF, 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'.
+* 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 0xFFFF. then the chooser menu will be shown 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 BPT, both chooser and chain items. When a chain item is selected from the menu (or as the 'default' item), then each
@@ Line 63: / Line 63: @@
 | 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 || 2 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 65535 (0xFFFF), then the chooser menu will be displayed immediately.  Any value between 1 and 65534 indicates the amount of time (in seconds) that the system should wait.
+| 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 || 10 bytes || Unused space padding out to 16 byte alignment.  This may be used in the future
+| Padding || 11 bytes || Unused space padding out to 16 byte alignment.  This may be used in the future
 |}

@@ Line 21: / Line 21: @@
 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).
 == Configuration ==
@@ Line 50: / Line 63: @@
 | 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 || 2 bytes || Indicates how long bayou should wait (in milliseconds) before starting the default chain or menu item.  Pressing a hot key during this time will start the chooser by default.
+| Timeout || 2 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 65535 (0xFFFF), then the chooser menu will be displayed immediately.  Any value between 1 and 65534 indicates the amount of time (in milliseconds) that the system should wait.
 |-
 | Padding || 10 bytes || Unused space padding out to 16 byte alignment.  This may be used in the future
@@ Line 66: / Line 79: @@
 !Description
 |-
-|- index || 1 byte || An index number for the entry - sub items will use this as the value of its 'parent' field
+| 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'