Various Doxygen-related fixes in libpayload (trivial).
- Drop all '@brief's, they're not needed as we use JAVADOC_AUTOBRIEF. The first sentence of every description will be treated as the '@brief' automatically. - Also, put all documentation/descriptions on top of the Doxygen-comments, and put the '@foo' keywords at the bottom of the comments for consistency. - Change comments for SEEK_SET/SEEK_CUR/SEEK_END from '/**@def' to '/**<' in order to make them appear in the output. - Drop all explicit '@struct' lines (which are optional; Doxygen will figure out that it's a struct if the comment is right before the struct). - Fix various typos, whitespace issues, etc. - Fix incorrect @param variable names, e.g. change '@param n foobar' to '@param s foobar' if the variable is named 's'. Signed-off-by: Uwe Hermann <uwe@hermann-uwe.de> Acked-by: Uwe Hermann <uwe@hermann-uwe.de> git-svn-id: svn://svn.coreboot.org/coreboot/trunk@3555 2b7e53f0-3cfb-0310-b3e9-8179ed1497e1
This commit is contained in:
Uwe Hermann
parent
0e6ad6bd09
commit
3153863567
|
|
@ -27,8 +27,9 @@
|
|||
* SUCH DAMAGE.
|
||||
*/
|
||||
|
||||
/** @file i386/timer.c
|
||||
* @brief i386 specific timer routines
|
||||
/**
|
||||
* @file i386/timer.c
|
||||
* i386 specific timer routines
|
||||
*/
|
||||
|
||||
#include <libpayload.h>
|
||||
|
|
@ -36,7 +37,7 @@
|
|||
|
||||
/**
|
||||
* @ingroup arch
|
||||
* Global variable containing the speed of the processor in KHz
|
||||
* Global variable containing the speed of the processor in KHz.
|
||||
*/
|
||||
u32 cpu_khz;
|
||||
|
||||
|
|
@ -81,8 +82,9 @@ static inline void _delay(unsigned int delta)
|
|||
}
|
||||
|
||||
/**
|
||||
* Delay for a specified number of nanoseconds
|
||||
* @param n Number of nanoseconds to delay for
|
||||
* Delay for a specified number of nanoseconds.
|
||||
*
|
||||
* @param n Number of nanoseconds to delay for.
|
||||
*/
|
||||
void ndelay(unsigned int n)
|
||||
{
|
||||
|
|
@ -90,8 +92,9 @@ void ndelay(unsigned int n)
|
|||
}
|
||||
|
||||
/**
|
||||
* Delay for a specified number of microseconds
|
||||
* @param n Number of microseconds to delay for
|
||||
* Delay for a specified number of microseconds.
|
||||
*
|
||||
* @param n Number of microseconds to delay for.
|
||||
*/
|
||||
void udelay(unsigned int n)
|
||||
{
|
||||
|
|
@ -99,20 +102,20 @@ void udelay(unsigned int n)
|
|||
}
|
||||
|
||||
/**
|
||||
* Delay for a specified number of milliseconds
|
||||
* @param n Number of milliseconds to delay for
|
||||
* Delay for a specified number of milliseconds.
|
||||
*
|
||||
* @param m Number of milliseconds to delay for.
|
||||
*/
|
||||
|
||||
void mdelay(unsigned int m)
|
||||
{
|
||||
_delay(m * cpu_khz);
|
||||
}
|
||||
|
||||
/**
|
||||
* Delay for a specified number of seconds
|
||||
* @param n Number of seconds to delay for
|
||||
* Delay for a specified number of seconds.
|
||||
*
|
||||
* @param s Number of seconds to delay for.
|
||||
*/
|
||||
|
||||
void delay(unsigned int s)
|
||||
{
|
||||
_delay(s * cpu_khz * 1000);
|
||||
|
|
|
|||
|
|
@ -27,7 +27,9 @@
|
|||
* SUCH DAMAGE.
|
||||
*/
|
||||
|
||||
/** @mainpage
|
||||
/**
|
||||
* @mainpage
|
||||
*
|
||||
* @section intro Introduction
|
||||
* libpayload is a small BSD-licensed static library (a lightweight
|
||||
* implementation of common and useful functions) intended to be used
|
||||
|
|
@ -36,10 +38,8 @@
|
|||
* @section example Example
|
||||
* Here is an example of a very simple payload:
|
||||
* @include sample/hello.c
|
||||
*
|
||||
*/
|
||||
|
||||
|
||||
#ifndef _LIBPAYLOAD_H
|
||||
#define _LIBPAYLOAD_H
|
||||
|
||||
|
|
@ -64,12 +64,12 @@
|
|||
|
||||
#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)[] \
|
||||
|
|
@ -90,9 +90,7 @@ static const char _pstruct(key)[] \
|
|||
#define NVRAM_RTC_FREQ_SELECT 10 /**< RTC Update Status Register */
|
||||
#define NVRAM_RTC_UIP 0x80
|
||||
|
||||
/** @struct tm
|
||||
* \brief Broken down time structure
|
||||
*/
|
||||
/** Broken down time structure */
|
||||
struct tm {
|
||||
int tm_sec; /**< Number of seconds after the minute */
|
||||
int tm_min; /**< Number of minutes after the hour */
|
||||
|
|
@ -136,7 +134,6 @@ void serial_init(void);
|
|||
void serial_putchar(unsigned char c);
|
||||
int serial_havechar(void);
|
||||
int serial_getchar(void);
|
||||
|
||||
void serial_clear(void);
|
||||
void serial_start_bold(void);
|
||||
void serial_end_bold(void);
|
||||
|
|
@ -189,7 +186,7 @@ extern int last_putchar;
|
|||
/** @} */
|
||||
|
||||
/**
|
||||
* @defgroup ctype Character Type Functions
|
||||
* @defgroup ctype Character type functions
|
||||
* @{
|
||||
*/
|
||||
int isalnum(int c);
|
||||
|
|
@ -210,14 +207,14 @@ int toupper(int c);
|
|||
/** @} */
|
||||
|
||||
/**
|
||||
* @defgroup ipchecksum IP Checksum Functions
|
||||
* @defgroup ipchecksum IP checksum functions
|
||||
* @{
|
||||
*/
|
||||
unsigned short ipchksum(const void *ptr, unsigned long nbytes);
|
||||
/** @} */
|
||||
|
||||
/**
|
||||
* @defgroup malloc Memory Allocation Functions
|
||||
* @defgroup malloc Memory allocation functions
|
||||
* @{
|
||||
*/
|
||||
void free(void *ptr);
|
||||
|
|
@ -227,14 +224,14 @@ void *realloc(void *ptr, size_t size);
|
|||
/** @} */
|
||||
|
||||
/**
|
||||
* @defgroup exec Execution Functions
|
||||
* @defgroup exec Execution functions
|
||||
* @{
|
||||
*/
|
||||
int exec(long addr, int argc, char **argv);
|
||||
/** @} */
|
||||
|
||||
/**
|
||||
* @defgroup misc Misc Functions
|
||||
* @defgroup misc Misc functions
|
||||
* @{
|
||||
*/
|
||||
int bcd2dec(int b);
|
||||
|
|
@ -244,11 +241,11 @@ 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));
|
||||
void fatal(const char *msg) __attribute__ ((noreturn));
|
||||
/** @} */
|
||||
|
||||
/**
|
||||
* @defgroup memory Memory Manipulation Functions
|
||||
* @defgroup memory Memory manipulation functions
|
||||
* @{
|
||||
*/
|
||||
void *memset(void *s, int c, size_t n);
|
||||
|
|
@ -258,7 +255,7 @@ int memcmp(const void *s1, const void *s2, size_t len);
|
|||
/** @} */
|
||||
|
||||
/**
|
||||
* @defgroup printf Print Functions
|
||||
* @defgroup printf Print functions
|
||||
* @{
|
||||
*/
|
||||
int snprintf(char *str, size_t size, const char *fmt, ...);
|
||||
|
|
@ -270,7 +267,7 @@ int vprintf(const char *fmt, va_list ap);
|
|||
/** @} */
|
||||
|
||||
/**
|
||||
* @defgroup rand Random Number Generator Functions
|
||||
* @defgroup rand Random number generator functions
|
||||
* @{
|
||||
*/
|
||||
int rand_r(unsigned int *seed);
|
||||
|
|
@ -279,7 +276,7 @@ void srand(unsigned int seed);
|
|||
/** @} */
|
||||
|
||||
/**
|
||||
* @defgroup hash Hashing Functions
|
||||
* @defgroup hash Hashing functions
|
||||
* @{
|
||||
*/
|
||||
#define SHA1_BLOCK_LENGTH 64
|
||||
|
|
@ -297,7 +294,7 @@ u8 *sha1(const u8 *data, size_t len, u8 *buf);
|
|||
/** @} */
|
||||
|
||||
/**
|
||||
* @defgroup string String Functions
|
||||
* @defgroup string String functions
|
||||
* @{
|
||||
*/
|
||||
size_t strnlen(const char *str, size_t maxlen);
|
||||
|
|
@ -313,14 +310,11 @@ char *strstr(const char *h, const char *n);
|
|||
/** @} */
|
||||
|
||||
/**
|
||||
* @defgroup time Time Functions
|
||||
* @defgroup time Time functions
|
||||
* @{
|
||||
*/
|
||||
|
||||
/** @struct timeval
|
||||
* @brief System time structure
|
||||
*/
|
||||
|
||||
/** System time structure */
|
||||
struct timeval {
|
||||
time_t tv_sec; /**< Seconds */
|
||||
suseconds_t tv_usec; /**< Microseconds */
|
||||
|
|
@ -330,15 +324,13 @@ int gettimeofday(struct timeval *tv, void *tz);
|
|||
/** @} */
|
||||
|
||||
/**
|
||||
* @defgroup lar LAR Functions
|
||||
* @defgroup lar LAR functions
|
||||
* @{
|
||||
*/
|
||||
|
||||
/** @struct LAR
|
||||
* @brief LAR File Header
|
||||
*/
|
||||
/** LAR file header */
|
||||
struct LAR {
|
||||
void * start; /**< Location of the LAR in memory */
|
||||
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 */
|
||||
|
|
@ -346,16 +338,12 @@ struct LAR {
|
|||
void **headers; /**< Pointer to the header cache */
|
||||
};
|
||||
|
||||
/** @struct larent
|
||||
* @brief A structure representing the next LAR entry
|
||||
*/
|
||||
/** A structure representing the next LAR entry */
|
||||
struct larent {
|
||||
u8 name[LAR_MAX_PATHLEN]; /**< The name of the next LAR entry */
|
||||
};
|
||||
|
||||
/** @struct larstat
|
||||
* @brief A structure containing information about a LAR file
|
||||
*/
|
||||
/** A structure containing information about a LAR file */
|
||||
struct larstat {
|
||||
u32 len; /**< Length of the file in the LAR */
|
||||
u32 reallen; /**< Length of the uncompressed file */
|
||||
|
|
@ -367,10 +355,7 @@ struct larstat {
|
|||
u64 loadaddress; /**< Address in memory to put the uncompressed file */
|
||||
};
|
||||
|
||||
/** @struct LFILE
|
||||
* @brief A structure representing a LAR file
|
||||
*/
|
||||
|
||||
/** A structure representing a LAR file */
|
||||
struct LFILE {
|
||||
struct LAR *lar; /**< Pointer to the LAR struct */
|
||||
struct lar_header *header; /**< Pointer to the header struct */
|
||||
|
|
@ -386,20 +371,20 @@ 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 /**@def The seek offset is absolute */
|
||||
#define SEEK_CUR 1 /**@def The seek offset is against the current position */
|
||||
#define SEEK_END 2 /**@def The see offset is against the end of the file */
|
||||
#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);
|
||||
/** @} */
|
||||
|
||||
/**
|
||||
* @defgroup arch Architecture Specific Functions
|
||||
* This modules contains global architecture specific functions.
|
||||
* @defgroup arch Architecture specific functions
|
||||
* This module contains global architecture specific functions.
|
||||
* All architectures are expected to define these functions.
|
||||
* @{
|
||||
*/
|
||||
|
|
@ -417,20 +402,18 @@ void delay(unsigned int n);
|
|||
#define abort() halt() /**< Alias for the halt() function */
|
||||
|
||||
/**
|
||||
* Stops executions and halts the processor. This function does
|
||||
* not return.
|
||||
* 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 are suitable for reading a
|
||||
* line of input from the console.
|
||||
* @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);
|
||||
char *readline(const char *prompt);
|
||||
int getline(char *buffer, int len);
|
||||
/** @} */
|
||||
|
||||
|
|
|
|||
|
|
@ -27,27 +27,27 @@
|
|||
* SUCH DAMAGE.
|
||||
*/
|
||||
|
||||
/** @file libc/readline.c
|
||||
* @brief Simple readline implementation
|
||||
/**
|
||||
* @file libc/readline.c
|
||||
* Simple readline implementation
|
||||
*/
|
||||
|
||||
#include <libpayload.h>
|
||||
|
||||
static char * readline_buffer;
|
||||
static char *readline_buffer;
|
||||
static int readline_bufferlen;
|
||||
|
||||
/**
|
||||
* @brief Read a line from the terminal and return it
|
||||
* @param prompt A prompt to display on the line
|
||||
* @return A pointer to the input string
|
||||
* Read a line from the terminal and return it.
|
||||
*
|
||||
* Read a line from the terminal and return it. This readline implementation
|
||||
* is rather simple, but it does more than the original readline() because
|
||||
* it allows us to have a pre-filled buffer. To pre-fill the buffer, use the
|
||||
* getline() function.
|
||||
* This readline implementation is rather simple, but it does more than the
|
||||
* original readline() because it allows us to have a pre-filled buffer.
|
||||
* To pre-fill the buffer, use the getline() function.
|
||||
*
|
||||
* @param prompt A prompt to display on the line.
|
||||
* @return A pointer to the input string.
|
||||
*/
|
||||
|
||||
char * readline(const char * prompt)
|
||||
char *readline(const char *prompt)
|
||||
{
|
||||
char *buffer;
|
||||
int current, ch, nonspace_seen;
|
||||
|
|
@ -141,7 +141,6 @@ char * readline(const char * prompt)
|
|||
}
|
||||
}
|
||||
|
||||
|
||||
out:
|
||||
if (current >= readline_bufferlen)
|
||||
current = readline_bufferlen - 1;
|
||||
|
|
@ -151,22 +150,23 @@ out:
|
|||
}
|
||||
|
||||
/**
|
||||
* @brief Read a line from the input and store it in a buffer
|
||||
* @param prompt A buffer to store the line in
|
||||
* @param len Length of the buffer
|
||||
* @return The final length of the string
|
||||
* This function allows the user to pass a predefined buffer to
|
||||
* readline(). The buffer may be filled with a default value
|
||||
* which will be displayed by readline and can be edited as normal.
|
||||
* The final input string returned by readline will be returned in
|
||||
* Read a line from the input and store it in a buffer.
|
||||
*
|
||||
* This function allows the user to pass a predefined buffer to readline().
|
||||
* The buffer may be filled with a default value which will be displayed by
|
||||
* readline() and can be edited as normal.
|
||||
* The final input string returned by readline() will be returned in
|
||||
* the buffer and the function will return the length of the string.
|
||||
*
|
||||
* @param buffer Pointer to a buffer to store the line in.
|
||||
* @param len Length of the buffer.
|
||||
* @return The final length of the string.
|
||||
*/
|
||||
|
||||
int getline(char *buffer, int len)
|
||||
{
|
||||
readline_buffer = buffer;
|
||||
readline_bufferlen = len;
|
||||
readline(NULL);
|
||||
|
||||
return strlen(buffer);
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -27,8 +27,9 @@
|
|||
* SUCH DAMAGE.
|
||||
*/
|
||||
|
||||
/** @file libc/time.c
|
||||
* @brief General Time Functions
|
||||
/**
|
||||
* @file libc/time.c
|
||||
* General time functions
|
||||
*/
|
||||
|
||||
#include <config.h>
|
||||
|
|
@ -115,18 +116,18 @@ static void gettimeofday_init(void)
|
|||
#endif
|
||||
|
||||
/**
|
||||
* Return the current time broken into a timeval structure
|
||||
* @param tv A pointer to a timeval structure
|
||||
* @param tz Added for compatability - not used
|
||||
* @return 0 for success
|
||||
* Return the current time broken into a timeval structure.
|
||||
*
|
||||
* @param tv A pointer to a timeval structure.
|
||||
* @param tz Added for compatability - not used.
|
||||
* @return 0 for success (this function cannot return non-zero currently).
|
||||
*/
|
||||
int gettimeofday(struct timeval *tv, void *tz)
|
||||
{
|
||||
/* Call the gtod init when we need it - this keeps
|
||||
the code from being included in the binary if we don't
|
||||
need it
|
||||
*/
|
||||
|
||||
/*
|
||||
* Call the gtod init when we need it - this keeps the code from
|
||||
* being included in the binary if we don't need it.
|
||||
*/
|
||||
if (!clock.ticks)
|
||||
gettimeofday_init();
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue