coreboot - User contributions [en]

Vendors

2008-09-02T14:53:37Z

JCrouse: /* AMD */ Expand

== Vendors ==

== AMD ==

*[http://www.amd.com AMD] has has been very actively supporting coreboot for a few years now. They have added support for many of their CPUs including:
** [http://www.amd.com/us-en/ConnectivitySolutions/ProductInformation/0,,50_2330,00.html|AMD Geode LX CPU]
** [http://www.amd.com/us-en/ConnectivitySolutions/ProductInformation/0,,50_2330_9863_13022^13054,00.html CS5536 Chipset]
** [http://www.amd.com/us-en/Processors/ProductInformation/0,,30_118_9485_9488,00.html K8/FAM 0F CPUs (Athlon, Opteron)]
** [http://www.amd.com/us-en/Processors/ProductInformation/0,,30_118_15331,00.html FAM10 CPUs (Barcelona, Phenom)]
* The [[AMD SimNow]] simulator is a fast and configurable x86 and AMD64 dynamically-translating instruction-level platform simulator. With SimNow users can connect complex software models to form a PC platform emulation environment. SimNow™ emulates AMD Athlon™ 64 and AMD Opteron™ uniprocessor and multiprocessor based systems that run several commercial operating systems and applications. 
*[[AMD Geode Porting Guide]] is a collection on information to help you on your way to porting coreboot to an AMD Geode platform. 
*AMD frequently has active coreboot developers in the '''#coreboot''' channel on [http://www.freenode.net irc.freenode.net].

== VIA ==

[http://www.via.com.tw VIA] is helping the coreboot community support many new Epia's, mainboards and chipsets with several code donations and open programming guides. With key input from VIA, coreboot will soon support over 30 more Mini-ITX mainboards. These mainboards are made by VIA, Jetway, Phitronics and MSI featuring the VIA C7 cpu, CN700 and VT8237 chipset. 

[http://linux.via.com.tw/support/downloadFiles.action Linux VIA Portal] aims to expand cooperation with open source communities by providing drivers, chipset programming manuals and source code for select Linux distributions to technical software developers.

VIA has recently donated v2 Cache-as-Ram (CAR) source for the C7 cpu.

VIA posted programming guides for CX700M/VX700 and VX800 at the [http://linux.via.com.tw/support/downloadFiles.action VIA Download Portal]

VIA help fix raminit for the CN700 so coreboot can now support all the C7 + CN700 + VT8237R boards (about 30- 40 currently in production) in V2 and move them into V3.

VIA helped support the VT8237S and KT890 for the [http://www.asus.com.tw/products.aspx?l1=3&l2=15&l3=143&l4=0&model=576&modelmenu=1 ASUS A8V-E SE] and [http://www.asus.com/products.aspx?l1=3&l2=101&l3=324&l4=0&model=1807&modelmenu=1 ASUS M2V-MX SE].

Libpayload

2008-08-28T19:46:55Z

JCrouse: add link to documentation

'''libpayload''' is a small BSD-licensed static library (a lightweight implementation of common and useful functions) intended to be used as a basis for coreboot payloads.

The benefits of linking a coreboot payload against libpayload are:

* Payloads do not have to implement and maintain low-level code for I/O, common functions, etc.
* Payloads can be recompiled and deployed for CPU architectures supported by coreboot in the future.
* The libpayload functions can be tested and scrutinized outside payload development.
* Payloads themselves may be partly host-tested, e.g. against an emulation libpayload.

''Just give us a main() and a pocket full of dreams and we'll do the rest.''

== Features ==

* Provides a [[Libpayload#Libc_Coverage|subset of libc functions]] (e.g. malloc, printf, strcmp, etc).
* Provides an optional tiny (n)curses implementation.
* Provides various small drivers for
** keyboard
** PC speaker
** NVRAM/CMOS access
** serial console
** VGA
** Geode framebuffer
* Reads and parses the coreboot table.http://qa.coreboot.org/docs/libpayload/

== Design ==
* [[Payload API|Discussion of the API for passing parameters to the payload]]

== Payloads using libpayload ==

* [[coreinfo]] is a small payload which can display system information such as PCI info, an NVRAM dump, or the coreboot v3 printk buffer.
* [[GRUB invaders]] has been ported successfully to libpayload (patch pending).
* [[tint]] (a console tetris clone) has been successfully ported to libpayload.
* [http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=tree;f=scripts/kconfig/lxdialog;hb=HEAD lxdialog] from the Linux '''kconfig''' utility has been ported to be usable when linked with libpayload (patch pending).

== Downloading and building libpayload ==

$ svn co svn://coreboot.org/repos/trunk/payloads/libpayload
$ cd libpayload
$ make menuconfig
$ make

== Documentation ==

See the autogenerated documentation for libpayload [http://qa.coreboot.org/docs/libpayload/ here].

== Libc coverage ==

{| border="0" valign="top"
| valign="top"|

{| border="0" style="font-size: smaller"
|- bgcolor="#6699ff"
! align="left" | Status
! align="left" | Function/Macro/Variable

|- bgcolor="#6699ff"
| colspan=2 | '''assert.h'''
|-
|- bgcolor="#eeeeee" valign="top"
| style="background:red" | no
| assert()

|- bgcolor="#6699ff"
| colspan=2 | '''ctype.h'''
|-
|- bgcolor="#eeeeee" valign="top"
| style="background:lime" | yes
| int isalnum(int character)
|-
|- bgcolor="#dddddd" valign="top"
| style="background:lime" | yes
| int isalpha(int character)
|-
|- bgcolor="#eeeeee" valign="top"
| style="background:lime" | yes
| int iscntrl(int character)
|-
|- bgcolor="#dddddd" valign="top"
| style="background:lime" | yes
| int isdigit(int character)
|-
|- bgcolor="#eeeeee" valign="top"
| style="background:lime" | yes
| int isgraph(int character)
|-
|- bgcolor="#dddddd" valign="top"
| style="background:lime" | yes
| int islower(int character)
|-
|- bgcolor="#eeeeee" valign="top"
| style="background:lime" | yes
| int isprint(int character)
|-
|- bgcolor="#dddddd" valign="top"
| style="background:lime" | yes
| int ispunct(int character)
|-
|- bgcolor="#eeeeee" valign="top"
| style="background:lime" | yes
| int isspace(int character)
|-
|- bgcolor="#dddddd" valign="top"
| style="background:lime" | yes
| int isupper(int character)
|-
|- bgcolor="#eeeeee" valign="top"
| style="background:lime" | yes
| int isxdigit(int character)

|- bgcolor="#6699ff"
| colspan=2 | '''errno.h'''
|-
| style="background:red" | no
| <code>errno</code> (global)

|- bgcolor="#6699ff"
| colspan=2 | '''float.h'''

|- bgcolor="#6699ff"
| colspan=2 | '''limits.h'''

|- bgcolor="#6699ff"
| colspan=2 | '''locale.h'''
|-
| style="background:red" | no
| <code>char *setlocale(int category, const char *locale)</code>
|-
| style="background:red" | no
| <code>struct lconv *localeconv(void)</code>

|- bgcolor="#6699ff"
| colspan=2 | '''math.h'''
|-
| style="background:red" | no
| <code>double exp(double x)</code>
|-
| style="background:red" | no
| <code>double log(double x)</code>
|-
| style="background:red" | no
| <code>double log10(double x)</code>
|-
| style="background:red" | no
| <code>double pow(double x, double y)</code>
|-
| style="background:red" | no
| <code>double sqrt(double x)</code>
|-
| style="background:red" | no
| <code>double ceil(double x)</code>
|-
| style="background:red" | no
| <code>double floor(double x)</code>
|-
| style="background:red" | no
| <code>double fabs(double x)</code>
|-
| style="background:red" | no
| <code>double ldexp(double x, int n)</code>
|-
| style="background:red" | no
| <code>double frexp(double x, int* exp)</code>
|-
| style="background:red" | no
| <code>double modf(double x, double* ip)</code>
|-
| style="background:red" | no
| <code>double fmod(double x, double y)</code>
|-
| style="background:red" | no
| <code>double sin(double x)</code>
|-
| style="background:red" | no
| <code>double cos(double x)</code>
|-
| style="background:red" | no
| <code>double tan(double x)</code>
|-
| style="background:red" | no
| <code>double asin(double x)</code>
|-
| style="background:red" | no
| <code>double acos(double x)</code>
|-
| style="background:red" | no
| <code>double atan(double x)</code>
|-
| style="background:red" | no
| <code>double atan2(double y, double x)</code>
|-
| style="background:red" | no
| <code>double sinh(double x)</code>
|-
| style="background:red" | no
| <code>double cosh(double x)</code>
|-
| style="background:red" | no
| <code>double tanh(double x)</code>

|- bgcolor="#6699ff"
| colspan=2 | '''setjmp.h'''
|-
| style="background:red" | no
| <code>int setjmp(jmp_buf env)</code>
|-
| style="background:red" | no
| <code>void longjmp(jmp_buf env, int val)</code>

|- bgcolor="#6699ff"
| colspan=2 | '''signal.h'''
|-
| style="background:red" | no
| <code>void (*signal(int sig, void (*handler)(int)))(int)</code>
|-
| style="background:red" | no
| <code>int raise(int sig)</code>

|- bgcolor="#6699ff"
| colspan=2 | '''stdarg.h'''
|-
| style="background:red" | no
| <code>void va_start(va_list ap, lastarg)</code>
|-
| style="background:red" | no
| <code>type va_arg(va_list ap, type)</code>
|-
| style="background:red" | no
| <code>void va_end(va_list ap)</code>

|- bgcolor="#6699ff"
| colspan=2 | '''stddef.h'''

|- colspan=2
| TODO

|- bgcolor="#6699ff"
| colspan=2 | '''stdio.h'''
|-
| style="background:red" | no
| <code>FILE* fopen(const char* filename, const char* mode)</code>
|-
| style="background:red" | no
| <code>FILE* freopen(const char* filename, const char* mode, FILE* stream)</code>
|-
| style="background:red" | no
| <code>int fflush(FILE* stream)</code>
|-
| style="background:red" | no
| <code>int fclose(FILE* stream)</code>
|-
| style="background:red" | no
| <code>int remove(const char* filename)</code>
|-
| style="background:red" | no
| <code>int rename(const char* oldname, const char* newname)</code>
|-
| style="background:red" | no
| <code>FILE* tmpfile()</code>
|-
| style="background:red" | no
| <code>char* tmpnam(char s[L_tmpnam])</code>
|-
| style="background:red" | no
| <code>int setvbuf(FILE* stream, char* buf, int mode, size_t size)</code>
|-
| style="background:red" | no
| <code>void setbuf(FILE* stream, char* buf)</code>
|-
| style="background:red" | no
| <code>int fprintf(FILE* stream, const char* format, ...)</code>
|-
| style="background:lime" | yes
| <code>int printf(const char* format, ...)</code>
|-
| style="background:lime" | yes
| <code>int sprintf(char* s, const char* format, ...)</code>
|-
| style="background:red" | no
| <code>int vfprintf(FILE* stream, const char* format, va_list arg)</code>
|-
| style="background:lime" | yes
| <code>int vprintf(const char* format, va_list arg)</code>
|-
| style="background:lime" | yes
| <code>int vsprintf(char* s, const char* format, va_list arg)</code>
|-
| style="background:red" | no
| <code>int fscanf(FILE* stream, const char* format, ...)</code>
|-
| style="background:red" | no
| <code>int scanf(const char* format, ...)</code>
|-
| style="background:red" | no
| <code>int sscanf(char* s, const char* format, ...)</code>
|-
| style="background:red" | no
| <code>int fgetc(FILE* stream)</code>
|-
| style="background:red" | no
| <code>char* fgets(char* s, int n, FILE* stream)</code>
|-
| style="background:red" | no
| <code>int fputc(int c, FILE* stream)</code>
|-
| style="background:red" | no
| <code>char* fputs(const char* s, FILE* stream)</code>
|-
| style="background:red" | no
| <code>int getc(FILE* stream)</code>
|-
| style="background:lime" | yes
| <code>int getchar(void)</code>
|-
| style="background:red" | no
| <code>char* gets(char* s)</code>
|-
| style="background:red" | no
| <code>int putc(int c, FILE* stream)</code>
|-
| style="background:lime" | yes
| <code>int putchar(int c)</code>
|-
| style="background:lime" | yes
| <code>int puts(const char* s)</code>
|-
| style="background:red" | no
| <code>int ungetc(int c, FILE* stream)</code>
|-
| style="background:red" | no
| <code>size_t fread(void* ptr, size_t size, size_t nobj, FILE* stream)</code>
|-
| style="background:red" | no
| <code>size_t fwrite(const void* ptr, size_t size, size_t nobj, FILE* stream)</code>
|-
| style="background:red" | no
| <code>int fseek(FILE* stream, long offset, int origin)</code>
|-
| style="background:red" | no
| <code>long ftell(FILE* stream)</code>
|-
| style="background:red" | no
| <code>void rewind(FILE* stream)</code>
|-
| style="background:red" | no
| <code>int fgetpos(FILE* stream, fpos_t* ptr)</code>
|-
| style="background:red" | no
| <code>int fsetpos(FILE* stream, const fpos_t* ptr)</code>
|-
| style="background:red" | no
| <code>void clearerr(FILE* stream)</code>
|-
| style="background:red" | no
| <code>int feof(FILE* stream)</code>
|-
| style="background:red" | no
| <code>int ferror(FILE* stream)</code>
|-
| style="background:red" | no
| <code>void perror(const char* s)</code>

|}

| valign="top"|

{| border="0" style="font-size: smaller"
|- bgcolor="#6699ff"
! align="left" | Status
! align="left" | Function/Macro/Variable

|- bgcolor="#6699ff"
| colspan=2 | '''stdlib.h'''
|-
| style="background:lime" | yes
| <code>int abs(int n)</code>
|-
| style="background:lime" | yes
| <code>long labs(long n)</code>
|-
| style="background:lime" | yes
| <code>long long llabs(long long n)</code>
|-
| style="background:red" | no
| <code>div_t div(int num, int denom)</code>
|-
| style="background:red" | no
| <code>ldiv_t ldiv(long num, long denom)</code>
|-
| style="background:red" | no
| <code>double atof(const char* s)</code>
|-
| style="background:red" | no
| <code>int atoi(const char* s)</code>
|-
| style="background:red" | no
| <code>long atol(const char* s)</code>
|-
| style="background:red" | no
| <code>double strtod(const char* s, char** endp)</code>
|-
| style="background:red" | no
| <code>long strtol(const char* s, char** endp, int base)</code>
|-
| style="background:red" | no
| <code>unsigned long strtoul(const char* s, char** endp, int base)</code>
|-
| style="background:lime" | yes
| <code>void* calloc(size_t nobj, size_t size)</code>
|-
| style="background:lime" | yes
| <code>void* malloc(size_t size)</code>
|-
| style="background:lime" | yes
| <code>void* realloc(void* p, size_t size)</code>
|-
| style="background:lime" | yes
| <code>void free(void* p)</code>
|-
| style="background:lime" | yes
| <code>void abort()</code>
|-
| style="background:red" | no
| <code>void exit(int status)</code>
|-
| style="background:red" | no
| <code>int atexit(void (*fcm)(void))</code>
|-
| style="background:red" | no
| <code>int system(const char* s)</code>
|-
| style="background:red" | no
| <code>char* getenv(const char* name)</code>
|-
| style="background:red" | no
| <code>void* bsearch(const void* key, const void* base, size_t n, size_t size, int (*cmp)(const void* keyval, const void* datum))</code>
|-
| style="background:red" | no
| <code>void qsort(void* base, size_t n, size_t size, int (*cmp)(const void*, const void*))</code>
|-
| style="background:lime" | yes
| <code>int rand(void)</code>
|-
| style="background:lime" | yes
| <code>void srand(unsigned int seed)</code>

|- bgcolor="#6699ff"
| colspan=2 | '''string.h'''
|-
| style="background:lime" | yes
| <code>char* strcpy(char* s, const char* ct)</code>
|-
| style="background:lime" | yes
| <code>char* strncpy(char* s, const char* ct, size_t n)</code>
|-
| style="background:red" | no
| <code>char* strcat(char* s, const char* ct)</code>
|-
| style="background:lime" | yes
| <code>char* strncat(char* s, const char* ct, size_t n)</code>
|-
| style="background:lime" | yes
| <code>int strcmp(const char* cs, const char* ct)</code>
|-
| style="background:lime" | yes
| <code>int strncmp(const char* cs, const char* ct, size_t n)</code>
|-
| style="background:red" | no
| <code>int strcoll(const char* cs, const char* ct)</code>
|-
| style="background:lime" | yes
| <code>char* strchr(const char* cs, int c)</code>
|-
| style="background:red" | no
| <code>char* strrchr(const char* cs, int c)</code>
|-
| style="background:red" | no
| <code>size_t strspn(const char* cs, const char* ct)</code>
|-
| style="background:red" | no
| <code>size_t strcspn(const char* cs, const char* ct)</code>
|-
| style="background:red" | no
| <code>char* strpbrk(const char* cs, const char* ct)</code>
|-
| style="background:lime" | yes
| <code>char* strstr(const char* cs, const char* ct)</code>
|-
| style="background:lime" | yes
| <code>size_t strlen(const char* cs)</code>
|-
| style="background:red" | no
| <code>char* strerror(int n)</code>
|-
| style="background:red" | no
| <code>char* strtok(char* s, const char* t)</code>
|-
| style="background:red" | no
| <code>size_t strxfrm(char* s, const char* ct, size_t n)</code>
|-
| style="background:lime" | yes
| <code>void* memcpy(void* s, const void* ct, size_t n)</code>
|-
| style="background:lime" | yes
| <code>void* memmove(void* s, const void* ct, size_t n)</code>
|-
| style="background:lime" | yes
| <code>int memcmp(const void* cs, const void* ct, size_t n)</code>
|-
| style="background:red" | no
| <code>void* memchr(const void* cs, int c, size_t n)</code>
|-
| style="background:lime" | yes
| <code>void* memset(void* s, int c, size_t n)</code>

|- bgcolor="#6699ff"
| colspan=2 | '''time.h'''
|-
| style="background:red" | no
| <code>clock_t clock(void)</code>
|-
| style="background:red" | no
| <code>time_t time(time_t* tp)</code>
|-
| style="background:red" | no
| <code>double difftime(time_t time2, time_t time1)</code>
|-
| style="background:red" | no
| <code>time_t mktime(struct tm* tp)</code>
|-
| style="background:red" | no
| <code>char* asctime(const struct tm* tp)</code>
|-
| style="background:red" | no
| <code>char* ctime(const time_t* tp)</code>
|-
| style="background:red" | no
| <code>struct tm* gmtime(const time_t* tp)</code>
|-
| style="background:red" | no
| <code>struct tm* localtime(const time_t* tp)</code>
|-
| style="background:red" | no
| <code>size_t strftime(char* s, size_t smax, const char* fmt, const struct tm* tp)</code>

|}
|}

== Usage example ==

Here's an example of a very simple payload (hello.c) and how to build it:

<pre>
#include <libpayload.h>

int main(void)
{
printf("Hello, world!\n");
halt();
return 0;
}
</pre>

Building the payload:

lpgcc -o hello.elf hello.c

{{PD-self}}

Rating System

2008-08-20T16:08:11Z

JCrouse: /* Criteria */ fix wording

At the coreboot summit 2008 in Denver we talked about a rating system for supported boards. The idea is to make it clear which boards are most highly recommended because the vendors cooperate. Thus the 'Vendor Cooperation Score' rating system was born.

= Introduction =

To get to such a rating for a particular board, we should establish a list of categories with an associated score. Each fulfilled criteria should be easily verifiable as a yes or no answer.
There should be no subjective elements to the rating system — only measurable criteria should be used to avoid bias or favoritism.

Adding up the scores for the major components on a board (CPU, chipsets, mainboard, others?) would give us a rating that results in a number of 'stars'.

Some ideas for those categories:

* Availability of documentation (nothing/NDA restricted == 0, NDA but free to publish code == 3, online with click through == 7, public URL == 10)
** There should be multiple categories of documentation (register set, BIOS programming guide, errata, schematics or pinouts (for motherboards))
* Vendor participation in the coreboot project
** How to quantify?
* Availability of example and support code
** ACPI tables
* "Hackability"
** LPC header, JTAG header, BIOS socket, etc.
** Should we dock a board because it requires soldering or a difficult process for flashing coreboot?
* ...

As we list boards, we should also make it clear if a board is actually available for purchase. A board might get a high rating, but be unavailable for purchase, in which case it should be carefully marked as such. Board availability will change over a board's lifespan.

Should we provide a separate rating for coreboot support (i.e. the stuff above) and how good our code actually is?

= Criteria =

When all the criteria have been evaluated, each platform will end up with a total score. To assign "hares" to the platform, we will divide the number of scored points by the number of maximum possible points and multiply that with the number of maximum hares (probably 5) and round down to the nearest half hare (bunny?).

== Documentation ==

Use the following criteria to evaluate each set of documentation:

{| border="1"
|- bgcolor="#6699ff"
!Points
!Description
|-
| 10 || Documentation is freely available and redistributable. It can be downloaded through a direct URL with no click-through pages.
|-
| 7 || Documentation is freely available and redistributable. It can be downloaded on the web after agreeing to a click-through license.
|-
| 3 || Documentation is restricted and only available under Non Disclosure Agreement, however the NDA allows source code written with the documentation to be freely available under the GPL (or another Free Software license).
|-
| 0 || Documentation is not available or the NDA does now allow release of code.
|}

X86 based platforms can have up to 80 points for documentation.

=== CPU ===

Evaluate the criteria against the following three sets of documentation (30 total points possible):

* Datasheet / register set (detailed information about programming registers and/or memory locations)
* BIOS programming guide
* Errata

=== Southbridge (chipset) ===

Evaluate the criteria against the following three sets of documentation (30 total points possible):

* Datasheet / register set (detailed information about programming registers and/or memory locations)
* BIOS programming guide
* Errata

=== Other chipsets (Super I/O, etc) ===

Evaluate the criteria against the following: (10 total points possible). Add 10 points if not applicable to the platform.

* Datasheet / register set (detailed information about programming registers and/or memory locations)

=== Mainboard ===

Evaluate the criteria against the following: (10 total points available)

* Schematics / Pinout (Sufficient documentation to detail the platform specific GPIO & IRQ assignments)

== Hackability ==

Use the following criteria to evaluate the hackability of a board. Maximum possible score: 24.

Rom chip:

{| border="1"
|- bgcolor="#6699ff"
!Points
!Description
|-
| 10 || Socketed rom chip.
|-
| 1 || Soldered rom chip with space on the board for a secondary rom chip (pads unpopulated).
|-
| 0 || Soldered rom chip, no space for secondary rom chip.
|}

LPC header:

{| border="1"
|- bgcolor="#6699ff"
!Points
!Description
|-
| 9 || LPC header, can be used to emulate rom chip.
|-
| 0 || No LPC header.
|}

JTAG header:

{| border="1"
|- bgcolor="#6699ff"
!Points
!Description
|-
| 5 || JTAG header.
|-
| 0 || No JTAG header.
|}

== Vendor participation ==

Does the board vendor participate directly in the coreboot project? Maximum score: 10.

{| border="1"
|- bgcolor="#6699ff"
!Points
!Description
|-
| 10 || Vendor employs people who are active in the project and contribute code.
|-
| 8 || Vendor has contributed the coreboot port and supports it by participating in the project and addressing any bugs.
|-
| 5 || Vendor has contributed the coreboot port but has disappeared from the project.
|-
| 0 || No direct vendor participation.
|}

== Example and support code ==

Is example and support code readily available? Maximum possible score: 10.

{| border="1"
|- bgcolor="#6699ff"
!Points
!Description
|-
| 10 || Code is freely available under a free software license. It can be downloaded through a direct URL with no click-through pages.
|-
| 7 || Code is freely available under a free software license. It can be downloaded on the web after agreeing to a click-through license.
|-
| 3 || Code is restricted and only available under Non Disclosure Agreement, however the NDA allows source code written using the sample code to be freely available under a free software license.
|-
| 0 || Code is not available or the NDA does now allow release of code.
|}

= Adding it all up =

The four categories above give us a scale with a maximum of 124 points. That means boards can get a score from zero to five 'hares':

{| border="1"
|- bgcolor="#6699ff"
!Points
!Score
|-
| 0 || [[Image:zero-hares.png]]
|-
| 1-24 || [[Image:one-hare.png]]
|-
| 25-49 || [[Image:two-hares.png]]
|-
| 50-74 || [[Image:three-hares.png]]
|-
| 75-99 || [[Image:four-hares.png]]
|-
| 100-124 || [[Image:five-hares.png]]
|}

= Example Board =

To demonstrate how this will work, we will apply the above criteria to the db800 platform from AMD, which is widely regarded as one of the better supported platforms in coreboot.
(Please fill in this section as new criteria are added).

Total available points: '''80'''
Total platform points: '''52'''
Total "stars": '''3'''

== Documentation ==

{| border="0" style="font-size: smaller"
|- bgcolor="#6699ff"
! align="left" | Item
! align="left" | Availability
! align="left" | Points

|- bgcolor="#6699ff"
| colspan="3" | '''CPU (Geode LX)'''

|- bgcolor="#eeeeee"
| '''Datasheet / register set'''
| Freely available [http://www.amd.com/files/connectivitysolutions/geode/geode_lx/33234F_LX_databook.pdf]
| style="background:lime" | 10

|- bgcolor="#dddddd"
| '''BIOS programming guide'''
| NDA allowing GPL'd code
| style="background:yellow" | 3

|- bgcolor="#eeeeee"
| '''Errata'''
| NDA allowing GPL'd code
| style="background:yellow" | 3

|- bgcolor="#6699ff"
| colspan="3" | '''Chipset (CS5536)'''

|- bgcolor="#eeeeee"
| '''Datasheet / register set'''
| Freely available [http://www.amd.com/files/connectivitysolutions/geode/geode_lx/33238G_cs5536_db.pdf]
| style="background:lime" | 10

|- bgcolor="#dddddd"
| '''BIOS programming guide'''
| NDA allowing GPL'd code
| style="background:yellow" | 3

|- bgcolor="#eeeeee"
| '''Errata'''
| Freely available [http://www.amd.com/files/connectivitysolutions/geode/geode_gx/34472D_CS5536_B1_specupdate.pdf]
| style="background:lime" | 10

|- bgcolor="#6699ff"
| colspan="3" | '''Super I/O'''

|- bgcolor="#eeeeee"
| '''Datasheet / register set'''
| Freely available [http://www.itox.com/pages/support/wdt/W83627HF.pdf]
| style="background:lime" | 10

|- bgcolor="#6699ff"
| colspan="3" | '''Mainboard'''

|- bgcolor="#eeeeee"
| '''Schematics'''
| NDA allowing GPL'd code
| style="background:yellow" | 3

|}

ADLO

2008-07-29T14:30:23Z

JCrouse: /* Where is ADLO? */ Change url to the correct location

== What is ADLO? ==

ADLO is a Add-on layer that bonds to the coreboot project and it derives from the 16-bit PC-BIOS of the Bochs emulator project.

----

On Sun Nov 24th, 2002 at 22:30:42 UTC, Adam Sulmicki announced via [http://www.coreboot.org/pipermail/coreboot/2002-November/001191.html coreboot mailing list] that him and a group of collegues ([http://www.missl.cs.umd.edu/sebos_phase2.html SEBOS team]) were successful at creating ADLO. ADLO was accomplished by developing software that combined elements from two rather successful projects:
coreboot (back then: LinuxBIOS) and BOCHS - with some help of the Etherboot project. The use of coreboot and BOCHS Bios source had helped them to create a wrapper to successfully boot a (Windows 2000 OS, OpenBSD, and Linux via GRUB or LILO as bootloaders) without a legacy, proprietary 16 bit BIOS.

With contribution from a grant from DARPA under the CHATS program, Adam Sulmicki, Adam Agnew and William Arbaugh had created a new way to succesfully boot multiple OS's without the need of proprietary software such as any BIOS from the market leaders AMI or Award.

The wrapper was originally written by [http://www.eax.com/ Adam Sulmicki.] and the [http://www.missl.cs.umd.edu/sebos_phase2.html SEBOS team].

Since Bochs BIOS provides many of the legacy BIOS services required by some x86 OS's it allows you to boot OS's that depend on those services.

The original release Supported OS's were:

1.Windows 2000 OS

2.OpenBSD

3.Linux via GRUB or LILO

At the time of ADLO launch the group was still working on supporting FreeBSD and Windows XP, they had also expected to improving ATA support will permit Win98 and WinXP to boot successfully with ADLO, also adding PIRQ support wich would permit FreeBSD to boot with ADLO.

Before the team made the ADLO source code public it was called the SEBOS project.
The motherboard used for testing was a Matsonic 7308e motherboard, and the support for ADLO on other motherboards was limited to that of the coreboot project at the time of release (Nov 2002).

The SEBOS team had also created it's adaptations to add security and encryption to an OS bootloader that has been missing in a 16-bit proprietary PC-BIOS for decades. ADLO is a simple wrapper that binds to the Bochs BIOS which allows coreboot to make use of the BIOS interrupt services. ADLO can be found in the coreboot-v2/util/ADLO directory in the coreboot subversion. Instructions for using ADLO can be found in the README contained within the source files.

Find out more at the team's website at :

http://www.missl.cs.umd.edu/sebos.html
http://www.missl.cs.umd.edu/sebos_phase2.html

== What is the current status and builds and contributions? ==

At the moment we are working with the original developer of ADLO to see if we can update the Wrapper and make future builds that can boot operating systems that require further 16-bit BIOS information and services like Windows XP and Windows Vista that are currently not supported with ADLO.

Not much has change from the original release of ADLO and we need a change badly. Keep in mind that the original release was back in Nov 2002.

WE ALSO NEED PEOPLE LIKE YOU WHO ARE INTERESTED IN CONTRIBUTING IN THE PROJECT.

If you can contribute, in any way to the ADLO project Please let US know. Contact bootblock at techgx.net with ideas, troubleshooting, or things that you know has worked for you.
experiments with coreboot and ADLO and other motherboards

== What bios services does ADLO provide and when would I need them ? ==

The full gory details for XP are at:

http://www.missl.cs.umd.edu/winint/index2.html

The full gory details for W2K are at:

http://www.missl.cs.umd.edu/winint/index1.html

Microsoft also published an article about their use of BIOS here:

http://www.microsoft.com/whdc/archive/Lf.mspx

== What bootloaders work with ADLO? ==

Currently known to work are:
* LILO
* GRUB
* NTLDR (Windows 2000)

There is no technical reason why it couldn't work with *BSD, (Free)Dos,
and other versions of Windows after some tweaking.

We need Beta testers to start testing
* freeldr (React OS)
* NTLDR (Windows XP)
* NTLDR (Windows XP embedded)
* NTLDR (Windows 2003)
* and Vista via EFI or Boot Manager BCD

== Where is ADLO? ==

ADLO is part of the coreboot v2 repository under [http://coreboot.org/viewvc/trunk/coreboot-v2/util/ADLO/ coreboot-v2/util/ADLO].

An older version was already part of coreboot v1 and is available at the [http://www.coreboot.org/viewcvs/trunk/LinuxBIOSv1/util/ADLO/ coreboot-v1/util/ADLO] directory.

== How do I get coreboot to boot ADLO? ==

ADLO compiles as an ELF image so you have to set up coreboot to elf boot just as if you were using any other ELF payload. In the [http://www.coreboot.org/viewcvs/trunk/LinuxBIOSv2/util/ADLO/ ADLO directory] are some READMEs. Make sure you have read them.

Compiling ADLO is quite simple. Mostly you just type ''make'' You will need the 16-bit assembler as86 installed to build the Bochs BIOS. You will also need a copy of your video BIOS if you want VGA to work. Again see the README.

=== BIOS shadowing ===

Out-of-the box ADLO probally won't boot unless you are using the exact mainboard that the ADLO project uses which is the Matsonic 7308e. The reason is that various areas of shadowing must be enabled for ADLO to boot. (FIXME: please explain)

If you see '''elfboot''' indicate that it is 'Jumping to boot code at 0x7c00' and then the board resets or hangs then its very likely that your shadow settings are incorrect. Applying the serial debug patch to ADLO can help you further investigate this.

<div style="margin-top:0.5em; padding:0.5em 0.5em 0.5em 0.5em; background-color:#ffdfdf; align:right; border:1px solid #aabbcc;">
FixMe Where is the ''de facto'' location for the serial patch?
</div>

The shadow settings are set in '''loader.s''' in the freebios/util/ADLO. Find section B. These are writes to PCI space that enable various areas of shadowing.

Technically, all you need is only 64kb at 0xF0000 and 64kb at 0xC0000. Your mileage may vary. Start by enabling Read/Write for all shadow ranges supported by your chipset and then back off to 0xF0000 and 0xC0000 after you get it working.

=== Video BIOS ===

The ADLO Makefile will copy your video bios from an existing setup. See the '''README''' and '''Makefile''' for details.

ADLO expects the video bios to be 64k in size whereas a lot of video BIOS images are only 32k. You can solve this by just duplicating in the same file and then letting ADLO use that. Some creative work with 'dd' and padding would achieve the same result.

=== Serial Output ===

Lastly if you have applied the serial debug patch to BOCHS then '''all''' the output is routed out to the serial port so your video screen will be blank.
However VSYNC will still be generated if the video chip is initialized properly. You can watch for VSYNC with a Oscope or plug a newer type monitor up to the video output. Most modern monitors will tell you when they can/can't find the VSYNC signal. Note you may have to power cycle the monitor between attempts as sometimes they can get very confused.

Bayou

2008-06-20T22:50:48Z

JCrouse: Add screenshots

'''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]] 
[[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"? ==

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.

== 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 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
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:

* 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
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
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
follows:

{| border="1"
|- bgcolor="#6699ff"
|-
| Global configuration
|-
| Payload tables
|}

The global configuration header controls general Bayou behavior:

{| border="1"
|- bgcolor="#6699ff"
!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

{| border="1"
|- bgcolor="#6699ff"
!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 LAR 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:

{| border="1"
|- bgcolor="#6699ff"
!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");

== 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.

=== LAR ===
* 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?
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 ===
* 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
* Modify the build system to allow the configuration system to modify the payload entry point

File:Bayou-screenshot-timeout.jpg

2008-06-20T22:46:22Z

JCrouse: The timeout message in Bayou. If the key is not pressed, then, the chooser menu would appear Author: Jordan Crouse {{PD-self}}

The timeout message in [[Bayou]]. If the key is not pressed, then, the chooser menu would appear

Author: Jordan Crouse

{{PD-self}}

File:Bayou-screenshot-serial.jpg

2008-06-20T22:45:36Z

JCrouse: Screen shot of Bayou in serial mode Author: Jordan Crouse {{PD-self}}

Screen shot of Bayou in serial mode

Author: Jordan Crouse

{{PD-self}}

File:Bayou-screenshot-info.jpg

2008-06-20T22:45:12Z

JCrouse: Bayou screenshot showing the "description" of the payload Author: Jordan Crouse {{PD-self}}

Bayou screenshot showing the "description" of the payload

Author: Jordan Crouse

{{PD-self}}

File:Bayou-screenshot-menu.jpg

2008-06-20T22:44:09Z

JCrouse: Bayou screenshot showing the chooser menu with two options Author: Jordan Crouse {{PD-self}}

[[Bayou]] screenshot showing the chooser menu with two options

Author: Jordan Crouse

{{PD-self}}

Bayou

2008-06-19T16:14:31Z

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

'''Bayou''' is the working name for a coreboot payload that can chose, load and run other payloads from a LAR archive on the ROM.

== 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.

== 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 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
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:

* 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
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
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
follows:

{| border="1"
|- bgcolor="#6699ff"
|-
| Global configuration
|-
| Payload tables
|}

The global configuration header controls general Bayou behavior:

{| border="1"
|- bgcolor="#6699ff"
!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

{| border="1"
|- bgcolor="#6699ff"
!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 LAR 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:

{| border="1"
|- bgcolor="#6699ff"
!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");

== 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.

=== LAR ===
* 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?
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 ===
* 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
* Modify the build system to allow the configuration system to modify the payload entry point

Bayou

2008-06-19T16:04:15Z

JCrouse: /* Bayou Payload Table */ Millisecond granularity

'''Bayou''' is the working name for a coreboot payload that can chose, load and run other payloads from a LAR archive on the ROM.

== 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.

== 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 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
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:

* 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'.
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.

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
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
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
follows:

{| border="1"
|- bgcolor="#6699ff"
|-
| Global configuration
|-
| Payload tables
|}

The global configuration header controls general Bayou behavior:

{| border="1"
|- bgcolor="#6699ff"
!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 || 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.
|-
| Padding || 10 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

{| border="1"
|- bgcolor="#6699ff"
!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 LAR 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:

{| border="1"
|- bgcolor="#6699ff"
!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");

== 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.

=== LAR ===
* 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?
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 ===
* 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
* Modify the build system to allow the configuration system to modify the payload entry point

Bayou

2008-06-16T17:34:21Z

JCrouse: Add behavior and cleanups

'''Bayou''' is the working name for a coreboot payload that can chose, load and run other payloads from a LAR archive on the ROM.

== 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.

== 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 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
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:

* 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'.
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.

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
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
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
follows:

{| border="1"
|- bgcolor="#6699ff"
|-
| Global configuration
|-
| Payload tables
|}

The global configuration header controls general Bayou behavior:

{| border="1"
|- bgcolor="#6699ff"
!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 || 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
|}

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

{| border="1"
|- bgcolor="#6699ff"
!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 LAR 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:

{| border="1"
|- bgcolor="#6699ff"
!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");

== 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.

=== LAR ===
* 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?
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 ===
* 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
* Modify the build system to allow the configuration system to modify the payload entry point

Bayou

2008-06-16T17:04:10Z

JCrouse: /* Architecture */ Add BPT description

'''Bayou''' is the working name for a coreboot payload that can chose, load and run other payloads from a LAR archive on the ROM.

== 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.

== 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 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
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).

== 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.

=== 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:

{| border="1"
|- bgcolor="#6699ff"
|-
| Global configuration
|-
| Payload tables
|}

The global configuration header controls general Bayou behavior:

{| border="1"
|- bgcolor="#6699ff"
!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 || 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.
|-
| Padding || 10 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

{| border="1"
|- bgcolor="#6699ff"
!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 LAR 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:

{| border="1"
|- bgcolor="#6699ff"
!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");

== 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.

=== LAR ===
* 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?
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 ===
* 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
* Modify the build system to allow the configuration system to modify the payload entry point

Payload API

2008-05-20T15:59:39Z

JCrouse: Initial revision

== Payload API ==

This page discusses the API for passing parameters to new payloads and getting a return value back. In the description below, the term ''parent'' refers to the entity that is
starting the payload; nominally coreboot or a chooser payload. The term ''child'' or ''payload'' refers to the payload code that is being executed.

This API is implemented by [[libpayload]].

=== Passing Parameters ===

Parameters are passed from the parent to the child in the form of an array of zero terminated strings, similar to a standard C application.
The calling application pushes on the stack (in order): the the number of elements in the array (argc), a pointer to the array (argv and a magic number
(0x12345678).

After control has been passed to the payload, the stack will look like this:

{| border="1"
|- bgcolor="#6699ff"
! Offset (from %esp)
! Size
! Parameter
! Value
|-
| 0x00 || 4 || return address
|-
| 0x04 || 4 || Magic number || 0x12345678
|-
| 0x08 || 4 || Pointer to the array (argv)
|-
| 0x10 || 4 || number of elements in the array (argc)
|}

The payload should first check offset 0x04 for the magic number. If it is not present, then the payload should assume that the parent did not pass any parameters (probably because it was a legacy application). Failure to check for the magic number could result in mistaken values for argc and argv which could cause program failure.
After verifying the magic number, the payload can collect the other two elements and process them accordingly.

== Return Value ==

After the payload has completed execution, i can return an integer exit code to the parent. The exit code will be passed in the %eax register. After
regaining control, the parent should take care to save off the value of %eax before using the register for other purposes.

Libpayload

2008-05-20T15:24:53Z

JCrouse: Add link to the payload API page

'''libpayload''' is a small BSD-licensed static library (a lightweight implementation of common and useful functions) intended to be used as a basis for coreboot payloads.

The benefits of linking a coreboot payload against libpayload are:

* Payloads do not have to implement and maintain low-level code for I/O, common functions, etc.
* Payloads can be recompiled and deployed for CPU architectures supported by coreboot in the future.
* The libpayload functions can be tested and scrutinized outside payload development.
* Payloads themselves may be partly host-tested, e.g. against an emulation libpayload.

''Just give us a main() and a pocket full of dreams and we'll do the rest.''

== Features ==

* Provides a [[Libpayload#Libc_Coverage|subset of libc functions]] (e.g. malloc, printf, strcmp, etc).
* Provides an optional tiny (n)curses implementation.
* Provides various small drivers for
** keyboard
** PC speaker
** NVRAM/CMOS access
** serial console
** VGA
** Geode framebuffer
* Reads and parses the coreboot table.

== Design ==
* [[Payload API|Discussion of the API for passing parameters to the payload]]

== Payloads using libpayload ==

* [[coreinfo]] is a small payload which can display system information such as PCI info, an NVRAM dump, or the coreboot v3 printk buffer.
* [[GRUB invaders]] has been ported successfully to libpayload (patch pending).
* [[tint]] (a console tetris clone) has been successfully ported to libpayload.
* [http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=tree;f=scripts/kconfig/lxdialog;hb=HEAD lxdialog] from the Linux '''kconfig''' utility has been ported to be usable when linked with libpayload (patch pending).

== Downloading and building libpayload ==

$ svn co svn://coreboot.org/repos/trunk/payloads/libpayload
$ cd libpayload
$ make menuconfig
$ make

== Libc coverage ==

{| border="0" valign="top"
| valign="top"|

{| border="0" style="font-size: smaller"
|- bgcolor="#6699ff"
! align="left" | Status
! align="left" | Function/Macro/Variable

|- bgcolor="#6699ff"
| colspan=2 | '''assert.h'''
|-
|- bgcolor="#eeeeee" valign="top"
| style="background:red" | no
| assert()

|- bgcolor="#6699ff"
| colspan=2 | '''ctype.h'''
|-
|- bgcolor="#eeeeee" valign="top"
| style="background:lime" | yes
| int isalnum(int character)
|-
|- bgcolor="#dddddd" valign="top"
| style="background:lime" | yes
| int isalpha(int character)
|-
|- bgcolor="#eeeeee" valign="top"
| style="background:lime" | yes
| int iscntrl(int character)
|-
|- bgcolor="#dddddd" valign="top"
| style="background:lime" | yes
| int isdigit(int character)
|-
|- bgcolor="#eeeeee" valign="top"
| style="background:lime" | yes
| int isgraph(int character)
|-
|- bgcolor="#dddddd" valign="top"
| style="background:lime" | yes
| int islower(int character)
|-
|- bgcolor="#eeeeee" valign="top"
| style="background:lime" | yes
| int isprint(int character)
|-
|- bgcolor="#dddddd" valign="top"
| style="background:lime" | yes
| int ispunct(int character)
|-
|- bgcolor="#eeeeee" valign="top"
| style="background:lime" | yes
| int isspace(int character)
|-
|- bgcolor="#dddddd" valign="top"
| style="background:lime" | yes
| int isupper(int character)
|-
|- bgcolor="#eeeeee" valign="top"
| style="background:lime" | yes
| int isxdigit(int character)

|- bgcolor="#6699ff"
| colspan=2 | '''errno.h'''
|-
| style="background:red" | no
| <code>errno</code> (global)

|- bgcolor="#6699ff"
| colspan=2 | '''float.h'''

|- bgcolor="#6699ff"
| colspan=2 | '''limits.h'''

|- bgcolor="#6699ff"
| colspan=2 | '''locale.h'''
|-
| style="background:red" | no
| <code>char *setlocale(int category, const char *locale)</code>
|-
| style="background:red" | no
| <code>struct lconv *localeconv(void)</code>

|- bgcolor="#6699ff"
| colspan=2 | '''math.h'''
|-
| style="background:red" | no
| <code>double exp(double x)</code>
|-
| style="background:red" | no
| <code>double log(double x)</code>
|-
| style="background:red" | no
| <code>double log10(double x)</code>
|-
| style="background:red" | no
| <code>double pow(double x, double y)</code>
|-
| style="background:red" | no
| <code>double sqrt(double x)</code>
|-
| style="background:red" | no
| <code>double ceil(double x)</code>
|-
| style="background:red" | no
| <code>double floor(double x)</code>
|-
| style="background:red" | no
| <code>double fabs(double x)</code>
|-
| style="background:red" | no
| <code>double ldexp(double x, int n)</code>
|-
| style="background:red" | no
| <code>double frexp(double x, int* exp)</code>
|-
| style="background:red" | no
| <code>double modf(double x, double* ip)</code>
|-
| style="background:red" | no
| <code>double fmod(double x, double y)</code>
|-
| style="background:red" | no
| <code>double sin(double x)</code>
|-
| style="background:red" | no
| <code>double cos(double x)</code>
|-
| style="background:red" | no
| <code>double tan(double x)</code>
|-
| style="background:red" | no
| <code>double asin(double x)</code>
|-
| style="background:red" | no
| <code>double acos(double x)</code>
|-
| style="background:red" | no
| <code>double atan(double x)</code>
|-
| style="background:red" | no
| <code>double atan2(double y, double x)</code>
|-
| style="background:red" | no
| <code>double sinh(double x)</code>
|-
| style="background:red" | no
| <code>double cosh(double x)</code>
|-
| style="background:red" | no
| <code>double tanh(double x)</code>

|- bgcolor="#6699ff"
| colspan=2 | '''setjmp.h'''
|-
| style="background:red" | no
| <code>int setjmp(jmp_buf env)</code>
|-
| style="background:red" | no
| <code>void longjmp(jmp_buf env, int val)</code>

|- bgcolor="#6699ff"
| colspan=2 | '''signal.h'''
|-
| style="background:red" | no
| <code>void (*signal(int sig, void (*handler)(int)))(int)</code>
|-
| style="background:red" | no
| <code>int raise(int sig)</code>

|- bgcolor="#6699ff"
| colspan=2 | '''stdarg.h'''
|-
| style="background:red" | no
| <code>void va_start(va_list ap, lastarg)</code>
|-
| style="background:red" | no
| <code>type va_arg(va_list ap, type)</code>
|-
| style="background:red" | no
| <code>void va_end(va_list ap)</code>

|- bgcolor="#6699ff"
| colspan=2 | '''stddef.h'''

|- colspan=2
| TODO

|- bgcolor="#6699ff"
| colspan=2 | '''stdio.h'''
|-
| style="background:red" | no
| <code>FILE* fopen(const char* filename, const char* mode)</code>
|-
| style="background:red" | no
| <code>FILE* freopen(const char* filename, const char* mode, FILE* stream)</code>
|-
| style="background:red" | no
| <code>int fflush(FILE* stream)</code>
|-
| style="background:red" | no
| <code>int fclose(FILE* stream)</code>
|-
| style="background:red" | no
| <code>int remove(const char* filename)</code>
|-
| style="background:red" | no
| <code>int rename(const char* oldname, const char* newname)</code>
|-
| style="background:red" | no
| <code>FILE* tmpfile()</code>
|-
| style="background:red" | no
| <code>char* tmpnam(char s[L_tmpnam])</code>
|-
| style="background:red" | no
| <code>int setvbuf(FILE* stream, char* buf, int mode, size_t size)</code>
|-
| style="background:red" | no
| <code>void setbuf(FILE* stream, char* buf)</code>
|-
| style="background:red" | no
| <code>int fprintf(FILE* stream, const char* format, ...)</code>
|-
| style="background:lime" | yes
| <code>int printf(const char* format, ...)</code>
|-
| style="background:lime" | yes
| <code>int sprintf(char* s, const char* format, ...)</code>
|-
| style="background:red" | no
| <code>int vfprintf(FILE* stream, const char* format, va_list arg)</code>
|-
| style="background:lime" | yes
| <code>int vprintf(const char* format, va_list arg)</code>
|-
| style="background:lime" | yes
| <code>int vsprintf(char* s, const char* format, va_list arg)</code>
|-
| style="background:red" | no
| <code>int fscanf(FILE* stream, const char* format, ...)</code>
|-
| style="background:red" | no
| <code>int scanf(const char* format, ...)</code>
|-
| style="background:red" | no
| <code>int sscanf(char* s, const char* format, ...)</code>
|-
| style="background:red" | no
| <code>int fgetc(FILE* stream)</code>
|-
| style="background:red" | no
| <code>char* fgets(char* s, int n, FILE* stream)</code>
|-
| style="background:red" | no
| <code>int fputc(int c, FILE* stream)</code>
|-
| style="background:red" | no
| <code>char* fputs(const char* s, FILE* stream)</code>
|-
| style="background:red" | no
| <code>int getc(FILE* stream)</code>
|-
| style="background:lime" | yes
| <code>int getchar(void)</code>
|-
| style="background:red" | no
| <code>char* gets(char* s)</code>
|-
| style="background:red" | no
| <code>int putc(int c, FILE* stream)</code>
|-
| style="background:lime" | yes
| <code>int putchar(int c)</code>
|-
| style="background:lime" | yes
| <code>int puts(const char* s)</code>
|-
| style="background:red" | no
| <code>int ungetc(int c, FILE* stream)</code>
|-
| style="background:red" | no
| <code>size_t fread(void* ptr, size_t size, size_t nobj, FILE* stream)</code>
|-
| style="background:red" | no
| <code>size_t fwrite(const void* ptr, size_t size, size_t nobj, FILE* stream)</code>
|-
| style="background:red" | no
| <code>int fseek(FILE* stream, long offset, int origin)</code>
|-
| style="background:red" | no
| <code>long ftell(FILE* stream)</code>
|-
| style="background:red" | no
| <code>void rewind(FILE* stream)</code>
|-
| style="background:red" | no
| <code>int fgetpos(FILE* stream, fpos_t* ptr)</code>
|-
| style="background:red" | no
| <code>int fsetpos(FILE* stream, const fpos_t* ptr)</code>
|-
| style="background:red" | no
| <code>void clearerr(FILE* stream)</code>
|-
| style="background:red" | no
| <code>int feof(FILE* stream)</code>
|-
| style="background:red" | no
| <code>int ferror(FILE* stream)</code>
|-
| style="background:red" | no
| <code>void perror(const char* s)</code>

|}

| valign="top"|

{| border="0" style="font-size: smaller"
|- bgcolor="#6699ff"
! align="left" | Status
! align="left" | Function/Macro/Variable

|- bgcolor="#6699ff"
| colspan=2 | '''stdlib.h'''
|-
| style="background:lime" | yes
| <code>int abs(int n)</code>
|-
| style="background:lime" | yes
| <code>long labs(long n)</code>
|-
| style="background:lime" | yes
| <code>long long llabs(long long n)</code>
|-
| style="background:red" | no
| <code>div_t div(int num, int denom)</code>
|-
| style="background:red" | no
| <code>ldiv_t ldiv(long num, long denom)</code>
|-
| style="background:red" | no
| <code>double atof(const char* s)</code>
|-
| style="background:red" | no
| <code>int atoi(const char* s)</code>
|-
| style="background:red" | no
| <code>long atol(const char* s)</code>
|-
| style="background:red" | no
| <code>double strtod(const char* s, char** endp)</code>
|-
| style="background:red" | no
| <code>long strtol(const char* s, char** endp, int base)</code>
|-
| style="background:red" | no
| <code>unsigned long strtoul(const char* s, char** endp, int base)</code>
|-
| style="background:lime" | yes
| <code>void* calloc(size_t nobj, size_t size)</code>
|-
| style="background:lime" | yes
| <code>void* malloc(size_t size)</code>
|-
| style="background:lime" | yes
| <code>void* realloc(void* p, size_t size)</code>
|-
| style="background:lime" | yes
| <code>void free(void* p)</code>
|-
| style="background:lime" | yes
| <code>void abort()</code>
|-
| style="background:red" | no
| <code>void exit(int status)</code>
|-
| style="background:red" | no
| <code>int atexit(void (*fcm)(void))</code>
|-
| style="background:red" | no
| <code>int system(const char* s)</code>
|-
| style="background:red" | no
| <code>char* getenv(const char* name)</code>
|-
| style="background:red" | no
| <code>void* bsearch(const void* key, const void* base, size_t n, size_t size, int (*cmp)(const void* keyval, const void* datum))</code>
|-
| style="background:red" | no
| <code>void qsort(void* base, size_t n, size_t size, int (*cmp)(const void*, const void*))</code>
|-
| style="background:lime" | yes
| <code>int rand(void)</code>
|-
| style="background:lime" | yes
| <code>void srand(unsigned int seed)</code>

|- bgcolor="#6699ff"
| colspan=2 | '''string.h'''
|-
| style="background:lime" | yes
| <code>char* strcpy(char* s, const char* ct)</code>
|-
| style="background:lime" | yes
| <code>char* strncpy(char* s, const char* ct, size_t n)</code>
|-
| style="background:red" | no
| <code>char* strcat(char* s, const char* ct)</code>
|-
| style="background:lime" | yes
| <code>char* strncat(char* s, const char* ct, size_t n)</code>
|-
| style="background:lime" | yes
| <code>int strcmp(const char* cs, const char* ct)</code>
|-
| style="background:lime" | yes
| <code>int strncmp(const char* cs, const char* ct, size_t n)</code>
|-
| style="background:red" | no
| <code>int strcoll(const char* cs, const char* ct)</code>
|-
| style="background:lime" | yes
| <code>char* strchr(const char* cs, int c)</code>
|-
| style="background:red" | no
| <code>char* strrchr(const char* cs, int c)</code>
|-
| style="background:red" | no
| <code>size_t strspn(const char* cs, const char* ct)</code>
|-
| style="background:red" | no
| <code>size_t strcspn(const char* cs, const char* ct)</code>
|-
| style="background:red" | no
| <code>char* strpbrk(const char* cs, const char* ct)</code>
|-
| style="background:lime" | yes
| <code>char* strstr(const char* cs, const char* ct)</code>
|-
| style="background:lime" | yes
| <code>size_t strlen(const char* cs)</code>
|-
| style="background:red" | no
| <code>char* strerror(int n)</code>
|-
| style="background:red" | no
| <code>char* strtok(char* s, const char* t)</code>
|-
| style="background:red" | no
| <code>size_t strxfrm(char* s, const char* ct, size_t n)</code>
|-
| style="background:lime" | yes
| <code>void* memcpy(void* s, const void* ct, size_t n)</code>
|-
| style="background:lime" | yes
| <code>void* memmove(void* s, const void* ct, size_t n)</code>
|-
| style="background:lime" | yes
| <code>int memcmp(const void* cs, const void* ct, size_t n)</code>
|-
| style="background:red" | no
| <code>void* memchr(const void* cs, int c, size_t n)</code>
|-
| style="background:lime" | yes
| <code>void* memset(void* s, int c, size_t n)</code>

|- bgcolor="#6699ff"
| colspan=2 | '''time.h'''
|-
| style="background:red" | no
| <code>clock_t clock(void)</code>
|-
| style="background:red" | no
| <code>time_t time(time_t* tp)</code>
|-
| style="background:red" | no
| <code>double difftime(time_t time2, time_t time1)</code>
|-
| style="background:red" | no
| <code>time_t mktime(struct tm* tp)</code>
|-
| style="background:red" | no
| <code>char* asctime(const struct tm* tp)</code>
|-
| style="background:red" | no
| <code>char* ctime(const time_t* tp)</code>
|-
| style="background:red" | no
| <code>struct tm* gmtime(const time_t* tp)</code>
|-
| style="background:red" | no
| <code>struct tm* localtime(const time_t* tp)</code>
|-
| style="background:red" | no
| <code>size_t strftime(char* s, size_t smax, const char* fmt, const struct tm* tp)</code>

|}
|}

== Usage example ==

Here's an example of a very simple payload (hello.c) and how to build it:

<pre>
#include <libpayload.h>

int main(void)
{
printf("Hello, world!\n");
halt();
return 0;
}
</pre>

Building the payload:

lpgcc -o hello.elf hello.c

{{PD-self}}

Bayou

2008-05-15T22:30:24Z

JCrouse: add param information

SELF

2008-05-15T22:20:05Z

JCrouse: Add the param section

'''SELF''' stands for '''S'''imple '''E'''xecutable '''L'''oader '''F'''ormat. It is a very simple take on the standard [[http://en.wikipedia.org/wiki/Executable_and_Linkable_Format ELF]] executable format. It is proposed that SELF be the the standard format for payload code stored in a LAR file and loaded and executed by coreboot-v3. The [[bayou]] chooser will also load and run payloads in the SELF format.

== Description ==
Each SELF file is defined as a group of different segments. Each segment either loads data into memory, zeroes a section of memory, or provides information to coreboot or the payload. The segments can be one of the following types:

{| border="1"
|- bgcolor="#6699ff"
!ID
!Segment
!Description
|-
| 'CODE' (0x45444F43) || CODE || This segment has executable code to be copied from the data section to memory. Each CODE segment has a corresponding block of data, which may be compressed in the LAR. Multiple segments of this type are allowed.
|-
| 'DATA' (0x41543144) || DATA || This segment has non-executable data to be copied from the data section into memory. Each DATA segment has a corresponding block of data, which may be compressed in the LAR. Multiple segments of this type are allowed.
|-
| 'BSS ' (0x20535342) || BSS || This segment defines a section of memory to be zeroed. BSS segments do not have any data associated with them. Multiple segments of this type are allowed.
|-
| 'PARA' (0x41524150)|| PARAMS || This segment contains the contents of the .notes.pinfo section from the payload ELF. The payload will store parameters in this section for the benefit of a chooser payload. The parameters will be stored as a series of strings of the format "key=value\0".
|-
| 'ENTR' (0x52544E45) || ENTRY || This segment defines the entry point for execution. This type signifies the end of the list of segments, and it must be the last segment defined in the SELF. It is mandatory and can only be used once.
|}

== Format ==

A SELF file is comprised of two parts: the segment table and the data section. Each is described below.

=== Segment Table ===

The segment table is located at the start of the ELF file, with one entry per segement. Each segment is identified by its type (as listed above). The structure of the header entry is as follows:

struct self_header {
unsigned long type;
unsigned long offset;
unsigned long long load_addr;
unsigned long len;
unsigned long mem_len;
};

All fields are present in each segment entry, though not every field will be valid for every segment type. The value of each field will be stored in little endian format. Big endian architectures will need to byte swap the value before using it. The following table lists which members are used and what they mean:

{| border="1"
|- bgcolor="#6699ff"
!Type
!offset
!load_addr
!len
!mem_len
|-
|CODE || Offset of the segment in the SELF file || address where the code should be copied in memory || length of the data in the segment data section || length of the data in memory
|-
| DATA || Offset of the segment in the SELF file || address where the code should be copied in memory || length of the data in the segment data section || length of the data in memory
|-
| BSS || N/A || Start address of the block in memory to be zeroed || N/A || Length of the block in memory to be zeroed
|-
| PARAM || Offset of the segment in the SELF file || N/A || length of the data in the segment data section || N/A
|-
| ENTRY || N/A || Address where execution should start || N/A || N/A
|}

=== Segment Section ===

The data section immediately follows the final entry in the segment table. Each block of segment data is written sequentially in this section, with the start of each block aligned to a 32 bit boundary.
CODE and DATA sections may be compressed according to the LAR compression scheme, the PARAM section must be uncompressed.

== Typical Use ==

The following pseudo code shows how a SELF is loaded and run:

decompress_and_run(void) {
ptr = SELF_start;

while(1) {
header = (struct self_header *) ptr;
switch(header->type) {
case TYPE_CODE:
case TYPE_DATA:
dlen = decompress(SELF_start + header->offset, header->load_addr, header->len);
memset(header->load_addr + dlen, 0, header->mem_len - dlen);
break;
case BSS:
memset(header->load_addr, 0, header->len);
break;
case LOAD:
return jump_to(header->load_addr);
}

ptr += sizeof(*header);
}
}

== Changelog ==

* Replace the NAME and NOTE sections with the PARAMS section
* Change ID of each segment to 4 text characters
* Each block of data needs to be 32 bit aligned
* Specified that all the segment header members are stored in little endian
* Changed the load address in the segment header structure to 64 bits.
* Clarified the compression of the code / data segments

Rating System

2008-04-18T17:43:16Z

JCrouse: add documentation critera from IRC discussion and example platform

== Rating System ==

At the coreboot summit in Denver we talked about a rating system for supported boards. The idea is to make it clear which boards are most highly recommended because the vendors cooperate.

To get to such a rating for a particular board, we should establish a list of categories with an associated score. Each fulfilled criteria should be easily verifiable as a yes or no answer.
There should be no subjective elements to the rating system - only measurable criteria should be used to avoid bias or favoritism.

Adding up the scores for the major components on a board (cpu, chipsets, mainboard, others?) would give us a rating that results in a number of 'stars'.

Some ideas for those categories:

* availability of documentation (nothing/NDA restricted == 0, NDA but free to publish code == 3, online with click through == 7, public URL == 10)
** There should be multiple categories of documentation (register set, BIOS programming guide, errata, schematics or pinouts (for motherboards)
* vendor participation in the coreboot project
** How to quantify?
* Availability of example and support code
** ACPI tables
* "Hackability"
** LPC header, JTAG header, BIOS socket, etc.
** Should we dock a board because it requires soldering or a difficult process for flashing coreboot?
* ...

As we list boards, we should also make it clear if a board is actually available for purchase. A board might get a high rating, but be unavailable for purchase, in which case it should be carefully marked as such. Board availability will change over a board's lifespan.

Should we provide a separate rating for coreboot support (i.e. the stuff above) and how good our code actually is?

= Criteria =

When all the criteria have been evaluated, each platform will end up with a total score. To assign "stars" to the platform, we will divide the number of points by the number of stars
(probably 5) and round down to the nearest half star.

== Documentation ==

Use the following criteria to evaluate each set of documentation:

{| border="1"
|- bgcolor="#6699ff"
!Points
!Description
|-
| 10 || Documentation is freely available and redistributable. It can be downloaded through a direct URL with no click-through pages.
|-
| 7 || Documentation is freely available and redistributable. It can be downloaded on the web after agreeing to a click-through license.
|-
| 3 || Documentation is restricted and only available under Non Disclosure Agreement, however the NDA allows source code written with the documentation to be freely available under the GPL.
|-
| 0 || Documentation is not available or the NDA does now allow release of code.
|}

X86 based platforms can have up to 80 points for documentation.

=== CPU ===

Evaluate the criteria against the following three sets of documentation (30 total points possible):

* Datasheet / register set (Detailed information about programming registers and/or memory locations)
* BIOS programming guide
* Errata

=== Southbridge (chipset) ===

Evaluate the criteria against the following three sets of documentation (30 total points possible):

* Datasheet / register set (Detailed information about programming registers and/or memory locations)
* BIOS programming guide
* Errata

=== Other chipsets (SuperIO, etc) ===

Evaluate the criteria against the following: (10 total points possible). Add 10 points if not applicable to the platform.

* Datasheet / register set (Detailed information about programming registers and/or memory locations)

=== Mainboard ===

Evaluate the criteria against the following: (10 total points available)

* Schematics / Pinout (Sufficient documentation to detail the platform specific GPIO & IRQ assignments)

= Example Board =
To demonstrate how this will work, we will apply the above criteria to the db800 platform from AMD, which is widely regarded as one of the better supported platforms in coreboot.
(Please fill in this section as new criteria are added).

Total available points: '''80'''
Total platform points: '''52'''
Total "stars": '''3'''

== Documentation ==
=== CPU (Geode LX) ===
* Datasheet / register set: Freely available [http://www.amd.com/files/connectivitysolutions/geode/geode_lx/33234F_LX_databook.pdf] - '''10 points'''
* BIOS programming guide: NDA allowing GPLed code - '''3 points'''
* Errata: NDA allowing GPL - '''3 points'''
== Chipset (CS5536) ===
* Datasheet / register set: Freely available [http://www.amd.com/files/connectivitysolutions/geode/geode_lx/33238G_cs5536_db.pdf] - '''10 points'''
* BIOS programming guide: NDA allowing GPLed code - '''3 points'''
* Errata: Freely available [http://www.amd.com/files/connectivitysolutions/geode/geode_gx/34472D_CS5536_B1_specupdate.pdf] - '''10 points'''
== SuperIO ==
* Datasheet / register set: Freely available [http://www.itox.com/pages/support/wdt/W83627HF.pdf] - '''10 points'''
==Mainboard==
* Schematics: NDA allowing GPLed code - '''3 points'''

Rating System

2008-04-17T18:01:57Z

JCrouse: Discuss quantitative criteria and add some ideas

SELF

2008-04-13T03:36:57Z

JCrouse: Changes based on feedback

'''SELF''' stands for '''S'''imple '''E'''xecutable '''L'''oader '''F'''ormat. It is a very simple take on the standard [[http://en.wikipedia.org/wiki/Executable_and_Linkable_Format ELF]] executable format. It is proposed that SELF be the the standard format for payload code stored in a LAR file and loaded and executed by coreboot-v3. The [[bayou]] chooser will also load and run payloads in the SELF format.

== Description ==
Each SELF file is defined as a group of different segments. Each segment either loads data into memory, zeroes a section of memory, or provides information to coreboot or the payload. The segments can be one of the following types:

{| border="1"
|- bgcolor="#6699ff"
!ID
!Segment
!Description
|-
| 'CODE' (0x45444F43) || CODE || This segment has executable code to be copied from the data section to memory. Each CODE segment has a corresponding block of data, which may be compressed in the LAR. Multiple segments of this type are allowed.
|-
| 'DATA' (0x41543144) || DATA || This segment has non-executable data to be copied from the data section into memory. Each DATA segment has a corresponding block of data, which may be compressed in the LAR. Multiple segments of this type are allowed.
|-
| 'BSS ' (0x20535342) || BSS || This segment defines a section of memory to be zeroed. BSS segments do not have any data associated with them. Multiple segments of this type are allowed.
|-
| 'NAME' (0x434D4145)|| NAME || This segment contains a descriptive string in the data section that is used by the payload loader to identify the current payload. NAME segments have corresponding blocks of data, but they are not loaded into system memory. The segment data must '''not''' be compressed. Multiple segments of this type are allowed, but likely won't be used by the payload loader.
|-
| 'NOTE' (0x45544F4E)|| NOTES || This segment contains the contents of the .notes section in the data segment. NOTES segments have corresponding blocks of data, but they are not loaded into system memory. The segment data must '''not''' be compressed. Multiple segments of this type are allowed.
|-
| 'ENTR' (0x52544E45) || ENTRY || This segment defines the entry point for execution. This type signifies the end of the list of segments. It is mandatory and can only be used once.
|}

== Format ==

A SELF file is comprised of two parts: the segment table and the data section. Each is described below.

=== Segment Table ===

The segment table is located at the start of the ELF file, with one entry per segement. Each segment is identified by its type (as listed above). The structure of the header entry is as follows:

struct self_header {
unsigned long type;
unsigned long offset;
unsigned long long load_addr;
unsigned long len;
unsigned long mem_len;
};

All fields are present in each segment entry, though not every field will be valid for every segment type. The value of each field will be stored in little endian format. Big endian architectures will need to byte swap the value before using it. The following table lists which members are used and what they mean:

{| border="1"
|- bgcolor="#6699ff"
!Type
!offset
!load_addr
!len
!mem_len
|-
|CODE || Offset of the segment in the SELF file || address where the code should be copied in memory || length of the data in the segment data section || length of the data in memory
|-
| DATA || Offset of the segment in the SELF file || address where the code should be copied in memory || length of the data in the segment data section || length of the data in memory
|-
| BSS || N/A || Start address of the block in memory to be zeroed || N/A || Length of the block in memory to be zeroed
|-
| NAME || Offset of the segment in the SELF file || N/A || length of the data in the segment data section || N/A
|-
| NOTES || Offset of the segment in the SELF file || N/A || length of the data in the segment data section || N/A
|-
| ENTRY || N/A || Address where execution should start || N/A || N/A
|}

=== Segment Section ===

The data section immediately follows the final entry in the segment table. Each block of segment data is written sequentially in this section, with the start of each block aligned to a 32 bit boundary.
CODE and DATA sections may be compressed according to the LAR compression scheme, NAME and NOTES sections must be uncompressed.

== Typical Use ==

There are two usage models for the SELF. The first is the payload loader that wishes to determine the name of the payload for a graphical chooser. The following is the psuedo code for accomplishing this:

get_name(char *name) {
ptr = SELF_start;
struct self_header *header;

do {
header = (struct self_header *) ptr;

if (header->type == SELF_NAME) {
memcpy(name, SELF_start + header->offset, header->size);
return 0;
}

ptr += sizeof(*header);
} while(header->type != SELF_ENTRY);

return -1;
}

The second usage model is actually loading and running the code - this is accomplished in a stream fashion like so:

decompress_and_run(void) {
ptr = SELF_start;

while(1) {
header = (struct self_header *) ptr;
switch(header->type) {
case TYPE_CODE:
case TYPE_DATA:
dlen = decompress(SELF_start + header->offset, header->load_addr, header->len);
memset(header->load_addr + dlen, 0, header->mem_len - dlen);
break;
case BSS:
memset(header->load_addr, 0, header->len);
break;
case LOAD:
return jump_to(header->load_addr);
}

ptr += sizeof(*header);
}
}

== Changelog ==

* Chage ID of each segment to 4 text characters
* Each block of data needs to be 32 bit aligned
* Specified that all the segment header members are stored in little endian
* Changed the load address in the segment header structure to 64 bits.
* Clarified the compression of the code / data segments

SELF

2008-04-12T22:51:09Z

JCrouse: /* Description */ clarify compression

'''SELF''' stands for '''S'''imple '''E'''xecutable '''L'''oader '''F'''ormat. It is a very simple take on the standard [[http://en.wikipedia.org/wiki/Executable_and_Linkable_Format ELF]] executable format. It is proposed that SELF be the the standard format for payload code stored in a LAR file and loaded and executed by coreboot-v3. The [[bayou]] chooser will also load and run payloads in the SELF format.

== Description ==
Each SELF file is defined as a group of different segments. Each segment either loads data into memory, zeroes a section of memory, or provides information to coreboot or the payload. The segments can be one of the following types:

{| border="1"
|- bgcolor="#6699ff"
!ID
!Segment
!Description
|-
| 1 || CODE || This segment has executable code to be copied from the data section to memory (segment data may be compressed if specified by the LAR)
|-
| 2 || DATA || This segment has non-executable data to be copied from the data section into memory (segment data may be compressed if specified by the LAR)
|-
| 3 || BSS || This segment defines a section of memory to be zeroed. Nothing is copied into memory.
|-
| 4 || NAME || This segment contains a descriptive string in the data section that is used by the payload loader to identify the current payload. Nothing is copied into memory (segment data must '''not''' be compressed)
|-
| 5 || NOTES || This segment contains the contents of the .notes section in the data segment. This is for use by the payload loader. Nothing is copied into memory (segment data must '''not''' be compressed)
|-
| 6 || ENTRY || This segment defines the entry point for execution. This type signifies the end of the list of segments. It is mandatory and can only be used once.
|}

== Format ==

A SELF file is comprised of two parts: the segment table and the data section. Each is described below.

=== Segment Table ===

The segment table is located at the start of the ELF file, with one entry per segement. Each segment is identified by its type (as listed above). The structure of the header entry is as follows:

struct self_header {
unsigned long type;
unsigned long offset;
unsigned long load_addr;
unsigned long len;
unsigned long mem_len;
};

All fields are present in each segment entry, though not every field will be valid for every segment type. The following table lists which members are used and what they mean:

{| border="1"
|- bgcolor="#6699ff"
!Type
!offset
!load_addr
!len
!mem_len
|-
|CODE || Offset of the segment in the SELF file || address where the code should be copied in memory || length of the data in the segment data section || length of the data in memory
|-
| DATA || Offset of the segment in the SELF file || address where the code should be copied in memory || length of the data in the segment data section || length of the data in memory
|-
| BSS || N/A || Start address of the block in memory to be zeroed || N/A || Length of the block in memory to be zeroed
|-
| NAME || Offset of the segment in the SELF file || N/A || length of the data in the segment data section || N/A
|-
| NOTES || Offset of the segment in the SELF file || N/A || length of the data in the segment data section || N/A
|-
| ENTRY || N/A || Address where execution should start || N/A || N/A
|}

=== Segment Section ===

The data section immediately follows the final entry in the segment table. Each block of segment data is written sequentially in this section. CODE and DATA sections may be compressed, NAME and NOTES sections must be uncompressed.

== Typical Use ==

There are two usage models for the SELF. The first is the payload loader that wishes to determine the name of the payload for a graphical chooser. The following is the psuedo code for accomplishing this:

get_name(char *name) {
ptr = SELF_start;
struct self_header *header;

do {
header = (struct self_header *) ptr;

if (header->type == SELF_NAME) {
memcpy(name, SELF_start + header->offset, header->size);
return 0;
}

ptr += sizeof(*header);
} while(header->type != SELF_ENTRY);

return -1;
}

The second usage model is actually loading and running the code - this is accomplished in a stream fashion like so:

decompress_and_run(void) {
ptr = SELF_start;

while(1) {
header = (struct self_header *) ptr;
switch(header->type) {
case TYPE_CODE:
case TYPE_DATA:
dlen = decompress(SELF_start + header->offset, header->load_addr, header->len);
memset(header->load_addr + dlen, 0, header->mem_len - dlen);
break;
case BSS:
memset(header->load_addr, 0, header->len);
break;
case LOAD:
return jump_to(header->load_addr);
}

ptr += sizeof(*header);
}
}

SELF

2008-04-11T23:39:28Z

JCrouse: /* Segment Table */ Seesh, who wrote this thing?

'''SELF''' stands for '''S'''imple '''E'''xecutable '''L'''oader '''F'''ormat. It is a very simple take on the standard [[http://en.wikipedia.org/wiki/Executable_and_Linkable_Format ELF]] executable format. It is proposed that SELF be the the standard format for payload code stored in a LAR file and loaded and executed by coreboot-v3. The [[bayou]] chooser will also load and run payloads in the SELF format.

== Description ==
Each SELF file is defined as a group of different segments. Each segment either loads data into memory, zeros a section of memory, or provides information to coreboot or the payload. The segments can be one of the following types:

{| border="1"
|- bgcolor="#6699ff"
!ID
!Segment
!Description
|-
| 1 || CODE || This segment has executable code to be copied from the data section to memory (segement data may be compressed)
|-
| 2 || DATA || This segment has non-executable data to be copied from the data section into memory (sigment data may be compressed)
|-
| 3 || BSS || This segment has defines a section of memory to be zeroed. Noting is copied into memory.
|-
| 4 || NAME || This segment contains a descriptive string in the data section that is used by the pyaload loader to identify the current payload. Noting is copied into memory (segment data must '''not''' be compressed)
|-
| 5 || NOTES || This segment contains the contents of the .notes section in the data segment. This is for the use the payload loader. Nothing is copied into memory (segment data must '''not''' be compressed)
|-
| 6 || ENTRY || This segment defines the entry point for execution. This type signifies the end of the list of segments. It is mandatory and can only be used once.
|}

== Format ==

A SELF file is conprised of two parts: the segment table and the data section. Each is described below.

=== Segment Table ===

The segment table is located at the start of the ELF file, with one entry per segement. Each segment is identified by its type (as listed above). The structure of the header entry is as follows:

struct self_header {
unsigned long type;
unsigned long offset;
unsigned long load_addr;
unsigned long len;
unsigned long mem_len;
};

All fields are present in each segment entry, though not every field will be valid for every segment type. The following table lists which members are used and what they mean:

{| border="1"
|- bgcolor="#6699ff"
!Type
!offset
!load_addr
!len
!mem_len
|-
|CODE || Offset of the segment in the SELF file || address where the code should be copied in memory || length of the data in the segment data section || length of the data in memory
|-
| DATA || Offset of the segment in the SELF file || address where the code should be copied in memory || length of the data in the segment data section || length of the data in memory
|-
| BSS || N/A || Start address of the block in memory to be zeroed || N/A || Length of the block in memory to be zeroed
|-
| NAME || Offset of the segment in the SELF file || N/A || length of the data in the segment data section || N/A
|-
| NOTES || Offset of the segment in the SELF file || N/A || length of the data in the segment data section || N/A
|-
| ENTRY || N/A || Address where execution should start || N/A || N/A
|}

=== Segment Section ===

The data section immediately follows the final entry in the segment table. Each block of segment data is written sequentially in this section. CODE and DATA sections may be compressed, NAME and NOTES sections must be uncompressed.

== Typical Use ==

There are two usage models for the SELF. The first is the payload loader that wishes to determine the name of the payload for a graphical chooser. The following is the psuedo code for accomplishing this:

get_name(char *name) {
ptr = SELF_start;
struct self_header *header;

do {
header = (struct self_header *) ptr;

if (header->type == SELF_NAME) {
memcpy(name, SELF_start + header->offset, header->size);
return 0;
}

ptr += sizeof(*header);
} while(header->type != SELF_ENTRY);

return -1;
}

The second usage model is actually loading and running the code - this is accomplished in a stream fashion like so:

decompress_and_run(void) {
ptr = SELF_start;

while(1) {
header = (struct self_header *) ptr;
switch(header->type) {
case TYPE_CODE:
case TYPE_DATA:
dlen = decompress(SELF_start + header->offset, header->load_addr, header->len);
memset(header->load_addr + dlen, 0, header->mem_len - dlen);
break;
case BSS:
memset(header->load_addr, 0, header->len);
break;
case LOAD:
return jump_to(header->load_addr);
}

ptr += sizeof(*header);
}
}

SELF

2008-04-11T23:37:12Z

JCrouse: Fix link

'''SELF''' stands for '''S'''imple '''E'''xecutable '''L'''oader '''F'''ormat. It is a very simple take on the standard [[http://en.wikipedia.org/wiki/Executable_and_Linkable_Format ELF]] executable format. It is proposed that SELF be the the standard format for payload code stored in a LAR file and loaded and executed by coreboot-v3. The [[bayou]] chooser will also load and run payloads in the SELF format.

== Description ==
Each SELF file is defined as a group of different segments. Each segment either loads data into memory, zeros a section of memory, or provides information to coreboot or the payload. The segments can be one of the following types:

{| border="1"
|- bgcolor="#6699ff"
!ID
!Segment
!Description
|-
| 1 || CODE || This segment has executable code to be copied from the data section to memory (segement data may be compressed)
|-
| 2 || DATA || This segment has non-executable data to be copied from the data section into memory (sigment data may be compressed)
|-
| 3 || BSS || This segment has defines a section of memory to be zeroed. Noting is copied into memory.
|-
| 4 || NAME || This segment contains a descriptive string in the data section that is used by the pyaload loader to identify the current payload. Noting is copied into memory (segment data must '''not''' be compressed)
|-
| 5 || NOTES || This segment contains the contents of the .notes section in the data segment. This is for the use the payload loader. Nothing is copied into memory (segment data must '''not''' be compressed)
|-
| 6 || ENTRY || This segment defines the entry point for execution. This type signifies the end of the list of segments. It is mandatory and can only be used once.
|}

== Format ==

A SELF file is conprised of two parts: the segment table and the data section. Each is described below.

=== Segment Table ===

The segment table is located at the start of the ELF file, with one entry per segement. Each segment is identified by its type (as listed above). The structure of the header entry is as follows:

struct self_header {
unsigned long type;
unsigned long offset;
unsigned long load_addr;
unsigned long len;
unsigned long mem_len;
};

All fields are present in each segment entry, though not every field will be valid for every segment type. The following table lists which members are required for each type:

{| border="1"
|- bgcolor="#6699ff"
!Type
!offset
!load_addr
!len
!mem_len
|-
|CODE || Offset of the segment in the SELF file || address where the code should be copied in memory || length of the data in the segment data section || length of the data in memory
|-
| DATA || Offset of the segment in the SELF file || address where the code should be copied in memory || length of the data in the segment data section || length of the data in memory
|-
| BSS || N/A || Start address of the block in memory to be zeroed || N/A || Length of the block in memory to be zeroed
|-
| NAME || Offset of the segment in the SELF file || N/A || length of the data in the segment section || N/A
|-
| NOTES || Offset of the segment in the SELF file || N/A || length of the data in the segment section || N/A
|-
| ENTRY || N/A || Address where execution should start || N/A || N/A
|}

=== Segment Section ===

The data section immediately follows the final entry in the segment table. Each block of segment data is written sequentially in this section. CODE and DATA sections may be compressed, NAME and NOTES sections must be uncompressed.

== Typical Use ==

There are two usage models for the SELF. The first is the payload loader that wishes to determine the name of the payload for a graphical chooser. The following is the psuedo code for accomplishing this:

get_name(char *name) {
ptr = SELF_start;
struct self_header *header;

do {
header = (struct self_header *) ptr;

if (header->type == SELF_NAME) {
memcpy(name, SELF_start + header->offset, header->size);
return 0;
}

ptr += sizeof(*header);
} while(header->type != SELF_ENTRY);

return -1;
}

The second usage model is actually loading and running the code - this is accomplished in a stream fashion like so:

decompress_and_run(void) {
ptr = SELF_start;

while(1) {
header = (struct self_header *) ptr;
switch(header->type) {
case TYPE_CODE:
case TYPE_DATA:
dlen = decompress(SELF_start + header->offset, header->load_addr, header->len);
memset(header->load_addr + dlen, 0, header->mem_len - dlen);
break;
case BSS:
memset(header->load_addr, 0, header->len);
break;
case LOAD:
return jump_to(header->load_addr);
}

ptr += sizeof(*header);
}
}

SELF

2008-04-11T22:21:06Z

JCrouse: Go with the initial description of SELF

'''SELF''' stands for '''S'''imple '''E'''xecutable '''L'''oader '''F'''ormat. It is a very simple take on an standard [[http://en.wikipedia.org/wiki/Executable_and_Linkable_Format|ELF]] executable format. It is proposed that SELF be the the standard format for payload code stored in a LAR file and loaded and executed by coreboot-v3. The [[bayou]] chooser will also load and run payloads in the SELF format.

== Description ==
Each SELF file is defined as a group of different segments. Each segment either loads data into memory, zeros a section of memory, or provides information to coreboot or the payload. The segments can be one of the following types:

{| border="1"
|- bgcolor="#6699ff"
!ID
!Segment
!Description
|-
| 1 || CODE || This segment has executable code to be copied from the data section to memory (segement data may be compressed)
|-
| 2 || DATA || This segment has non-executable data to be copied from the data section into memory (sigment data may be compressed)
|-
| 3 || BSS || This segment has defines a section of memory to be zeroed. Noting is copied into memory.
|-
| 4 || NAME || This segment contains a descriptive string in the data section that is used by the pyaload loader to identify the current payload. Noting is copied into memory (segment data must '''not''' be compressed)
|-
| 5 || NOTES || This segment contains the contents of the .notes section in the data segment. This is for the use the payload loader. Nothing is copied into memory (segment data must '''not''' be compressed)
|-
| 6 || ENTRY || This segment defines the entry point for execution. This type signifies the end of the list of segments. It is mandatory and can only be used once.
|}

== Format ==

A SELF file is conprised of two parts: the segment table and the data section. Each is described below.

=== Segment Table ===

The segment table is located at the start of the ELF file, with one entry per segement. Each segment is identified by its type (as listed above). The structure of the header entry is as follows:

struct self_header {
unsigned long type;
unsigned long offset;
unsigned long load_addr;
unsigned long len;
unsigned long mem_len;
};

All fields are present in each segment entry, though not every field will be valid for every segment type. The following table lists which members are required for each type:

{| border="1"
|- bgcolor="#6699ff"
!Type
!offset
!load_addr
!len
!mem_len
|-
|CODE || Offset of the segment in the SELF file || address where the code should be copied in memory || length of the data in the segment data section || length of the data in memory
|-
| DATA || Offset of the segment in the SELF file || address where the code should be copied in memory || length of the data in the segment data section || length of the data in memory
|-
| BSS || N/A || Start address of the block in memory to be zeroed || N/A || Length of the block in memory to be zeroed
|-
| NAME || Offset of the segment in the SELF file || N/A || length of the data in the segment section || N/A
|-
| NOTES || Offset of the segment in the SELF file || N/A || length of the data in the segment section || N/A
|-
| ENTRY || N/A || Address where execution should start || N/A || N/A
|}

=== Segment Section ===

The data section immediately follows the final entry in the segment table. Each block of segment data is written sequentially in this section. CODE and DATA sections may be compressed, NAME and NOTES sections must be uncompressed.

== Typical Use ==

There are two usage models for the SELF. The first is the payload loader that wishes to determine the name of the payload for a graphical chooser. The following is the psuedo code for accomplishing this:

get_name(char *name) {
ptr = SELF_start;
struct self_header *header;

do {
header = (struct self_header *) ptr;

if (header->type == SELF_NAME) {
memcpy(name, SELF_start + header->offset, header->size);
return 0;
}

ptr += sizeof(*header);
} while(header->type != SELF_ENTRY);

return -1;
}

The second usage model is actually loading and running the code - this is accomplished in a stream fashion like so:

decompress_and_run(void) {
ptr = SELF_start;

while(1) {
header = (struct self_header *) ptr;
switch(header->type) {
case TYPE_CODE:
case TYPE_DATA:
dlen = decompress(SELF_start + header->offset, header->load_addr, header->len);
memset(header->load_addr + dlen, 0, header->mem_len - dlen);
break;
case BSS:
memset(header->load_addr, 0, header->len);
break;
case LOAD:
return jump_to(header->load_addr);
}

ptr += sizeof(*header);
}
}

Bayou

2008-04-11T21:21:54Z

JCrouse: Initial architecture document for bayou

Coreboot Symposium 2008

2008-03-27T20:02:55Z

JCrouse: Update what I'm bringing and fix typos

== Agenda ==

general: breaks at 10-10:30, 12-1, 3-3:30

=== Thursday ===

{| border="0" style="font-size: smaller" valign="top"
|- bgcolor="#6699dd"
! align="left" | Time
! align="left" | Speaker
! align="left" | Topic

|- bgcolor="#eeeeee" valign="top"
| 1:00-2:00
| Ron Minnich
| Opening of the meeting and discussion of the last year

|- bgcolor="#dddddd" valign="top"
| 2:00-3:00
| Stefan Reinauer
| Automated Testbed, GSoC 2007, 2008

|- bgcolor="#eeeeee" valign="top"
| 3:00-3:30
|
| break

|- bgcolor="#dddddd" valign="top"
| 3:30-4:00
| Stefan Reinauer
| coresystems' various BIOS customers, recent ports and other related work

|- bgcolor="#eeeeee" valign="top"
| 4:00-end
|
| hack session -- set up boards and prioritize the goals of the rest of the time

|}

=== Friday ===

{| border="0" style="font-size: smaller" valign="top"
|- bgcolor="#6699dd"
! align="left" | Time
! align="left" | Speaker
! align="left" | Topic

|- bgcolor="#eeeeee" valign="top"
| 8:30-10:00
| Marc Jones (AMD)
| AMD talks about whatever they want :-)
- consumer issues

- what's going on

- new ports this year

- K10?

|- bgcolor="#dddddd" valign="top"
| 10:00-10:30
|
| break

|- bgcolor="#eeeeee" valign="top"
| 10:30-12:00
| Marc Karasek (Sun)
| Marc talks about his work at Sun with SimNow

|- bgcolor="#dddddd" valign="top"
| 12:00-1:00
|
| Lunch

|- bgcolor="#eeeeee" valign="top"
| 1:00-3:00
| Ron Minnich
| Ron gives an overview of v3, from the smallest to the large bits.
Sample build/burn session

|- bgcolor="#dddddd" valign="top"
| 3:00-3:30
|
| break

|- bgcolor="#eeeeee" valign="top"
| 3:30-4:00
|
| open questions (please add some)
1. how do we tell when a board is good enough to move from v2 to v3?

What's the test?

2. What pending issues are there?

|- bgcolor="#dddddd" valign="top"
| 4:00-5:00
| Ward Vandewege
| The view from the FSF -- what's going on, etc.

|}

=== Saturday ===

* hack all day. We hope to fix the problems we prioritized Thursday.

== What needs to be brought ==

* monitor
* power supplies

== Who is bringing what ==

'''Ron:''' dbe61 and dbe62. Alix 1C. Alix LPC pod. Artec LPC pod. T23 with ubuntu. OLPC devel board for v3 test. (No OLPC, it's too distracting). Outlet strips. FS2 if it arrives from LANL on time (it may not). USB hubs?
What else?

'''Ward:''' alix2c3, Artec LPC dongle. I can bring an alix.1c too but Ron's already bringing one.

'''Stefan:''' Advantech PCM-5820, possibly other boards, Artec LPC Dongle, ByteBlaster II (if it arrives in time), other JTAG cables on Request, Galep-5 Flash Writer, Flash Plaice(?)

'''Jordan:''' Norwich, FS2, ROM emulator, monitor, PS/2 keyboard, serial cable, laptop and lots of code.

AMD SimNow

2007-12-13T18:44:24Z

JCrouse: /* Serial Port Configuration */ Add information about snserial

These are the steps I use to download, install, and use the AMD SimNow simulator.
You may not want to do exactly what I did, but it should get you started.
There is PDF documentation that you can download on the same page as the simulator.
== Build a ROM image for SimNow (Skip this step if you have your own Bios you want to use)==
# install Intel's ASL iasl tool
# ''svn co svn://linuxbios.org/buildrom/''
# ''cd buildrom/buildrom-devel/''
# ''make menuconfig''
## Choose Platform Configuration
### Vendor AMD
### Platform Target AMD Serengeti-Cheetah
### Select Build for SimNow emulator
## Choose Payload Configuration
### Desired Payload Linux-As-Bootloader
### Desired Target Architecture 64-bit
### LAB Configuration
#### Select Busybox but not reduced-size kexec tools
## Save and Exit
# ''make''
# Enjoy your amd_serengeti_cheetah.rom file
== Download SimNow ==
# Download SimNow from [http://developer.amd.com/simnow.jsp AMD's website]
## Create an account
## Accept the license agreement
## Log in.
#Untar the .tar.gz file you download in a convenient place (You'll now have a directory called simnow-linux64-4.4.1pub)

== Run SimNow ==
#Run ''./simnow'' from the simnow-linux64-4.4.1pub directory
#Inside the SimNow Main Window do File->Open BSD, browse to the simnow-linux64-4.4.1pub/bsds directory and load either cheetah_1p.bsd or cheetah_1pjh.bsd (jh is dual-core)<pre><nowiki>Now you have a single Opteron socket motherboard with an AMD-8132 PCI-X controller, an AMD-8111 I/O hub, and a Winbond W83627HF SuperIO.</nowiki></pre>
#Copy your LinuxBIOS ROM image to simnow-linux64-4.4.1pub/Images for convenience.
#Open the SimNow Device Window (View->Show Devices)
#Double click on Memory Device #5 (Your BIOS chip)
#Click on the Memory Configuration Tab, and change the Base Address, Size, and File (I use Base Address = fff00000 and Size = 32 because I use a 1 MB image)
#Go to the main simulator window and hit Run Simulation (Play button)
##You will get this error:
<pre><nowiki>"BIOS ROM file is the wrong size for this BSD. Please either point the memdevice to the correct BIOS ROM file, or configure the memdevice to be the correct size." </nowiki></pre>
Repeat the last few steps to set the size and try again. This happens whenever you increase the BIOS size.
== Serial Port Configuration ==
In order to see the console output, go to the terminal you are running ./simnow in. Hit enter. You'll see a simnow> prompt.
# Type ''serial.SetCommPort pipe'' and hit enter.
# Type ''serial.GetCommPort'' and hit enter.
On my machine this returns
path (/home/myles/.simnow/com1), mode (PIPE)

Open a new terminal and type cat /home/myles/.simnow/com1/simnow_out
If you need to send input to the serial port, echo to /home/myles/.simnow/com1/simnow_in

=== Using the snserial tool ===

Alternatively, you can use a tool called 'snserial' to interact with the serial ports. snserial will combine the input and output, and provide access to the combined stream through either a psuedo tty, or a telenet port.

# Download the snserial tool from http://linuxbios.org/~jcrouse/snserial-1.0.tar.gz.
# Extract it: ''tar -zxvf snserial-1.0.tar.gz''
# Build it: ''cd snserial/; make''

Before running the tool, make sure that you have enabled the serial pipes as detailed above.

To enable serial through a pseudo TTY, start your simulation and type ''./snserial comX'' in another Linux terminal window (where X is 1 or 2). The program will respond with:

SimNow Serial pipe Muxer

Connection established.
Type 'target remote /dev/pts/2' in GDB to connect.
(Press CTRL-C to exit)

You can now connect your serial application (minicom, or GDB for debugging) to the specified pseudo-tty.

To enable serial interaction through telnet, start the simulation and type ''./snserial -t comX''. The program will respond with:

SimNow Serial pipe Muxer

COM 1: Listening on port 9000
(Press CTRL-C to exit)

You can now connect to the serial stream by typing 'telnet localhost 9000' in a Linux terminal window.

'''Note:''' It is a quirk of SimNow that the pipes are not created until the simulation for the BSD is started for the first time. Make sure you start the simulation before running ''snserial'', otherwise you will see this: ''Couldn't stat /home/<user>/.simnow/com1/simnow_out: No such file or directory.'' The best course of action is to start the simulation quickly, attach the snserial program, and then restart the simulation to see the early serial output.

== Add disks ==
#Hit the Stop Simulation button if the simulation is running
##File->Set IDE Primary Master Image
###Browse to your hard drive image
##File->Set IDE Secondary Master Image
###Browse to a CD .iso
#Hit Run Simulation again

You should get output from the serial port scrolling in one terminal, and be able to watch the VGA output in the main window.

If you used buildrom to get a BIOS image with LinuxBIOS + LAB, you'll end up at a linux prompt where you can mount the disks, etc.

{{Cc-by-sa-3.0}}

Buildrom

2007-10-23T22:28:27Z

JCrouse: Fixup the page

'''BuildROM''' is a tool that can construct a LinuxBIOS image (comprising the LinuxBIOS loader and payload) from scratch. Starting from a configuration file, it will download and build all the code necessary to construct the final binary.

A tool with similar functionality is [[Etherboot]]'s [http://rom-o-matic.net/ ROM-o-matic] which builds etherboot as a LinuxBIOS ELF payload.

== Supported Platforms ==

Buildrom supports the following platforms:

* AMD Geode LX 'Norwich'
* Artec Group dbe61
* PC Engines ALIX1.C
* Digital Logic msm800sev
* AMD DB800
* Gigabyte 57SLI
* Tyan S2891
* AMD "Serengeti Cheetah"

== Supported Payloads ==

Buildrom supports the following payloads:

* Linux kernel
* [[Etherboot]]
* [[FILO]]
* "Linux-as-bootloader"
* Memtest86+ (except the M57SLI and the TYAN S891)

== Download ==

$ svn co svn://linuxbios.org/buildrom

== Prerequisites ==
You will need the following packages on your system to use buildrom. Please consult your distribution documentation on how to install new packages:

* subversion
* make
* quilt
* GNU compiler tools (as, ld, gcc)
* iasl (for AMD K8 platforms)

== Configuration ==

In the buildrom-devel directory, type:
$ make menuconfig

You can now navigate the configuration system (this is the same configuration engine that the Linux kernel uses, so it should be familiar to some readers).

== Building the ROM ==

Make sure you have access to the internet (to download new packages), and type the following to create your ROM:
$ make

Buildrom will download and build all the components of the ROM selected in the configuration stage. if the build is successful, then the final ROM will be located in ''buildrom-devel/deploy''. If it is not successful, then you will see an error message. You can see the build output for each package in by reading build.log in the work/<package>logs/ directory (i.e work/filo/logs/build.log).

== Developing within buildROM ==

This section is for the developers who wish to change and rebuild the code. BuildROM builds the code for LinuxBIOS and the payloads in the work/ directory. Here is a typical view of the buildROM work/ directory:
$ ls work/
linuxbios filo

In each directory, you will find three directories. Logs from the build will be found in logs/ and timestamps that the build system uses are in stamps/. You normally won't have to touch these directories. The source code is located in the third directory. BuildROM provides several commands to make it easy to rebuild individual packages and ROMs. To clean a directory (but not remove the source code) use 'make <package>-clean'. You can build an individual packages with 'make <package>'. f you wish to completely erase the source code and start again with a pristine version, use 'make <package>-distclean'. Typing 'make' at any time will rebuild the ROM using the most current versions of the individual packages.
Here is a typical work flow for modifying LinuxBIOS code:

#Build the initial ROM from scratch with 'make'
#Edit the LinuxBIOS source code in work/linuxbios/svn/
#Clean the linuxbios package with 'make linuxbios-clean'
#Rebuild the ROM with 'make'