github-mirror/linux
1
0
Fork 0
mirror of https://github.com/torvalds/linux.git synced 2026-11-07 06:17:02 +01:00
Code Issues Actions Packages Projects Releases Wiki Activity Graph

docs: core-api: Document the seq_buf API

Browse Source 
The kernel-doc in include/linux/seq_buf.h and lib/seq_buf.c documents
the seq_buf interface, but no .rst file pulls either of them in, so none
of it reaches the generated documentation.

Add the missing kernel-doc for seq_buf_clear() and seq_buf_init(), and a
Sequence Buffers section to the kernel API documentation. The static
internal helper seq_buf_can_fit() is left out. Additionally fix
seq_buf_hex_dump() indentation to avoid the reported Sphinx error:

  ERROR: Unexpected indentation.
  WARNING: Block quote ends without a blank line; unexpected unindent.

Verified with "make SPHINXDIRS=core-api htmldocs", which rendered
happily into core-api/kernel-api.html.

Assisted-by: LLM
Co-developed-by: Bill Wendling <morbo@google.com>
Signed-off-by: Bill Wendling <morbo@google.com>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Link: https://patch.msgid.link/20261005155708.1471260-12-kees@kernel.org
Signed-off-by: Kees Cook <kees@kernel.org>
This commit is contained in:
Kees Cook 2026-10-05 08:57:02 -07:00
parent 9ac219976e
commit e3f8dfafd7
3 changed files with 28 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
Documentation/core-api/kernel-api.rst
View File

@ -96,6 +96,15 @@ Error Pointers
.. kernel-doc:: include/linux/err.h
:internal:
Sequence Buffers
----------------
.. kernel-doc:: include/linux/seq_buf.h
:internal:
.. kernel-doc:: lib/seq_buf.c
:no-identifiers: seq_buf_can_fit
Sorting
-------

12
include/linux/seq_buf.h
View File

@ -31,6 +31,10 @@ struct seq_buf {
.size = SIZE, \
}
/**
* seq_buf_clear - reset the seq_buf to be read / appended from the beginning
* @s: the seq_buf handle
*/
static inline void seq_buf_clear(struct seq_buf *s)
{
s->len = 0;
@ -38,6 +42,14 @@ static inline void seq_buf_clear(struct seq_buf *s)
s->buffer[0] = '\0';
}
/**
* seq_buf_init - initialize a seq_buf
* @s: the seq_buf handle
* @buf: pointer to the buffer
* @size: total size of @buf
*
* The contents of the buffer are ignored.
*/
static inline void
seq_buf_init(struct seq_buf *s, char *buf, unsigned int size)
{

13
lib/seq_buf.c
View File

@ -409,12 +409,13 @@ int seq_buf_to_user(struct seq_buf *s, char __user *ubuf, size_t start, int cnt)
*
* Function is an analogue of print_hex_dump() and thus has similar interface.
*
* linebuf size is maximal length for one line.
* 32 * 3 - maximum bytes per line, each printed into 2 chars + 1 for
* separating space
* 2 - spaces separating hex dump and ASCII representation
* 32 - ASCII representation
* 1 - terminating '\0'
* linebuf size is maximal length for one line::
*
* 32 * 3 - maximum bytes per line, each printed into 2 chars + 1 for
* separating space
* 2 - spaces separating hex dump and ASCII representation
* 32 - ASCII representation
* 1 - terminating '\0'
*
* Returns: zero on success, -1 on overflow.
*/