Libpayload: Difference between revisions

From coreboot
Jump to navigation Jump to search
m (Fixed downloading from Subversion to Git)
 
(23 intermediate revisions by 6 users not shown)
Line 1: Line 1:
'''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.
'''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]].
 
== Overview ==


The benefits of linking a coreboot payload against libpayload are:
The benefits of linking a coreboot payload against libpayload are:
Line 11: Line 9:


''Just give us a main() and a pocket full of dreams and we'll do the rest.''
''Just give us a main() and a pocket full of dreams and we'll do the rest.''
== Download ==
  $ svn co svn://coreboot.org/repos/trunk/payloads/libpayload


== Features ==
== Features ==


* Provides a [[Libpayload#Libc_Coverage|subset of libc functions]] (e.g. malloc, printf, strcmp, etc).
* Provides a [[Libpayload#Libc_coverage|subset of libc functions]] (e.g. malloc, printf, strcmp, etc).
* Provides an optional tiny (n)curses implementation.
* Provides an optional tiny (n)curses implementation.
* Provides various small drivers for
* Provides various small drivers for
Line 27: Line 21:
** VGA
** VGA
** Geode framebuffer
** Geode framebuffer
** USB stack
* Reads and parses the coreboot table.
* Reads and parses the coreboot table.
== Design ==
* [[Payload API|Discussion of the API for passing parameters to the payload]]


== Payloads using libpayload ==
== 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.
* [[FILO]] is a bootloader which loads boot images from a local filesystem, without help from legacy BIOS services.
* [[invaders|GRUB invaders]] has been ported successfully to libpayload (patch pending).
* [[coreinfo]] is a small payload which can display system information such as PCI info, or an NVRAM dump.
* [http://oasis.frogfoot.net/code/tint/download/0.03b/ tint] (a console tetris clone) is currently being ported to libpayload (patch pending).
* [[GRUB invaders]] has been ported successfully to libpayload (patch pending).
* [[tint]] (a "falling blocks" game) 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).
* [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).


== Libc Coverage ==
== Downloading and building libpayload ==
 
It is now in main coreboot git tree (see [[Download_coreboot]] for additional reference)
 
$ '''git clone http://review.coreboot.org/p/coreboot'''
$ '''cd payloads/libpayload'''
$ '''make menuconfig'''
$ '''make install'''
 
Here [http://review.coreboot.org/#/q/status:open+project:coreboot+message:libpayload,n,z gerrit] you can find pending patches for libpayload
 
== Documentation ==
 
See the autogenerated documentation for libpayload [http://qa.coreboot.org/docs/libpayload/ here].


{| border="0"  
== Libc coverage ==
 
{| border="0" valign="top"
| valign="top"|
 
{| border="0" style="font-size: smaller"
|- bgcolor="#6699ff"  
|- bgcolor="#6699ff"  
! align="left" | Status
! align="left" | Status
Line 46: Line 64:
| colspan=2 | '''assert.h'''
| colspan=2 | '''assert.h'''
|-  
|-  
| style="background:red" | no
|- bgcolor="#eeeeee" valign="top"
| <code>assert( )</code> (macro)
| style="background:lime" | no
| assert()


|- bgcolor="#6699ff"
|- bgcolor="#6699ff"
| colspan=2 | '''ctype.h'''
| colspan=2 | '''ctype.h'''
|-  
|-  
| style="background:red" | no
|- bgcolor="#eeeeee" valign="top"
| <code>int isalnum(int character)</code>
| style="background:lime" | yes
| int isalnum(int character)
|-
|- bgcolor="#dddddd" valign="top"
| style="background:lime" | yes
| int isalpha(int character)
|-
|- bgcolor="#dddddd" valign="top"
| style="background:lime" | yes
| int isascii(int character)
|-
|- bgcolor="#dddddd" valign="top"
| style="background:lime" | yes
| int isblanc(int character)
|-
|- bgcolor="#eeeeee" valign="top"
| style="background:lime" | yes
| int iscntrl(int character)
|-  
|-  
| style="background:red" | no
|- bgcolor="#dddddd" valign="top"
| <code>int isalpha(int character)</code>
| style="background:lime" | yes
| int isdigit(int character)
|-  
|-  
| style="background:red" | no
|- bgcolor="#eeeeee" valign="top"
| <code>int iscntrl(int character)</code>
| style="background:lime" | yes
| int isgraph(int character)
|-  
|-  
|- bgcolor="#dddddd" valign="top"
| style="background:lime" | yes
| style="background:lime" | yes
| <code>int isdigit(int character)</code>
| int islower(int character)
|-  
|-  
| style="background:red" | no
|- bgcolor="#eeeeee" valign="top"
| <code>int isgraph(int character)</code>
| style="background:lime" | yes
| int isprint(int character)
|-  
|-  
| style="background:red" | no
|- bgcolor="#dddddd" valign="top"
| <code>int islower(int character)</code>
| style="background:lime" | yes
| int ispunct(int character)
|-  
|-  
| style="background:red" | no
|- bgcolor="#eeeeee" valign="top"
| <code>int isprint(int character)</code>
| style="background:lime" | yes
| int isspace(int character)
|-  
|-  
| style="background:red" | no
|- bgcolor="#dddddd" valign="top"
| <code>int ispunct(int character)</code>
| style="background:lime" | yes
| int isupper(int character)
|-  
|-  
|- bgcolor="#eeeeee" valign="top"
| style="background:lime" | yes
| style="background:lime" | yes
| <code>int isspace(int character)</code>
| int isxdigit(int character)
|-  
|-  
| style="background:red" | no
|- bgcolor="#eeeeee" valign="top"
| <code>int isupper(int character)</code>
| style="background:lime" | yes
| int tolower(int character)
|-  
|-  
| style="background:red" | no
|- bgcolor="#eeeeee" valign="top"
| <code>int isxdigit(int character)</code>
| style="background:lime" | yes
| int toupper(int character)


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


Line 247: Line 293:
| <code>int fprintf(FILE* stream, const char* format, ...)</code>
| <code>int fprintf(FILE* stream, const char* format, ...)</code>
|-  
|-  
| style="background:yellow" | partial
| style="background:lime" | yes
| <code>int printf(const char* format, ...)</code>
| <code>int printf(const char* format, ...)</code>
|-  
|-  
| style="background:yellow" | partial
| style="background:lime" | yes
| <code>int sprintf(char* s, const char* format, ...)</code>
| <code>int sprintf(char* s, const char* format, ...)</code>
|-
| style="background:lime" | yes
| <code>int snprintf(char* s, size_t size, const char* format, ...)</code>
|-  
|-  
| style="background:red" | no
| style="background:red" | no
| <code>int vfprintf(FILE* stream, const char* format, va_list arg)</code>
| <code>int vfprintf(FILE* stream, const char* format, va_list arg)</code>
|-  
|-  
| style="background:yellow" | partial
| style="background:lime" | yes
| <code>int vprintf(const char* format, va_list arg)</code>
| <code>int vprintf(const char* format, va_list arg)</code>
|-  
|-  
| style="background:yellow" | partial
| style="background:lime" | yes
| <code>int vsprintf(char* s, const char* format, va_list arg)</code>
| <code>int vsprintf(char* s, const char* format, va_list arg)</code>
|-
| style="background:lime" | yes
| <code>int vsnprintf(char* s, size_t size, const char* format, va_list arg)</code>
|-  
|-  
| style="background:red" | no
| style="background:red" | no
Line 336: Line 388:
| style="background:red" | no
| style="background:red" | no
| <code>void perror(const char* s)</code>
| <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"
|- bgcolor="#6699ff"
| colspan=2 | '''stdlib.h'''
| colspan=2 | '''stdlib.h'''
|-  
|-  
| style="background:red" | no
| style="background:lime" | yes
| <code>int abs(int n)</code>
| <code>int abs(int n)</code>
|-  
|-  
| style="background:red" | no
| style="background:lime" | yes
| <code>long labs(long n)</code>
| <code>long labs(long n)</code>
|-
| style="background:lime" | yes
| <code>long long llabs(long long n)</code>
|-  
|-  
| style="background:red" | no
| style="background:red" | no
Line 364: Line 428:
| <code>double strtod(const char* s, char** endp)</code>
| <code>double strtod(const char* s, char** endp)</code>
|-  
|-  
| style="background:red" | no
| style="background:lime" | no
| <code>long strtol(const char* s, char** endp, int base)</code>
| <code>long strtol(const char* s, char** endp, int base)</code>
|-  
|-  
| style="background:red" | no
| style="background:lime" | yes
| <code>unsigned long strtoul(const char* s, char** endp, int base)</code>
| <code>unsigned long strtoul(const char* s, char** endp, int base)</code>
|-  
|-  
Line 382: Line 446:
| <code>void free(void* p)</code>
| <code>void free(void* p)</code>
|-  
|-  
| style="background:lime" | yes as <code>halt()</code>
| style="background:lime" | yes
| <code>void * memalign (size_t align, size_t size)</code>
|-
| style="background:lime" | yes
| <code>void abort()</code>
| <code>void abort()</code>
|-  
|-  
| style="background:red" | no
| style="background:lime" | no
| <code>void exit(int status)</code>
| <code>void exit(int status)</code>
|-  
|-  
Line 398: Line 465:
|-  
|-  
| style="background:red" | no
| 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>
| <code>void* bsearch(const void* key, const void* base, size_t n,<br />size_t size, int (*cmp)(const void* keyval, const void* datum))</code>
|-  
|-  
| style="background:red" | no
| style="background:red" | no
| <code>void qsort(void* base, size_t n, size_t size, int (*cmp)(const void*, const void*))</code>
| <code>void qsort(void* base, size_t n, size_t size, <br />int (*cmp)(const void*, const void*))</code>
|-  
|-  
| style="background:red" | no
| style="background:lime" | yes
| <code>int rand(void)</code>
| <code>int rand(void)</code>
|-  
|-  
| style="background:red" | no
| style="background:lime" | yes
| <code>void srand(unsigned int seed)</code>
| <code>void srand(unsigned int seed)</code>


Line 418: Line 485:
| <code>char* strncpy(char* s, const char* ct, size_t n)</code>
| <code>char* strncpy(char* s, const char* ct, size_t n)</code>
|-  
|-  
| style="background:red" | no
| style="background:lime" | no
| <code>char* strcat(char* s, const char* ct)</code>
| <code>char* strcat(char* s, const char* ct)</code>
|-  
|-  
Line 436: Line 503:
| <code>char* strchr(const char* cs, int c)</code>
| <code>char* strchr(const char* cs, int c)</code>
|-  
|-  
| style="background:red" | no
| style="background:lime" | no
| <code>char* strrchr(const char* cs, int c)</code>
| <code>char* strrchr(const char* cs, int c)</code>
|-  
|-  
| style="background:red" | no
| style="background:lime" | no
| <code>size_t strspn(const char* cs, const char* ct)</code>
| <code>size_t strspn(const char* cs, const char* ct)</code>
|-  
|-  
| style="background:red" | no
| style="background:lime" | no
| <code>size_t strcspn(const char* cs, const char* ct)</code>
| <code>size_t strcspn(const char* cs, const char* ct)</code>
|-  
|-  
Line 453: Line 520:
| style="background:lime" | yes
| style="background:lime" | yes
| <code>size_t strlen(const char* cs)</code>
| <code>size_t strlen(const char* cs)</code>
|-
| style="background:lime" | yes
| <code>size_t strnlen(const char* cs, size_t maxlen)</code>
|-
| style="background:lime" | yes
| <code>char * strdup (const char *s)</code>
|-  
|-  
| style="background:red" | no
| style="background:red" | no
| <code>char* strerror(int n)</code>
| <code>char* strerror(int n)</code>
|-  
|-  
| style="background:red" | no
| style="background:lime" | no
| <code>char* strtok(char* s, const char* t)</code>
| <code>char* strtok(char* s, const char* t)</code>
|-
| style="background:lime" | no
| <code>char* strtok_r(char* s, const char* t, char **p)</code>
|-  
|-  
| style="background:red" | no
| style="background:red" | no
Line 483: Line 559:
| style="background:red" | no
| style="background:red" | no
| <code>clock_t clock(void)</code>
| <code>clock_t clock(void)</code>
|-
| style="background:lime" | yes
| <code>int gettimeofday (struct timeval *tv, void *tz)</code>
|-  
|-  
| style="background:red" | no
| style="background:red" | no
Line 506: Line 585:
|-  
|-  
| style="background:red" | no
| style="background:red" | no
| <code>size_t strftime(char* s, size_t smax, const char* fmt, const struct tm* tp)</code>
| <code>size_t strftime(char* s, size_t smax, const char* fmt,<br />const struct tm* tp)</code>
 
|- bgcolor="#6699ff"
| colspan=2 | '''unistd.h'''
|-
| style="background:lime" | yes
| <code>int exec (long addr, int argc, char **argv)</code>


|}
|}
{| border="1"
|- bgcolor="red"
| No Support
|- bgcolor="yellow"
| Partial Support
|- bgcolor="lime"
| Full Support
|}
|}


== Usage Example ==
== Usage example ==


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


<pre>
<source lang="C">
#include <libpayload.h>
#include <libpayload.h>


Line 533: Line 609:
     return 0;
     return 0;
}
}
</pre>
</source>


Build example:
Building the payload:


  lpgcc -o hello.elf hello.c
  $ '''lpgcc -o hello.elf hello.c'''




{{PD-self}}
{{PD-self}}

Latest revision as of 10:23, 1 June 2012

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 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
    • USB stack
  • Reads and parses the coreboot table.

Design

Payloads using libpayload

  • FILO is a bootloader which loads boot images from a local filesystem, without help from legacy BIOS services.
  • coreinfo is a small payload which can display system information such as PCI info, or an NVRAM dump.
  • GRUB invaders has been ported successfully to libpayload (patch pending).
  • tint (a "falling blocks" game) has been successfully ported to libpayload.
  • lxdialog from the Linux kconfig utility has been ported to be usable when linked with libpayload (patch pending).

Downloading and building libpayload

It is now in main coreboot git tree (see Download_coreboot for additional reference)

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

Here gerrit you can find pending patches for libpayload

Documentation

See the autogenerated documentation for libpayload here.

Libc coverage

Status Function/Macro/Variable
assert.h
no assert()
ctype.h
yes int isalnum(int character)
yes int isalpha(int character)
yes int isascii(int character)
yes int isblanc(int character)
yes int iscntrl(int character)
yes int isdigit(int character)
yes int isgraph(int character)
yes int islower(int character)
yes int isprint(int character)
yes int ispunct(int character)
yes int isspace(int character)
yes int isupper(int character)
yes int isxdigit(int character)
yes int tolower(int character)
yes int toupper(int character)
errno.h
no errno (global)
float.h
limits.h
locale.h
no char *setlocale(int category, const char *locale)
no struct lconv *localeconv(void)
math.h
no double exp(double x)
no double log(double x)
no double log10(double x)
no double pow(double x, double y)
no double sqrt(double x)
no double ceil(double x)
no double floor(double x)
no double fabs(double x)
no double ldexp(double x, int n)
no double frexp(double x, int* exp)
no double modf(double x, double* ip)
no double fmod(double x, double y)
no double sin(double x)
no double cos(double x)
no double tan(double x)
no double asin(double x)
no double acos(double x)
no double atan(double x)
no double atan2(double y, double x)
no double sinh(double x)
no double cosh(double x)
no double tanh(double x)
setjmp.h
no int setjmp(jmp_buf env)
no void longjmp(jmp_buf env, int val)
signal.h
no void (*signal(int sig, void (*handler)(int)))(int)
no int raise(int sig)
stdarg.h
no void va_start(va_list ap, lastarg)
no type va_arg(va_list ap, type)
no void va_end(va_list ap)
stddef.h
TODO
stdio.h
no FILE* fopen(const char* filename, const char* mode)
no FILE* freopen(const char* filename, const char* mode, FILE* stream)
no int fflush(FILE* stream)
no int fclose(FILE* stream)
no int remove(const char* filename)
no int rename(const char* oldname, const char* newname)
no FILE* tmpfile()
no char* tmpnam(char s[L_tmpnam])
no int setvbuf(FILE* stream, char* buf, int mode, size_t size)
no void setbuf(FILE* stream, char* buf)
no int fprintf(FILE* stream, const char* format, ...)
yes int printf(const char* format, ...)
yes int sprintf(char* s, const char* format, ...)
yes int snprintf(char* s, size_t size, const char* format, ...)
no int vfprintf(FILE* stream, const char* format, va_list arg)
yes int vprintf(const char* format, va_list arg)
yes int vsprintf(char* s, const char* format, va_list arg)
yes int vsnprintf(char* s, size_t size, const char* format, va_list arg)
no int fscanf(FILE* stream, const char* format, ...)
no int scanf(const char* format, ...)
no int sscanf(char* s, const char* format, ...)
no int fgetc(FILE* stream)
no char* fgets(char* s, int n, FILE* stream)
no int fputc(int c, FILE* stream)
no char* fputs(const char* s, FILE* stream)
no int getc(FILE* stream)
yes int getchar(void)
no char* gets(char* s)
no int putc(int c, FILE* stream)
yes int putchar(int c)
yes int puts(const char* s)
no int ungetc(int c, FILE* stream)
no size_t fread(void* ptr, size_t size, size_t nobj, FILE* stream)
no size_t fwrite(const void* ptr, size_t size, size_t nobj, FILE* stream)
no int fseek(FILE* stream, long offset, int origin)
no long ftell(FILE* stream)
no void rewind(FILE* stream)
no int fgetpos(FILE* stream, fpos_t* ptr)
no int fsetpos(FILE* stream, const fpos_t* ptr)
no void clearerr(FILE* stream)
no int feof(FILE* stream)
no int ferror(FILE* stream)
no void perror(const char* s)
Status Function/Macro/Variable
stdlib.h
yes int abs(int n)
yes long labs(long n)
yes long long llabs(long long n)
no div_t div(int num, int denom)
no ldiv_t ldiv(long num, long denom)
no double atof(const char* s)
no int atoi(const char* s)
no long atol(const char* s)
no double strtod(const char* s, char** endp)
no long strtol(const char* s, char** endp, int base)
yes unsigned long strtoul(const char* s, char** endp, int base)
yes void* calloc(size_t nobj, size_t size)
yes void* malloc(size_t size)
yes void* realloc(void* p, size_t size)
yes void free(void* p)
yes void * memalign (size_t align, size_t size)
yes void abort()
no void exit(int status)
no int atexit(void (*fcm)(void))
no int system(const char* s)
no char* getenv(const char* name)
no void* bsearch(const void* key, const void* base, size_t n,
size_t size, int (*cmp)(const void* keyval, const void* datum))
no void qsort(void* base, size_t n, size_t size,
int (*cmp)(const void*, const void*))
yes int rand(void)
yes void srand(unsigned int seed)
string.h
yes char* strcpy(char* s, const char* ct)
yes char* strncpy(char* s, const char* ct, size_t n)
no char* strcat(char* s, const char* ct)
yes char* strncat(char* s, const char* ct, size_t n)
yes int strcmp(const char* cs, const char* ct)
yes int strncmp(const char* cs, const char* ct, size_t n)
no int strcoll(const char* cs, const char* ct)
yes char* strchr(const char* cs, int c)
no char* strrchr(const char* cs, int c)
no size_t strspn(const char* cs, const char* ct)
no size_t strcspn(const char* cs, const char* ct)
no char* strpbrk(const char* cs, const char* ct)
yes char* strstr(const char* cs, const char* ct)
yes size_t strlen(const char* cs)
yes size_t strnlen(const char* cs, size_t maxlen)
yes char * strdup (const char *s)
no char* strerror(int n)
no char* strtok(char* s, const char* t)
no char* strtok_r(char* s, const char* t, char **p)
no size_t strxfrm(char* s, const char* ct, size_t n)
yes void* memcpy(void* s, const void* ct, size_t n)
yes void* memmove(void* s, const void* ct, size_t n)
yes int memcmp(const void* cs, const void* ct, size_t n)
no void* memchr(const void* cs, int c, size_t n)
yes void* memset(void* s, int c, size_t n)
time.h
no clock_t clock(void)
yes int gettimeofday (struct timeval *tv, void *tz)
no time_t time(time_t* tp)
no double difftime(time_t time2, time_t time1)
no time_t mktime(struct tm* tp)
no char* asctime(const struct tm* tp)
no char* ctime(const time_t* tp)
no struct tm* gmtime(const time_t* tp)
no struct tm* localtime(const time_t* tp)
no size_t strftime(char* s, size_t smax, const char* fmt,
const struct tm* tp)
unistd.h
yes int exec (long addr, int argc, char **argv)

Usage example

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

<source lang="C">

  1. include <libpayload.h>

int main(void) {

   printf("Hello, world!\n");
   halt();
   return 0;

} </source>

Building the payload:

$ lpgcc -o hello.elf hello.c


Public domain I, the copyright holder of this work, hereby release it into the public domain. This applies worldwide.

In case this is not legally possible:
I grant anyone the right to use this work for any purpose, without any conditions, unless such conditions are required by law.