Hi Heinrich,
On Mon, 2 Nov 2020 at 17:13, Heinrich Schuchardt xypron.glpk@gmx.de wrote:
Am 3. November 2020 01:06:00 MEZ schrieb Simon Glass sjg@chromium.org:
Hi Heinrich,
On Tue, 27 Oct 2020 at 13:29, Heinrich Schuchardt xypron.glpk@gmx.de wrote:
Use Sphinx style function descriptions.
Signed-off-by: Heinrich Schuchardt xypron.glpk@gmx.de
v3: no change v2: new patch
include/os.h | 223
++++++++++++++++++++++++++++++---------------------
1 file changed, 130 insertions(+), 93 deletions(-)
diff --git a/include/os.h b/include/os.h index 88dfb71c1a..1fe44f3510 100644 --- a/include/os.h +++ b/include/os.h @@ -19,30 +19,30 @@ struct sandbox_state; /**
- Access to the OS read() system call
- \param fd File descriptor as returned by os_open()
- \param buf Buffer to place data
- \param count Number of bytes to read
- \return number of bytes read, or -1 on error
- @fd: File descriptor as returned by os_open()
- @buf: Buffer to place data
- @count: Number of bytes to read
*/
- Return: number of bytes read, or -1 on error
ssize_t os_read(int fd, void *buf, size_t count);
/**
- Access to the OS write() system call
- \param fd File descriptor as returned by os_open()
- \param buf Buffer containing data to write
- \param count Number of bytes to write
- \return number of bytes written, or -1 on error
- @fd: File descriptor as returned by os_open()
- @buf: Buffer containing data to write
- @count: Number of bytes to write
*/
- Return: number of bytes written, or -1 on error
ssize_t os_write(int fd, const void *buf, size_t count);
/**
- Access to the OS lseek() system call
- \param fd File descriptor as returned by os_open()
- \param offset File offset (based on whence)
- \param whence Position offset is relative to (see below)
- \return new file offset
- @fd: File descriptor as returned by os_open()
- @offset: File offset (based on whence)
- @whence: Position offset is relative to (see below)
*/
- Return: new file offset
off_t os_lseek(int fd, off_t offset, int whence);
@@ -54,9 +54,9 @@ off_t os_lseek(int fd, off_t offset, int whence); /**
- Access to the OS open() system call
- \param pathname Pathname of file to open
- \param flags Flags, like OS_O_RDONLY, OS_O_RDWR
- \return file descriptor, or -1 on error
- @pathname: Pathname of file to open
- @flags: Flags, like OS_O_RDONLY, OS_O_RDWR
*/
- Return: file descriptor, or -1 on error
int os_open(const char *pathname, int flags);
@@ -68,42 +68,42 @@ int os_open(const char *pathname, int flags); #define OS_O_TRUNC 01000
/**
- Access to the OS close() system call
- os_close() - access to the OS close() system call
- \param fd File descriptor to close
- \return 0 on success, -1 on error
- @fd: File descriptor to close
*/
- Return: 0 on success, -1 on error
int os_close(int fd);
/**
- Access to the OS unlink() system call
- os_unlink() - access to the OS unlink() system call
- \param pathname Path of file to delete
- \return 0 for success, other for error
- @pathname: Path of file to delete
*/
- Return: 0 for success, other for error
int os_unlink(const char *pathname);
/**
- Access to the OS exit() system call
- os_exit() - access to the OS exit() system call
- This exits with the supplied return code, which should be 0 to
indicate
- success.
- @param exit_code exit code for U-Boot
*/
- @exit_code: exit code for U-Boot
void os_exit(int exit_code) __attribute__((noreturn));
/**
- Put tty into raw mode to mimic serial console better
- os_tty_raw() - put tty into raw mode to mimic serial console
better
- @param fd File descriptor of stdin (normally 0)
- @param allow_sigs Allow Ctrl-C, Ctrl-Z to generate signals
rather than
be handled by U-Boot
- @fd: File descriptor of stdin (normally 0)
- @allow_sigs: Allow Ctrl-C, Ctrl-Z to generate signals
rather than
*/
be handled by U-Bootvoid os_tty_raw(int fd, bool allow_sigs);
/**
- Restore the tty to its original mode
- os_fs_restore() - restore the tty to its original mode
- Call this to restore the original terminal mode, after it has
been changed
- by os_tty_raw(). This is an internal function.
@@ -111,144 +111,180 @@ void os_tty_raw(int fd, bool allow_sigs); void os_fd_restore(void);
/**
- Acquires some memory from the underlying os.
- os_malloc() - aquires some memory from the underlying os.
- \param length Number of bytes to be allocated
- \return Pointer to length bytes or NULL on error
- @length: Number of bytes to be allocated
*/
- Return: Pointer to length bytes or NULL on error
void *os_malloc(size_t length);
/**
- Free memory previous allocated with os_malloc()
- os_free() - free memory previous allocated with os_malloc()
- This returns the memory to the OS.
- \param ptr Pointer to memory block to free
*/
- @ptr: Pointer to memory block to free
void os_free(void *ptr);
/**
- Access to the usleep function of the os
- os_usleep() - access to the usleep function of the os
- \param usec Time to sleep in micro seconds
*/
- @usec: time to sleep in micro seconds
void os_usleep(unsigned long usec);
/**
- Gets a monotonic increasing number of nano seconds from the OS
- \return A monotonic increasing time scaled in nano seconds
*/
- Return: a monotonic increasing time scaled in nano seconds
uint64_t os_get_nsec(void);
/**
- Parse arguments and update sandbox state.
- @param state Sandbox state to update
- @param argc Argument count
- @param argv Argument vector
- @return 0 if ok, and program should continue;
1 if ok, but program should stop;
-1 on error: program should terminate.
- @state: sandbox state to update
- @argc: argument count
- @argv: argument vector
- Return:
- 0 if ok, and program should continue
- 1 if ok, but program should stop
*/
- -1 on error: program should terminate
int os_parse_args(struct sandbox_state *state, int argc, char
*argv[]);
/*
- enum os_dirent_t - type of directory entry
- Types of directory entry that we support. See also
os_dirent_typename in
- the C file.
*/ enum os_dirent_t {
OS_FILET_REG, /* Regular file */OS_FILET_LNK, /* Symbolic link */OS_FILET_DIR, /* Directory */OS_FILET_UNKNOWN, /* Something else */
/*** @OS_FILET_REG: regular file*/OS_FILET_REG,Maybe I missed your response about a similar thing with global_data.h...can we not do this?
OS_FILET_REG, /**< @OS_FILET_REG: regular file */
or
OS_FILET_REG, /**< regular file */
/*** @OS_FILET_LNK: symbolic link*/or even:
/** @OS_FILET_LNK: symbolic link */
OS_FILET_LNK,/*** @OS_FILET_DIR: directory*/Regards, Simon
We want to follow the Linux documentation style. Otherwise we cannot profit from the upstream scripts.
https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#structure-u...
There are so many different styles floating around that I am not even sure what this new one is called.
But it does suggest there is a single-line option:
/** @foobar: Single line description. */ int foobar;
It is quite a bit less verbose and use up a lot less vertical screen real estate.
Reviewed-by: Simon Glass sjg@chromium.org
Regards, Simon