X-Git-Url: http://wien.tomnetworks.com/gitweb/?a=blobdiff_plain;f=payloads%2Flibpayload%2Finclude%2Flibpayload.h;h=9ad3c82dd1bfcd4b2296a02cb5c97c79c716023c;hb=41514397e7168fdd4b2066435cc3c668e68514d6;hp=dc2f5eec1b561b00bd76374f1e05874e1ab57203;hpb=fc697ad028be74df40fde7eb3f18fc12d75a3d1d;p=coreboot.git diff --git a/payloads/libpayload/include/libpayload.h b/payloads/libpayload/include/libpayload.h index dc2f5eec1..9ad3c82dd 100644 --- a/payloads/libpayload/include/libpayload.h +++ b/payloads/libpayload/include/libpayload.h @@ -27,16 +27,30 @@ * SUCH DAMAGE. */ +/** + * @mainpage + * + * @section intro Introduction + * 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. + * + * @section example Example + * Here is an example of a very simple payload: + * @include sample/hello.c + */ + #ifndef _LIBPAYLOAD_H #define _LIBPAYLOAD_H -#include #include #include #include +#include #include #include #include +#include #define MIN(a,b) ((a) < (b) ? (a) : (b)) #define MAX(a,b) ((a) > (b) ? (a) : (b)) @@ -44,82 +58,135 @@ #define LITTLE_ENDIAN 1234 #define BIG_ENDIAN 4321 -#ifdef CONFIG_TARGET_I386 -#define BYTE_ORDER LITTLE_ENDIAN -#else -#define BYTE_ORDER BIG_ENDIAN -#endif #define EXIT_SUCCESS 0 #define EXIT_FAILURE 1 #define RAND_MAX 0x7fffffff -/* Payload information parameters - these are used to pass information - * to the entity loading the payload - * Usage: PAYLOAD_INFO(key, value) - * Example: PAYLOAD_INFO(name, "CoreInfo!") +/* + * Payload information parameters - these are used to pass information + * to the entity loading the payload. + * Usage: PAYLOAD_INFO(key, value) + * Example: PAYLOAD_INFO(name, "CoreInfo!") */ - #define _pstruct(key) __pinfo_ ##key #define PAYLOAD_INFO(key, value) \ static const char _pstruct(key)[] \ __attribute__((__used__)) \ __attribute__((section(".note.pinfo"),unused)) = #key "=" value -/* Some NVRAM byte definitions */ -#define NVRAM_RTC_SECONDS 0 -#define NVRAM_RTC_MINUTES 2 -#define NVRAM_RTC_HOURS 4 -#define NVRAM_RTC_DAY 7 -#define NVRAM_RTC_MONTH 8 -#define NVRAM_RTC_YEAR 9 -#define NVRAM_RTC_FREQ_SELECT 10 +/** + * @defgroup nvram NVRAM and RTC functions + * @{ + */ + +#define NVRAM_RTC_SECONDS 0 /**< RTC Seconds offset in CMOS */ +#define NVRAM_RTC_MINUTES 2 /**< RTC Minutes offset in CMOS */ +#define NVRAM_RTC_HOURS 4 /**< RTC Hours offset in CMOS */ +#define NVRAM_RTC_DAY 7 /**< RTC Days offset in CMOS */ +#define NVRAM_RTC_MONTH 8 /**< RTC Month offset in CMOS */ +#define NVRAM_RTC_YEAR 9 /**< RTC Year offset in CMOS */ +#define NVRAM_RTC_FREQ_SELECT 10 /**< RTC Update Status Register */ #define NVRAM_RTC_UIP 0x80 +/** Broken down time structure */ struct tm { - int tm_sec; - int tm_min; - int tm_hour; - int tm_mday; - int tm_mon; - int tm_year; - int tm_wday; - int tm_yday; - int tm_isdst; + int tm_sec; /**< Number of seconds after the minute */ + int tm_min; /**< Number of minutes after the hour */ + int tm_hour; /**< Number of hours past midnight */ + int tm_mday; /**< The day of the month */ + int tm_mon; /**< The month of the year */ + int tm_year; /**< The number of years since 1900 */ + int tm_wday; /**< The day of the week */ + int tm_yday; /**< The number of days since January 1 */ + int tm_isdst; /**< A flag indicating daylight savings time */ }; -/* drivers/nvram.c */ u8 nvram_read(u8 addr); void nvram_write(u8 val, u8 addr); int nvram_updating(void); void rtc_read_clock(struct tm *tm); +/** @} */ -/* drivers/keyboard.c */ +/** + * @defgroup usb USB functions + * @{ + */ +int usb_initialize(void); +/** @} */ + +/** + * @defgroup input Device functions + * @{ @} + */ + +/** + * @defgroup keyboard Keyboard functions + * @ingroup input + * @{ + */ void keyboard_init(void); int keyboard_havechar(void); unsigned char keyboard_get_scancode(void); int keyboard_getchar(void); - -/* drivers/serial.c */ +int keyboard_set_layout(char *country); +int keyboard_add_reset_handler(void (*new_handler)(void)); +/** @} */ + +/** + * @defgroup serial Serial functions + * @ingroup input + * @{ + */ void serial_init(void); +void serial_hardware_init(int port, int speed, int word_bits, int parity, int stop_bits); void serial_putchar(unsigned char c); int serial_havechar(void); int serial_getchar(void); - -/* drivers/speaker.c */ +void serial_clear(void); +void serial_start_bold(void); +void serial_end_bold(void); +void serial_start_reverse(void); +void serial_end_reverse(void); +void serial_start_altcharset(void); +void serial_end_altcharset(void); +void serial_set_color(short fg, short bg); +void serial_cursor_enable(int state); +void serial_set_cursor(int y, int x); +/** @} */ + +/** + * @defgroup speaker Speaker functions + * @ingroup input + * @{ + */ void speaker_enable(u16 freq); void speaker_disable(void); void speaker_tone(u16 freq, unsigned int duration); +/** @} */ -/* video/video.c */ +/** + * @defgroup video Video functions + * @ingroup input + * @{ + */ int video_console_init(void); void video_console_putchar(unsigned int ch); void video_console_putc(u8 row, u8 col, unsigned int ch); void video_console_clear(void); void video_console_cursor_enable(int state); +void video_console_get_cursor(unsigned int *x, unsigned int *y, unsigned int *en); +void video_console_set_cursor(unsigned int cursorx, unsigned int cursory); +/** @} */ -/* libc/console.c */ +/* drivers/option.c */ +int get_option(void *dest, char *name); + +/** + * @defgroup console Console functions + * @{ + */ void console_init(void); int putchar(int c); int puts(const char *s); @@ -130,8 +197,12 @@ int getchar_timeout(int *ms); extern int last_putchar; #define havechar havekey +/** @} */ -/* libc/ctype.c */ +/** + * @defgroup ctype Character type functions + * @{ + */ int isalnum(int c); int isalpha(int c); int isascii(int c); @@ -147,20 +218,37 @@ int isupper(int c); int isxdigit(int c); int tolower(int c); int toupper(int c); +/** @} */ -/* libc/ipchecksum.c */ -unsigned short ipchksum(const unsigned short *ptr, unsigned long nbytes); +/** + * @defgroup ipchecksum IP checksum functions + * @{ + */ +unsigned short ipchksum(const void *ptr, unsigned long nbytes); +/** @} */ -/* libc/malloc.c */ +/** + * @defgroup malloc Memory allocation functions + * @{ + */ void free(void *ptr); void *malloc(size_t size); void *calloc(size_t nmemb, size_t size); void *realloc(void *ptr, size_t size); +void *memalign(size_t align, size_t size); +/** @} */ -/* libc/exec.c */ +/** + * @defgroup exec Execution functions + * @{ + */ int exec(long addr, int argc, char **argv); +/** @} */ -/* libc/lib.c */ +/** + * @defgroup misc Misc functions + * @{ + */ int bcd2dec(int b); int dec2bcd(int d); int abs(int j); @@ -168,27 +256,44 @@ long int labs(long int j); long long int llabs(long long int j); u8 bin2hex(u8 b); u8 hex2bin(u8 h); +void fatal(const char *msg) __attribute__ ((noreturn)); +/** @} */ -/* libc/memory.c */ +/** + * @defgroup memory Memory manipulation functions + * @{ + */ void *memset(void *s, int c, size_t n); void *memcpy(void *dst, const void *src, size_t n); void *memmove(void *dst, const void *src, size_t n); -int memcmp(const char *s1, const char *s2, size_t len); +int memcmp(const void *s1, const void *s2, size_t len); +/** @} */ -/* libc/printf.c */ +/** + * @defgroup printf Print functions + * @{ + */ int snprintf(char *str, size_t size, const char *fmt, ...); int sprintf(char *str, const char *fmt, ...); int vsnprintf(char *str, size_t size, const char *fmt, va_list ap); int vsprintf(char *str, const char *fmt, va_list ap); int printf(const char *fmt, ...); int vprintf(const char *fmt, va_list ap); +/** @} */ -/* libc/rand.c */ +/** + * @defgroup rand Random number generator functions + * @{ + */ int rand_r(unsigned int *seed); int rand(void); void srand(unsigned int seed); +/** @} */ -/* libc/sha1.c */ +/** + * @defgroup hash Hashing functions + * @{ + */ #define SHA1_BLOCK_LENGTH 64 #define SHA1_DIGEST_LENGTH 20 typedef struct { @@ -201,60 +306,78 @@ void SHA1Transform(u32 state[5], const u8 buffer[SHA1_BLOCK_LENGTH]); void SHA1Update(SHA1_CTX *context, const u8 *data, size_t len); void SHA1Final(u8 digest[SHA1_DIGEST_LENGTH], SHA1_CTX *context); u8 *sha1(const u8 *data, size_t len, u8 *buf); +/** @} */ -/* libc/string.c */ +/** + * @defgroup string String functions + * @{ + */ size_t strnlen(const char *str, size_t maxlen); size_t strlen(const char *str); int strcmp(const char *s1, const char *s2); -int strncmp(const char *s1, const char *s2, int maxlen); -char *strncpy(char *d, const char *s, int n); +int strncmp(const char *s1, const char *s2, size_t maxlen); +char *strncpy(char *d, const char *s, size_t n); char *strcpy(char *d, const char *s); -char *strncat(char *d, const char *s, int n); +char *strncat(char *d, const char *s, size_t n); char *strchr(const char *s, int c); char *strdup(const char *s); char *strstr(const char *h, const char *n); +char *strsep(char **stringp, const char *delim); +/** @} */ -/* libc/time.c */ +/** + * @defgroup time Time functions + * @{ + */ +/** System time structure */ struct timeval { - time_t tv_sec; - suseconds_t tv_usec; + time_t tv_sec; /**< Seconds */ + suseconds_t tv_usec; /**< Microseconds */ }; int gettimeofday(struct timeval *tv, void *tz); +/** @} */ -/* libc/lar.c */ +/** + * @defgroup lar LAR functions + * @{ + */ +/** LAR file header */ struct LAR { - void * start; - int cindex; - int count; - int alloc; - int eof; - void **headers; + void *start; /**< Location of the LAR in memory */ + int cindex; /**< Next file to return in readlar() */ + int count; /**< Number of entries in the header cache */ + int alloc; /**< Number of slots in the header cache */ + int eof; /**< Last entry in the header cache */ + void **headers; /**< Pointer to the header cache */ }; +/** A structure representing the next LAR entry */ struct larent { - u8 name[LAR_MAX_PATHLEN]; + u8 name[LAR_MAX_PATHLEN]; /**< The name of the next LAR entry */ }; +/** A structure containing information about a LAR file */ struct larstat { - u32 len; - u32 reallen; - u32 checksum; - u32 compchecksum; - u32 offset; - u32 compression; - u64 entry; - u64 loadaddress; + u32 len; /**< Length of the file in the LAR */ + u32 reallen; /**< Length of the uncompressed file */ + u32 checksum; /**< Checksum of the uncompressed file */ + u32 compchecksum; /**< Checksum of the compressed file in the LAR */ + u32 offset; /**< Offset of the file in the LAR */ + u32 compression; /**< Compression type of the file */ + u64 entry; /**< Entry point of the file for executables */ + u64 loadaddress; /**< Address in memory to put the uncompressed file */ }; +/** A structure representing a LAR file */ struct LFILE { - struct LAR *lar; - struct lar_header *header; - u32 size; - void *start; - u32 offset; + struct LAR *lar; /**< Pointer to the LAR struct */ + struct lar_header *header; /**< Pointer to the header struct */ + u32 size; /**< Size of the file */ + void *start; /**< Start of the file in memory */ + u32 offset; /**< Offset of the file in the LAR */ }; struct LAR *openlar(void *addr); @@ -264,23 +387,27 @@ void rewindlar(struct LAR *lar); int larstat(struct LAR *lar, const char *path, struct larstat *buf); void *larfptr(struct LAR *lar, const char *filename); int lfverify(struct LAR *lar, const char *filename); -struct LFILE * lfopen(struct LAR *lar, const char *filename); +struct LFILE *lfopen(struct LAR *lar, const char *filename); int lfread(void *ptr, size_t size, size_t nmemb, struct LFILE *stream); -#define SEEK_SET 0 -#define SEEK_CUR 1 -#define SEEK_END 2 +#define SEEK_SET 0 /**< The seek offset is absolute. */ +#define SEEK_CUR 1 /**< The seek offset is against the current position. */ +#define SEEK_END 2 /**< The seek offset is against the end of the file. */ int lfseek(struct LFILE *stream, long offset, int whence); int lfclose(struct LFILE *file); +/** @} */ -/* i386/coreboot.c */ +/** + * @defgroup arch Architecture specific functions + * This module contains global architecture specific functions. + * All architectures are expected to define these functions. + * @{ + */ int get_coreboot_info(struct sysinfo_t *info); -/* i386/sysinfo.c */ void lib_get_sysinfo(void); -/* i386/timer.c */ /* Timer functions - defined by each architecture. */ unsigned int get_cpu_speed(void); void ndelay(unsigned int n); @@ -288,8 +415,22 @@ void udelay(unsigned int n); void mdelay(unsigned int n); void delay(unsigned int n); -/* i386/util.S */ -#define abort() halt() +#define abort() halt() /**< Alias for the halt() function */ + +/** + * Stop execution and halt the processor (this function does not return). + */ void halt(void) __attribute__ ((noreturn)); +/** @} */ + +/** + * @defgroup readline Readline functions + * This interface provides a simple implementation of the standard readline() + * and getline() functions. They read a line of input from the console. + * @{ + */ +char *readline(const char *prompt); +int getline(char *buffer, int len); +/** @} */ #endif