From dd05add7b2b6004c5fa3a1f276f56d8668f86b65 Mon Sep 17 00:00:00 2001 From: Paulo Alcantara Date: Sat, 26 Sep 2026 19:20:30 -0300 Subject: netfs: zero the tail of a short DIO/unbuffered read The buffered read collector zero-fills the tail of a short read that stops below the inode's i_size (netfs_clear_unread()), so a read that races an extending write still returns the expected number of bytes. The non-buffered collector path does no such thing: it just records how much was transferred. Add the same zero-fill for the non-buffered case, gated on NETFS_SREQ_CLEAR_TAIL: a subreq's source sets that flag when a short result from it is known to be safe to treat as a hole, as opposed to NETFS_SREQ_HIT_EOF, which means the read genuinely ran off the end of the file and should be reported short as-is. Only CLEAR_TAIL should zero-fill here; a real EOF must stay a real short read. No source currently sets CLEAR_TAIL on an unbuffered/DIO subrequest, so this is inert on its own -- a following change teaches cifs to set it in the one case that needs it. Fixes: e2d46f2ec332 ("netfs: Change the read result collector to only use one work item") Reviewed-by: David Howells Reviewed-by: Namjae Jeon Signed-off-by: Paulo Alcantara Cc: Christian Brauner Cc: Matthew Wilcox Cc: Ronnie Sahlberg Cc: Shyam Prasad N Cc: Tom Talpey Cc: Bharath SM Cc: stable@vger.kernel.org --- Documentation/doc-guide/parse-headers.rst | 187 ++++++++++++++++++++++++++++++ 1 file changed, 187 insertions(+) create mode 100644 Documentation/doc-guide/parse-headers.rst (limited to 'Documentation/doc-guide/parse-headers.rst') diff --git a/Documentation/doc-guide/parse-headers.rst b/Documentation/doc-guide/parse-headers.rst new file mode 100644 index 000000000..a7bb01ff0 --- /dev/null +++ b/Documentation/doc-guide/parse-headers.rst @@ -0,0 +1,187 @@ +=========================== +Including uAPI header files +=========================== + +Sometimes, it is useful to include header files and C example codes in +order to describe the userspace API and to generate cross-references +between the code and the documentation. Adding cross-references for +userspace API files has an additional advantage: Sphinx will generate warnings +if a symbol is not found at the documentation. That helps to keep the +uAPI documentation in sync with the Kernel changes. +The :ref:`parse_headers.py ` provides a way to generate such +cross-references. It has to be called via Makefile, while building the +documentation. Please see ``Documentation/userspace-api/media/Makefile`` for an example +about how to use it inside the Kernel tree. + +.. _parse_headers: + +tools/docs/parse_headers.py +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +NAME +**** + +parse_headers.py - parse a C file, in order to identify functions, structs, +enums and defines and create cross-references to a Sphinx book. + +USAGE +***** + +parse-headers.py [-h] [-d] [-t] ``FILE_IN`` ``FILE_OUT`` ``FILE_RULES`` + +SYNOPSIS +******** + +Converts a C header or source file ``FILE_IN`` into a ReStructured Text +included via ..parsed-literal block with cross-references for the +documentation files that describe the API. It accepts an optional +``FILE_RULES`` file to describe what elements will be either ignored or +be pointed to a non-default reference type/name. + +The output is written at ``FILE_OUT``. + +It is capable of identifying ``define``, ``struct``, ``typedef``, ``enum`` +and enum ``symbol``, creating cross-references for all of them. + +It is also capable of distinguishing ``#define`` used for specifying +Linux-specific macros used to define ``ioctl``. + +The optional ``FILE_RULES`` contains a set of rules like:: + + ignore ioctl VIDIOC_ENUM_FMT + replace ioctl VIDIOC_DQBUF vidioc_qbuf + replace define V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ :c:type:`v4l2_event_motion_det` + +POSITIONAL ARGUMENTS +******************** + + ``FILE_IN`` + Input C file + + ``FILE_OUT`` + Output RST file + + ``FILE_RULES`` + Exceptions file (optional) + +OPTIONS +******* + + ``-h``, ``--help`` + show a help message and exit + ``-d``, ``--debug`` + Increase debug level. Can be used multiple times + ``-t``, ``--toc`` + instead of a literal block, outputs a TOC table at the RST file + + +DESCRIPTION +*********** + +Creates an enriched version of a Kernel header file with cross-links +to each C data structure type, from ``FILE_IN``, formatting it with +reStructuredText notation, either as-is or as a table of contents. + +It accepts an optional ``FILE_RULES`` which describes what elements will be +either ignored or be pointed to a non-default reference, and optionally +defines the C namespace to be used. + +It is meant to allow having more comprehensive documentation, where +uAPI headers will create cross-reference links to the code. + +The output is written at the ``FILE_OUT``. + +The ``FILE_RULES`` may contain contain three types of statements: +**ignore**, **replace** and **namespace**. + +By default, it create rules for all symbols and defines, but it also +allows parsing an exception file. Such file contains a set of rules +using the syntax below: + +1. Ignore rules: + + ignore *type* *symbol* + +Removes the symbol from reference generation. + +2. Replace rules: + + replace *type* *old_symbol* *new_reference* + + Replaces *old_symbol* with a *new_reference*. + The *new_reference* can be: + + - A simple symbol name; + - A full Sphinx reference. + +3. Namespace rules + + namespace *namespace* + + Sets C *namespace* to be used during cross-reference generation. Can + be overridden by replace rules. + +On ignore and replace rules, *type* can be: + + - ioctl: + for defines of the form ``_IO*``, e.g., ioctl definitions + + - define: + for other defines + + - symbol: + for symbols defined within enums; + + - typedef: + for typedefs; + + - enum: + for the name of a non-anonymous enum; + + - struct: + for structs. + + +EXAMPLES +******** + +- Ignore a define ``_VIDEODEV2_H`` at ``FILE_IN``:: + + ignore define _VIDEODEV2_H + +- On an data structure like this enum:: + + enum foo { BAR1, BAR2, PRIVATE }; + + It won't generate cross-references for ``PRIVATE``:: + + ignore symbol PRIVATE + + At the same struct, instead of creating one cross reference per symbol, + make them all point to the ``enum foo`` C type:: + + replace symbol BAR1 :c:type:\`foo\` + replace symbol BAR2 :c:type:\`foo\` + + +- Use C namespace ``MC`` for all symbols at ``FILE_IN``:: + + namespace MC + +BUGS +**** + + +Report bugs to Mauro Carvalho Chehab + + +COPYRIGHT +********* + + +Copyright (c) 2016, 2025 by Mauro Carvalho Chehab . + +License GPLv2: GNU GPL version 2 . + +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. -- cgit v1.3.1