From 6656ae4df1a6ad6dfb5c4ce4c76136a42abb9bf4 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Thu, 7 Aug 2025 15:16:28 -0600 Subject: [PATCH 001/193] docs: kdoc: consolidate the stripping of private struct/union members There were two locations duplicating the logic of stripping private members and associated comments; coalesce them into one, and add some comments describing what's going on. Output change: we now no longer add extraneous white space around macro definitions. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250807211639.47286-2-corbet@lwn.net --- scripts/lib/kdoc/kdoc_parser.py | 40 ++++++++++++++++++--------------- 1 file changed, 22 insertions(+), 18 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py index c3fe4bd5eab4..93fcd8807aa8 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -81,6 +81,21 @@ multi_space = KernRe(r'\s\s+') def trim_whitespace(s): return multi_space.sub(' ', s.strip()) +# +# Remove struct/enum members that have been marked "private". +# +def trim_private_members(text): + # + # First look for a "public:" block that ends a private region, then + # handle the "private until the end" case. + # + text = KernRe(r'/\*\s*private:.*?/\*\s*public:.*?\*/', flags=re.S).sub('', text) + text = KernRe(r'/\*\s*private:.*', flags=re.S).sub('', text) + # + # We needed the comments to do the above, but now we can take them out. + # + return KernRe(r'\s*/\*.*?\*/\s*', flags=re.S).sub('', text).strip() + class state: """ State machine enums @@ -568,12 +583,6 @@ class KernelDoc: args_pattern = r'([^,)]+)' sub_prefixes = [ - (KernRe(r'\/\*\s*private:.*?\/\*\s*public:.*?\*\/', re.S | re.I), ''), - (KernRe(r'\/\*\s*private:.*', re.S | re.I), ''), - - # Strip comments - (KernRe(r'\/\*.*?\*\/', re.S), ''), - # Strip attributes (attribute, ' '), (KernRe(r'\s*__aligned\s*\([^;]*\)', re.S), ' '), @@ -648,6 +657,7 @@ class KernelDoc: (re.compile(r'\bSTRUCT_GROUP\('), r'\1'), ] + members = trim_private_members(members) for search, sub in sub_prefixes: members = search.sub(sub, members) @@ -797,24 +807,18 @@ class KernelDoc: """ Stores an enum inside self.entries array. """ - - # Ignore members marked private - proto = KernRe(r'\/\*\s*private:.*?\/\*\s*public:.*?\*\/', flags=re.S).sub('', proto) - proto = KernRe(r'\/\*\s*private:.*}', flags=re.S).sub('}', proto) - - # Strip comments - proto = KernRe(r'\/\*.*?\*\/', flags=re.S).sub('', proto) - - # Strip #define macros inside enums + # + # Strip preprocessor directives. Note that this depends on the + # trailing semicolon we added in process_proto_type(). + # proto = KernRe(r'#\s*((define|ifdef|if)\s+|endif)[^;]*;', flags=re.S).sub('', proto) - # # Parse out the name and members of the enum. Typedef form first. # r = KernRe(r'typedef\s+enum\s*\{(.*)\}\s*(\w*)\s*;') if r.search(proto): declaration_name = r.group(2) - members = r.group(1).rstrip() + members = trim_private_members(r.group(1)) # # Failing that, look for a straight enum # @@ -822,7 +826,7 @@ class KernelDoc: r = KernRe(r'enum\s+(\w*)\s*\{(.*)\}') if r.match(proto): declaration_name = r.group(1) - members = r.group(2).rstrip() + members = trim_private_members(r.group(2)) # # OK, this isn't going to work. # From 259feba4dde78f165b03e231ea9985dfe600c202 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Thu, 7 Aug 2025 15:16:29 -0600 Subject: [PATCH 002/193] docs: kdoc: Move a regex line in dump_struct() The complex struct_members regex was defined far from its use; bring the two together. Remove some extraneous backslashes while making the move. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250807211639.47286-3-corbet@lwn.net --- scripts/lib/kdoc/kdoc_parser.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py index 93fcd8807aa8..aa6d11bf29b1 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -551,7 +551,6 @@ class KernelDoc: ] definition_body = r'\{(.*)\}\s*' + "(?:" + '|'.join(qualifiers) + ")?" - struct_members = KernRe(type_pattern + r'([^\{\};]+)(\{)([^\{\}]*)(\})([^\{\}\;]*)(\;)') # Extract struct/union definition members = None @@ -683,6 +682,7 @@ class KernelDoc: # So, we need to have an extra loop on Python to override such # re limitation. + struct_members = KernRe(type_pattern + r'([^\{\};]+)(\{)([^\{\}]*)(\})([^\{\};]*)(;)') while True: tuples = struct_members.findall(members) if not tuples: From 5fd513f01169ae93d202b8c30f0837096664e7d7 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Thu, 7 Aug 2025 15:16:30 -0600 Subject: [PATCH 003/193] docs: kdoc: backslashectomy in kdoc_parser A lot of the regular expressions in this file have extraneous backslashes that may have been needed in Perl, but aren't helpful here. Take them out to reduce slightly the visual noise. Escaping of (){}[] has been left in place, even when unnecessary, for visual clarity. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250807211639.47286-4-corbet@lwn.net --- scripts/lib/kdoc/kdoc_parser.py | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py index aa6d11bf29b1..14ded23f11e0 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -46,7 +46,7 @@ doc_decl = doc_com + KernRe(r'(\w+)', cache=False) known_section_names = 'description|context|returns?|notes?|examples?' known_sections = KernRe(known_section_names, flags = re.I) doc_sect = doc_com + \ - KernRe(r'\s*(\@[.\w]+|\@\.\.\.|' + known_section_names + r')\s*:([^:].*)?$', + KernRe(r'\s*(@[.\w]+|@\.\.\.|' + known_section_names + r')\s*:([^:].*)?$', flags=re.I, cache=False) doc_content = doc_com_body + KernRe(r'(.*)', cache=False) @@ -60,7 +60,7 @@ attribute = KernRe(r"__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)", export_symbol = KernRe(r'^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*', cache=False) export_symbol_ns = KernRe(r'^\s*EXPORT_SYMBOL_NS(_GPL)?\s*\(\s*(\w+)\s*,\s*"\S+"\)\s*', cache=False) -type_param = KernRe(r"\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)", cache=False) +type_param = KernRe(r"@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)", cache=False) # # Tests for the beginning of a kerneldoc block in its various forms. @@ -405,7 +405,7 @@ class KernelDoc: for arg in args.split(splitter): # Strip comments - arg = KernRe(r'\/\*.*\*\/').sub('', arg) + arg = KernRe(r'/\*.*\*/').sub('', arg) # Ignore argument attributes arg = KernRe(r'\sPOS0?\s').sub(' ', arg) @@ -428,7 +428,7 @@ class KernelDoc: arg = arg.replace('#', ',') - r = KernRe(r'[^\(]+\(\*?\s*([\w\[\]\.]*)\s*\)') + r = KernRe(r'[^\(]+\(\*?\s*([\w\[\].]*)\s*\)') if r.match(arg): param = r.group(1) else: @@ -443,7 +443,7 @@ class KernelDoc: # Array-of-pointers arg = arg.replace('#', ',') - r = KernRe(r'[^\(]+\(\s*\*\s*([\w\[\]\.]*?)\s*(\s*\[\s*[\w]+\s*\]\s*)*\)') + r = KernRe(r'[^\(]+\(\s*\*\s*([\w\[\].]*?)\s*(\s*\[\s*[\w]+\s*\]\s*)*\)') if r.match(arg): param = r.group(1) else: @@ -709,7 +709,7 @@ class KernelDoc: if not arg: continue - r = KernRe(r'^([^\(]+\(\*?\s*)([\w\.]*)(\s*\).*)') + r = KernRe(r'^([^\(]+\(\*?\s*)([\w.]*)(\s*\).*)') if r.match(arg): # Pointer-to-function dtype = r.group(1) @@ -1044,7 +1044,7 @@ class KernelDoc: Stores a typedef inside self.entries array. """ - typedef_type = r'((?:\s+[\w\*]+\b){0,7}\s+(?:\w+\b|\*+))\s*' + typedef_type = r'((?:\s+[\w*]+\b){0,7}\s+(?:\w+\b|\*+))\s*' typedef_ident = r'\*?\s*(\w\S+)\s*' typedef_args = r'\s*\((.*)\);' @@ -1265,7 +1265,7 @@ class KernelDoc: self.dump_section() # Look for doc_com + + doc_end: - r = KernRe(r'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') + r = KernRe(r'\s*\*\s*[a-zA-Z_0-9:.]+\*/') if r.match(line): self.emit_msg(ln, f"suspicious ending line: {line}") @@ -1476,7 +1476,7 @@ class KernelDoc: """Ancillary routine to process a function prototype""" # strip C99-style comments to end of line - line = KernRe(r"\/\/.*$", re.S).sub('', line) + line = KernRe(r"//.*$", re.S).sub('', line) # # Soak up the line's worth of prototype text, stopping at { or ; if present. # From 64cf83bcd3217a9583caeb404ff136366a46705c Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Thu, 7 Aug 2025 15:16:31 -0600 Subject: [PATCH 004/193] docs: kdoc: move the prefix transforms out of dump_struct() dump_struct is one of the longest functions in the kdoc_parser class, making it hard to read and reason about. Move the definition of the prefix transformations out of the function, join them with the definition of "attribute" (which was defined at the top of the file but only used here), and reformat the code slightly for shorter line widths. Just code movement in the end. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250807211639.47286-5-corbet@lwn.net --- scripts/lib/kdoc/kdoc_parser.py | 179 +++++++++++++++++--------------- 1 file changed, 96 insertions(+), 83 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py index 14ded23f11e0..3d007d200da6 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -54,8 +54,6 @@ doc_inline_start = KernRe(r'^\s*/\*\*\s*$', cache=False) doc_inline_sect = KernRe(r'\s*\*\s*(@\s*[\w][\w\.]*\s*):(.*)', cache=False) doc_inline_end = KernRe(r'^\s*\*/\s*$', cache=False) doc_inline_oneline = KernRe(r'^\s*/\*\*\s*(@[\w\s]+):\s*(.*)\s*\*/\s*$', cache=False) -attribute = KernRe(r"__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)", - flags=re.I | re.S, cache=False) export_symbol = KernRe(r'^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*', cache=False) export_symbol_ns = KernRe(r'^\s*EXPORT_SYMBOL_NS(_GPL)?\s*\(\s*(\w+)\s*,\s*"\S+"\)\s*', cache=False) @@ -74,6 +72,97 @@ doc_begin_func = KernRe(str(doc_com) + # initial " * ' r'(?:[-:].*)?$', # description (not captured) cache = False) +# +# Here begins a long set of transformations to turn structure member prefixes +# and macro invocations into something we can parse and generate kdoc for. +# +struct_attribute = KernRe(r"__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)", + flags=re.I | re.S, cache=False) +struct_args_pattern = r'([^,)]+)' + +struct_prefixes = [ + # Strip attributes + (struct_attribute, ' '), + (KernRe(r'\s*__aligned\s*\([^;]*\)', re.S), ' '), + (KernRe(r'\s*__counted_by\s*\([^;]*\)', re.S), ' '), + (KernRe(r'\s*__counted_by_(le|be)\s*\([^;]*\)', re.S), ' '), + (KernRe(r'\s*__packed\s*', re.S), ' '), + (KernRe(r'\s*CRYPTO_MINALIGN_ATTR', re.S), ' '), + (KernRe(r'\s*____cacheline_aligned_in_smp', re.S), ' '), + (KernRe(r'\s*____cacheline_aligned', re.S), ' '), + # + # Unwrap struct_group macros based on this definition: + # __struct_group(TAG, NAME, ATTRS, MEMBERS...) + # which has variants like: struct_group(NAME, MEMBERS...) + # Only MEMBERS arguments require documentation. + # + # Parsing them happens on two steps: + # + # 1. drop struct group arguments that aren't at MEMBERS, + # storing them as STRUCT_GROUP(MEMBERS) + # + # 2. remove STRUCT_GROUP() ancillary macro. + # + # The original logic used to remove STRUCT_GROUP() using an + # advanced regex: + # + # \bSTRUCT_GROUP(\(((?:(?>[^)(]+)|(?1))*)\))[^;]*; + # + # with two patterns that are incompatible with + # Python re module, as it has: + # + # - a recursive pattern: (?1) + # - an atomic grouping: (?>...) + # + # I tried a simpler version: but it didn't work either: + # \bSTRUCT_GROUP\(([^\)]+)\)[^;]*; + # + # As it doesn't properly match the end parenthesis on some cases. + # + # So, a better solution was crafted: there's now a NestedMatch + # class that ensures that delimiters after a search are properly + # matched. So, the implementation to drop STRUCT_GROUP() will be + # handled in separate. + # + (KernRe(r'\bstruct_group\s*\(([^,]*,)', re.S), r'STRUCT_GROUP('), + (KernRe(r'\bstruct_group_attr\s*\(([^,]*,){2}', re.S), r'STRUCT_GROUP('), + (KernRe(r'\bstruct_group_tagged\s*\(([^,]*),([^,]*),', re.S), r'struct \1 \2; STRUCT_GROUP('), + (KernRe(r'\b__struct_group\s*\(([^,]*,){3}', re.S), r'STRUCT_GROUP('), + # + # Replace macros + # + # TODO: use NestedMatch for FOO($1, $2, ...) matches + # + # it is better to also move those to the NestedMatch logic, + # to ensure that parenthesis will be properly matched. + # + (KernRe(r'__ETHTOOL_DECLARE_LINK_MODE_MASK\s*\(([^\)]+)\)', re.S), + r'DECLARE_BITMAP(\1, __ETHTOOL_LINK_MODE_MASK_NBITS)'), + (KernRe(r'DECLARE_PHY_INTERFACE_MASK\s*\(([^\)]+)\)', re.S), + r'DECLARE_BITMAP(\1, PHY_INTERFACE_MODE_MAX)'), + (KernRe(r'DECLARE_BITMAP\s*\(' + struct_args_pattern + r',\s*' + struct_args_pattern + r'\)', + re.S), r'unsigned long \1[BITS_TO_LONGS(\2)]'), + (KernRe(r'DECLARE_HASHTABLE\s*\(' + struct_args_pattern + r',\s*' + struct_args_pattern + r'\)', + re.S), r'unsigned long \1[1 << ((\2) - 1)]'), + (KernRe(r'DECLARE_KFIFO\s*\(' + struct_args_pattern + r',\s*' + struct_args_pattern + + r',\s*' + struct_args_pattern + r'\)', re.S), r'\2 *\1'), + (KernRe(r'DECLARE_KFIFO_PTR\s*\(' + struct_args_pattern + r',\s*' + + struct_args_pattern + r'\)', re.S), r'\2 *\1'), + (KernRe(r'(?:__)?DECLARE_FLEX_ARRAY\s*\(' + struct_args_pattern + r',\s*' + + struct_args_pattern + r'\)', re.S), r'\1 \2[]'), + (KernRe(r'DEFINE_DMA_UNMAP_ADDR\s*\(' + struct_args_pattern + r'\)', re.S), r'dma_addr_t \1'), + (KernRe(r'DEFINE_DMA_UNMAP_LEN\s*\(' + struct_args_pattern + r'\)', re.S), r'__u32 \1'), +] +# +# Regexes here are guaranteed to have the end limiter matching +# the start delimiter. Yet, right now, only one replace group +# is allowed. +# +struct_nested_prefixes = [ + (re.compile(r'\bSTRUCT_GROUP\('), r'\1'), +] + + # # A little helper to get rid of excess white space # @@ -578,91 +667,15 @@ class KernelDoc: self.emit_msg(ln, f"expecting prototype for {decl_type} {self.entry.identifier}. Prototype was for {decl_type} {declaration_name} instead\n") return - - args_pattern = r'([^,)]+)' - - sub_prefixes = [ - # Strip attributes - (attribute, ' '), - (KernRe(r'\s*__aligned\s*\([^;]*\)', re.S), ' '), - (KernRe(r'\s*__counted_by\s*\([^;]*\)', re.S), ' '), - (KernRe(r'\s*__counted_by_(le|be)\s*\([^;]*\)', re.S), ' '), - (KernRe(r'\s*__packed\s*', re.S), ' '), - (KernRe(r'\s*CRYPTO_MINALIGN_ATTR', re.S), ' '), - (KernRe(r'\s*____cacheline_aligned_in_smp', re.S), ' '), - (KernRe(r'\s*____cacheline_aligned', re.S), ' '), - - # Unwrap struct_group macros based on this definition: - # __struct_group(TAG, NAME, ATTRS, MEMBERS...) - # which has variants like: struct_group(NAME, MEMBERS...) - # Only MEMBERS arguments require documentation. - # - # Parsing them happens on two steps: - # - # 1. drop struct group arguments that aren't at MEMBERS, - # storing them as STRUCT_GROUP(MEMBERS) - # - # 2. remove STRUCT_GROUP() ancillary macro. - # - # The original logic used to remove STRUCT_GROUP() using an - # advanced regex: - # - # \bSTRUCT_GROUP(\(((?:(?>[^)(]+)|(?1))*)\))[^;]*; - # - # with two patterns that are incompatible with - # Python re module, as it has: - # - # - a recursive pattern: (?1) - # - an atomic grouping: (?>...) - # - # I tried a simpler version: but it didn't work either: - # \bSTRUCT_GROUP\(([^\)]+)\)[^;]*; - # - # As it doesn't properly match the end parenthesis on some cases. - # - # So, a better solution was crafted: there's now a NestedMatch - # class that ensures that delimiters after a search are properly - # matched. So, the implementation to drop STRUCT_GROUP() will be - # handled in separate. - - (KernRe(r'\bstruct_group\s*\(([^,]*,)', re.S), r'STRUCT_GROUP('), - (KernRe(r'\bstruct_group_attr\s*\(([^,]*,){2}', re.S), r'STRUCT_GROUP('), - (KernRe(r'\bstruct_group_tagged\s*\(([^,]*),([^,]*),', re.S), r'struct \1 \2; STRUCT_GROUP('), - (KernRe(r'\b__struct_group\s*\(([^,]*,){3}', re.S), r'STRUCT_GROUP('), - - # Replace macros - # - # TODO: use NestedMatch for FOO($1, $2, ...) matches - # - # it is better to also move those to the NestedMatch logic, - # to ensure that parenthesis will be properly matched. - - (KernRe(r'__ETHTOOL_DECLARE_LINK_MODE_MASK\s*\(([^\)]+)\)', re.S), r'DECLARE_BITMAP(\1, __ETHTOOL_LINK_MODE_MASK_NBITS)'), - (KernRe(r'DECLARE_PHY_INTERFACE_MASK\s*\(([^\)]+)\)', re.S), r'DECLARE_BITMAP(\1, PHY_INTERFACE_MODE_MAX)'), - (KernRe(r'DECLARE_BITMAP\s*\(' + args_pattern + r',\s*' + args_pattern + r'\)', re.S), r'unsigned long \1[BITS_TO_LONGS(\2)]'), - (KernRe(r'DECLARE_HASHTABLE\s*\(' + args_pattern + r',\s*' + args_pattern + r'\)', re.S), r'unsigned long \1[1 << ((\2) - 1)]'), - (KernRe(r'DECLARE_KFIFO\s*\(' + args_pattern + r',\s*' + args_pattern + r',\s*' + args_pattern + r'\)', re.S), r'\2 *\1'), - (KernRe(r'DECLARE_KFIFO_PTR\s*\(' + args_pattern + r',\s*' + args_pattern + r'\)', re.S), r'\2 *\1'), - (KernRe(r'(?:__)?DECLARE_FLEX_ARRAY\s*\(' + args_pattern + r',\s*' + args_pattern + r'\)', re.S), r'\1 \2[]'), - (KernRe(r'DEFINE_DMA_UNMAP_ADDR\s*\(' + args_pattern + r'\)', re.S), r'dma_addr_t \1'), - (KernRe(r'DEFINE_DMA_UNMAP_LEN\s*\(' + args_pattern + r'\)', re.S), r'__u32 \1'), - ] - - # Regexes here are guaranteed to have the end limiter matching - # the start delimiter. Yet, right now, only one replace group - # is allowed. - - sub_nested_prefixes = [ - (re.compile(r'\bSTRUCT_GROUP\('), r'\1'), - ] - + # + # Go through the list of members applying all of our transformations. + # members = trim_private_members(members) - for search, sub in sub_prefixes: + for search, sub in struct_prefixes: members = search.sub(sub, members) nested = NestedMatch() - - for search, sub in sub_nested_prefixes: + for search, sub in struct_nested_prefixes: members = nested.sub(search, sub, members) # Keeps the original declaration as-is From 0f7344129434a6b44d4abb5080a9d67dd734ee07 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Thu, 7 Aug 2025 15:16:32 -0600 Subject: [PATCH 005/193] docs: kdoc: split top-level prototype parsing out of dump_struct() Move the initial split of the prototype into its own function in the ongoing effort to cut dump_struct() down to size. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250807211639.47286-6-corbet@lwn.net --- scripts/lib/kdoc/kdoc_parser.py | 43 +++++++++++++++------------------ 1 file changed, 20 insertions(+), 23 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py index 3d007d200da6..ab896dcd9572 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -624,13 +624,11 @@ class KernelDoc: self.emit_msg(ln, f"No description found for return value of '{declaration_name}'") - def dump_struct(self, ln, proto): - """ - Store an entry for an struct or union - """ - + # + # Split apart a structure prototype; returns (struct|union, name, members) or None + # + def split_struct_proto(self, proto): type_pattern = r'(struct|union)' - qualifiers = [ "__attribute__", "__packed", @@ -638,34 +636,33 @@ class KernelDoc: "____cacheline_aligned_in_smp", "____cacheline_aligned", ] - definition_body = r'\{(.*)\}\s*' + "(?:" + '|'.join(qualifiers) + ")?" - # Extract struct/union definition - members = None - declaration_name = None - decl_type = None - r = KernRe(type_pattern + r'\s+(\w+)\s*' + definition_body) if r.search(proto): - decl_type = r.group(1) - declaration_name = r.group(2) - members = r.group(3) + return (r.group(1), r.group(2), r.group(3)) else: r = KernRe(r'typedef\s+' + type_pattern + r'\s*' + definition_body + r'\s*(\w+)\s*;') - if r.search(proto): - decl_type = r.group(1) - declaration_name = r.group(3) - members = r.group(2) + return (r.group(1), r.group(3), r.group(2)) + return None - if not members: + def dump_struct(self, ln, proto): + """ + Store an entry for an struct or union + """ + # + # Do the basic parse to get the pieces of the declaration. + # + struct_parts = self.split_struct_proto(proto) + if not struct_parts: self.emit_msg(ln, f"{proto} error: Cannot parse struct or union!") return + decl_type, declaration_name, members = struct_parts if self.entry.identifier != declaration_name: - self.emit_msg(ln, - f"expecting prototype for {decl_type} {self.entry.identifier}. Prototype was for {decl_type} {declaration_name} instead\n") + self.emit_msg(ln, f"expecting prototype for {decl_type} {self.entry.identifier}. " + f"Prototype was for {decl_type} {declaration_name} instead\n") return # # Go through the list of members applying all of our transformations. @@ -695,7 +692,7 @@ class KernelDoc: # So, we need to have an extra loop on Python to override such # re limitation. - struct_members = KernRe(type_pattern + r'([^\{\};]+)(\{)([^\{\}]*)(\})([^\{\};]*)(;)') + struct_members = KernRe(r'(struct|union)([^\{\};]+)(\{)([^\{\}]*)(\})([^\{\};]*)(;)') while True: tuples = struct_members.findall(members) if not tuples: From 77e3c875f0a83d9192079e88d8569ac36c6b6bea Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Thu, 7 Aug 2025 15:16:33 -0600 Subject: [PATCH 006/193] docs: kdoc: split struct-member rewriting out of dump_struct() The massive loop that massages struct members shares no data with the rest of dump_struct(); split it out into its own function. Code movement only, no other changes. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250807211639.47286-7-corbet@lwn.net --- scripts/lib/kdoc/kdoc_parser.py | 65 +++++++++++++++++---------------- 1 file changed, 34 insertions(+), 31 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py index ab896dcd9572..fbd7f6ce3360 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -647,37 +647,7 @@ class KernelDoc: return (r.group(1), r.group(3), r.group(2)) return None - def dump_struct(self, ln, proto): - """ - Store an entry for an struct or union - """ - # - # Do the basic parse to get the pieces of the declaration. - # - struct_parts = self.split_struct_proto(proto) - if not struct_parts: - self.emit_msg(ln, f"{proto} error: Cannot parse struct or union!") - return - decl_type, declaration_name, members = struct_parts - - if self.entry.identifier != declaration_name: - self.emit_msg(ln, f"expecting prototype for {decl_type} {self.entry.identifier}. " - f"Prototype was for {decl_type} {declaration_name} instead\n") - return - # - # Go through the list of members applying all of our transformations. - # - members = trim_private_members(members) - for search, sub in struct_prefixes: - members = search.sub(sub, members) - - nested = NestedMatch() - for search, sub in struct_nested_prefixes: - members = nested.sub(search, sub, members) - - # Keeps the original declaration as-is - declaration = members - + def rewrite_struct_members(self, members): # Split nested struct/union elements # # This loop was simpler at the original kernel-doc perl version, as @@ -768,6 +738,39 @@ class KernelDoc: newmember += f"{dtype} {s_id}.{name}; " members = members.replace(oldmember, newmember) + return members + + def dump_struct(self, ln, proto): + """ + Store an entry for an struct or union + """ + # + # Do the basic parse to get the pieces of the declaration. + # + struct_parts = self.split_struct_proto(proto) + if not struct_parts: + self.emit_msg(ln, f"{proto} error: Cannot parse struct or union!") + return + decl_type, declaration_name, members = struct_parts + + if self.entry.identifier != declaration_name: + self.emit_msg(ln, f"expecting prototype for {decl_type} {self.entry.identifier}. " + f"Prototype was for {decl_type} {declaration_name} instead\n") + return + # + # Go through the list of members applying all of our transformations. + # + members = trim_private_members(members) + for search, sub in struct_prefixes: + members = search.sub(sub, members) + + nested = NestedMatch() + for search, sub in struct_nested_prefixes: + members = nested.sub(search, sub, members) + + # Keeps the original declaration as-is + declaration = members + members = self.rewrite_struct_members(members) # Ignore other nested elements, like enums members = re.sub(r'(\{[^\{\}]*\})', '', members) From f8208676c1c85c0b91e726954c05f5859b890ccb Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Thu, 7 Aug 2025 15:16:34 -0600 Subject: [PATCH 007/193] docs: kdoc: rework the rewrite_struct_members() main loop Adopt a more Pythonic form for the main loop of this function, getting rid of the "while True:" construction and making the actual loop invariant explicit. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250807211639.47286-8-corbet@lwn.net --- scripts/lib/kdoc/kdoc_parser.py | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py index fbd7f6ce3360..e11f3d6e9469 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -663,11 +663,8 @@ class KernelDoc: # re limitation. struct_members = KernRe(r'(struct|union)([^\{\};]+)(\{)([^\{\}]*)(\})([^\{\};]*)(;)') - while True: - tuples = struct_members.findall(members) - if not tuples: - break - + tuples = struct_members.findall(members) + while tuples: for t in tuples: newmember = "" maintype = t[0] @@ -738,6 +735,7 @@ class KernelDoc: newmember += f"{dtype} {s_id}.{name}; " members = members.replace(oldmember, newmember) + tuples = struct_members.findall(members) return members def dump_struct(self, ln, proto): From fb20e610393b02a832a0bf4964e12c20a7ffa2f8 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Thu, 7 Aug 2025 15:16:35 -0600 Subject: [PATCH 008/193] docs: kdoc: remove an extraneous strip() call ...the variable in question was already strip()ed at the top of the loop. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250807211639.47286-9-corbet@lwn.net --- scripts/lib/kdoc/kdoc_parser.py | 1 - 1 file changed, 1 deletion(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py index e11f3d6e9469..0c279aa802a0 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -703,7 +703,6 @@ class KernelDoc: newmember += f"{dtype}{s_id}.{name}{extra}; " else: - arg = arg.strip() # Handle bitmaps arg = KernRe(r':\s*\d+\s*').sub('', arg) From a8c4b0a8f1969e5ee0e8abb62cde8f0d7bcc2009 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Thu, 7 Aug 2025 15:16:36 -0600 Subject: [PATCH 009/193] docs: kdoc: Some rewrite_struct_members() commenting Add comments to rewrite_struct_members() describing what it is actually doing, and reformat/comment the main struct_members regex so that it is (more) comprehensible to humans. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250807211639.47286-10-corbet@lwn.net --- scripts/lib/kdoc/kdoc_parser.py | 32 +++++++++++++++++++------------- 1 file changed, 19 insertions(+), 13 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py index 0c279aa802a0..e3d0270b1a19 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -647,22 +647,28 @@ class KernelDoc: return (r.group(1), r.group(3), r.group(2)) return None + # + # Rewrite the members of a structure or union for easier formatting later on. + # Among other things, this function will turn a member like: + # + # struct { inner_members; } foo; + # + # into: + # + # struct foo; inner_members; + # def rewrite_struct_members(self, members): - # Split nested struct/union elements # - # This loop was simpler at the original kernel-doc perl version, as - # while ($members =~ m/$struct_members/) { ... } - # reads 'members' string on each interaction. + # Process struct/union members from the most deeply nested outward. The + # trick is in the ^{ below - it prevents a match of an outer struct/union + # until the inner one has been munged (removing the "{" in the process). # - # Python behavior is different: it parses 'members' only once, - # creating a list of tuples from the first interaction. - # - # On other words, this won't get nested structs. - # - # So, we need to have an extra loop on Python to override such - # re limitation. - - struct_members = KernRe(r'(struct|union)([^\{\};]+)(\{)([^\{\}]*)(\})([^\{\};]*)(;)') + struct_members = KernRe(r'(struct|union)' # 0: declaration type + r'([^\{\};]+)' # 1: possible name + r'(\{)' + r'([^\{\}]*)' # 3: Contents of declaration + r'(\})' + r'([^\{\};]*)(;)') # 5: Remaining stuff after declaration tuples = struct_members.findall(members) while tuples: for t in tuples: From e6dd4e2a5ca1c1e2fb168249532da1d95b5b24af Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Thu, 7 Aug 2025 15:16:37 -0600 Subject: [PATCH 010/193] docs: kdoc: further rewrite_struct_members() cleanup Get rid of some redundant checks, and generally tighten up the code; no logical change. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250807211639.47286-11-corbet@lwn.net --- scripts/lib/kdoc/kdoc_parser.py | 86 ++++++++++++++++----------------- 1 file changed, 41 insertions(+), 45 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py index e3d0270b1a19..b3f937901037 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -673,73 +673,69 @@ class KernelDoc: while tuples: for t in tuples: newmember = "" - maintype = t[0] - s_ids = t[5] - content = t[3] - - oldmember = "".join(t) - - for s_id in s_ids.split(','): + oldmember = "".join(t) # Reconstruct the original formatting + dtype, name, lbr, content, rbr, rest, semi = t + # + # Pass through each field name, normalizing the form and formatting. + # + for s_id in rest.split(','): s_id = s_id.strip() - - newmember += f"{maintype} {s_id}; " + newmember += f"{dtype} {s_id}; " + # + # Remove bitfield/array/pointer info, getting the bare name. + # s_id = KernRe(r'[:\[].*').sub('', s_id) s_id = KernRe(r'^\s*\**(\S+)\s*').sub(r'\1', s_id) - + # + # Pass through the members of this inner structure/union. + # for arg in content.split(';'): arg = arg.strip() - - if not arg: - continue - + # + # Look for (type)(*name)(args) - pointer to function + # r = KernRe(r'^([^\(]+\(\*?\s*)([\w.]*)(\s*\).*)') if r.match(arg): + dtype, name, extra = r.group(1), r.group(2), r.group(3) # Pointer-to-function - dtype = r.group(1) - name = r.group(2) - extra = r.group(3) - - if not name: - continue - if not s_id: # Anonymous struct/union newmember += f"{dtype}{name}{extra}; " else: newmember += f"{dtype}{s_id}.{name}{extra}; " - + # + # Otherwise a non-function member. + # else: - # Handle bitmaps + # + # Remove bitmap and array portions and spaces around commas + # arg = KernRe(r':\s*\d+\s*').sub('', arg) - - # Handle arrays arg = KernRe(r'\[.*\]').sub('', arg) - - # Handle multiple IDs arg = KernRe(r'\s*,\s*').sub(',', arg) - + # + # Look for a normal decl - "type name[,name...]" + # r = KernRe(r'(.*)\s+([\S+,]+)') - if r.search(arg): - dtype = r.group(1) - names = r.group(2) + for name in r.group(2).split(','): + name = KernRe(r'^\s*\**(\S+)\s*').sub(r'\1', name) + if not s_id: + # Anonymous struct/union + newmember += f"{r.group(1)} {name}; " + else: + newmember += f"{r.group(1)} {s_id}.{name}; " else: newmember += f"{arg}; " - continue - - for name in names.split(','): - name = KernRe(r'^\s*\**(\S+)\s*').sub(r'\1', name).strip() - - if not name: - continue - - if not s_id: - # Anonymous struct/union - newmember += f"{dtype} {name}; " - else: - newmember += f"{dtype} {s_id}.{name}; " - + # + # At the end of the s_id loop, replace the original declaration with + # the munged version. + # members = members.replace(oldmember, newmember) + # + # End of the tuple loop - search again and see if there are outer members + # that now turn up. + # tuples = struct_members.findall(members) return members From 23c47b09315935df140ca5ce2ddddb85453ed64d Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Thu, 7 Aug 2025 15:16:38 -0600 Subject: [PATCH 011/193] docs: kdoc: extract output formatting from dump_struct() The last thing done in dump_struct() is to format the structure for printing. That, too, is a separate activity; split it out into its own function. dump_struct() now fits in a single, full-hight editor screen. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250807211639.47286-12-corbet@lwn.net --- scripts/lib/kdoc/kdoc_parser.py | 72 +++++++++++++++++---------------- 1 file changed, 37 insertions(+), 35 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py index b3f937901037..878fbfab4ac7 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -739,6 +739,42 @@ class KernelDoc: tuples = struct_members.findall(members) return members + # + # Format the struct declaration into a standard form for inclusion in the + # resulting docs. + # + def format_struct_decl(self, declaration): + # + # Insert newlines, get rid of extra spaces. + # + declaration = KernRe(r'([\{;])').sub(r'\1\n', declaration) + declaration = KernRe(r'\}\s+;').sub('};', declaration) + # + # Format inline enums with each member on its own line. + # + r = KernRe(r'(enum\s+\{[^\}]+),([^\n])') + while r.search(declaration): + declaration = r.sub(r'\1,\n\2', declaration) + # + # Now go through and supply the right number of tabs + # for each line. + # + def_args = declaration.split('\n') + level = 1 + declaration = "" + for clause in def_args: + clause = KernRe(r'\s+').sub(' ', clause.strip(), count=1) + if clause: + if '}' in clause and level > 1: + level -= 1 + if not clause.startswith('#'): + declaration += "\t" * level + declaration += "\t" + clause + "\n" + if "{" in clause and "}" not in clause: + level += 1 + return declaration + + def dump_struct(self, ln, proto): """ Store an entry for an struct or union @@ -777,42 +813,8 @@ class KernelDoc: self.create_parameter_list(ln, decl_type, members, ';', declaration_name) self.check_sections(ln, declaration_name, decl_type) - - # Adjust declaration for better display - declaration = KernRe(r'([\{;])').sub(r'\1\n', declaration) - declaration = KernRe(r'\}\s+;').sub('};', declaration) - - # Better handle inlined enums - while True: - r = KernRe(r'(enum\s+\{[^\}]+),([^\n])') - if not r.search(declaration): - break - - declaration = r.sub(r'\1,\n\2', declaration) - - def_args = declaration.split('\n') - level = 1 - declaration = "" - for clause in def_args: - - clause = clause.strip() - clause = KernRe(r'\s+').sub(' ', clause, count=1) - - if not clause: - continue - - if '}' in clause and level > 1: - level -= 1 - - if not KernRe(r'^\s*#').match(clause): - declaration += "\t" * level - - declaration += "\t" + clause + "\n" - if "{" in clause and "}" not in clause: - level += 1 - self.output_declaration(decl_type, declaration_name, - definition=declaration, + definition=self.format_struct_decl(declaration), purpose=self.entry.declaration_purpose) def dump_enum(self, ln, proto): From e282303e718b2007b3db77c6db75ecaf4419a1af Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Thu, 7 Aug 2025 15:16:39 -0600 Subject: [PATCH 012/193] docs: kdoc: a few final dump_struct() touches Add a couple more comments so that each phase of the process is now clearly marked. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250807211639.47286-13-corbet@lwn.net --- scripts/lib/kdoc/kdoc_parser.py | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py index 878fbfab4ac7..9b21fb86709a 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -802,14 +802,15 @@ class KernelDoc: nested = NestedMatch() for search, sub in struct_nested_prefixes: members = nested.sub(search, sub, members) - - # Keeps the original declaration as-is + # + # Deal with embedded struct and union members, and drop enums entirely. + # declaration = members members = self.rewrite_struct_members(members) - - # Ignore other nested elements, like enums members = re.sub(r'(\{[^\{\}]*\})', '', members) - + # + # Output the result and we are done. + # self.create_parameter_list(ln, decl_type, members, ';', declaration_name) self.check_sections(ln, declaration_name, decl_type) From fc973dcd73f242480c61eccb1aa7306adafd2907 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 29 Jul 2025 18:43:03 +0200 Subject: [PATCH 013/193] docs: kernel-doc: avoid script crash on ancient Python While we do need at least 3.6 for kernel-doc to work, and at least 3.7 for it to output functions and structs with parameters at the right order, let the python binary be compatible with legacy versions. The rationale is that the Kernel build nowadays calls kernel-doc with -none on some places. Better not to bail out when older versions are found. With that, potentially this will run with python 2.7 and 3.2+, according with vermin: $ vermin --no-tips -v ./scripts/kernel-doc Detecting python files.. Analyzing using 24 processes.. 2.7, 3.2 /new_devel/v4l/docs/scripts/kernel-doc Minimum required versions: 2.7, 3.2 3.2 minimal requirement is due to argparse. The minimal version I could check was version 3.4 (using anaconda). Anaconda doesn't support 3.2 or 3.3 anymore, and 3.2 doesn't even compile (I tested compiling Python 3.2 on Fedora 42 and on Fedora 32 - no show). With 3.4, the script didn't crash and emitted the right warning: $ conda create -n py34 python=3.4 $ conda activate py34 python --version Python 3.4.5 $ python ./scripts/kernel-doc --none include/media Error: Python 3.6 or later is required by kernel-doc $ conda deactivate $ python --version Python 3.13.5 $ python ./scripts/kernel-doc --none include/media (no warnings and script ran properly) Supporting 2.7 is out of scope, as it is EOL for 5 years, and changing shebang to point to "python" instead of "python3" would have a wider impact. I did some extra checks about the differences from 3.2 and 3.4, and didn't find anything that would cause troubles: grep -rE "yield from|asyncio|pathlib|async|await|enum" scripts/kernel-doc Also, it doesn't use "@" operator. So, I'm confident that it should run (producing the exit warning) since Python 3.2. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/87d55e76b0b1391cb7a83e3e965dbddb83fa9786.1753806485.git.mchehab+huawei@kernel.org --- scripts/kernel-doc.py | 34 ++++++++++++++++++++++++---------- 1 file changed, 24 insertions(+), 10 deletions(-) diff --git a/scripts/kernel-doc.py b/scripts/kernel-doc.py index fc3d46ef519f..d9fe2bcbd39c 100755 --- a/scripts/kernel-doc.py +++ b/scripts/kernel-doc.py @@ -2,8 +2,17 @@ # SPDX-License-Identifier: GPL-2.0 # Copyright(c) 2025: Mauro Carvalho Chehab . # -# pylint: disable=C0103,R0915 -# +# pylint: disable=C0103,R0912,R0914,R0915 + +# NOTE: While kernel-doc requires at least version 3.6 to run, the +# command line should work with Python 3.2+ (tested with 3.4). +# The rationale is that it shall fail gracefully during Kernel +# compilation with older Kernel versions. Due to that: +# - encoding line is needed here; +# - no f-strings can be used on this file. +# - the libraries that require newer versions can only be included +# after Python version is checked. + # Converted from the kernel-doc script originally written in Perl # under GPLv2, copyrighted since 1998 by the following authors: # @@ -107,9 +116,6 @@ SRC_DIR = os.path.dirname(os.path.realpath(__file__)) sys.path.insert(0, os.path.join(SRC_DIR, LIB_DIR)) -from kdoc_files import KernelFiles # pylint: disable=C0413 -from kdoc_output import RestFormat, ManFormat # pylint: disable=C0413 - DESC = """ Read C language source or header FILEs, extract embedded documentation comments, and print formatted documentation to standard output. @@ -273,14 +279,22 @@ def main(): python_ver = sys.version_info[:2] if python_ver < (3,6): - logger.warning("Python 3.6 or later is required by kernel-doc") + # Depending on Kernel configuration, kernel-doc --none is called at + # build time. As we don't want to break compilation due to the + # usage of an old Python version, return 0 here. + if args.none: + logger.error("Python 3.6 or later is required by kernel-doc. skipping checks") + sys.exit(0) - # Return 0 here to avoid breaking compilation - sys.exit(0) + sys.exit("Python 3.6 or later is required by kernel-doc. Aborting.") if python_ver < (3,7): logger.warning("Python 3.7 or later is required for correct results") + # Import kernel-doc libraries only after checking Python version + from kdoc_files import KernelFiles # pylint: disable=C0415 + from kdoc_output import RestFormat, ManFormat # pylint: disable=C0415 + if args.man: out_style = ManFormat(modulename=args.modulename) elif args.none: @@ -308,11 +322,11 @@ def main(): sys.exit(0) if args.werror: - print(f"{error_count} warnings as errors") + print("%s warnings as errors" % error_count) # pylint: disable=C0209 sys.exit(error_count) if args.verbose: - print(f"{error_count} errors") + print("%s errors" % error_count) # pylint: disable=C0209 if args.none: sys.exit(0) From bc20c56e98e0bd08e89f4fe327f4f14994d339b5 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 29 Jul 2025 18:43:04 +0200 Subject: [PATCH 014/193] docs: changes: better document Python needs Python is listed as an optional dependency, but this is not true, as: 1) arm (multi_v7_defconfig and other defconfigs) and arm64 defconfig needs it due to DRM_MSM dependencies; 2) CONFIG_LTO_CLANG runs a python script at scripts/Makefile.vmlinux_o; 3) kernel-doc is called during compilation when some DRM options like CONFIG_DRM_I915_WERROR are enabled; 4) allyesconfig/allmodconfig will enable CONFIG_* dependencies that needs it; 5) besides DRM, other subsystems seem to have logic calling *.py scripts. So, better document that and change the dependency from optional to mandatory to reflect the current needs. Signed-off-by: Mauro Carvalho Chehab Acked-by: Rob Herring (Arm) Acked-by: Akira Yokosawa Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/b03b95b8d09358e81e4f27942839191f49b0ba80.1753806485.git.mchehab+huawei@kernel.org --- Documentation/process/changes.rst | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst index bccfa19b45df..4c9088e429c8 100644 --- a/Documentation/process/changes.rst +++ b/Documentation/process/changes.rst @@ -61,7 +61,7 @@ Sphinx\ [#f1]_ 3.4.3 sphinx-build --version GNU tar 1.28 tar --version gtags (optional) 6.6.5 gtags --version mkimage (optional) 2017.01 mkimage --version -Python (optional) 3.9.x python3 --version +Python 3.9.x python3 --version GNU AWK (optional) 5.1.0 gawk --version ====================== =============== ======================================== @@ -154,6 +154,13 @@ Perl You will need perl 5 and the following modules: ``Getopt::Long``, ``Getopt::Std``, ``File::Basename``, and ``File::Find`` to build the kernel. +Python +------ + +Several config options require it: it is required for arm/arm64 +default configs, CONFIG_LTO_CLANG, some DRM optional configs, +the kernel-doc tool, and docs build (Sphinx), among others. + BC -- From 119996c9a4be91f70779efe0a4f178356820249a Mon Sep 17 00:00:00 2001 From: Geert Uytterhoeven Date: Thu, 7 Aug 2025 09:36:01 +0200 Subject: [PATCH 015/193] Documentation/printf: Use literal fwnode_handle MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit When looking for fwnode_handle in the printk format documentation, it is only found in the Chinese translation: $ git grep fwnode_handle -- Documentation/*printk-formats.rst Documentation/translations/zh_CN/core-api/printk-formats.rst:用于打印fwnode_handles的消息。默认情况下是打印完整的节点名称，包括路径。 This happens because the original documentation talks about "fwnode handles", without mentioning the actual type name. Signed-off-by: Geert Uytterhoeven Tested-by: Kunwu Chan Reviewed-by: Kunwu Chan Reviewed-by: Andy Shevchenko Reviewed-by: Sakari Ailus Fixes: 3bd32d6a2ee62db3 ("lib/vsprintf: Add %pfw conversion specifier for printing fwnode names") Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/07262c55e82fc4a3e3dbe7c45713b14955271e7f.1754552156.git.geert+renesas@glider.be --- Documentation/core-api/printk-formats.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/core-api/printk-formats.rst b/Documentation/core-api/printk-formats.rst index 4b7f3646ec6c..7f2f11b48286 100644 --- a/Documentation/core-api/printk-formats.rst +++ b/Documentation/core-api/printk-formats.rst @@ -521,7 +521,7 @@ Fwnode handles %pfw[fP] -For printing information on fwnode handles. The default is to print the full +For printing information on an fwnode_handle. The default is to print the full node name, including the path. The modifiers are functionally equivalent to %pOF above. From 3feaa8a469ccb14e8adf69ae3235785182905bfc Mon Sep 17 00:00:00 2001 From: Osama Albahrani Date: Mon, 4 Aug 2025 18:25:14 +0300 Subject: [PATCH 016/193] docs: aoe: Remove trailing whitespace Fix `ERROR: trailing whitespace` errors from scripts/checkpatch.pl Signed-off-by: Osama Albahrani Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250804152516.16493-1-osalbahr@gmail.com --- Documentation/admin-guide/aoe/udev.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Documentation/admin-guide/aoe/udev.txt b/Documentation/admin-guide/aoe/udev.txt index 5fb756466bc7..d55ecb411c21 100644 --- a/Documentation/admin-guide/aoe/udev.txt +++ b/Documentation/admin-guide/aoe/udev.txt @@ -2,7 +2,7 @@ # They may be installed along the following lines. Check the section # 8 udev manpage to see whether your udev supports SUBSYSTEM, and # whether it uses one or two equal signs for SUBSYSTEM and KERNEL. -# +# # ecashin@makki ~$ su # Password: # bash# find /etc -type f -name udev.conf @@ -13,7 +13,7 @@ # 10-wacom.rules 50-udev.rules # bash# cp /path/to/linux/Documentation/admin-guide/aoe/udev.txt \ # /etc/udev/rules.d/60-aoe.rules -# +# # aoe char devices SUBSYSTEM=="aoe", KERNEL=="discover", NAME="etherd/%k", GROUP="disk", MODE="0220" @@ -22,5 +22,5 @@ SUBSYSTEM=="aoe", KERNEL=="interfaces", NAME="etherd/%k", GROUP="disk", MODE="02 SUBSYSTEM=="aoe", KERNEL=="revalidate", NAME="etherd/%k", GROUP="disk", MODE="0220" SUBSYSTEM=="aoe", KERNEL=="flush", NAME="etherd/%k", GROUP="disk", MODE="0220" -# aoe block devices +# aoe block devices KERNEL=="etherd*", GROUP="disk" From 4fff5db420fef91d439f87f6c0d439ef291b3dd2 Mon Sep 17 00:00:00 2001 From: Kim Tae Hyun Date: Sat, 2 Aug 2025 21:58:01 +0900 Subject: [PATCH 017/193] docs: update physical memory documentation by adding N_GENERIC_INITIATOR to enum node_states While reading physical_memory.rst, I noticed that N_GENERIC_INITIATOR has not been update from the node_states list, even though it's already added in commit 894c26a1c274b8eafbb4b1dad67e70e51a106061. Signed-off-by: Kim Tae Hyun Acked-by: Mike Rapoport (Microsoft) Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250802125801.10068-1-kimth0312@gmail.com --- Documentation/mm/physical_memory.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Documentation/mm/physical_memory.rst b/Documentation/mm/physical_memory.rst index 9af11b5bd145..b76183545e5b 100644 --- a/Documentation/mm/physical_memory.rst +++ b/Documentation/mm/physical_memory.rst @@ -171,6 +171,8 @@ nodes with particular properties as defined by ``enum node_states``: The node has memory(regular, high, movable) ``N_CPU`` The node has one or more CPUs +``N_GENERIC_INITIATOR`` + The node has one or more Generic Initiators For each node that has a property described above, the bit corresponding to the node ID in the ``node_states[]`` bitmask is set. From 7069b5296e968d0e7d5fd6b825f221f0d766f3ea Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=A0t=C4=9Bp=C3=A1n=20N=C4=9Bmec?= Date: Tue, 29 Jul 2025 20:40:36 +0200 Subject: [PATCH 018/193] docs: admin-guide: update to current minimum pipe size default MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The pipe size limit used when the fs.pipe-user-pages-soft sysctl value is reached was increased from one to two pages in commit 46c4c9d1beb7; update the documentation to match the new reality. Fixes: 46c4c9d1beb7 ("pipe: increase minimum default pipe size to 2 pages") Signed-off-by: Štěpán Němec Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250729-pipedoc-v2-1-18b8e735a9c6@smrk.net --- Documentation/admin-guide/sysctl/fs.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/admin-guide/sysctl/fs.rst b/Documentation/admin-guide/sysctl/fs.rst index 6c54718c9d04..9b7f65c3efd8 100644 --- a/Documentation/admin-guide/sysctl/fs.rst +++ b/Documentation/admin-guide/sysctl/fs.rst @@ -164,8 +164,8 @@ pipe-user-pages-soft -------------------- Maximum total number of pages a non-privileged user may allocate for pipes -before the pipe size gets limited to a single page. Once this limit is reached, -new pipes will be limited to a single page in size for this user in order to +before the pipe size gets limited to two pages. Once this limit is reached, +new pipes will be limited to two pages in size for this user in order to limit total memory usage, and trying to increase them using ``fcntl()`` will be denied until usage goes below the limit again. The default value allows to allocate up to 1024 pipes at their default size. When set to 0, no limit is From 1f590377eb3c2680cb1101fa1a6a1f20a5fc4002 Mon Sep 17 00:00:00 2001 From: Ranganath V N Date: Sat, 26 Jul 2025 12:06:44 +0530 Subject: [PATCH 019/193] Documentation: Fix minor typos Corrected a few spelling errors and improved the phrasing changes since v1: --corrected as per review Signed-off-by: Ranganath V N Reviewed-by: Randy Dunlap Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250726063645.4156-1-vnranganath.20@gmail.com --- Documentation/arch/loongarch/irq-chip-model.rst | 4 ++-- Documentation/arch/x86/cpuinfo.rst | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/Documentation/arch/loongarch/irq-chip-model.rst b/Documentation/arch/loongarch/irq-chip-model.rst index a7ecce11e445..8f5c3345109e 100644 --- a/Documentation/arch/loongarch/irq-chip-model.rst +++ b/Documentation/arch/loongarch/irq-chip-model.rst @@ -139,13 +139,13 @@ Feature EXTIOI_HAS_INT_ENCODE is part of standard EIOINTC. If it is 1, it indicates that CPU Interrupt Pin selection can be normal method rather than bitmap method, so interrupt can be routed to IP0 - IP15. -Feature EXTIOI_HAS_CPU_ENCODE is entension of V-EIOINTC. If it is 1, it +Feature EXTIOI_HAS_CPU_ENCODE is extension of V-EIOINTC. If it is 1, it indicates that CPU selection can be normal method rather than bitmap method, so interrupt can be routed to CPU0 - CPU255. EXTIOI_VIRT_CONFIG ------------------ -This register is read-write register, for compatibility intterupt routed uses +This register is read-write register, for compatibility interrupt routed uses the default method which is the same with standard EIOINTC. If the bit is set with 1, it indicated HW to use normal method rather than bitmap method. diff --git a/Documentation/arch/x86/cpuinfo.rst b/Documentation/arch/x86/cpuinfo.rst index dd8b7806944e..9f2e47c4b1c8 100644 --- a/Documentation/arch/x86/cpuinfo.rst +++ b/Documentation/arch/x86/cpuinfo.rst @@ -11,7 +11,7 @@ The list of feature flags in /proc/cpuinfo is not complete and represents an ill-fated attempt from long time ago to put feature flags in an easy to find place for userspace. -However, the amount of feature flags is growing by the CPU generation, +However, the number of feature flags is growing with each CPU generation, leading to unparseable and unwieldy /proc/cpuinfo. What is more, those feature flags do not even need to be in that file From 2115dc3e3376b7bd5021950b45eebbcd992e9be9 Mon Sep 17 00:00:00 2001 From: Bart Van Assche Date: Thu, 24 Jul 2025 08:34:42 -0700 Subject: [PATCH 020/193] docs: filesystems: sysfs: Recommend sysfs_emit() for new code only The advantages of converting existing sysfs show() methods to sysfs_emit() and sysfs_emit_at() do not outweigh the risk of introducing bugs. Hence recommend sysfs_emit() and sysfs_emit_at() only for new implementations of show() methods. Cc: Greg Kroah-Hartman Cc: James Bottomley Cc: Martin K. Petersen Signed-off-by: Bart Van Assche Reviewed-by: Martin K. Petersen Acked-by: Greg Kroah-Hartman Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250724153449.2433395-1-bvanassche@acm.org --- Documentation/filesystems/sysfs.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/filesystems/sysfs.rst b/Documentation/filesystems/sysfs.rst index c32993bc83c7..624e4f51212e 100644 --- a/Documentation/filesystems/sysfs.rst +++ b/Documentation/filesystems/sysfs.rst @@ -243,8 +243,8 @@ Other notes: - show() methods should return the number of bytes printed into the buffer. -- show() should only use sysfs_emit() or sysfs_emit_at() when formatting - the value to be returned to user space. +- New implementations of show() methods should only use sysfs_emit() or + sysfs_emit_at() when formatting the value to be returned to user space. - store() should return the number of bytes used from the buffer. If the entire buffer has been used, just return the count argument. From 6bed0a50235aaeae2c33f3cfee5ffa5d040be570 Mon Sep 17 00:00:00 2001 From: Dongliang Mu Date: Tue, 12 Aug 2025 13:07:10 +0800 Subject: [PATCH 021/193] MAINTAINERS: add File entry for scripts/checktransupdate.py to DOCUMENTATION As suggested by Nathan, add a File entry for scripts/checktransupdate.py to the DOCUMENTATION section to maintain this script. Link: https://lore.kernel.org/all/20250811212446.GA924610@ax162/ Signed-off-by: Dongliang Mu Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250812050711.2515173-1-dzm91@hust.edu.cn --- MAINTAINERS | 1 + 1 file changed, 1 insertion(+) diff --git a/MAINTAINERS b/MAINTAINERS index 39d5e4e09273..dafc11712544 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -7302,6 +7302,7 @@ P: Documentation/doc-guide/maintainer-profile.rst T: git git://git.lwn.net/linux.git docs-next F: Documentation/ F: scripts/check-variable-fonts.sh +F: scripts/checktransupdate.py F: scripts/documentation-file-ref-check F: scripts/get_abi.py F: scripts/kernel-doc* From 0e6bb6888791656c3973f26da3288323524573c0 Mon Sep 17 00:00:00 2001 From: Gopi Krishna Menon Date: Mon, 11 Aug 2025 05:23:44 +0530 Subject: [PATCH 022/193] docs: folio_queue: Fix minor typo in folio_queue page Specifically, fix typo 'hese'-> 'these' Signed-off-by: Gopi Krishna Menon Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250810235346.4153-1-krishnagopi487@gmail.com --- Documentation/core-api/folio_queue.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/core-api/folio_queue.rst b/Documentation/core-api/folio_queue.rst index 83cfbc157e49..b7628896d2b6 100644 --- a/Documentation/core-api/folio_queue.rst +++ b/Documentation/core-api/folio_queue.rst @@ -44,7 +44,7 @@ Each segment in the list also stores: * the size of each folio and * three 1-bit marks per folio, -but hese should not be accessed directly as the underlying data structure may +but these should not be accessed directly as the underlying data structure may change, but rather the access functions outlined below should be used. The facility can be made accessible by:: From 70d476b63a1494337f2b9fec1e9b1cab2e6116d3 Mon Sep 17 00:00:00 2001 From: Gopi Krishna Menon Date: Sun, 10 Aug 2025 16:42:48 +0530 Subject: [PATCH 023/193] Documentation/rv: Fix minor typo in monitor_synthesis page Specifically, fix spelling of "practice" Signed-off-by: Gopi Krishna Menon Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250810111249.93181-1-krishnagopi487@gmail.com --- Documentation/trace/rv/monitor_synthesis.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/trace/rv/monitor_synthesis.rst b/Documentation/trace/rv/monitor_synthesis.rst index ac808a7554f5..3a7d7b2f6cb6 100644 --- a/Documentation/trace/rv/monitor_synthesis.rst +++ b/Documentation/trace/rv/monitor_synthesis.rst @@ -181,7 +181,7 @@ which is the list of atomic propositions present in the LTL specification functions interacting with the Buchi automaton. While generating code, `rvgen` cannot understand the meaning of the atomic -propositions. Thus, that task is left for manual work. The recommended pratice +propositions. Thus, that task is left for manual work. The recommended practice is adding tracepoints to places where the atomic propositions change; and in the tracepoints' handlers: the Buchi automaton is executed using:: From a49eebfa8ba1a90cbe01371f852b8da805d3aa55 Mon Sep 17 00:00:00 2001 From: Akshaykumar Gunari Date: Thu, 7 Aug 2025 20:21:19 +0530 Subject: [PATCH 024/193] docs: arm: stm32: fix typo "busses" -> "buses" Fix the spelling of "busses" to the preferred form "buses" in STM32 ARM architecture documentation. Signed-off-by: Akshaykumar Gunari Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250807145119.2214-1-akshaygunari@gmail.com --- Documentation/arch/arm/stm32/stm32f746-overview.rst | 2 +- Documentation/arch/arm/stm32/stm32f769-overview.rst | 2 +- Documentation/arch/arm/stm32/stm32h743-overview.rst | 2 +- Documentation/arch/arm/stm32/stm32h750-overview.rst | 2 +- Documentation/arch/arm/stm32/stm32mp13-overview.rst | 2 +- Documentation/arch/arm/stm32/stm32mp151-overview.rst | 2 +- 6 files changed, 6 insertions(+), 6 deletions(-) diff --git a/Documentation/arch/arm/stm32/stm32f746-overview.rst b/Documentation/arch/arm/stm32/stm32f746-overview.rst index 78befddc7740..335f0855a858 100644 --- a/Documentation/arch/arm/stm32/stm32f746-overview.rst +++ b/Documentation/arch/arm/stm32/stm32f746-overview.rst @@ -15,7 +15,7 @@ It features: - SD/MMC/SDIO support - Ethernet controller - USB OTFG FS & HS controllers -- I2C, SPI, CAN busses support +- I2C, SPI, CAN buses support - Several 16 & 32 bits general purpose timers - Serial Audio interface - LCD controller diff --git a/Documentation/arch/arm/stm32/stm32f769-overview.rst b/Documentation/arch/arm/stm32/stm32f769-overview.rst index e482980ddf21..ef31aadee68f 100644 --- a/Documentation/arch/arm/stm32/stm32f769-overview.rst +++ b/Documentation/arch/arm/stm32/stm32f769-overview.rst @@ -15,7 +15,7 @@ It features: - SD/MMC/SDIO support*2 - Ethernet controller - USB OTFG FS & HS controllers -- I2C*4, SPI*6, CAN*3 busses support +- I2C*4, SPI*6, CAN*3 buses support - Several 16 & 32 bits general purpose timers - Serial Audio interface*2 - LCD controller diff --git a/Documentation/arch/arm/stm32/stm32h743-overview.rst b/Documentation/arch/arm/stm32/stm32h743-overview.rst index 4e15f1a42730..7659df24d362 100644 --- a/Documentation/arch/arm/stm32/stm32h743-overview.rst +++ b/Documentation/arch/arm/stm32/stm32h743-overview.rst @@ -15,7 +15,7 @@ It features: - SD/MMC/SDIO support - Ethernet controller - USB OTFG FS & HS controllers -- I2C, SPI, CAN busses support +- I2C, SPI, CAN buses support - Several 16 & 32 bits general purpose timers - Serial Audio interface - LCD controller diff --git a/Documentation/arch/arm/stm32/stm32h750-overview.rst b/Documentation/arch/arm/stm32/stm32h750-overview.rst index 0e51235c9547..be032b77d1f1 100644 --- a/Documentation/arch/arm/stm32/stm32h750-overview.rst +++ b/Documentation/arch/arm/stm32/stm32h750-overview.rst @@ -15,7 +15,7 @@ It features: - SD/MMC/SDIO support - Ethernet controller - USB OTFG FS & HS controllers -- I2C, SPI, CAN busses support +- I2C, SPI, CAN buses support - Several 16 & 32 bits general purpose timers - Serial Audio interface - LCD controller diff --git a/Documentation/arch/arm/stm32/stm32mp13-overview.rst b/Documentation/arch/arm/stm32/stm32mp13-overview.rst index 3bb9492dad49..b5e9589fb06f 100644 --- a/Documentation/arch/arm/stm32/stm32mp13-overview.rst +++ b/Documentation/arch/arm/stm32/stm32mp13-overview.rst @@ -24,7 +24,7 @@ More details: - ADC/DAC - USB EHCI/OHCI controllers - USB OTG -- I2C, SPI, CAN busses support +- I2C, SPI, CAN buses support - Several general purpose timers - Serial Audio interface - LCD controller diff --git a/Documentation/arch/arm/stm32/stm32mp151-overview.rst b/Documentation/arch/arm/stm32/stm32mp151-overview.rst index f42a2ac309c0..b58c256ede9a 100644 --- a/Documentation/arch/arm/stm32/stm32mp151-overview.rst +++ b/Documentation/arch/arm/stm32/stm32mp151-overview.rst @@ -23,7 +23,7 @@ More details: - ADC/DAC - USB EHCI/OHCI controllers - USB OTG -- I2C, SPI busses support +- I2C, SPI buses support - Several general purpose timers - Serial Audio interface - LCD-TFT controller From 7bb184222e9fa8b839247c3a1cb1bcf628e519a5 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 12 Aug 2025 17:52:18 +0200 Subject: [PATCH 025/193] scripts: sphinx-pre-install: fix version check for Fedora The script is now picking the wrong version. Fix it. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/9d1e5c9906534e2bae586f891770066346463146.1754992972.git.mchehab+huawei@kernel.org --- scripts/sphinx-pre-install | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index 3f8d6925e896..07234d482fa8 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -413,7 +413,7 @@ sub give_redhat_hints() my $old = 0; my $rel; my $noto_sans_redhat = "google-noto-sans-cjk-ttc-fonts"; - $rel = $1 if ($system_release =~ /(release|Linux)\s+(\d+)/); + $rel = $2 if ($system_release =~ /(release|Linux)\s+(\d+)/); if (!($system_release =~ /Fedora/)) { $map{"virtualenv"} = "python-virtualenv"; From a9c50a51e0129057dbaf58fbaf7ba1a8a69e9b21 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 12 Aug 2025 17:52:19 +0200 Subject: [PATCH 026/193] scripts: sphinx-pre-install: rename it to scripts/sphinx-pre-install.pl That helps us to later replace the scripts. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/08d9a32a5aaf3784fef016594efe505d7c5a2697.1754992972.git.mchehab+huawei@kernel.org --- Documentation/Makefile | 14 +++++++------- .../{sphinx-pre-install => sphinx-pre-install.pl} | 0 2 files changed, 7 insertions(+), 7 deletions(-) rename scripts/{sphinx-pre-install => sphinx-pre-install.pl} (100%) diff --git a/Documentation/Makefile b/Documentation/Makefile index b98477df5ddf..c486fe3cc5e1 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -46,7 +46,7 @@ ifeq ($(HAVE_SPHINX),0) .DEFAULT: $(warning The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed and in PATH, or set the SPHINXBUILD make variable to point to the full path of the '$(SPHINXBUILD)' executable.) @echo - @$(srctree)/scripts/sphinx-pre-install + @$(srctree)/scripts/sphinx-pre-install.pl @echo " SKIP Sphinx $@ target." else # HAVE_SPHINX @@ -121,7 +121,7 @@ $(YNL_RST_DIR)/%.rst: $(YNL_YAML_DIR)/%.yaml $(YNL_TOOL) htmldocs texinfodocs latexdocs epubdocs xmldocs: $(YNL_INDEX) htmldocs: - @$(srctree)/scripts/sphinx-pre-install --version-check + @$(srctree)/scripts/sphinx-pre-install.pl --version-check @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var))) # If Rust support is available and .config exists, add rustdoc generated contents. @@ -135,7 +135,7 @@ endif endif texinfodocs: - @$(srctree)/scripts/sphinx-pre-install --version-check + @$(srctree)/scripts/sphinx-pre-install.pl --version-check @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,texinfo,$(var),texinfo,$(var))) # Note: the 'info' Make target is generated by sphinx itself when @@ -147,7 +147,7 @@ linkcheckdocs: @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,linkcheck,$(var),,$(var))) latexdocs: - @$(srctree)/scripts/sphinx-pre-install --version-check + @$(srctree)/scripts/sphinx-pre-install.pl --version-check @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,latex,$(var),latex,$(var))) ifeq ($(HAVE_PDFLATEX),0) @@ -160,7 +160,7 @@ else # HAVE_PDFLATEX pdfdocs: DENY_VF = XDG_CONFIG_HOME=$(FONTS_CONF_DENY_VF) pdfdocs: latexdocs - @$(srctree)/scripts/sphinx-pre-install --version-check + @$(srctree)/scripts/sphinx-pre-install.pl --version-check $(foreach var,$(SPHINXDIRS), \ $(MAKE) PDFLATEX="$(PDFLATEX)" LATEXOPTS="$(LATEXOPTS)" $(DENY_VF) -C $(BUILDDIR)/$(var)/latex || sh $(srctree)/scripts/check-variable-fonts.sh || exit; \ mkdir -p $(BUILDDIR)/$(var)/pdf; \ @@ -170,11 +170,11 @@ pdfdocs: latexdocs endif # HAVE_PDFLATEX epubdocs: - @$(srctree)/scripts/sphinx-pre-install --version-check + @$(srctree)/scripts/sphinx-pre-install.pl --version-check @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,epub,$(var),epub,$(var))) xmldocs: - @$(srctree)/scripts/sphinx-pre-install --version-check + @$(srctree)/scripts/sphinx-pre-install.pl --version-check @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,xml,$(var),xml,$(var))) endif # HAVE_SPHINX diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install.pl similarity index 100% rename from scripts/sphinx-pre-install rename to scripts/sphinx-pre-install.pl From ca9087f50772aa5794dd655ff5a0719dd4b83b1f Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 12 Aug 2025 17:52:20 +0200 Subject: [PATCH 027/193] scripts: sphinx-pre-install: Convert script to Python Port scripts/sphinx-pre-install to Python. That allows a better maintainance of the file. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/8d236079545aff796900bde4cdaaf79411d04074.1754992972.git.mchehab+huawei@kernel.org --- scripts/sphinx-pre-install.py | 1102 +++++++++++++++++++++++++++++++++ 1 file changed, 1102 insertions(+) create mode 100755 scripts/sphinx-pre-install.py diff --git a/scripts/sphinx-pre-install.py b/scripts/sphinx-pre-install.py new file mode 100755 index 000000000000..dcee2181b72f --- /dev/null +++ b/scripts/sphinx-pre-install.py @@ -0,0 +1,1102 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: GPL-2.0-or-later +# Copyright (c) 2017-2025 Mauro Carvalho Chehab +# +# pylint: disable=C0103,C0114,C0115,C0116,C0301 +# pylint: disable=R0902,R0904,R0912,R0915,R1705,R1710,E1121 + + +import argparse +import os +import re +import subprocess +import sys +from glob import glob + + +def parse_version(version): + """Convert a major.minor.patch version into a tuple""" +# + return tuple(int(x) for x in version.split(".")) + + +def ver_str(version): + """Returns a version tuple as major.minor.patch""" + + return ".".join([str(x) for x in version]) + + +RECOMMENDED_VERSION = parse_version("3.4.3") + + +class SphinxDependencyChecker: + # List of required texlive packages on Fedora and OpenSuse + texlive = { + "amsfonts.sty": "texlive-amsfonts", + "amsmath.sty": "texlive-amsmath", + "amssymb.sty": "texlive-amsfonts", + "amsthm.sty": "texlive-amscls", + "anyfontsize.sty": "texlive-anyfontsize", + "atbegshi.sty": "texlive-oberdiek", + "bm.sty": "texlive-tools", + "capt-of.sty": "texlive-capt-of", + "cmap.sty": "texlive-cmap", + "ctexhook.sty": "texlive-ctex", + "ecrm1000.tfm": "texlive-ec", + "eqparbox.sty": "texlive-eqparbox", + "eu1enc.def": "texlive-euenc", + "fancybox.sty": "texlive-fancybox", + "fancyvrb.sty": "texlive-fancyvrb", + "float.sty": "texlive-float", + "fncychap.sty": "texlive-fncychap", + "footnote.sty": "texlive-mdwtools", + "framed.sty": "texlive-framed", + "luatex85.sty": "texlive-luatex85", + "multirow.sty": "texlive-multirow", + "needspace.sty": "texlive-needspace", + "palatino.sty": "texlive-psnfss", + "parskip.sty": "texlive-parskip", + "polyglossia.sty": "texlive-polyglossia", + "tabulary.sty": "texlive-tabulary", + "threeparttable.sty": "texlive-threeparttable", + "titlesec.sty": "texlive-titlesec", + "ucs.sty": "texlive-ucs", + "upquote.sty": "texlive-upquote", + "wrapfig.sty": "texlive-wrapfig", + } + + def __init__(self, args): + self.pdf = args.pdf + self.virtualenv = args.virtualenv + self.version_check = args.version_check + + self.missing = {} + + self.need = 0 + self.optional = 0 + self.need_symlink = 0 + self.need_sphinx = 0 + self.need_pip = 0 + self.need_virtualenv = 0 + self.rec_sphinx_upgrade = 0 + self.verbose_warn_install = 1 + + self.system_release = "" + self.install = "" + self.virtenv_dir = "" + self.python_cmd = "" + self.activate_cmd = "" + + self.min_version = (0, 0, 0) + self.cur_version = (0, 0, 0) + self.latest_avail_ver = (0, 0, 0) + self.venv_ver = (0, 0, 0) + + prefix = os.environ.get("srctree", ".") + "/" + + self.conf = prefix + "Documentation/conf.py" + self.requirement_file = prefix + "Documentation/sphinx/requirements.txt" + self.virtenv_prefix = ["sphinx_", "Sphinx_" ] + + # + # Ancillary methods that don't depend on self + # + + @staticmethod + def which(prog): + for path in os.environ.get("PATH", "").split(":"): + full_path = os.path.join(path, prog) + if os.access(full_path, os.X_OK): + return full_path + + return None + + @staticmethod + def find_python_no_venv(): + # FIXME: does it makes sense now that this script is in Python? + + result = subprocess.run(["pwd"], capture_output=True, text=True) + cur_dir = result.stdout.strip() + + python_names = ["python3", "python"] + + for d in os.environ.get("PATH", "").split(":"): + if f"{cur_dir}/sphinx" in d: + continue + + for p in python_names: + if os.access(os.path.join(d, p), os.X_OK): + return os.path.join(d, p) + + # Python not found at the PATH + return python_names[-1] + + @staticmethod + def run(*args, **kwargs): + """Excecute a command, hiding its output by default""" + + if not kwargs.get('capture_output', False): + if 'stdout' not in kwargs: + kwargs['stdout'] = subprocess.DEVNULL + if 'stderr' not in kwargs: + kwargs['stderr'] = subprocess.DEVNULL + + return subprocess.run(*args, **kwargs) + + # + # Methods to check if a feature exists + # + + # Note: is_optional has 3 states: + # - 0: mandatory + # - 1: optional, but nice to have + # - 2: LaTeX optional - pdf builds without it, but may have visual impact + + def check_missing(self, progs): + for prog, is_optional in sorted(self.missing.items()): + # At least on some LTS distros like CentOS 7, texlive doesn't + # provide all packages we need. When such distros are + # detected, we have to disable PDF output. + # + # So, we need to ignore the packages that distros would + # need for LaTeX to work + if is_optional == 2 and not self.pdf: + self.optional -= 1 + continue + + if self.verbose_warn_install: + if is_optional: + print(f'Warning: better to also install "{prog}".') + else: + print(f'ERROR: please install "{prog}", otherwise, build won\'t work.') + + self.install += " " + progs.get(prog, prog) + + self.install = self.install.lstrip() + + def add_package(self, package, is_optional): + self.missing[package] = is_optional + if is_optional: + self.optional += 1 + else: + self.need += 1 + + def check_missing_file(self, files, package, is_optional): + for f in files: + if os.path.exists(f): + return + self.add_package(package, is_optional) + + def check_program(self, prog, is_optional): + found = self.which(prog) + if found: + return found + + self.add_package(prog, is_optional) + + return None + + def check_perl_module(self, prog, is_optional): + # While testing with lxc download template, one of the + # distros (Oracle) didn't have perl - nor even an option to install + # before installing oraclelinux-release-el9 package. + # + # Check it before running an error. If perl is not there, + # add it as a mandatory package, as some parts of the doc builder + # needs it. + if not self.which("perl"): + self.add_package("perl", 0) + self.add_package(prog, is_optional) + return + + try: + self.run(["perl", f"-M{prog}", "-e", "1"], check=True) + except subprocess.CalledProcessError: + self.add_package(prog, is_optional) + + def check_python_module(self, module, is_optional): + # FIXME: is it needed at the Python version? Maybe due to venv? + if not self.python_cmd: + return + + try: + self.run([self.python_cmd, "-c", f"import {module}"], check=True) + except subprocess.CalledProcessError: + self.add_package(module, is_optional) + + def check_rpm_missing(self, pkgs, is_optional): + for prog in pkgs: + try: + self.run(["rpm", "-q", prog], check=True) + except subprocess.CalledProcessError: + self.add_package(prog, is_optional) + + def check_pacman_missing(self, pkgs, is_optional): + for prog in pkgs: + try: + self.run(["pacman", "-Q", prog], check=True) + except subprocess.CalledProcessError: + self.add_package(prog, is_optional) + + def check_missing_tex(self, is_optional): + kpsewhich = self.which("kpsewhich") + for prog, package in self.texlive.items(): + + # If kpsewhich is not there, just add it to deps + if not kpsewhich: + self.add_package(package, is_optional) + continue + + # Check if the package is needed + try: + result = self.run( + [kpsewhich, prog], stdout=subprocess.PIPE, text=True, check=True + ) + + # Didn't find. Add it + if not result.stdout.strip(): + self.add_package(package, is_optional) + + except subprocess.CalledProcessError: + # kpsewhich returned an error. Add it, just in case + self.add_package(package, is_optional) + + def get_sphinx_fname(self): + if "SPHINXBUILD" in os.environ: + return os.environ["SPHINXBUILD"] + + fname = "sphinx-build" + if self.which(fname): + return fname + + fname = "sphinx-build-3" + if self.which(fname): + self.need_symlink = 1 + return fname + + return "" + + def get_sphinx_version(self, cmd): + try: + result = self.run([cmd, "--version"], + stdout=subprocess.PIPE, + stderr=subprocess.STDOUT, + text=True, check=True) + except (subprocess.CalledProcessError, FileNotFoundError): + return None + + for line in result.stdout.split("\n"): + match = re.match(r"^sphinx-build\s+([\d\.]+)(?:\+(?:/[\da-f]+)|b\d+)?\s*$", line) + if match: + return parse_version(match.group(1)) + + match = re.match(r"^Sphinx.*\s+([\d\.]+)\s*$", line) + if match: + return parse_version(match.group(1)) + + def check_sphinx(self): + try: + with open(self.conf, "r", encoding="utf-8") as f: + for line in f: + match = re.match(r"^\s*needs_sphinx\s*=\s*[\'\"]([\d\.]+)[\'\"]", line) + if match: + self.min_version = parse_version(match.group(1)) + break + except IOError: + sys.exit(f"Can't open {self.conf}") + + if not self.min_version: + sys.exit(f"Can't get needs_sphinx version from {self.conf}") + + self.virtenv_dir = self.virtenv_prefix[0] + "latest" + + sphinx = self.get_sphinx_fname() + if not sphinx: + self.need_sphinx = 1 + return + + self.cur_version = self.get_sphinx_version(sphinx) + if not self.cur_version: + sys.exit(f"{sphinx} didn't return its version") + + if self.cur_version < self.min_version: + curver = ver_str(self.cur_version) + minver = ver_str(self.min_version) + + print(f"ERROR: Sphinx version is {curver}. It should be >= {minver}") + self.need_sphinx = 1 + return + + # On version check mode, just assume Sphinx has all mandatory deps + if self.version_check and self.cur_version >= RECOMMENDED_VERSION: + sys.exit(0) + + def catcheck(self, filename): + if os.path.exists(filename): + with open(filename, "r", encoding="utf-8") as f: + return f.read().strip() + return "" + + # + # Distro-specific hints methods + # + + def give_debian_hints(self): + progs = { + "Pod::Usage": "perl-modules", + "convert": "imagemagick", + "dot": "graphviz", + "ensurepip": "python3-venv", + "python-sphinx": "python3-sphinx", + "rsvg-convert": "librsvg2-bin", + "virtualenv": "virtualenv", + "xelatex": "texlive-xetex", + "yaml": "python3-yaml", + } + + if self.pdf: + pdf_pkgs = { + "texlive-lang-chinese": [ + "/usr/share/texlive/texmf-dist/tex/latex/ctex/ctexhook.sty", + ], + "fonts-dejavu": [ + "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf", + ], + "fonts-noto-cjk": [ + "/usr/share/fonts/noto-cjk/NotoSansCJK-Regular.ttc", + "/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc", + "/usr/share/fonts/opentype/noto/NotoSerifCJK-Regular.ttc", + ], + } + + for package, files in pdf_pkgs.items(): + self.check_missing_file(files, package, 2) + + self.check_program("dvipng", 2) + + self.check_missing(progs) + + if not self.need and not self.optional: + return + + if self.verbose_warn_install: + print("You should run:") + print(f"\n\tsudo apt-get install {self.install}") + + def give_redhat_hints(self): + progs = { + "Pod::Usage": "perl-Pod-Usage", + "convert": "ImageMagick", + "dot": "graphviz", + "python-sphinx": "python3-sphinx", + "rsvg-convert": "librsvg2-tools", + "virtualenv": "python3-virtualenv", + "xelatex": "texlive-xetex-bin", + "yaml": "python3-pyyaml", + } + + fedora26_opt_pkgs = [ + "graphviz-gd", # Fedora 26: needed for PDF support + ] + + fedora_tex_pkgs = [ + "dejavu-sans-fonts", + "dejavu-sans-mono-fonts", + "dejavu-serif-fonts", + "texlive-collection-fontsrecommended", + "texlive-collection-latex", + "texlive-xecjk", + ] + + old = 0 + rel = None + pkg_manager = "dnf" + + match = re.search(r"(release|Linux)\s+(\d+)", self.system_release) + if match: + rel = int(match.group(2)) + + if not rel: + print("Couldn't identify release number") + old = 1 + self.pdf = False + elif re.search("Fedora", self.system_release): + # Fedora 38 and upper use this CJK font + + noto_sans_redhat = "google-noto-sans-cjk-fonts" + else: + # Almalinux, CentOS, RHEL, ... + + # at least up to version 9 (and Fedora < 38), that's the CJK font + noto_sans_redhat = "google-noto-sans-cjk-ttc-fonts" + + progs["virtualenv"] = "python-virtualenv" + + if rel and rel < 8: + old = 1 + self.pdf = False + + # RHEL 7 is in ELS, currently up to Jun, 2026 + + print("Note: texlive packages on RHEL/CENTOS <= 7 are incomplete. Can't support PDF output") + print("If you want to build PDF, please read:") + print("\thttps://www.systutorials.com/241660/how-to-install-tex-live-on-centos-7-linux/") + + if self.pdf: + pdf_pkgs = [ + "/usr/share/fonts/google-noto-cjk/NotoSansCJK-Regular.ttc", + "/usr/share/fonts/google-noto-sans-cjk-fonts/NotoSansCJK-Regular.ttc", + ] + + self.check_missing_file(pdf_pkgs, noto_sans_redhat, 2) + + if not old: + self.check_rpm_missing(fedora26_opt_pkgs, 2) + self.check_rpm_missing(fedora_tex_pkgs, 2) + + self.check_missing_tex(2) + + self.check_missing(progs) + + if not self.need and not self.optional: + return + + if self.verbose_warn_install: + print("You should run:") + + if old: + # dnf is there since Fedora 18+ and RHEL 8 + pkg_manager = "yum" + + print(f"\n\tsudo {pkg_manager} install -y {self.install}") + + def give_opensuse_hints(self): + progs = { + "Pod::Usage": "perl-Pod-Usage", + "convert": "ImageMagick", + "dot": "graphviz", + "python-sphinx": "python3-sphinx", + "virtualenv": "python3-virtualenv", + "xelatex": "texlive-xetex-bin", + "yaml": "python3-pyyaml", + } + + # On Tumbleweed, this package is also named rsvg-convert + if not re.search(r"Tumbleweed", self.system_release): + progs["rsvg-convert"] = "rsvg-view" + + suse_tex_pkgs = [ + "texlive-babel-english", + "texlive-caption", + "texlive-colortbl", + "texlive-courier", + "texlive-dvips", + "texlive-helvetic", + "texlive-makeindex", + "texlive-metafont", + "texlive-metapost", + "texlive-palatino", + "texlive-preview", + "texlive-times", + "texlive-zapfchan", + "texlive-zapfding", + ] + + progs["latexmk"] = "texlive-latexmk-bin" + + # FIXME: add support for installing CJK fonts + # + # I tried hard, but was unable to find a way to install + # "Noto Sans CJK SC" on openSUSE + + if self.pdf: + self.check_rpm_missing(suse_tex_pkgs, 2) + if self.pdf: + self.check_missing_tex(2) + self.check_missing(progs) + + if not self.need and not self.optional: + return + + if self.verbose_warn_install: + print("You should run:") + print(f"\n\tsudo zypper install --no-recommends {self.install}") + + def give_mageia_hints(self): + progs = { + "Pod::Usage": "perl-Pod-Usage", + "convert": "ImageMagick", + "dot": "graphviz", + "python-sphinx": "python3-sphinx", + "rsvg-convert": "librsvg2", + "virtualenv": "python3-virtualenv", + "xelatex": "texlive", + "yaml": "python3-yaml", + } + + tex_pkgs = [ + "texlive-fontsextra", + ] + + if re.search(r"OpenMandriva", self.system_release): + packager_cmd = "dnf install" + noto_sans = "noto-sans-cjk-fonts" + tex_pkgs = ["texlive-collection-fontsextra"] + else: + packager_cmd = "urpmi" + noto_sans = "google-noto-sans-cjk-ttc-fonts" + + progs["latexmk"] = "texlive-collection-basic" + + if self.pdf: + pdf_pkgs = [ + "/usr/share/fonts/google-noto-cjk/NotoSansCJK-Regular.ttc", + "/usr/share/fonts/TTF/NotoSans-Regular.ttf", + ] + + self.check_missing_file(pdf_pkgs, noto_sans, 2) + self.check_rpm_missing(tex_pkgs, 2) + + self.check_missing(progs) + + if not self.need and not self.optional: + return + if self.verbose_warn_install: + print("You should run:") + print(f"\n\tsudo {packager_cmd} {self.install}") + + def give_arch_linux_hints(self): + progs = { + "convert": "imagemagick", + "dot": "graphviz", + "latexmk": "texlive-core", + "rsvg-convert": "extra/librsvg", + "virtualenv": "python-virtualenv", + "xelatex": "texlive-xetex", + "yaml": "python-yaml", + } + + archlinux_tex_pkgs = [ + "texlive-core", + "texlive-latexextra", + "ttf-dejavu", + ] + + if self.pdf: + self.check_pacman_missing(archlinux_tex_pkgs, 2) + + self.check_missing_file( + ["/usr/share/fonts/noto-cjk/NotoSansCJK-Regular.ttc"], + "noto-fonts-cjk", + 2, + ) + + self.check_missing(progs) + + if not self.need and not self.optional: + return + if self.verbose_warn_install: + print("You should run:") + print(f"\n\tsudo pacman -S {self.install}") + + def give_gentoo_hints(self): + progs = { + "convert": "media-gfx/imagemagick", + "dot": "media-gfx/graphviz", + "rsvg-convert": "gnome-base/librsvg", + "virtualenv": "dev-python/virtualenv", + "xelatex": "dev-texlive/texlive-xetex media-fonts/dejavu", + "yaml": "dev-python/pyyaml", + } + + if self.pdf: + pdf_pkgs = { + "media-fonts/dejavu": [ + "/usr/share/fonts/dejavu/DejaVuSans.ttf", + ], + "media-fonts/noto-cjk": [ + "/usr/share/fonts/noto-cjk/NotoSansCJKsc-Regular.otf", + "/usr/share/fonts/noto-cjk/NotoSerifCJK-Regular.ttc", + ], + } + for package, files in pdf_pkgs.items(): + self.check_missing_file(files, package, 2) + + self.check_missing(progs) + + if not self.need and not self.optional: + return + + if self.verbose_warn_install: + print("You should run:") + print("\n") + + imagemagick = "media-gfx/imagemagick svg png" + cairo = "media-gfx/graphviz cairo pdf" + portage_imagemagick = "/etc/portage/package.use/imagemagick" + portage_cairo = "/etc/portage/package.use/graphviz" + + result = self.run(["grep", "imagemagick", portage_imagemagick], + stdout=subprocess.PIPE, text=True) + if not result.stdout.strip(): + print(f"\tsudo su -c 'echo \"{imagemagick}\" > {portage_imagemagick}'") + + result = self.run(["grep", "graphviz", portage_cairo], + stdout=subprocess.PIPE, text=True) + + if not result.stdout.strip(): + print(f"\tsudo su -c 'echo \"{cairo}\" > {portage_cairo}'") + + print(f"\tsudo emerge --ask {self.install}") + + # + # Dispatch the check to an os_specific hinter + # + + def check_distros(self): + # OS-specific hints logic + os_hints = { + re.compile("Red Hat Enterprise Linux"): self.give_redhat_hints, + re.compile("Fedora"): self.give_redhat_hints, + re.compile("AlmaLinux"): self.give_redhat_hints, + re.compile("Amazon Linux"): self.give_redhat_hints, + re.compile("CentOS"): self.give_redhat_hints, + re.compile("openEuler"): self.give_redhat_hints, + re.compile("Oracle Linux Server"): self.give_redhat_hints, + re.compile("Rocky Linux"): self.give_redhat_hints, + re.compile("Scientific Linux"): self.give_redhat_hints, + re.compile("Springdale Open Enterprise"): self.give_redhat_hints, + + re.compile("Ubuntu"): self.give_debian_hints, + re.compile("Debian"): self.give_debian_hints, + re.compile("Devuan"): self.give_debian_hints, + re.compile("Kali"): self.give_debian_hints, + re.compile("Mint"): self.give_debian_hints, + + re.compile("openSUSE"): self.give_opensuse_hints, + + re.compile("Mageia"): self.give_mageia_hints, + re.compile("OpenMandriva"): self.give_mageia_hints, + + re.compile("Arch Linux"): self.give_arch_linux_hints, + re.compile("Gentoo"): self.give_gentoo_hints, + } + + # If the OS is detected, use per-OS hint logic + for regex, os_hint in os_hints.items(): + if regex.search(self.system_release): + os_hint() + + return + + # + # Fall-back to generic hint code for other distros + # That's far from ideal, specially for LaTeX dependencies. + # + progs = {"sphinx-build": "sphinx"} + if self.pdf: + self.check_missing_tex(2) + + self.check_missing(progs) + + print(f"I don't know distro {self.system_release}.") + print("So, I can't provide you a hint with the install procedure.") + print("There are likely missing dependencies.") + + # + # Common dependencies + # + def deactivate_help(self): + print("\n If you want to exit the virtualenv, you can use:") + print("\tdeactivate") + + def get_virtenv(self): + cwd = os.getcwd() + + activates = [] + + # Add all sphinx prefixes with possible version numbers + for p in self.virtenv_prefix: + activates += glob(f"{cwd}/{p}[0-9]*/bin/activate") + + activates.sort(reverse=True, key=str.lower) + + # Place sphinx_latest first, if it exists + for p in self.virtenv_prefix: + activates = glob(f"{cwd}/{p}*latest/bin/activate") + activates + + ver = (0, 0, 0) + for f in activates: + # Discard too old Sphinx virtual environments + match = re.search(r"(\d+)\.(\d+)\.(\d+)", f) + if match: + ver = (int(match.group(1)), int(match.group(2)), int(match.group(3))) + + if ver < self.min_version: + continue + + sphinx_cmd = f.replace("activate", "sphinx-build") + if not os.path.isfile(sphinx_cmd): + continue + + ver = self.get_sphinx_version(sphinx_cmd) + + if not ver: + venv_dir = f.replace("/bin/activate", "") + print(f"Warning: virtual environment {venv_dir} is not working.\n" \ + "Python version upgrade? Remove it with:\n\n" \ + "\trm -rf {venv_dir}\n\n") + else: + if self.need_sphinx and ver >= self.min_version: + return (f, ver) + elif parse_version(ver) > self.cur_version: + return (f, ver) + + return ("", ver) + + def recommend_sphinx_upgrade(self): + # Avoid running sphinx-builds from venv if cur_version is good + if self.cur_version and self.cur_version >= RECOMMENDED_VERSION: + self.latest_avail_ver = self.cur_version + return None + + # Get the highest version from sphinx_*/bin/sphinx-build and the + # corresponding command to activate the venv/virtenv + self.activate_cmd, self.venv_ver = self.get_virtenv() + + # Store the highest version from Sphinx existing virtualenvs + if self.activate_cmd and self.venv_ver > self.cur_version: + self.latest_avail_ver = self.venv_ver + else: + if self.cur_version: + self.latest_avail_ver = self.cur_version + else: + self.latest_avail_ver = (0, 0, 0) + + # As we don't know package version of Sphinx, and there's no + # virtual environments, don't check if upgrades are needed + if not self.virtualenv: + if not self.latest_avail_ver: + return None + + return self.latest_avail_ver + + # Either there are already a virtual env or a new one should be created + self.need_pip = 1 + + if not self.latest_avail_ver: + return None + + # Return if the reason is due to an upgrade or not + if self.latest_avail_ver != (0, 0, 0): + if self.latest_avail_ver < RECOMMENDED_VERSION: + self.rec_sphinx_upgrade = 1 + + return self.latest_avail_ver + + def recommend_sphinx_version(self, virtualenv_cmd): + # The logic here is complex, as it have to deal with different versions: + # - minimal supported version; + # - minimal PDF version; + # - recommended version. + # It also needs to work fine with both distro's package and venv/virtualenv + + # Version is OK. Nothing to do. + if self.cur_version != (0, 0, 0) and self.cur_version >= RECOMMENDED_VERSION: + return + + if not self.need_sphinx: + # sphinx-build is present and its version is >= $min_version + + # only recommend enabling a newer virtenv version if makes sense. + if self.latest_avail_ver and self.latest_avail_ver > self.cur_version: + print("\nYou may also use the newer Sphinx version {self.latest_avail_ver} with:") + if f"{self.virtenv_prefix}" in os.getcwd(): + print("\tdeactivate") + print(f"\t. {self.activate_cmd}") + self.deactivate_help() + return + + if self.latest_avail_ver and self.latest_avail_ver >= RECOMMENDED_VERSION: + return + + if not self.virtualenv: + # No sphinx either via package or via virtenv. As we can't + # Compare the versions here, just return, recommending the + # user to install it from the package distro. + if not self.latest_avail_ver or self.latest_avail_ver == (0, 0, 0): + return + + # User doesn't want a virtenv recommendation, but he already + # installed one via virtenv with a newer version. + # So, print commands to enable it + if self.latest_avail_ver > self.cur_version: + print("\nYou may also use the Sphinx virtualenv version {self.latest_avail_ver} with:") + if f"{self.virtenv_prefix}" in os.getcwd(): + print("\tdeactivate") + print(f"\t. {self.activate_cmd}") + self.deactivate_help() + return + print("\n") + else: + if self.need_sphinx: + self.need += 1 + + # Suggest newer versions if current ones are too old + if self.latest_avail_ver and self.latest_avail_ver >= self.min_version: + if self.latest_avail_ver >= RECOMMENDED_VERSION: + print("\nNeed to activate Sphinx (version {self.latest_avail_ver}) on virtualenv with:") + print(f"\t. {self.activate_cmd}") + self.deactivate_help() + return + + # Version is above the minimal required one, but may be + # below the recommended one. So, print warnings/notes + if self.latest_avail_ver < RECOMMENDED_VERSION: + print(f"Warning: It is recommended at least Sphinx version {RECOMMENDED_VERSION}.") + + # At this point, either it needs Sphinx or upgrade is recommended, + # both via pip + + if self.rec_sphinx_upgrade: + if not self.virtualenv: + print("Instead of install/upgrade Python Sphinx pkg, you could use pip/pypi with:\n\n") + else: + print("To upgrade Sphinx, use:\n\n") + else: + print("\nSphinx needs to be installed either:\n1) via pip/pypi with:\n") + + self.python_cmd = self.find_python_no_venv() + + print(f"\t{virtualenv_cmd} {self.virtenv_dir}") + print(f"\t. {self.virtenv_dir}/bin/activate") + print(f"\tpip install -r {self.requirement_file}") + self.deactivate_help() + + print("\n2) As a package with:") + + old_need = self.need + old_optional = self.optional + self.missing = {} + self.pdf = False + self.optional = 0 + self.install = "" + old_verbose = self.verbose_warn_install + self.verbose_warn_install = 0 + + self.add_package("python-sphinx", 0) + + self.check_distros() + + self.need = old_need + self.optional = old_optional + self.verbose_warn_install = old_verbose + + print("\n" \ + " Please note that Sphinx >= 3.0 will currently produce false-positive\n" \ + " warning when the same name is used for more than one type (functions,\n" \ + " structs, enums,...). This is known Sphinx bug. For more details, see:\n" \ + "\thttps://github.com/sphinx-doc/sphinx/pull/8313") + + def check_needs(self): + self.get_system_release() + + # Check if Sphinx is already accessible from current environment + self.check_sphinx() + + if self.system_release: + print(f"Detected OS: {self.system_release}.") + else: + print("Unknown OS") + if self.cur_version != (0, 0, 0): + ver = ver_str(self.cur_version) + print(f"Sphinx version: {ver}\n") + + # FIXME: Check python command line, trying first python3 + self.python_cmd = self.which("python3") + if not self.python_cmd: + self.python_cmd = self.check_program("python", 0) + + # Check the type of virtual env, depending on Python version + if self.python_cmd: + if self.virtualenv: + try: + result = self.run( + [self.python_cmd, "--version"], + capture_output=True, + text=True, + check=True, + ) + + output = result.stdout + result.stderr + + match = re.search(r"(\d+)\.(\d+)\.", output) + if match: + major = int(match.group(1)) + minor = int(match.group(2)) + + if major < 3: + sys.exit("Python 3 is required to build the kernel docs") + if major == 3 and minor < 3: + self.need_virtualenv = True + else: + sys.exit(f"Warning: couldn't identify {self.python_cmd} version!") + + except subprocess.CalledProcessError as e: + sys.exit(f"Error checking Python version: {e}") + else: + self.add_package("python-sphinx", 0) + + self.venv_ver = self.recommend_sphinx_upgrade() + + virtualenv_cmd = "" + + if self.need_pip: + # Set virtualenv command line, if python < 3.3 + # FIXME: can be removed as we're now with an upper min requirement + # but then we need to check python version + if self.need_virtualenv: + virtualenv_cmd = self.which("virtualenv-3") + if not virtualenv_cmd: + virtualenv_cmd = self.which("virtualenv-3.5") + if not virtualenv_cmd: + self.check_program("virtualenv", 0) + virtualenv_cmd = "virtualenv" + else: + virtualenv_cmd = f"{self.python_cmd} -m venv" + self.check_python_module("ensurepip", 0) + + # Check for needed programs/tools + self.check_perl_module("Pod::Usage", 0) + self.check_python_module("yaml", 0) + self.check_program("make", 0) + self.check_program("gcc", 0) + self.check_program("dot", 1) + self.check_program("convert", 1) + + if self.pdf: + # Extra PDF files - should use 2 for LaTeX is_optional + self.check_program("xelatex", 2) + self.check_program("rsvg-convert", 2) + self.check_program("latexmk", 2) + + # Do distro-specific checks and output distro-install commands + self.check_distros() + + if not self.python_cmd: + if self.need == 1: + sys.exit("Can't build as 1 mandatory dependency is missing") + elif self.need: + sys.exit(f"Can't build as {self.need} mandatory dependencies are missing") + + # Check if sphinx-build is called sphinx-build-3 + if self.need_symlink: + sphinx_path = self.which("sphinx-build-3") + if sphinx_path: + print(f"\tsudo ln -sf {sphinx_path} /usr/bin/sphinx-build\n") + + self.recommend_sphinx_version(virtualenv_cmd) + print("") + + if not self.optional: + print("All optional dependencies are met.") + + if self.need == 1: + sys.exit("Can't build as 1 mandatory dependency is missing") + elif self.need: + sys.exit(f"Can't build as {self.need} mandatory dependencies are missing") + + print("Needed package dependencies are met.") + + def get_system_release(self): + """ + Determine the system type. There's no unique way that would work + with all distros with a minimal package install. So, several + methods are used here. + + By default, it will use lsb_release function. If not available, it will + fail back to reading the known different places where the distro name + is stored. + + Several modern distros now have /etc/os-release, which usually have + a decent coverage. + """ + + if self.which("lsb_release"): + result = self.run(["lsb_release", "-d"], capture_output=True, text=True) + self.system_release = result.stdout.replace("Description:", "").strip() + + release_files = [ + "/etc/system-release", + "/etc/redhat-release", + "/etc/lsb-release", + "/etc/gentoo-release", + ] + + if not self.system_release: + for f in release_files: + self.system_release = self.catcheck(f) + if self.system_release: + break + + # This seems more common than LSB these days + if not self.system_release: + os_var = {} + try: + with open("/etc/os-release", "r", encoding="utf-8") as f: + for line in f: + match = re.match(r"^([\w\d\_]+)=\"?([^\"]*)\"?\n", line) + if match: + os_var[match.group(1)] = match.group(2) + + self.system_release = os_var.get("NAME", "") + if "VERSION_ID" in os_var: + self.system_release += " " + os_var["VERSION_ID"] + elif "VERSION" in os_var: + self.system_release += " " + os_var["VERSION"] + except IOError: + pass + + if not self.system_release: + self.system_release = self.catcheck("/etc/issue") + + self.system_release = self.system_release.strip() + +DESCRIPTION = """ +Process some flags related to Sphinx installation and documentation build. +""" + + +def main(): + parser = argparse.ArgumentParser(description=DESCRIPTION) + + parser.add_argument( + "--no-virtualenv", + action="store_false", + dest="virtualenv", + help="Recommend installing Sphinx instead of using a virtualenv", + ) + + parser.add_argument( + "--no-pdf", + action="store_false", + dest="pdf", + help="Don't check for dependencies required to build PDF docs", + ) + + parser.add_argument( + "--version-check", + action="store_true", + dest="version_check", + help="If version is compatible, don't check for missing dependencies", + ) + + args = parser.parse_args() + + checker = SphinxDependencyChecker(args) + + checker.check_needs() + + +if __name__ == "__main__": + main() From 56a8767751c4bd2b93ba8840a78eccae7018d57c Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 12 Aug 2025 17:52:21 +0200 Subject: [PATCH 028/193] scripts: sphinx-pre-install: Make it compatible with Python 3.6 The minimal version requirements we have is 3.9. Yet, the script which detects it is this one. So, let's try supporting an old version here, as we may want to suggest to upgrade Python version to build the docs. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/39d6e27a047bc3cc8208ac5e11fe6ba44faff9c4.1754992972.git.mchehab+huawei@kernel.org --- scripts/sphinx-pre-install.py | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/scripts/sphinx-pre-install.py b/scripts/sphinx-pre-install.py index dcee2181b72f..71d86b230b22 100755 --- a/scripts/sphinx-pre-install.py +++ b/scripts/sphinx-pre-install.py @@ -115,7 +115,8 @@ class SphinxDependencyChecker: def find_python_no_venv(): # FIXME: does it makes sense now that this script is in Python? - result = subprocess.run(["pwd"], capture_output=True, text=True) + result = SphinxDependencyChecker.run(["pwd"], capture_output=True, + text=True) cur_dir = result.stdout.strip() python_names = ["python3", "python"] @@ -135,12 +136,23 @@ class SphinxDependencyChecker: def run(*args, **kwargs): """Excecute a command, hiding its output by default""" - if not kwargs.get('capture_output', False): + capture_output = kwargs.pop('capture_output', False) + + if capture_output: + if 'stdout' not in kwargs: + kwargs['stdout'] = subprocess.PIPE + if 'stderr' not in kwargs: + kwargs['stderr'] = subprocess.PIPE + else: if 'stdout' not in kwargs: kwargs['stdout'] = subprocess.DEVNULL if 'stderr' not in kwargs: kwargs['stderr'] = subprocess.DEVNULL + # Don't break with older Python versions + if 'text' in kwargs and sys.version_info < (3, 7): + kwargs['universal_newlines'] = kwargs.pop('text') + return subprocess.run(*args, **kwargs) # From 728648b6a5faa1d6be1e90c04a71481ba33fd08d Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 12 Aug 2025 17:52:22 +0200 Subject: [PATCH 029/193] scripts: sphinx-pre-install: run on a supported version The scripts/sphinx-pre-install is used to detect problems at the system environment and adjust it to build the Kernel documentation. If the version is too old, it won't run, though. Check if the version which started the script is valid. If not, seek for a new one that is compatible with documentation build. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/76627055a7f82f6a79296ddbd873fa5ac8f82a1d.1754992972.git.mchehab+huawei@kernel.org --- scripts/sphinx-pre-install.py | 65 ++++++++++++++++++++++++++++++++++- 1 file changed, 64 insertions(+), 1 deletion(-) diff --git a/scripts/sphinx-pre-install.py b/scripts/sphinx-pre-install.py index 71d86b230b22..3912359d2bae 100755 --- a/scripts/sphinx-pre-install.py +++ b/scripts/sphinx-pre-install.py @@ -5,6 +5,9 @@ # pylint: disable=C0103,C0114,C0115,C0116,C0301 # pylint: disable=R0902,R0904,R0912,R0915,R1705,R1710,E1121 +# Note: this script requires at least Python 3.6 to run. +# Don't add changes not compatible with it, it is meant to report +# incompatible python versions. import argparse import os @@ -16,7 +19,6 @@ from glob import glob def parse_version(version): """Convert a major.minor.patch version into a tuple""" -# return tuple(int(x) for x in version.split(".")) @@ -27,6 +29,7 @@ def ver_str(version): RECOMMENDED_VERSION = parse_version("3.4.3") +MIN_PYTHON_VERSION = parse_version("3.7") class SphinxDependencyChecker: @@ -132,6 +135,65 @@ class SphinxDependencyChecker: # Python not found at the PATH return python_names[-1] + @staticmethod + def get_python_version(cmd): + + result = SphinxDependencyChecker.run([cmd, "--version"], + capture_output=True, text=True) + version = result.stdout.strip() + + match = re.search(r"(\d+\.\d+\.\d+)", version) + if match: + return parse_version(match.group(1)) + + print(f"Can't parse version {version}") + return (0, 0, 0) + + @staticmethod + def find_python(): + + patterns = [ + "python3.[0-9]", + "python3.[0-9][0-9]", + ] + + new_python_cmd = None + + # Seek for a python binary newer than MIN_PYTHON_VERSION + for path in os.getenv("PATH", "").split(":"): + for pattern in patterns: + for cmd in glob(os.path.join(path, pattern)): + if os.path.isfile(cmd) and os.access(cmd, os.X_OK): + version = SphinxDependencyChecker.get_python_version(cmd) + if version >= MIN_PYTHON_VERSION: + return(cmd) + + @staticmethod + def check_python(): + + cur_ver = sys.version_info[:3] + if cur_ver >= MIN_PYTHON_VERSION: + return + + python_ver = ver_str(cur_ver) + + new_python_cmd = SphinxDependencyChecker.find_python() + if not new_python_cmd: + print(f"ERROR: Python version {python_ver} is not spported anymore") + print(f" Can't find a new version. This script may fail") + return + + # Restart script using the newer version + script_path = os.path.abspath(sys.argv[0]) + args = [new_python_cmd, script_path] + sys.argv[1:] + + print(f"Python {python_ver} not supported. Changing to {new_python_cmd}") + + try: + os.execv(new_python_cmd, args) + except OSError as e: + sys.exit(f"Failed to restart with {new_python_cmd}: {e}") + @staticmethod def run(*args, **kwargs): """Excecute a command, hiding its output by default""" @@ -1107,6 +1169,7 @@ def main(): checker = SphinxDependencyChecker(args) + checker.check_python() checker.check_needs() From ea5dd67722c1ac8ae65ae5a9390452931890f52e Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 12 Aug 2025 17:52:23 +0200 Subject: [PATCH 030/193] scripts: sphinx-pre-install: drop obsolete routines Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/afb97854f05b0852f4c6c1fcee102e9697c14cd8.1754992972.git.mchehab+huawei@kernel.org --- scripts/sphinx-pre-install.py | 23 +---------------------- 1 file changed, 1 insertion(+), 22 deletions(-) diff --git a/scripts/sphinx-pre-install.py b/scripts/sphinx-pre-install.py index 3912359d2bae..b639acd455cc 100755 --- a/scripts/sphinx-pre-install.py +++ b/scripts/sphinx-pre-install.py @@ -114,27 +114,6 @@ class SphinxDependencyChecker: return None - @staticmethod - def find_python_no_venv(): - # FIXME: does it makes sense now that this script is in Python? - - result = SphinxDependencyChecker.run(["pwd"], capture_output=True, - text=True) - cur_dir = result.stdout.strip() - - python_names = ["python3", "python"] - - for d in os.environ.get("PATH", "").split(":"): - if f"{cur_dir}/sphinx" in d: - continue - - for p in python_names: - if os.access(os.path.join(d, p), os.X_OK): - return os.path.join(d, p) - - # Python not found at the PATH - return python_names[-1] - @staticmethod def get_python_version(cmd): @@ -940,7 +919,7 @@ class SphinxDependencyChecker: else: print("\nSphinx needs to be installed either:\n1) via pip/pypi with:\n") - self.python_cmd = self.find_python_no_venv() + self.python_cmd = os.path.abspath(sys.argv[0]) print(f"\t{virtualenv_cmd} {self.virtenv_dir}") print(f"\t. {self.virtenv_dir}/bin/activate") From f25bf12afc03ce88ca82fd2ed67fbee5c1ed0cd8 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 12 Aug 2025 17:52:24 +0200 Subject: [PATCH 031/193] scripts: sphinx-pre-install: drop support for old virtualenv Up to Python 3.2, the virtual environment were created via virtualenv binary. As we dropped support for such old version, clean up the code. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/31afe394bcfd8f7e450263c1922d2c73b91d36d8.1754992972.git.mchehab+huawei@kernel.org --- scripts/sphinx-pre-install.py | 69 +++++++++-------------------------- 1 file changed, 18 insertions(+), 51 deletions(-) diff --git a/scripts/sphinx-pre-install.py b/scripts/sphinx-pre-install.py index b639acd455cc..0a73b1b33842 100755 --- a/scripts/sphinx-pre-install.py +++ b/scripts/sphinx-pre-install.py @@ -80,7 +80,6 @@ class SphinxDependencyChecker: self.need_symlink = 0 self.need_sphinx = 0 self.need_pip = 0 - self.need_virtualenv = 0 self.rec_sphinx_upgrade = 0 self.verbose_warn_install = 1 @@ -919,12 +918,14 @@ class SphinxDependencyChecker: else: print("\nSphinx needs to be installed either:\n1) via pip/pypi with:\n") - self.python_cmd = os.path.abspath(sys.argv[0]) - - print(f"\t{virtualenv_cmd} {self.virtenv_dir}") - print(f"\t. {self.virtenv_dir}/bin/activate") - print(f"\tpip install -r {self.requirement_file}") - self.deactivate_help() + if not virtualenv_cmd: + print(" Currently not possible.\n") + print(" Please upgrade Python to a newer version and run this script again") + else: + print(f"\t{virtualenv_cmd} {self.virtenv_dir}") + print(f"\t. {self.virtenv_dir}/bin/activate") + print(f"\tpip install -r {self.requirement_file}") + self.deactivate_help() print("\n2) As a package with:") @@ -953,6 +954,7 @@ class SphinxDependencyChecker: def check_needs(self): self.get_system_release() + self.python_cmd = sys.executable # Check if Sphinx is already accessible from current environment self.check_sphinx() @@ -965,56 +967,21 @@ class SphinxDependencyChecker: ver = ver_str(self.cur_version) print(f"Sphinx version: {ver}\n") - # FIXME: Check python command line, trying first python3 - self.python_cmd = self.which("python3") - if not self.python_cmd: - self.python_cmd = self.check_program("python", 0) - # Check the type of virtual env, depending on Python version - if self.python_cmd: - if self.virtualenv: - try: - result = self.run( - [self.python_cmd, "--version"], - capture_output=True, - text=True, - check=True, - ) + virtualenv_cmd = None - output = result.stdout + result.stderr - - match = re.search(r"(\d+)\.(\d+)\.", output) - if match: - major = int(match.group(1)) - minor = int(match.group(2)) - - if major < 3: - sys.exit("Python 3 is required to build the kernel docs") - if major == 3 and minor < 3: - self.need_virtualenv = True - else: - sys.exit(f"Warning: couldn't identify {self.python_cmd} version!") - - except subprocess.CalledProcessError as e: - sys.exit(f"Error checking Python version: {e}") - else: - self.add_package("python-sphinx", 0) + if sys.version_info < MIN_PYTHON_VERSION: + min_ver = ver_str(MIN_PYTHON_VERSION) + print(f"ERROR: at least python {min_ver} is required to build the kernel docs") + self.need_sphinx = 1 self.venv_ver = self.recommend_sphinx_upgrade() - virtualenv_cmd = "" - if self.need_pip: - # Set virtualenv command line, if python < 3.3 - # FIXME: can be removed as we're now with an upper min requirement - # but then we need to check python version - if self.need_virtualenv: - virtualenv_cmd = self.which("virtualenv-3") - if not virtualenv_cmd: - virtualenv_cmd = self.which("virtualenv-3.5") - if not virtualenv_cmd: - self.check_program("virtualenv", 0) - virtualenv_cmd = "virtualenv" + if sys.version_info < MIN_PYTHON_VERSION: + self.need_pip = False + print("Warning: python version is not supported.") + else: virtualenv_cmd = f"{self.python_cmd} -m venv" self.check_python_module("ensurepip", 0) From 2cb4877b74349e33be9e209fbcce6114c9a38b9f Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 12 Aug 2025 17:52:25 +0200 Subject: [PATCH 032/193] scripts: sphinx-pre-install: Address issues with OpenSUSE Leap 15.x On openSUSE Leap 15.6, which is the current LTS version, has two Sphinx packages. The normal one requires Python 3.6, which we don't support anymore. However, it also has Python 3.11 with a newer Sphinx version (7.2.6). Suggest the newer version: Detected OS: openSUSE Leap 15.6. ERROR: at least python 3.7 is required to build the kernel docs Warning: python version is not supported. Warning: better to also install "convert". Warning: better to also install "dot". ERROR: please install "yaml", otherwise, build won't work. You should run: sudo zypper install --no-recommends ImageMagick graphviz python311-pyyaml Sphinx needs to be installed either: 1) via pip/pypi with: Currently not possible. Please upgrade Python to a newer version and run this script again 2) As a package with: sudo zypper install --no-recommends python311-Sphinx Please note that Sphinx >= 3.0 will currently produce false-positive warning when the same name is used for more than one type (functions, structs, enums,...). This is known Sphinx bug. For more details, see: https://github.com/sphinx-doc/sphinx/pull/8313 Can't build as 2 mandatory dependencies are missing Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/a1600e292b63f96f40163e350238812158ebd6c2.1754992972.git.mchehab+huawei@kernel.org --- scripts/sphinx-pre-install.py | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/scripts/sphinx-pre-install.py b/scripts/sphinx-pre-install.py index 0a73b1b33842..eca42d90ed01 100755 --- a/scripts/sphinx-pre-install.py +++ b/scripts/sphinx-pre-install.py @@ -556,6 +556,22 @@ class SphinxDependencyChecker: progs["latexmk"] = "texlive-latexmk-bin" + match = re.search(r"(Leap)\s+(\d+).(\d)", self.system_release) + if match: + rel = int(match.group(2)) + + # Leap 15.x uses Python 3.6, which is not compatible with + # the build system anymore. Suggest Python 3.11 + if rel == 15: + if not self.which(self.python_cmd): + self.add_package(self.python_cmd, 0) + + progs.update({ + "python-sphinx": "python311-Sphinx", + "virtualenv": "python311-virtualenv", + "yaml": "python311-pyyaml", + }) + # FIXME: add support for installing CJK fonts # # I tried hard, but was unable to find a way to install From c5ffae0fa965884d09458002e3d990c039602809 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 12 Aug 2025 17:52:26 +0200 Subject: [PATCH 033/193] scripts: sphinx-pre-install: fix opensuse Leap hint for PyYAML On Leap, the name of the package is python311-PyYAML. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/0266c5e28e136c62de33d2d7f7d5e69b273e0d01.1754992972.git.mchehab+huawei@kernel.org --- scripts/sphinx-pre-install.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/sphinx-pre-install.py b/scripts/sphinx-pre-install.py index eca42d90ed01..65438c198674 100755 --- a/scripts/sphinx-pre-install.py +++ b/scripts/sphinx-pre-install.py @@ -569,7 +569,7 @@ class SphinxDependencyChecker: progs.update({ "python-sphinx": "python311-Sphinx", "virtualenv": "python311-virtualenv", - "yaml": "python311-pyyaml", + "yaml": "python311-PyYAML", }) # FIXME: add support for installing CJK fonts From 582b0f95c92e0a0ec79d23ed434786251bd4378b Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 12 Aug 2025 17:52:27 +0200 Subject: [PATCH 034/193] scripts: sphinx-pre-install: fix support for gentoo Some gentoo packages have changes. Fix it. While here, improve emerge portage use logic. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/283987633aae7d99e0eff41e24eb6285c1b6b335.1754992972.git.mchehab+huawei@kernel.org --- scripts/sphinx-pre-install.py | 35 ++++++++++++++++------------------- 1 file changed, 16 insertions(+), 19 deletions(-) diff --git a/scripts/sphinx-pre-install.py b/scripts/sphinx-pre-install.py index 65438c198674..b793796329c8 100755 --- a/scripts/sphinx-pre-install.py +++ b/scripts/sphinx-pre-install.py @@ -669,12 +669,13 @@ class SphinxDependencyChecker: def give_gentoo_hints(self): progs = { - "convert": "media-gfx/imagemagick", - "dot": "media-gfx/graphviz", - "rsvg-convert": "gnome-base/librsvg", - "virtualenv": "dev-python/virtualenv", - "xelatex": "dev-texlive/texlive-xetex media-fonts/dejavu", - "yaml": "dev-python/pyyaml", + "convert": "media-gfx/imagemagick", + "dot": "media-gfx/graphviz", + "rsvg-convert": "gnome-base/librsvg", + "virtualenv": "dev-python/virtualenv", + "xelatex": "dev-texlive/texlive-xetex media-fonts/dejavu", + "yaml": "dev-python/pyyaml", + "python-sphinx": "dev-python/sphinx", } if self.pdf: @@ -699,21 +700,17 @@ class SphinxDependencyChecker: print("You should run:") print("\n") - imagemagick = "media-gfx/imagemagick svg png" - cairo = "media-gfx/graphviz cairo pdf" - portage_imagemagick = "/etc/portage/package.use/imagemagick" - portage_cairo = "/etc/portage/package.use/graphviz" - result = self.run(["grep", "imagemagick", portage_imagemagick], - stdout=subprocess.PIPE, text=True) - if not result.stdout.strip(): - print(f"\tsudo su -c 'echo \"{imagemagick}\" > {portage_imagemagick}'") + portages = [ + "media-gfx/imagemagick", + "media-gfx/graphviz", + ] - result = self.run(["grep", "graphviz", portage_cairo], - stdout=subprocess.PIPE, text=True) - - if not result.stdout.strip(): - print(f"\tsudo su -c 'echo \"{cairo}\" > {portage_cairo}'") + for p in portages: + result = self.run(["grep", p, "/etc/portage/package.use/*"], + stdout=subprocess.PIPE, text=True) + if not result.stdout.strip(): + print(f"\tsudo emerge -av1 {p}") print(f"\tsudo emerge --ask {self.install}") From 94a161d998a103346088d97da6d1cfec4df97ddc Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 12 Aug 2025 17:52:28 +0200 Subject: [PATCH 035/193] scripts: sphinx-pre-install: Address issues with OpenSUSE Tumbleweed On Tumbleweed, package names are named after python-313*, as it also has older python versions on it. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/fe0b5f7c18d7b32e0229c0890371e1441ffea294.1754992972.git.mchehab+huawei@kernel.org --- scripts/sphinx-pre-install.py | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/scripts/sphinx-pre-install.py b/scripts/sphinx-pre-install.py index b793796329c8..0e165ad05fdb 100755 --- a/scripts/sphinx-pre-install.py +++ b/scripts/sphinx-pre-install.py @@ -571,6 +571,14 @@ class SphinxDependencyChecker: "virtualenv": "python311-virtualenv", "yaml": "python311-PyYAML", }) + else: + # Tumbleweed defaults to Python 3.11 + + progs.update({ + "python-sphinx": "python313-Sphinx", + "virtualenv": "python313-virtualenv", + "yaml": "python313-PyYAML", + }) # FIXME: add support for installing CJK fonts # From 12bdcf898977172a93fc30668f8918da83c51f86 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 12 Aug 2025 17:52:29 +0200 Subject: [PATCH 036/193] scripts: sphinx-pre-install: only show portage hints once On gentoo, doesn't repeat instructions about how to enable portage. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/d4e7ef1d5e1f0412eb9f9ae4913dc64c0821e002.1754992972.git.mchehab+huawei@kernel.org --- scripts/sphinx-pre-install.py | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/scripts/sphinx-pre-install.py b/scripts/sphinx-pre-install.py index 0e165ad05fdb..808d31bfa790 100755 --- a/scripts/sphinx-pre-install.py +++ b/scripts/sphinx-pre-install.py @@ -89,6 +89,9 @@ class SphinxDependencyChecker: self.python_cmd = "" self.activate_cmd = "" + # Certain hints are meant to be shown only once + self.first_hint = True + self.min_version = (0, 0, 0) self.cur_version = (0, 0, 0) self.latest_avail_ver = (0, 0, 0) @@ -714,11 +717,14 @@ class SphinxDependencyChecker: "media-gfx/graphviz", ] - for p in portages: - result = self.run(["grep", p, "/etc/portage/package.use/*"], - stdout=subprocess.PIPE, text=True) - if not result.stdout.strip(): - print(f"\tsudo emerge -av1 {p}") + if self.first_hint: + for p in portages: + result = self.run(["grep", p, "/etc/portage/package.use/*"], + stdout=subprocess.PIPE, text=True) + if not result.stdout.strip(): + print(f"\tsudo emerge -av1 {p}") + + self.first_hint = False print(f"\tsudo emerge --ask {self.install}") From 8f6f54c464d7fccfb8da46ca0afcb0860e6d73bb Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 12 Aug 2025 17:52:30 +0200 Subject: [PATCH 037/193] scripts: sphinx-pre-install: cleanup rhel support Rhel < 8.0 is not supported anymore. Drop support for it. Rhel 8 is problematic: at least on the tests I did with a docker repo, it didn't work, but it could be due to the issue that it is actually different than a real One. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/62fe8ab243ad39f4964f1f74b965e43dc8f10e23.1754992972.git.mchehab+huawei@kernel.org --- scripts/sphinx-pre-install.py | 26 +++++++++++++++++++++----- 1 file changed, 21 insertions(+), 5 deletions(-) diff --git a/scripts/sphinx-pre-install.py b/scripts/sphinx-pre-install.py index 808d31bfa790..42f55e67256d 100755 --- a/scripts/sphinx-pre-install.py +++ b/scripts/sphinx-pre-install.py @@ -487,15 +487,31 @@ class SphinxDependencyChecker: progs["virtualenv"] = "python-virtualenv" - if rel and rel < 8: + if not rel or rel < 8: old = 1 self.pdf = False - # RHEL 7 is in ELS, currently up to Jun, 2026 + print("ERROR: Distro not supported. Too old?") + return + + # TODO: check if RHEL8 still works. + # On my tests with docker "redhat/ubi8" image, there's no + # python3-sphinx (or similar) package. It comes with Python 3.6, + # but there are other python packages over there, so it may be + # possible to work with venv. + + if self.first_hint: + print("Note: RHEL-based distros typically require extra repositories.\n" \ + "For most, enabling epel and crb are enough:\n" \ + "\tsudo dnf install -y epel-release", \ + "\tsudo dnf config-manager --set-enabled crb\n" \ + "Yet, some may have other required repositories. Those commands could be useful:" \ + "\tsudo dnf repolist all" \ + "\tsudo repoquery --available --info ", + "\tsudo dnf config-manager --set-enabled '*' # enable all - probably not what you want") + + self.first_hint = False - print("Note: texlive packages on RHEL/CENTOS <= 7 are incomplete. Can't support PDF output") - print("If you want to build PDF, please read:") - print("\thttps://www.systutorials.com/241660/how-to-install-tex-live-on-centos-7-linux/") if self.pdf: pdf_pkgs = [ From 637fa6b38113fddca7da2f0507f709f46a44047a Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 12 Aug 2025 17:52:31 +0200 Subject: [PATCH 038/193] scripts: sphinx-pre-install: output Python and docutils version Specially when debugging issues, knowing the versions is important. Add it to the script output. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/96142ec916b9064c859b200639c3595115080322.1754992972.git.mchehab+huawei@kernel.org --- scripts/sphinx-pre-install.py | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/scripts/sphinx-pre-install.py b/scripts/sphinx-pre-install.py index 42f55e67256d..de5bcfd052b5 100755 --- a/scripts/sphinx-pre-install.py +++ b/scripts/sphinx-pre-install.py @@ -154,6 +154,20 @@ class SphinxDependencyChecker: cur_ver = sys.version_info[:3] if cur_ver >= MIN_PYTHON_VERSION: + ver = ver_str(cur_ver) + print(f"Python version: {ver}") + + # This could be useful for debugging purposes + if SphinxDependencyChecker.which("docutils"): + result = SphinxDependencyChecker.run(["docutils", "--version"], + capture_output=True, text=True) + ver = result.stdout.strip() + match = re.search(r"(\d+\.\d+\.\d+)", ver) + if match: + ver = match.group(1) + + print(f"Docutils version: {ver}") + return python_ver = ver_str(cur_ver) From cccc5389811a34eccbd0f531c89d284f1cebdd70 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 12 Aug 2025 17:52:32 +0200 Subject: [PATCH 039/193] scripts: sphinx-pre-install: add a missing f-string marker I forgot one f-string marker, with turned to be affecting 3 lines, because of cut-and-paste ;-) Use the proper f-string marker to print Sphinx version at the hint lines. Yet, we don't want to print as a tuple, so call ver_str() for it. Ideally, we would be placing it directly at the f-string, but Python 3.6 f-string support was pretty much limited. Only 3.12 (PEP 701) makes it similar to Perl, allowing expressions inside it. It sounds that function call itself was introduced on 3.7. As we explicitly want this one to run on 3.6, as latest Leap comes with it, we can't use function calls on f-string. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/b0ad1795446b17a00ba2dd83f366e784253668e6.1754992972.git.mchehab+huawei@kernel.org --- scripts/sphinx-pre-install.py | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/scripts/sphinx-pre-install.py b/scripts/sphinx-pre-install.py index de5bcfd052b5..6a244105f7ef 100755 --- a/scripts/sphinx-pre-install.py +++ b/scripts/sphinx-pre-install.py @@ -914,12 +914,15 @@ class SphinxDependencyChecker: if self.cur_version != (0, 0, 0) and self.cur_version >= RECOMMENDED_VERSION: return + if self.latest_avail_ver: + latest_avail_ver = ver_str(self.latest_avail_ver) + if not self.need_sphinx: # sphinx-build is present and its version is >= $min_version # only recommend enabling a newer virtenv version if makes sense. if self.latest_avail_ver and self.latest_avail_ver > self.cur_version: - print("\nYou may also use the newer Sphinx version {self.latest_avail_ver} with:") + print(f"\nYou may also use the newer Sphinx version {latest_avail_ver} with:") if f"{self.virtenv_prefix}" in os.getcwd(): print("\tdeactivate") print(f"\t. {self.activate_cmd}") @@ -940,7 +943,7 @@ class SphinxDependencyChecker: # installed one via virtenv with a newer version. # So, print commands to enable it if self.latest_avail_ver > self.cur_version: - print("\nYou may also use the Sphinx virtualenv version {self.latest_avail_ver} with:") + print(f"\nYou may also use the Sphinx virtualenv version {latest_avail_ver} with:") if f"{self.virtenv_prefix}" in os.getcwd(): print("\tdeactivate") print(f"\t. {self.activate_cmd}") @@ -954,7 +957,7 @@ class SphinxDependencyChecker: # Suggest newer versions if current ones are too old if self.latest_avail_ver and self.latest_avail_ver >= self.min_version: if self.latest_avail_ver >= RECOMMENDED_VERSION: - print("\nNeed to activate Sphinx (version {self.latest_avail_ver}) on virtualenv with:") + print(f"\nNeed to activate Sphinx (version {latest_avail_ver}) on virtualenv with:") print(f"\t. {self.activate_cmd}") self.deactivate_help() return From 8b18e86f6c0063e33096bf84ffcd9fb9ced4844d Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 12 Aug 2025 17:52:33 +0200 Subject: [PATCH 040/193] scripts: sphinx-pre-install: fix Leap support for rsvg-convert There is a test logic meant to be for Leap, renaming rsvg-convert package. Well, at least on latest Leap releases, this is wrong, causing install to fail. Drop it. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/6fcc94533d860e2f6f4f2c7d6ceb6cca70f48bb6.1754992972.git.mchehab+huawei@kernel.org --- scripts/sphinx-pre-install.py | 4 ---- 1 file changed, 4 deletions(-) diff --git a/scripts/sphinx-pre-install.py b/scripts/sphinx-pre-install.py index 6a244105f7ef..6b5f9eda91bb 100755 --- a/scripts/sphinx-pre-install.py +++ b/scripts/sphinx-pre-install.py @@ -566,10 +566,6 @@ class SphinxDependencyChecker: "yaml": "python3-pyyaml", } - # On Tumbleweed, this package is also named rsvg-convert - if not re.search(r"Tumbleweed", self.system_release): - progs["rsvg-convert"] = "rsvg-view" - suse_tex_pkgs = [ "texlive-babel-english", "texlive-caption", From e53e6d395fe036bb2c24dc79dc728e9a82ee0b82 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 12 Aug 2025 17:52:34 +0200 Subject: [PATCH 041/193] scripts: sphinx-pre-install: fix rhel recomendations Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/393a299a850ba9d94c6a8965e78db4da2dbf7e37.1754992972.git.mchehab+huawei@kernel.org --- scripts/sphinx-pre-install.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/scripts/sphinx-pre-install.py b/scripts/sphinx-pre-install.py index 6b5f9eda91bb..1f64909953b9 100755 --- a/scripts/sphinx-pre-install.py +++ b/scripts/sphinx-pre-install.py @@ -519,9 +519,9 @@ class SphinxDependencyChecker: "For most, enabling epel and crb are enough:\n" \ "\tsudo dnf install -y epel-release", \ "\tsudo dnf config-manager --set-enabled crb\n" \ - "Yet, some may have other required repositories. Those commands could be useful:" \ - "\tsudo dnf repolist all" \ - "\tsudo repoquery --available --info ", + "Yet, some may have other required repositories. Those commands could be useful:\n" \ + "\tsudo dnf repolist all\n" \ + "\tsudo dnf repoquery --available --info \n", "\tsudo dnf config-manager --set-enabled '*' # enable all - probably not what you want") self.first_hint = False From 42e3f9f360e70bea4ee7d4e895f042d86ee11500 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 12 Aug 2025 17:52:35 +0200 Subject: [PATCH 042/193] scripts: sphinx-pre-install: remove Scientific Linux According with its website: https://scientificlinux.org/ Scientific Linux reached end of life in June 30, 2024. Also, it was based on RHEL 7, which is not compatible with our build system anymore. So, drop support for it. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/dde5e0c95017022840f8a522ce44759e51f52aa1.1754992972.git.mchehab+huawei@kernel.org --- scripts/sphinx-pre-install.py | 1 - 1 file changed, 1 deletion(-) diff --git a/scripts/sphinx-pre-install.py b/scripts/sphinx-pre-install.py index 1f64909953b9..cd9c83b17971 100755 --- a/scripts/sphinx-pre-install.py +++ b/scripts/sphinx-pre-install.py @@ -769,7 +769,6 @@ class SphinxDependencyChecker: re.compile("openEuler"): self.give_redhat_hints, re.compile("Oracle Linux Server"): self.give_redhat_hints, re.compile("Rocky Linux"): self.give_redhat_hints, - re.compile("Scientific Linux"): self.give_redhat_hints, re.compile("Springdale Open Enterprise"): self.give_redhat_hints, re.compile("Ubuntu"): self.give_debian_hints, From 1a7da749f18335d7996df3004225ca7418a1052d Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 12 Aug 2025 17:52:36 +0200 Subject: [PATCH 043/193] scripts: sphinx-pre-install: improve Gentoo package deps logic It took me a lot of time, but I guess understand now what it takes to install a package on Gentoo. Handling dependencies is a nightmare, as Gentoo refuses to emerge some packages if there's no package.use file describing them. To make it worse, compilation flags shall also be present there for some packages. If USE is not perfect, error/warning messages like those are shown: gnome-base/librsvg dev-texlive/texlive-xetex media-fonts/dejavu dev-python/pyyaml ... !!! The following binary packages have been ignored due to non matching USE: =media-gfx/graphviz-12.2.1-r1 X pdf -python_single_target_python3_13 qt6 svg =media-gfx/graphviz-12.2.1-r1 X pdf python_single_target_python3_12 -python_single_target_python3_13 qt6 svg =media-gfx/graphviz-12.2.1-r1 X pdf qt6 svg =media-gfx/graphviz-12.2.1-r1 X pdf -python_single_target_python3_10 qt6 svg =media-gfx/graphviz-12.2.1-r1 X pdf -python_single_target_python3_10 python_single_target_python3_12 -python_single_target_python3_13 qt6 svg =media-fonts/noto-cjk-20190416 X =app-text/texlive-core-2024-r1 X cjk -xetex =app-text/texlive-core-2024-r1 X -xetex =app-text/texlive-core-2024-r1 -xetex =dev-libs/zziplib-0.13.79-r1 sdl If emerge is allowed, it will simply ignore the above packages, creating an incomplete installation, which will later fail when one tries to build docs with images or build PDFs. After the fix, command line commands to produce the needed USE chain will be emitted, if they don't exist yet. sudo su -c 'echo "media-gfx/graphviz" > /etc/portage/package.use/graphviz' sudo su -c 'echo "media-gfx/imagemagick" > /etc/portage/package.use/imagemagick' sudo su -c 'echo "media-libs/harfbuzz icu" > /etc/portage/package.use/media-libs' sudo su -c 'echo "media-fonts/noto-cjk" > /etc/portage/package.use/media-fonts' sudo su -c 'echo "app-text/texlive-core xetex" > /etc/portage/package.use/texlive' sudo su -c 'echo "dev-libs/zziplib sdl" > /etc/portage/package.use/zziblib' The new logic tries to be smart enough to detect for missing files and missing arguments. Yet, as Gentoo seems to require users to manage those package.use files by hand, the logic isn't perfect: users may still need to verify for conflicts on different use files. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/365fe5e7d568da932dcffde65f48f2c1256cb773.1754992972.git.mchehab+huawei@kernel.org --- scripts/sphinx-pre-install.py | 86 +++++++++++++++++++++++++++++++---- 1 file changed, 76 insertions(+), 10 deletions(-) diff --git a/scripts/sphinx-pre-install.py b/scripts/sphinx-pre-install.py index cd9c83b17971..94f3d2e32fd6 100755 --- a/scripts/sphinx-pre-install.py +++ b/scripts/sphinx-pre-install.py @@ -737,22 +737,88 @@ class SphinxDependencyChecker: print("You should run:") print("\n") + # Handling dependencies is a nightmare, as Gentoo refuses to emerge + # some packages if there's no package.use file describing them. + # To make it worse, compilation flags shall also be present there + # for some packages. If USE is not perfect, error/warning messages + # like those are shown: + # + # !!! The following binary packages have been ignored due to non matching USE: + # + # =media-gfx/graphviz-12.2.1-r1 X pdf -python_single_target_python3_13 qt6 svg + # =media-gfx/graphviz-12.2.1-r1 X pdf python_single_target_python3_12 -python_single_target_python3_13 qt6 svg + # =media-gfx/graphviz-12.2.1-r1 X pdf qt6 svg + # =media-gfx/graphviz-12.2.1-r1 X pdf -python_single_target_python3_10 qt6 svg + # =media-gfx/graphviz-12.2.1-r1 X pdf -python_single_target_python3_10 python_single_target_python3_12 -python_single_target_python3_13 qt6 svg + # =media-fonts/noto-cjk-20190416 X + # =app-text/texlive-core-2024-r1 X cjk -xetex + # =app-text/texlive-core-2024-r1 X -xetex + # =app-text/texlive-core-2024-r1 -xetex + # =dev-libs/zziplib-0.13.79-r1 sdl + # + # And will ignore such packages, installing the remaining ones. That + # affects mostly the image extension and PDF generation. - portages = [ - "media-gfx/imagemagick", - "media-gfx/graphviz", - ] + # Package dependencies and the minimal needed args: + portages = { + "graphviz": "media-gfx/graphviz", + "imagemagick": "media-gfx/imagemagick", + "media-libs": "media-libs/harfbuzz icu", + "media-fonts": "media-fonts/noto-cjk", + "texlive": "app-text/texlive-core xetex", + "zziblib": "dev-libs/zziplib sdl", + } if self.first_hint: - for p in portages: - result = self.run(["grep", p, "/etc/portage/package.use/*"], - stdout=subprocess.PIPE, text=True) - if not result.stdout.strip(): - print(f"\tsudo emerge -av1 {p}") + use_base = "/etc/portage/package.use" + files = glob(f"{use_base}/*") + + for fname, portage in portages.items(): + install = False + + while install == False: + if not files: + # No files under package.usage. Install all + install = True + break + + args = portage.split(" ") + + name = args.pop(0) + + cmd = ["grep", "-l", "-E", rf"^{name}\b" ] + files + result = self.run(cmd, stdout=subprocess.PIPE, text=True) + if result.returncode or not result.stdout.strip(): + # File containing portage name not found + install = True + break + + # Ensure that needed USE flags are present + if args: + match_fname = result.stdout.strip() + with open(match_fname, 'r', encoding='utf8', + errors='backslashreplace') as fp: + for line in fp: + for arg in args: + if arg.startswith("-"): + continue + + if not re.search(rf"\s*{arg}\b", line): + # Needed file argument not found + install = True + break + + # Everything looks ok, don't install + break + + # emit a code to setup missing USE + if install: + print(f"\tsudo su -c 'echo \"{portage}\" > {use_base}/{fname}'") self.first_hint = False - print(f"\tsudo emerge --ask {self.install}") + # Now, we can use emerge and let it respect USE + print(f"\tsudo emerge --ask --changed-use --binpkg-respect-use=y {self.install}") # # Dispatch the check to an os_specific hinter From fb08659be07e646f8103449e02d5e58b32c284d9 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 12 Aug 2025 17:52:37 +0200 Subject: [PATCH 044/193] scripts: sphinx-pre-install: fix OpenMandriva support OpenMandriva Lx 4.3 has different package names for ImageMagick and yaml. Fix them to ensure that system setup will pass. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/0b4e7aa88c96e6a5b8f2e6f381b3e21124680d33.1754992972.git.mchehab+huawei@kernel.org --- scripts/sphinx-pre-install.py | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/scripts/sphinx-pre-install.py b/scripts/sphinx-pre-install.py index 94f3d2e32fd6..2f6036eadc94 100755 --- a/scripts/sphinx-pre-install.py +++ b/scripts/sphinx-pre-install.py @@ -647,6 +647,11 @@ class SphinxDependencyChecker: packager_cmd = "dnf install" noto_sans = "noto-sans-cjk-fonts" tex_pkgs = ["texlive-collection-fontsextra"] + + # Tested on OpenMandriva Lx 4.3 + progs["convert"] = "imagemagick" + progs["yaml"] = "python-pyyaml" + else: packager_cmd = "urpmi" noto_sans = "google-noto-sans-cjk-ttc-fonts" From 1ad72e9dfa5ef24ca489b7cbaa5f6f85b1fe87d8 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 12 Aug 2025 17:52:38 +0200 Subject: [PATCH 045/193] scripts: sphinx-pre-install: move package instructions to a new func Currently, if Python < 3.7, package install will fail. That happens with OpenSuse Leap and RHEL-based ver 8 distros. OpenSuse allows installing Sphinx with Python 3.11, but RHEL-based distros don't. Prepare to recomend only venv on such cases. For now, just split the recomendation on a new function that will check for a paramtere to be called. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/4fb2181c960e89774309a833f80209a1a3ab10d2.1754992972.git.mchehab+huawei@kernel.org --- scripts/sphinx-pre-install.py | 44 +++++++++++++++++++++-------------- 1 file changed, 26 insertions(+), 18 deletions(-) diff --git a/scripts/sphinx-pre-install.py b/scripts/sphinx-pre-install.py index 2f6036eadc94..2360ca2ed21c 100755 --- a/scripts/sphinx-pre-install.py +++ b/scripts/sphinx-pre-install.py @@ -89,6 +89,9 @@ class SphinxDependencyChecker: self.python_cmd = "" self.activate_cmd = "" + # Some distros may not have a Sphinx shipped package compatible with + # our minimal requirements + self.package_supported = True # Certain hints are meant to be shown only once self.first_hint = True @@ -969,6 +972,27 @@ class SphinxDependencyChecker: return self.latest_avail_ver + def recommend_package(self): + + print("\n2) As a package with:") + + old_need = self.need + old_optional = self.optional + self.missing = {} + self.pdf = False + self.optional = 0 + self.install = "" + old_verbose = self.verbose_warn_install + self.verbose_warn_install = 0 + + self.add_package("python-sphinx", 0) + + self.check_distros() + + self.need = old_need + self.optional = old_optional + self.verbose_warn_install = old_verbose + def recommend_sphinx_version(self, virtualenv_cmd): # The logic here is complex, as it have to deal with different versions: # - minimal supported version; @@ -1053,24 +1077,8 @@ class SphinxDependencyChecker: print(f"\tpip install -r {self.requirement_file}") self.deactivate_help() - print("\n2) As a package with:") - - old_need = self.need - old_optional = self.optional - self.missing = {} - self.pdf = False - self.optional = 0 - self.install = "" - old_verbose = self.verbose_warn_install - self.verbose_warn_install = 0 - - self.add_package("python-sphinx", 0) - - self.check_distros() - - self.need = old_need - self.optional = old_optional - self.verbose_warn_install = old_verbose + if self.package_supported: + self.recommend_package() print("\n" \ " Please note that Sphinx >= 3.0 will currently produce false-positive\n" \ From 6db1d3977baf7ac895033624897d38fb60cbe3f7 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 12 Aug 2025 17:52:39 +0200 Subject: [PATCH 046/193] scripts: sphinx-pre-install: adjust a warning message There is one extra space at the first line. Also, as now we only support Python 3.4+, update the text. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/74a17edd70364ca623a54b62bd97a344bb474988.1754992972.git.mchehab+huawei@kernel.org --- scripts/sphinx-pre-install.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/scripts/sphinx-pre-install.py b/scripts/sphinx-pre-install.py index 2360ca2ed21c..365590f81551 100755 --- a/scripts/sphinx-pre-install.py +++ b/scripts/sphinx-pre-install.py @@ -1081,8 +1081,8 @@ class SphinxDependencyChecker: self.recommend_package() print("\n" \ - " Please note that Sphinx >= 3.0 will currently produce false-positive\n" \ - " warning when the same name is used for more than one type (functions,\n" \ + " Please note that Sphinx currentlys produce false-positive\n" \ + " warnings when the same name is used for more than one type (functions,\n" \ " structs, enums,...). This is known Sphinx bug. For more details, see:\n" \ "\thttps://github.com/sphinx-doc/sphinx/pull/8313") From 8cd256524a920782268a0dd7e3e0404c34bfc65f Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 12 Aug 2025 17:52:40 +0200 Subject: [PATCH 047/193] scripts: sphinx-pre-install: better handle Python min version Don't do any recommendations about Sphinx install with too old python versions. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/013aeb848ecc3f6b69b4518cf3d335bd2353b6e1.1754992972.git.mchehab+huawei@kernel.org --- scripts/sphinx-pre-install.py | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/scripts/sphinx-pre-install.py b/scripts/sphinx-pre-install.py index 365590f81551..a5c777e529ec 100755 --- a/scripts/sphinx-pre-install.py +++ b/scripts/sphinx-pre-install.py @@ -92,6 +92,10 @@ class SphinxDependencyChecker: # Some distros may not have a Sphinx shipped package compatible with # our minimal requirements self.package_supported = True + + # Recommend a new python version + self.recommend_python = None + # Certain hints are meant to be shown only once self.first_hint = True @@ -511,11 +515,11 @@ class SphinxDependencyChecker: print("ERROR: Distro not supported. Too old?") return - # TODO: check if RHEL8 still works. - # On my tests with docker "redhat/ubi8" image, there's no - # python3-sphinx (or similar) package. It comes with Python 3.6, - # but there are other python packages over there, so it may be - # possible to work with venv. + # RHEL 8 uses Python 3.6, which is not compatible with + # the build system anymore. Suggest Python 3.11 + if rel == 8: + self.add_package("python39", 0) + self.recommend_python = True if self.first_hint: print("Note: RHEL-based distros typically require extra repositories.\n" \ @@ -596,6 +600,7 @@ class SphinxDependencyChecker: # the build system anymore. Suggest Python 3.11 if rel == 15: if not self.which(self.python_cmd): + self.recommend_python = True self.add_package(self.python_cmd, 0) progs.update({ @@ -1000,6 +1005,11 @@ class SphinxDependencyChecker: # - recommended version. # It also needs to work fine with both distro's package and venv/virtualenv + if self.recommend_python: + print("\nPython version is incompatible with doc build.\n" \ + "Please upgrade it and re-run.\n") + return + # Version is OK. Nothing to do. if self.cur_version != (0, 0, 0) and self.cur_version >= RECOMMENDED_VERSION: return From 9ecda2e10101537e97bcb2b05049e58306ac4e1b Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 12 Aug 2025 17:52:41 +0200 Subject: [PATCH 048/193] scripts: sphinx-pre-install: convert is_optional to a class When is_optional was added in Perl, it was a boolean. With time, it ended becoming a sort of enum, which makes the module harder to maintain. Convert it to a enum-like class and add more options to it. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/42290a24f3b1dbea9ebe19747cf5622bb2f2cf5c.1754992972.git.mchehab+huawei@kernel.org --- scripts/sphinx-pre-install.py | 194 +++++++++++++++++++++++----------- 1 file changed, 131 insertions(+), 63 deletions(-) diff --git a/scripts/sphinx-pre-install.py b/scripts/sphinx-pre-install.py index a5c777e529ec..0963da21c27b 100755 --- a/scripts/sphinx-pre-install.py +++ b/scripts/sphinx-pre-install.py @@ -32,6 +32,53 @@ RECOMMENDED_VERSION = parse_version("3.4.3") MIN_PYTHON_VERSION = parse_version("3.7") +class DepType: + + # Internal types of dependencies. + _SYS_TYPE = 0 + _PHY_TYPE = 1 + _PDF_TYPE = 2 + + # Let's define keys as a tuple with the type and mandatory/optional. + # This way, checking for optional or type is easy. + + SYSTEM_MANDATORY = (_SYS_TYPE, True) + PYTHON_MANDATORY = (_PHY_TYPE, True) + PDF_MANDATORY = (_PDF_TYPE, True) + + # Currently we're not using all optional types, but let's keep all + # combinations here, as we may end needing them in the future. Also, + # it allows a name() function that handles all possibilities. + SYSTEM_OPTIONAL = (_SYS_TYPE, False) + PYTHON_OPTIONAL = (_PHY_TYPE, False) + PDF_OPTIONAL = (_PDF_TYPE, True) + + @staticmethod + def name(dtype): + if dtype[0] == DepType._SYS_TYPE: + msg = "build" + elif dtype[0] == DepType._PHY_TYPE: + msg = "Python" + else: + msg = "PDF" + + if dtype[1]: + return f"ERROR: {msg} mandatory deps missing" + else: + out = f"Warning: {msg} optional deps missing" + + @staticmethod + def is_optional(dtype): + return not dtype[1] + + @staticmethod + def is_pdf(dtype): + if (dtype[0] == DepType._PDF_TYPE): + return True + + return False + + class SphinxDependencyChecker: # List of required texlive packages on Fedora and OpenSuse texlive = { @@ -223,56 +270,68 @@ class SphinxDependencyChecker: # Methods to check if a feature exists # - # Note: is_optional has 3 states: - # - 0: mandatory - # - 1: optional, but nice to have - # - 2: LaTeX optional - pdf builds without it, but may have visual impact - def check_missing(self, progs): - for prog, is_optional in sorted(self.missing.items()): + run = {} + + for prog, dtype in sorted(self.missing.items()): # At least on some LTS distros like CentOS 7, texlive doesn't # provide all packages we need. When such distros are # detected, we have to disable PDF output. # # So, we need to ignore the packages that distros would # need for LaTeX to work - if is_optional == 2 and not self.pdf: + if DepType.is_pdf(dtype) and not self.pdf: self.optional -= 1 continue - if self.verbose_warn_install: - if is_optional: - print(f'Warning: better to also install "{prog}".') - else: - print(f'ERROR: please install "{prog}", otherwise, build won\'t work.') + if not dtype in run: + run[dtype] = [] - self.install += " " + progs.get(prog, prog) + run[dtype].append(prog) + + output_msg = "" + + for dtype in sorted(run.keys()): + progs = " ".join(run[dtype]) + + if self.verbose_warn_install: + try: + name = DepType.name(dtype) + output_msg += f'{name}:\t{progs}\n' + except KeyError: + raise KeyError(f"ERROR!!!: invalid dtype for {progs}: {dtype}") + + self.install += " " + progs + + if output_msg: + print(f"\n{output_msg}\n") self.install = self.install.lstrip() - def add_package(self, package, is_optional): - self.missing[package] = is_optional + def add_package(self, package, dtype): + is_optional = DepType.is_optional(dtype) + self.missing[package] = dtype if is_optional: self.optional += 1 else: self.need += 1 - def check_missing_file(self, files, package, is_optional): + def check_missing_file(self, files, package, dtype): for f in files: if os.path.exists(f): return - self.add_package(package, is_optional) + self.add_package(package, dtype) - def check_program(self, prog, is_optional): + def check_program(self, prog, dtype): found = self.which(prog) if found: return found - self.add_package(prog, is_optional) + self.add_package(prog, dtype) return None - def check_perl_module(self, prog, is_optional): + def check_perl_module(self, prog, dtype): # While testing with lxc download template, one of the # distros (Oracle) didn't have perl - nor even an option to install # before installing oraclelinux-release-el9 package. @@ -281,46 +340,52 @@ class SphinxDependencyChecker: # add it as a mandatory package, as some parts of the doc builder # needs it. if not self.which("perl"): - self.add_package("perl", 0) - self.add_package(prog, is_optional) + self.add_package("perl", DepType.SYSTEM_MANDATORY) + self.add_package(prog, dtype) return try: self.run(["perl", f"-M{prog}", "-e", "1"], check=True) except subprocess.CalledProcessError: - self.add_package(prog, is_optional) + self.add_package(prog, dtype) - def check_python_module(self, module, is_optional): - # FIXME: is it needed at the Python version? Maybe due to venv? - if not self.python_cmd: - return + def check_python_module(self, module, is_optional=False): + if is_optional: + dtype = DepType.PYTHON_OPTIONAL + else: + dtype = DepType.PYTHON_MANDATORY try: self.run([self.python_cmd, "-c", f"import {module}"], check=True) except subprocess.CalledProcessError: - self.add_package(module, is_optional) + self.add_package(module, dtype) - def check_rpm_missing(self, pkgs, is_optional): + def check_rpm_missing(self, pkgs, dtype): for prog in pkgs: try: self.run(["rpm", "-q", prog], check=True) except subprocess.CalledProcessError: - self.add_package(prog, is_optional) + self.add_package(prog, dtype) - def check_pacman_missing(self, pkgs, is_optional): + def check_pacman_missing(self, pkgs, dtype): for prog in pkgs: try: self.run(["pacman", "-Q", prog], check=True) except subprocess.CalledProcessError: - self.add_package(prog, is_optional) + self.add_package(prog, dtype) + + def check_missing_tex(self, is_optional=False): + if is_optional: + dtype = DepType.PDF_OPTIONAL + else: + dtype = DepType.PDF_MANDATORY - def check_missing_tex(self, is_optional): kpsewhich = self.which("kpsewhich") for prog, package in self.texlive.items(): # If kpsewhich is not there, just add it to deps if not kpsewhich: - self.add_package(package, is_optional) + self.add_package(package, dtype) continue # Check if the package is needed @@ -331,11 +396,11 @@ class SphinxDependencyChecker: # Didn't find. Add it if not result.stdout.strip(): - self.add_package(package, is_optional) + self.add_package(package, dtype) except subprocess.CalledProcessError: # kpsewhich returned an error. Add it, just in case - self.add_package(package, is_optional) + self.add_package(package, dtype) def get_sphinx_fname(self): if "SPHINXBUILD" in os.environ: @@ -446,9 +511,9 @@ class SphinxDependencyChecker: } for package, files in pdf_pkgs.items(): - self.check_missing_file(files, package, 2) + self.check_missing_file(files, package, DepType.PDF_MANDATORY) - self.check_program("dvipng", 2) + self.check_program("dvipng", DepType.PDF_MANDATORY) self.check_missing(progs) @@ -518,7 +583,7 @@ class SphinxDependencyChecker: # RHEL 8 uses Python 3.6, which is not compatible with # the build system anymore. Suggest Python 3.11 if rel == 8: - self.add_package("python39", 0) + self.add_package("python39", DepType.SYSTEM_MANDATORY) self.recommend_python = True if self.first_hint: @@ -540,13 +605,13 @@ class SphinxDependencyChecker: "/usr/share/fonts/google-noto-sans-cjk-fonts/NotoSansCJK-Regular.ttc", ] - self.check_missing_file(pdf_pkgs, noto_sans_redhat, 2) + self.check_missing_file(pdf_pkgs, noto_sans_redhat, DepType.PDF_MANDATORY) if not old: - self.check_rpm_missing(fedora26_opt_pkgs, 2) - self.check_rpm_missing(fedora_tex_pkgs, 2) + self.check_rpm_missing(fedora26_opt_pkgs, DepType.PDF_MANDATORY) + self.check_rpm_missing(fedora_tex_pkgs, DepType.PDF_MANDATORY) - self.check_missing_tex(2) + self.check_missing_tex() self.check_missing(progs) @@ -601,7 +666,7 @@ class SphinxDependencyChecker: if rel == 15: if not self.which(self.python_cmd): self.recommend_python = True - self.add_package(self.python_cmd, 0) + self.add_package(self.python_cmd, DepType.SYSTEM_MANDATORY) progs.update({ "python-sphinx": "python311-Sphinx", @@ -623,9 +688,9 @@ class SphinxDependencyChecker: # "Noto Sans CJK SC" on openSUSE if self.pdf: - self.check_rpm_missing(suse_tex_pkgs, 2) + self.check_rpm_missing(suse_tex_pkgs, DepType.PDF_MANDATORY) if self.pdf: - self.check_missing_tex(2) + self.check_missing_tex() self.check_missing(progs) if not self.need and not self.optional: @@ -672,8 +737,8 @@ class SphinxDependencyChecker: "/usr/share/fonts/TTF/NotoSans-Regular.ttf", ] - self.check_missing_file(pdf_pkgs, noto_sans, 2) - self.check_rpm_missing(tex_pkgs, 2) + self.check_missing_file(pdf_pkgs, noto_sans, DepType.PDF_MANDATORY) + self.check_rpm_missing(tex_pkgs, DepType.PDF_MANDATORY) self.check_missing(progs) @@ -701,7 +766,7 @@ class SphinxDependencyChecker: ] if self.pdf: - self.check_pacman_missing(archlinux_tex_pkgs, 2) + self.check_pacman_missing(archlinux_tex_pkgs, DepType.PDF_MANDATORY) self.check_missing_file( ["/usr/share/fonts/noto-cjk/NotoSansCJK-Regular.ttc"], @@ -739,7 +804,7 @@ class SphinxDependencyChecker: ], } for package, files in pdf_pkgs.items(): - self.check_missing_file(files, package, 2) + self.check_missing_file(files, package, DepType.PDF_MANDATORY) self.check_missing(progs) @@ -878,7 +943,7 @@ class SphinxDependencyChecker: # progs = {"sphinx-build": "sphinx"} if self.pdf: - self.check_missing_tex(2) + self.check_missing_tex() self.check_missing(progs) @@ -990,7 +1055,7 @@ class SphinxDependencyChecker: old_verbose = self.verbose_warn_install self.verbose_warn_install = 0 - self.add_package("python-sphinx", 0) + self.add_package("python-sphinx", DepType.PYTHON_MANDATORY) self.check_distros() @@ -1010,6 +1075,7 @@ class SphinxDependencyChecker: "Please upgrade it and re-run.\n") return + # Version is OK. Nothing to do. if self.cur_version != (0, 0, 0) and self.cur_version >= RECOMMENDED_VERSION: return @@ -1128,21 +1194,23 @@ class SphinxDependencyChecker: else: virtualenv_cmd = f"{self.python_cmd} -m venv" - self.check_python_module("ensurepip", 0) + self.check_python_module("ensurepip") # Check for needed programs/tools - self.check_perl_module("Pod::Usage", 0) - self.check_python_module("yaml", 0) - self.check_program("make", 0) - self.check_program("gcc", 0) - self.check_program("dot", 1) - self.check_program("convert", 1) + self.check_perl_module("Pod::Usage", DepType.SYSTEM_MANDATORY) + + self.check_program("make", DepType.SYSTEM_MANDATORY) + self.check_program("gcc", DepType.SYSTEM_MANDATORY) + + self.check_program("dot", DepType.SYSTEM_OPTIONAL) + self.check_program("convert", DepType.SYSTEM_OPTIONAL) + + self.check_python_module("yaml") if self.pdf: - # Extra PDF files - should use 2 for LaTeX is_optional - self.check_program("xelatex", 2) - self.check_program("rsvg-convert", 2) - self.check_program("latexmk", 2) + self.check_program("xelatex", DepType.PDF_MANDATORY) + self.check_program("rsvg-convert", DepType.PDF_MANDATORY) + self.check_program("latexmk", DepType.PDF_MANDATORY) # Do distro-specific checks and output distro-install commands self.check_distros() From 272f5e0390dd9b5f62b480eae482a67d2493630e Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 12 Aug 2025 17:52:42 +0200 Subject: [PATCH 049/193] scripts: sphinx-pre-install: better handle RHEL-based distros Better implement support for RHEL-based distros. While here, get rid of a Fedora 28 support which cause troubles with server distros. Also, get rid of yum, as RHEL8 already suppords dnf, and this is not the minimal version we may still support. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/4d1b27d3a381f011e150bb50176babba83af9e1a.1754992972.git.mchehab+huawei@kernel.org --- scripts/sphinx-pre-install.py | 31 ++++++++++++------------------- 1 file changed, 12 insertions(+), 19 deletions(-) diff --git a/scripts/sphinx-pre-install.py b/scripts/sphinx-pre-install.py index 0963da21c27b..592223fa686f 100755 --- a/scripts/sphinx-pre-install.py +++ b/scripts/sphinx-pre-install.py @@ -536,10 +536,6 @@ class SphinxDependencyChecker: "yaml": "python3-pyyaml", } - fedora26_opt_pkgs = [ - "graphviz-gd", # Fedora 26: needed for PDF support - ] - fedora_tex_pkgs = [ "dejavu-sans-fonts", "dejavu-sans-mono-fonts", @@ -549,9 +545,8 @@ class SphinxDependencyChecker: "texlive-xecjk", ] - old = 0 + fedora = False rel = None - pkg_manager = "dnf" match = re.search(r"(release|Linux)\s+(\d+)", self.system_release) if match: @@ -559,12 +554,12 @@ class SphinxDependencyChecker: if not rel: print("Couldn't identify release number") - old = 1 self.pdf = False elif re.search("Fedora", self.system_release): # Fedora 38 and upper use this CJK font noto_sans_redhat = "google-noto-sans-cjk-fonts" + fedora = True else: # Almalinux, CentOS, RHEL, ... @@ -574,9 +569,6 @@ class SphinxDependencyChecker: progs["virtualenv"] = "python-virtualenv" if not rel or rel < 8: - old = 1 - self.pdf = False - print("ERROR: Distro not supported. Too old?") return @@ -607,11 +599,16 @@ class SphinxDependencyChecker: self.check_missing_file(pdf_pkgs, noto_sans_redhat, DepType.PDF_MANDATORY) - if not old: - self.check_rpm_missing(fedora26_opt_pkgs, DepType.PDF_MANDATORY) - self.check_rpm_missing(fedora_tex_pkgs, DepType.PDF_MANDATORY) + self.check_rpm_missing(fedora_tex_pkgs, DepType.PDF_MANDATORY) + + self.check_missing_tex(DepType.PDF_MANDATORY) + + # There's no texlive-ctex on RHEL 8 repositories. This will + # likely affect CJK pdf build only. + if not fedora and rel == 8: + if "texlive-ctex" in self.missing: + del self.missing["texlive-ctex"] - self.check_missing_tex() self.check_missing(progs) @@ -621,11 +618,7 @@ class SphinxDependencyChecker: if self.verbose_warn_install: print("You should run:") - if old: - # dnf is there since Fedora 18+ and RHEL 8 - pkg_manager = "yum" - - print(f"\n\tsudo {pkg_manager} install -y {self.install}") + print(f"\n\tsudo dnf install -y {self.install}") def give_opensuse_hints(self): progs = { From 2cab00fb178a31bca45adc1ff5f0994679d116a4 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 12 Aug 2025 17:52:43 +0200 Subject: [PATCH 050/193] scripts: sphinx-pre-install: move missing logic to a separate class Better manage dependencies by placing them on a distro-independent class. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/f4f5bf276e07dc494f5dc83c4c2d087be7f790e6.1754992972.git.mchehab+huawei@kernel.org --- scripts/sphinx-pre-install.py | 251 +++++++++++++++++++--------------- 1 file changed, 138 insertions(+), 113 deletions(-) diff --git a/scripts/sphinx-pre-install.py b/scripts/sphinx-pre-install.py index 592223fa686f..47dce1fcddfb 100755 --- a/scripts/sphinx-pre-install.py +++ b/scripts/sphinx-pre-install.py @@ -32,7 +32,7 @@ RECOMMENDED_VERSION = parse_version("3.4.3") MIN_PYTHON_VERSION = parse_version("3.7") -class DepType: +class DepManager: # Internal types of dependencies. _SYS_TYPE = 0 @@ -53,11 +53,18 @@ class DepType: PYTHON_OPTIONAL = (_PHY_TYPE, False) PDF_OPTIONAL = (_PDF_TYPE, True) + def __init__(self, pdf): + self.missing = {} + self.run = {} + self.need = 0 + self.optional = 0 + self.pdf = pdf + @staticmethod def name(dtype): - if dtype[0] == DepType._SYS_TYPE: + if dtype[0] == DepManager._SYS_TYPE: msg = "build" - elif dtype[0] == DepType._PHY_TYPE: + elif dtype[0] == DepManager._PHY_TYPE: msg = "Python" else: msg = "PDF" @@ -73,11 +80,75 @@ class DepType: @staticmethod def is_pdf(dtype): - if (dtype[0] == DepType._PDF_TYPE): + if (dtype[0] == DepManager._PDF_TYPE): return True return False + def add_package(self, package, dtype): + is_optional = DepManager.is_optional(dtype) + self.missing[package] = dtype + if is_optional: + self.optional += 1 + else: + self.need += 1 + + def del_package(self, package): + if package in self.missing: + del self.missing[package] + + def clear_deps(self): + """ + Clear dependencies without changing needed/optional. + + This is an ackward way to have a separate section to recommend + a package after system main dependencies. + + TODO: rework the logic to prevent needing it + """ + + self.missing = {} + + def check_missing(self, progs): + self.run = {} + + for prog, dtype in sorted(self.missing.items()): + # At least on some LTS distros like CentOS 7, texlive doesn't + # provide all packages we need. When such distros are + # detected, we have to disable PDF output. + # + # So, we need to ignore the packages that distros would + # need for LaTeX to work + if DepManager.is_pdf(dtype) and not self.pdf: + self.optional -= 1 + continue + + if not dtype in self.run: + self.run[dtype] = [] + + self.run[dtype].append(progs.get(prog, prog)) + + install = [] + for dtype in self.run.keys(): + install += self.run[dtype] + + return " ".join(sorted(set(install))) + + def warn_install(self): + + output_msg = "" + + for dtype in sorted(self.run.keys()): + progs = " ".join(sorted(set(self.run[dtype]))) + + try: + name = DepManager.name(dtype) + output_msg += f'{name}:\t{progs}\n' + except KeyError: + raise KeyError(f"ERROR!!!: invalid dtype for {progs}: {dtype}") + + if output_msg: + print(f"\n{output_msg}\n") class SphinxDependencyChecker: # List of required texlive packages on Fedora and OpenSuse @@ -120,10 +191,8 @@ class SphinxDependencyChecker: self.virtualenv = args.virtualenv self.version_check = args.version_check - self.missing = {} + self.deps = DepManager(self.pdf) - self.need = 0 - self.optional = 0 self.need_symlink = 0 self.need_sphinx = 0 self.need_pip = 0 @@ -270,64 +339,18 @@ class SphinxDependencyChecker: # Methods to check if a feature exists # - def check_missing(self, progs): - run = {} - - for prog, dtype in sorted(self.missing.items()): - # At least on some LTS distros like CentOS 7, texlive doesn't - # provide all packages we need. When such distros are - # detected, we have to disable PDF output. - # - # So, we need to ignore the packages that distros would - # need for LaTeX to work - if DepType.is_pdf(dtype) and not self.pdf: - self.optional -= 1 - continue - - if not dtype in run: - run[dtype] = [] - - run[dtype].append(prog) - - output_msg = "" - - for dtype in sorted(run.keys()): - progs = " ".join(run[dtype]) - - if self.verbose_warn_install: - try: - name = DepType.name(dtype) - output_msg += f'{name}:\t{progs}\n' - except KeyError: - raise KeyError(f"ERROR!!!: invalid dtype for {progs}: {dtype}") - - self.install += " " + progs - - if output_msg: - print(f"\n{output_msg}\n") - - self.install = self.install.lstrip() - - def add_package(self, package, dtype): - is_optional = DepType.is_optional(dtype) - self.missing[package] = dtype - if is_optional: - self.optional += 1 - else: - self.need += 1 - def check_missing_file(self, files, package, dtype): for f in files: if os.path.exists(f): return - self.add_package(package, dtype) + self.deps.add_package(package, dtype) def check_program(self, prog, dtype): found = self.which(prog) if found: return found - self.add_package(prog, dtype) + self.deps.add_package(prog, dtype) return None @@ -340,52 +363,52 @@ class SphinxDependencyChecker: # add it as a mandatory package, as some parts of the doc builder # needs it. if not self.which("perl"): - self.add_package("perl", DepType.SYSTEM_MANDATORY) - self.add_package(prog, dtype) + self.deps.add_package("perl", DepManager.SYSTEM_MANDATORY) + self.deps.add_package(prog, dtype) return try: self.run(["perl", f"-M{prog}", "-e", "1"], check=True) except subprocess.CalledProcessError: - self.add_package(prog, dtype) + self.deps.add_package(prog, dtype) def check_python_module(self, module, is_optional=False): if is_optional: - dtype = DepType.PYTHON_OPTIONAL + dtype = DepManager.PYTHON_OPTIONAL else: - dtype = DepType.PYTHON_MANDATORY + dtype = DepManager.PYTHON_MANDATORY try: self.run([self.python_cmd, "-c", f"import {module}"], check=True) except subprocess.CalledProcessError: - self.add_package(module, dtype) + self.deps.add_package(module, dtype) def check_rpm_missing(self, pkgs, dtype): for prog in pkgs: try: self.run(["rpm", "-q", prog], check=True) except subprocess.CalledProcessError: - self.add_package(prog, dtype) + self.deps.add_package(prog, dtype) def check_pacman_missing(self, pkgs, dtype): for prog in pkgs: try: self.run(["pacman", "-Q", prog], check=True) except subprocess.CalledProcessError: - self.add_package(prog, dtype) + self.deps.add_package(prog, dtype) def check_missing_tex(self, is_optional=False): if is_optional: - dtype = DepType.PDF_OPTIONAL + dtype = DepManager.PDF_OPTIONAL else: - dtype = DepType.PDF_MANDATORY + dtype = DepManager.PDF_MANDATORY kpsewhich = self.which("kpsewhich") for prog, package in self.texlive.items(): # If kpsewhich is not there, just add it to deps if not kpsewhich: - self.add_package(package, dtype) + self.deps.add_package(package, dtype) continue # Check if the package is needed @@ -396,11 +419,11 @@ class SphinxDependencyChecker: # Didn't find. Add it if not result.stdout.strip(): - self.add_package(package, dtype) + self.deps.add_package(package, dtype) except subprocess.CalledProcessError: # kpsewhich returned an error. Add it, just in case - self.add_package(package, dtype) + self.deps.add_package(package, dtype) def get_sphinx_fname(self): if "SPHINXBUILD" in os.environ: @@ -478,6 +501,17 @@ class SphinxDependencyChecker: return f.read().strip() return "" + def check_missing(self, progs): + self.install += self.deps.check_missing(progs) + if self.verbose_warn_install: + self.deps.warn_install() + + if not self.deps.need and not self.deps.optional: + return False + + return True + + # # Distro-specific hints methods # @@ -511,13 +545,11 @@ class SphinxDependencyChecker: } for package, files in pdf_pkgs.items(): - self.check_missing_file(files, package, DepType.PDF_MANDATORY) + self.check_missing_file(files, package, DepManager.PDF_MANDATORY) - self.check_program("dvipng", DepType.PDF_MANDATORY) + self.check_program("dvipng", DepManager.PDF_MANDATORY) - self.check_missing(progs) - - if not self.need and not self.optional: + if self.check_missing(progs): return if self.verbose_warn_install: @@ -575,7 +607,7 @@ class SphinxDependencyChecker: # RHEL 8 uses Python 3.6, which is not compatible with # the build system anymore. Suggest Python 3.11 if rel == 8: - self.add_package("python39", DepType.SYSTEM_MANDATORY) + self.deps.add_package("python39", DepManager.SYSTEM_MANDATORY) self.recommend_python = True if self.first_hint: @@ -597,22 +629,18 @@ class SphinxDependencyChecker: "/usr/share/fonts/google-noto-sans-cjk-fonts/NotoSansCJK-Regular.ttc", ] - self.check_missing_file(pdf_pkgs, noto_sans_redhat, DepType.PDF_MANDATORY) + self.check_missing_file(pdf_pkgs, noto_sans_redhat, DepManager.PDF_MANDATORY) - self.check_rpm_missing(fedora_tex_pkgs, DepType.PDF_MANDATORY) + self.check_rpm_missing(fedora_tex_pkgs, DepManager.PDF_MANDATORY) - self.check_missing_tex(DepType.PDF_MANDATORY) + self.check_missing_tex(DepManager.PDF_MANDATORY) # There's no texlive-ctex on RHEL 8 repositories. This will # likely affect CJK pdf build only. if not fedora and rel == 8: - if "texlive-ctex" in self.missing: - del self.missing["texlive-ctex"] + self.deps.del_package("texlive-ctex") - - self.check_missing(progs) - - if not self.need and not self.optional: + if self.check_missing(progs): return if self.verbose_warn_install: @@ -659,7 +687,7 @@ class SphinxDependencyChecker: if rel == 15: if not self.which(self.python_cmd): self.recommend_python = True - self.add_package(self.python_cmd, DepType.SYSTEM_MANDATORY) + self.deps.add_package(self.python_cmd, DepManager.SYSTEM_MANDATORY) progs.update({ "python-sphinx": "python311-Sphinx", @@ -681,12 +709,11 @@ class SphinxDependencyChecker: # "Noto Sans CJK SC" on openSUSE if self.pdf: - self.check_rpm_missing(suse_tex_pkgs, DepType.PDF_MANDATORY) + self.check_rpm_missing(suse_tex_pkgs, DepManager.PDF_MANDATORY) if self.pdf: self.check_missing_tex() - self.check_missing(progs) - if not self.need and not self.optional: + if self.check_missing(progs): return if self.verbose_warn_install: @@ -730,13 +757,12 @@ class SphinxDependencyChecker: "/usr/share/fonts/TTF/NotoSans-Regular.ttf", ] - self.check_missing_file(pdf_pkgs, noto_sans, DepType.PDF_MANDATORY) - self.check_rpm_missing(tex_pkgs, DepType.PDF_MANDATORY) + self.check_missing_file(pdf_pkgs, noto_sans, DepManager.PDF_MANDATORY) + self.check_rpm_missing(tex_pkgs, DepManager.PDF_MANDATORY) - self.check_missing(progs) - - if not self.need and not self.optional: + if self.check_missing(progs): return + if self.verbose_warn_install: print("You should run:") print(f"\n\tsudo {packager_cmd} {self.install}") @@ -759,7 +785,7 @@ class SphinxDependencyChecker: ] if self.pdf: - self.check_pacman_missing(archlinux_tex_pkgs, DepType.PDF_MANDATORY) + self.check_pacman_missing(archlinux_tex_pkgs, DepManager.PDF_MANDATORY) self.check_missing_file( ["/usr/share/fonts/noto-cjk/NotoSansCJK-Regular.ttc"], @@ -767,10 +793,9 @@ class SphinxDependencyChecker: 2, ) - self.check_missing(progs) - - if not self.need and not self.optional: + if self.check_missing(progs): return + if self.verbose_warn_install: print("You should run:") print(f"\n\tsudo pacman -S {self.install}") @@ -797,11 +822,9 @@ class SphinxDependencyChecker: ], } for package, files in pdf_pkgs.items(): - self.check_missing_file(files, package, DepType.PDF_MANDATORY) + self.check_missing_file(files, package, DepManager.PDF_MANDATORY) - self.check_missing(progs) - - if not self.need and not self.optional: + if self.check_missing(progs): return if self.verbose_warn_install: @@ -1039,16 +1062,18 @@ class SphinxDependencyChecker: print("\n2) As a package with:") - old_need = self.need - old_optional = self.optional - self.missing = {} + old_need = self.deps.need + old_optional = self.deps.optional + self.pdf = False self.optional = 0 self.install = "" old_verbose = self.verbose_warn_install self.verbose_warn_install = 0 - self.add_package("python-sphinx", DepType.PYTHON_MANDATORY) + self.deps.clear_deps() + + self.deps.add_package("python-sphinx", DepManager.PYTHON_MANDATORY) self.check_distros() @@ -1111,7 +1136,7 @@ class SphinxDependencyChecker: print("\n") else: if self.need_sphinx: - self.need += 1 + self.deps.need += 1 # Suggest newer versions if current ones are too old if self.latest_avail_ver and self.latest_avail_ver >= self.min_version: @@ -1190,20 +1215,20 @@ class SphinxDependencyChecker: self.check_python_module("ensurepip") # Check for needed programs/tools - self.check_perl_module("Pod::Usage", DepType.SYSTEM_MANDATORY) + self.check_perl_module("Pod::Usage", DepManager.SYSTEM_MANDATORY) - self.check_program("make", DepType.SYSTEM_MANDATORY) - self.check_program("gcc", DepType.SYSTEM_MANDATORY) + self.check_program("make", DepManager.SYSTEM_MANDATORY) + self.check_program("gcc", DepManager.SYSTEM_MANDATORY) - self.check_program("dot", DepType.SYSTEM_OPTIONAL) - self.check_program("convert", DepType.SYSTEM_OPTIONAL) + self.check_program("dot", DepManager.SYSTEM_OPTIONAL) + self.check_program("convert", DepManager.SYSTEM_OPTIONAL) self.check_python_module("yaml") if self.pdf: - self.check_program("xelatex", DepType.PDF_MANDATORY) - self.check_program("rsvg-convert", DepType.PDF_MANDATORY) - self.check_program("latexmk", DepType.PDF_MANDATORY) + self.check_program("xelatex", DepManager.PDF_MANDATORY) + self.check_program("rsvg-convert", DepManager.PDF_MANDATORY) + self.check_program("latexmk", DepManager.PDF_MANDATORY) # Do distro-specific checks and output distro-install commands self.check_distros() From 1e9ba3b6d4cef8b1b87d6226ab7026c9745cc1d7 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 12 Aug 2025 17:52:44 +0200 Subject: [PATCH 051/193] scripts: sphinx-pre-install: move ancillary checkers to a separate class The code there are just a bunch of static functions that are used by the main class. group them altogether to better organize the code. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/e2671eb14fae7a8510f5305ac44ad8063e237a5f.1754992972.git.mchehab+huawei@kernel.org --- scripts/sphinx-pre-install.py | 160 +++++++++++++++++----------------- 1 file changed, 81 insertions(+), 79 deletions(-) diff --git a/scripts/sphinx-pre-install.py b/scripts/sphinx-pre-install.py index 47dce1fcddfb..b00e50028f4d 100755 --- a/scripts/sphinx-pre-install.py +++ b/scripts/sphinx-pre-install.py @@ -150,85 +150,11 @@ class DepManager: if output_msg: print(f"\n{output_msg}\n") -class SphinxDependencyChecker: - # List of required texlive packages on Fedora and OpenSuse - texlive = { - "amsfonts.sty": "texlive-amsfonts", - "amsmath.sty": "texlive-amsmath", - "amssymb.sty": "texlive-amsfonts", - "amsthm.sty": "texlive-amscls", - "anyfontsize.sty": "texlive-anyfontsize", - "atbegshi.sty": "texlive-oberdiek", - "bm.sty": "texlive-tools", - "capt-of.sty": "texlive-capt-of", - "cmap.sty": "texlive-cmap", - "ctexhook.sty": "texlive-ctex", - "ecrm1000.tfm": "texlive-ec", - "eqparbox.sty": "texlive-eqparbox", - "eu1enc.def": "texlive-euenc", - "fancybox.sty": "texlive-fancybox", - "fancyvrb.sty": "texlive-fancyvrb", - "float.sty": "texlive-float", - "fncychap.sty": "texlive-fncychap", - "footnote.sty": "texlive-mdwtools", - "framed.sty": "texlive-framed", - "luatex85.sty": "texlive-luatex85", - "multirow.sty": "texlive-multirow", - "needspace.sty": "texlive-needspace", - "palatino.sty": "texlive-psnfss", - "parskip.sty": "texlive-parskip", - "polyglossia.sty": "texlive-polyglossia", - "tabulary.sty": "texlive-tabulary", - "threeparttable.sty": "texlive-threeparttable", - "titlesec.sty": "texlive-titlesec", - "ucs.sty": "texlive-ucs", - "upquote.sty": "texlive-upquote", - "wrapfig.sty": "texlive-wrapfig", - } - - def __init__(self, args): - self.pdf = args.pdf - self.virtualenv = args.virtualenv - self.version_check = args.version_check - - self.deps = DepManager(self.pdf) - - self.need_symlink = 0 - self.need_sphinx = 0 - self.need_pip = 0 - self.rec_sphinx_upgrade = 0 - self.verbose_warn_install = 1 - - self.system_release = "" - self.install = "" - self.virtenv_dir = "" - self.python_cmd = "" - self.activate_cmd = "" - - # Some distros may not have a Sphinx shipped package compatible with - # our minimal requirements - self.package_supported = True - - # Recommend a new python version - self.recommend_python = None - - # Certain hints are meant to be shown only once - self.first_hint = True - - self.min_version = (0, 0, 0) - self.cur_version = (0, 0, 0) - self.latest_avail_ver = (0, 0, 0) - self.venv_ver = (0, 0, 0) - - prefix = os.environ.get("srctree", ".") + "/" - - self.conf = prefix + "Documentation/conf.py" - self.requirement_file = prefix + "Documentation/sphinx/requirements.txt" - self.virtenv_prefix = ["sphinx_", "Sphinx_" ] - - # - # Ancillary methods that don't depend on self - # +class AncillaryCheckers: + """ + Ancillary methods that checks for missing dependencies for different + types of types, like binaries, python modules, rpm deps, etc. + """ @staticmethod def which(prog): @@ -335,6 +261,82 @@ class SphinxDependencyChecker: return subprocess.run(*args, **kwargs) +class SphinxDependencyChecker(AncillaryCheckers): + # List of required texlive packages on Fedora and OpenSuse + texlive = { + "amsfonts.sty": "texlive-amsfonts", + "amsmath.sty": "texlive-amsmath", + "amssymb.sty": "texlive-amsfonts", + "amsthm.sty": "texlive-amscls", + "anyfontsize.sty": "texlive-anyfontsize", + "atbegshi.sty": "texlive-oberdiek", + "bm.sty": "texlive-tools", + "capt-of.sty": "texlive-capt-of", + "cmap.sty": "texlive-cmap", + "ctexhook.sty": "texlive-ctex", + "ecrm1000.tfm": "texlive-ec", + "eqparbox.sty": "texlive-eqparbox", + "eu1enc.def": "texlive-euenc", + "fancybox.sty": "texlive-fancybox", + "fancyvrb.sty": "texlive-fancyvrb", + "float.sty": "texlive-float", + "fncychap.sty": "texlive-fncychap", + "footnote.sty": "texlive-mdwtools", + "framed.sty": "texlive-framed", + "luatex85.sty": "texlive-luatex85", + "multirow.sty": "texlive-multirow", + "needspace.sty": "texlive-needspace", + "palatino.sty": "texlive-psnfss", + "parskip.sty": "texlive-parskip", + "polyglossia.sty": "texlive-polyglossia", + "tabulary.sty": "texlive-tabulary", + "threeparttable.sty": "texlive-threeparttable", + "titlesec.sty": "texlive-titlesec", + "ucs.sty": "texlive-ucs", + "upquote.sty": "texlive-upquote", + "wrapfig.sty": "texlive-wrapfig", + } + + def __init__(self, args): + self.pdf = args.pdf + self.virtualenv = args.virtualenv + self.version_check = args.version_check + + self.deps = DepManager(self.pdf) + + self.need_symlink = 0 + self.need_sphinx = 0 + self.need_pip = 0 + self.rec_sphinx_upgrade = 0 + self.verbose_warn_install = 1 + + self.system_release = "" + self.install = "" + self.virtenv_dir = "" + self.python_cmd = "" + self.activate_cmd = "" + + # Some distros may not have a Sphinx shipped package compatible with + # our minimal requirements + self.package_supported = True + + # Recommend a new python version + self.recommend_python = None + + # Certain hints are meant to be shown only once + self.first_hint = True + + self.min_version = (0, 0, 0) + self.cur_version = (0, 0, 0) + self.latest_avail_ver = (0, 0, 0) + self.venv_ver = (0, 0, 0) + + prefix = os.environ.get("srctree", ".") + "/" + + self.conf = prefix + "Documentation/conf.py" + self.requirement_file = prefix + "Documentation/sphinx/requirements.txt" + self.virtenv_prefix = ["sphinx_", "Sphinx_" ] + # # Methods to check if a feature exists # From 9bb5f0dc18d037635f4c5075747de1e47493b538 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 12 Aug 2025 17:52:45 +0200 Subject: [PATCH 052/193] scripts: sphinx-pre-install: add more generic checkers on a class Better organize the code by moving the more generic methods to MissingCheckers. Such class contain only binary and package dependent missing checkers, but no distro-specific data or code. All distro-specific data/code remains at SphinxDependencyChecker class. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/11a252fe816bd7c85583d26ade0666eb2b481bf0.1754992972.git.mchehab+huawei@kernel.org --- scripts/sphinx-pre-install.py | 142 ++++++++++++++++++---------------- 1 file changed, 76 insertions(+), 66 deletions(-) diff --git a/scripts/sphinx-pre-install.py b/scripts/sphinx-pre-install.py index b00e50028f4d..9127487bd4d7 100755 --- a/scripts/sphinx-pre-install.py +++ b/scripts/sphinx-pre-install.py @@ -150,7 +150,7 @@ class DepManager: if output_msg: print(f"\n{output_msg}\n") -class AncillaryCheckers: +class AncillaryMethods: """ Ancillary methods that checks for missing dependencies for different types of types, like binaries, python modules, rpm deps, etc. @@ -261,81 +261,24 @@ class AncillaryCheckers: return subprocess.run(*args, **kwargs) -class SphinxDependencyChecker(AncillaryCheckers): - # List of required texlive packages on Fedora and OpenSuse - texlive = { - "amsfonts.sty": "texlive-amsfonts", - "amsmath.sty": "texlive-amsmath", - "amssymb.sty": "texlive-amsfonts", - "amsthm.sty": "texlive-amscls", - "anyfontsize.sty": "texlive-anyfontsize", - "atbegshi.sty": "texlive-oberdiek", - "bm.sty": "texlive-tools", - "capt-of.sty": "texlive-capt-of", - "cmap.sty": "texlive-cmap", - "ctexhook.sty": "texlive-ctex", - "ecrm1000.tfm": "texlive-ec", - "eqparbox.sty": "texlive-eqparbox", - "eu1enc.def": "texlive-euenc", - "fancybox.sty": "texlive-fancybox", - "fancyvrb.sty": "texlive-fancyvrb", - "float.sty": "texlive-float", - "fncychap.sty": "texlive-fncychap", - "footnote.sty": "texlive-mdwtools", - "framed.sty": "texlive-framed", - "luatex85.sty": "texlive-luatex85", - "multirow.sty": "texlive-multirow", - "needspace.sty": "texlive-needspace", - "palatino.sty": "texlive-psnfss", - "parskip.sty": "texlive-parskip", - "polyglossia.sty": "texlive-polyglossia", - "tabulary.sty": "texlive-tabulary", - "threeparttable.sty": "texlive-threeparttable", - "titlesec.sty": "texlive-titlesec", - "ucs.sty": "texlive-ucs", - "upquote.sty": "texlive-upquote", - "wrapfig.sty": "texlive-wrapfig", - } +class MissingCheckers(AncillaryMethods): - def __init__(self, args): + def __init__(self, args, texlive): self.pdf = args.pdf self.virtualenv = args.virtualenv self.version_check = args.version_check + self.texlive = texlive self.deps = DepManager(self.pdf) self.need_symlink = 0 self.need_sphinx = 0 - self.need_pip = 0 - self.rec_sphinx_upgrade = 0 + self.verbose_warn_install = 1 - self.system_release = "" - self.install = "" self.virtenv_dir = "" - self.python_cmd = "" - self.activate_cmd = "" - # Some distros may not have a Sphinx shipped package compatible with - # our minimal requirements - self.package_supported = True - - # Recommend a new python version - self.recommend_python = None - - # Certain hints are meant to be shown only once - self.first_hint = True - - self.min_version = (0, 0, 0) - self.cur_version = (0, 0, 0) - self.latest_avail_ver = (0, 0, 0) - self.venv_ver = (0, 0, 0) - - prefix = os.environ.get("srctree", ".") + "/" - - self.conf = prefix + "Documentation/conf.py" - self.requirement_file = prefix + "Documentation/sphinx/requirements.txt" - self.virtenv_prefix = ["sphinx_", "Sphinx_" ] + self.install = "" # # Methods to check if a feature exists @@ -460,9 +403,9 @@ class SphinxDependencyChecker(AncillaryCheckers): if match: return parse_version(match.group(1)) - def check_sphinx(self): + def check_sphinx(self, conf): try: - with open(self.conf, "r", encoding="utf-8") as f: + with open(conf, "r", encoding="utf-8") as f: for line in f: match = re.match(r"^\s*needs_sphinx\s*=\s*[\'\"]([\d\.]+)[\'\"]", line) if match: @@ -513,6 +456,73 @@ class SphinxDependencyChecker(AncillaryCheckers): return True +class SphinxDependencyChecker(MissingCheckers): + + def __init__(self, args): + # List of required texlive packages on Fedora and OpenSuse + texlive = { + "amsfonts.sty": "texlive-amsfonts", + "amsmath.sty": "texlive-amsmath", + "amssymb.sty": "texlive-amsfonts", + "amsthm.sty": "texlive-amscls", + "anyfontsize.sty": "texlive-anyfontsize", + "atbegshi.sty": "texlive-oberdiek", + "bm.sty": "texlive-tools", + "capt-of.sty": "texlive-capt-of", + "cmap.sty": "texlive-cmap", + "ctexhook.sty": "texlive-ctex", + "ecrm1000.tfm": "texlive-ec", + "eqparbox.sty": "texlive-eqparbox", + "eu1enc.def": "texlive-euenc", + "fancybox.sty": "texlive-fancybox", + "fancyvrb.sty": "texlive-fancyvrb", + "float.sty": "texlive-float", + "fncychap.sty": "texlive-fncychap", + "footnote.sty": "texlive-mdwtools", + "framed.sty": "texlive-framed", + "luatex85.sty": "texlive-luatex85", + "multirow.sty": "texlive-multirow", + "needspace.sty": "texlive-needspace", + "palatino.sty": "texlive-psnfss", + "parskip.sty": "texlive-parskip", + "polyglossia.sty": "texlive-polyglossia", + "tabulary.sty": "texlive-tabulary", + "threeparttable.sty": "texlive-threeparttable", + "titlesec.sty": "texlive-titlesec", + "ucs.sty": "texlive-ucs", + "upquote.sty": "texlive-upquote", + "wrapfig.sty": "texlive-wrapfig", + } + + super().__init__(args, texlive) + + self.need_pip = 0 + self.rec_sphinx_upgrade = 0 + + self.system_release = "" + self.python_cmd = "" + self.activate_cmd = "" + + # Some distros may not have a Sphinx shipped package compatible with + # our minimal requirements + self.package_supported = True + + # Recommend a new python version + self.recommend_python = None + + # Certain hints are meant to be shown only once + self.first_hint = True + + self.min_version = (0, 0, 0) + self.cur_version = (0, 0, 0) + self.latest_avail_ver = (0, 0, 0) + self.venv_ver = (0, 0, 0) + + prefix = os.environ.get("srctree", ".") + "/" + + self.conf = prefix + "Documentation/conf.py" + self.requirement_file = prefix + "Documentation/sphinx/requirements.txt" + self.virtenv_prefix = ["sphinx_", "Sphinx_" ] # # Distro-specific hints methods @@ -1187,7 +1197,7 @@ class SphinxDependencyChecker(AncillaryCheckers): self.python_cmd = sys.executable # Check if Sphinx is already accessible from current environment - self.check_sphinx() + self.check_sphinx(self.conf) if self.system_release: print(f"Detected OS: {self.system_release}.") From fb22e438b23eabd828a0ca1076be5ecf9b0262db Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 12 Aug 2025 17:52:46 +0200 Subject: [PATCH 053/193] scripts: sphinx-pre-install: move get_system_release() The code at get_system_release() is actually a helper function, independent from the actual Sphinx verification checker. Move it to MissingCheckers class, where other checkers are present. With that, the entire distro-specific handler logic, with all its complexity is confined at SphinxDependencyChecker class. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/4b42a85bbb6575bb34a58cf66019038c4afa1d5b.1754992972.git.mchehab+huawei@kernel.org --- scripts/sphinx-pre-install.py | 115 +++++++++++++++++----------------- 1 file changed, 59 insertions(+), 56 deletions(-) diff --git a/scripts/sphinx-pre-install.py b/scripts/sphinx-pre-install.py index 9127487bd4d7..593982f350b3 100755 --- a/scripts/sphinx-pre-install.py +++ b/scripts/sphinx-pre-install.py @@ -456,6 +456,64 @@ class MissingCheckers(AncillaryMethods): return True + def get_system_release(self): + """ + Determine the system type. There's no unique way that would work + with all distros with a minimal package install. So, several + methods are used here. + + By default, it will use lsb_release function. If not available, it will + fail back to reading the known different places where the distro name + is stored. + + Several modern distros now have /etc/os-release, which usually have + a decent coverage. + """ + + system_release = "" + + if self.which("lsb_release"): + result = self.run(["lsb_release", "-d"], capture_output=True, text=True) + system_release = result.stdout.replace("Description:", "").strip() + + release_files = [ + "/etc/system-release", + "/etc/redhat-release", + "/etc/lsb-release", + "/etc/gentoo-release", + ] + + if not system_release: + for f in release_files: + system_release = self.catcheck(f) + if system_release: + break + + # This seems more common than LSB these days + if not system_release: + os_var = {} + try: + with open("/etc/os-release", "r", encoding="utf-8") as f: + for line in f: + match = re.match(r"^([\w\d\_]+)=\"?([^\"]*)\"?\n", line) + if match: + os_var[match.group(1)] = match.group(2) + + system_release = os_var.get("NAME", "") + if "VERSION_ID" in os_var: + system_release += " " + os_var["VERSION_ID"] + elif "VERSION" in os_var: + system_release += " " + os_var["VERSION"] + except IOError: + pass + + if not system_release: + system_release = self.catcheck("/etc/issue") + + system_release = system_release.strip() + + return system_release + class SphinxDependencyChecker(MissingCheckers): def __init__(self, args): @@ -499,7 +557,7 @@ class SphinxDependencyChecker(MissingCheckers): self.need_pip = 0 self.rec_sphinx_upgrade = 0 - self.system_release = "" + self.system_release = self.get_system_release() self.python_cmd = "" self.activate_cmd = "" @@ -1193,7 +1251,6 @@ class SphinxDependencyChecker(MissingCheckers): "\thttps://github.com/sphinx-doc/sphinx/pull/8313") def check_needs(self): - self.get_system_release() self.python_cmd = sys.executable # Check if Sphinx is already accessible from current environment @@ -1270,60 +1327,6 @@ class SphinxDependencyChecker(MissingCheckers): print("Needed package dependencies are met.") - def get_system_release(self): - """ - Determine the system type. There's no unique way that would work - with all distros with a minimal package install. So, several - methods are used here. - - By default, it will use lsb_release function. If not available, it will - fail back to reading the known different places where the distro name - is stored. - - Several modern distros now have /etc/os-release, which usually have - a decent coverage. - """ - - if self.which("lsb_release"): - result = self.run(["lsb_release", "-d"], capture_output=True, text=True) - self.system_release = result.stdout.replace("Description:", "").strip() - - release_files = [ - "/etc/system-release", - "/etc/redhat-release", - "/etc/lsb-release", - "/etc/gentoo-release", - ] - - if not self.system_release: - for f in release_files: - self.system_release = self.catcheck(f) - if self.system_release: - break - - # This seems more common than LSB these days - if not self.system_release: - os_var = {} - try: - with open("/etc/os-release", "r", encoding="utf-8") as f: - for line in f: - match = re.match(r"^([\w\d\_]+)=\"?([^\"]*)\"?\n", line) - if match: - os_var[match.group(1)] = match.group(2) - - self.system_release = os_var.get("NAME", "") - if "VERSION_ID" in os_var: - self.system_release += " " + os_var["VERSION_ID"] - elif "VERSION" in os_var: - self.system_release += " " + os_var["VERSION"] - except IOError: - pass - - if not self.system_release: - self.system_release = self.catcheck("/etc/issue") - - self.system_release = self.system_release.strip() - DESCRIPTION = """ Process some flags related to Sphinx installation and documentation build. """ From f477c6d71d3947ab8f2e9e7d5fd8448f7a26c1ab Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 12 Aug 2025 17:52:47 +0200 Subject: [PATCH 054/193] scripts: sphinx-pre-install: add documentation for the ancillary classes. While here, rename a parameter to have its usage better documented. No functional changes. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/7421112b14edf5c21cc4cf0f2ee320fcaf874b40.1754992972.git.mchehab+huawei@kernel.org --- scripts/sphinx-pre-install.py | 162 +++++++++++++++++++++++++++++----- 1 file changed, 140 insertions(+), 22 deletions(-) diff --git a/scripts/sphinx-pre-install.py b/scripts/sphinx-pre-install.py index 593982f350b3..1dc3f19804ab 100755 --- a/scripts/sphinx-pre-install.py +++ b/scripts/sphinx-pre-install.py @@ -33,35 +33,62 @@ MIN_PYTHON_VERSION = parse_version("3.7") class DepManager: + """ + Manage package dependencies. There are three types of dependencies: - # Internal types of dependencies. + - System: dependencies required for docs build; + - Python: python dependencies for a native distro Sphinx install; + - PDF: dependencies needed by PDF builds. + + Each dependency can be mandatory or optional. Not installing an optional + dependency won't break the build, but will cause degradation at the + docs output. + """ + + # Internal types of dependencies. Don't use them outside DepManager class. _SYS_TYPE = 0 _PHY_TYPE = 1 _PDF_TYPE = 2 - # Let's define keys as a tuple with the type and mandatory/optional. - # This way, checking for optional or type is easy. + # Dependencies visible outside the class. + # The keys are tuple with: (type, is_mandatory flag). + # + # Currently we're not using all optional dep types. Yet, we'll keep all + # possible combinations here. They're not many, and that makes easier + # if later needed and for the name() method below SYSTEM_MANDATORY = (_SYS_TYPE, True) PYTHON_MANDATORY = (_PHY_TYPE, True) PDF_MANDATORY = (_PDF_TYPE, True) - # Currently we're not using all optional types, but let's keep all - # combinations here, as we may end needing them in the future. Also, - # it allows a name() function that handles all possibilities. SYSTEM_OPTIONAL = (_SYS_TYPE, False) PYTHON_OPTIONAL = (_PHY_TYPE, False) PDF_OPTIONAL = (_PDF_TYPE, True) def __init__(self, pdf): + """ + Initialize internal vars: + + - missing: missing dependencies list, containing a distro-independent + name for a missing dependency and its type. + - missing_pkg: ancillary dict containing missing dependencies in + distro namespace, organized by type. + - need: total number of needed dependencies. Never cleaned. + - optional: total number of optional dependencies. Never cleaned. + - pdf: PDF support is enabled? + """ self.missing = {} - self.run = {} + self.missing_pkg = {} self.need = 0 self.optional = 0 self.pdf = pdf @staticmethod def name(dtype): + """ + Ancillary routine to output a warn/error message reporting + missing dependencies. + """ if dtype[0] == DepManager._SYS_TYPE: msg = "build" elif dtype[0] == DepManager._PHY_TYPE: @@ -76,16 +103,22 @@ class DepManager: @staticmethod def is_optional(dtype): + """Ancillary routine to report if a dependency is optional""" return not dtype[1] @staticmethod def is_pdf(dtype): + """Ancillary routine to report if a dependency is for PDF generation""" if (dtype[0] == DepManager._PDF_TYPE): return True return False def add_package(self, package, dtype): + """ + Add a package at the self.missing() dictionary. + Doesn't update missing_pkg. + """ is_optional = DepManager.is_optional(dtype) self.missing[package] = dtype if is_optional: @@ -94,6 +127,10 @@ class DepManager: self.need += 1 def del_package(self, package): + """ + Remove a package at the self.missing() dictionary. + Doesn't update missing_pkg. + """ if package in self.missing: del self.missing[package] @@ -104,13 +141,22 @@ class DepManager: This is an ackward way to have a separate section to recommend a package after system main dependencies. - TODO: rework the logic to prevent needing it + TODO: rework the logic to prevent needing it. """ self.missing = {} + self.missing_pkg = {} def check_missing(self, progs): - self.run = {} + """ + Update self.missing_pkg, using progs dict to convert from the + agnostic package name to distro-specific one. + + Returns an string with the packages to be installed, sorted and + with eventual duplicates removed. + """ + + self.missing_pkg = {} for prog, dtype in sorted(self.missing.items()): # At least on some LTS distros like CentOS 7, texlive doesn't @@ -123,23 +169,26 @@ class DepManager: self.optional -= 1 continue - if not dtype in self.run: - self.run[dtype] = [] + if not dtype in self.missing_pkg: + self.missing_pkg[dtype] = [] - self.run[dtype].append(progs.get(prog, prog)) + self.missing_pkg[dtype].append(progs.get(prog, prog)) install = [] - for dtype in self.run.keys(): - install += self.run[dtype] + for dtype in self.missing_pkg.keys(): + install += self.missing_pkg[dtype] return " ".join(sorted(set(install))) def warn_install(self): + """ + Emit warnings/errors related to missing packages. + """ output_msg = "" - for dtype in sorted(self.run.keys()): - progs = " ".join(sorted(set(self.run[dtype]))) + for dtype in sorted(self.missing_pkg.keys()): + progs = " ".join(sorted(set(self.missing_pkg[dtype]))) try: name = DepManager.name(dtype) @@ -158,6 +207,11 @@ class AncillaryMethods: @staticmethod def which(prog): + """ + Our own implementation of which(). We could instead use + shutil.which(), but this function is simple enough. + Probably faster to use this implementation than to import shutil. + """ for path in os.environ.get("PATH", "").split(":"): full_path = os.path.join(path, prog) if os.access(full_path, os.X_OK): @@ -167,6 +221,10 @@ class AncillaryMethods: @staticmethod def get_python_version(cmd): + """ + Get python version from a Python binary. As we need to detect if + are out there newer python binaries, we can't rely on sys.release here. + """ result = SphinxDependencyChecker.run([cmd, "--version"], capture_output=True, text=True) @@ -181,7 +239,13 @@ class AncillaryMethods: @staticmethod def find_python(): + """ + Detect if are out there any python 3.xy version newer than the + current one. + Note: this routine is limited to up to 2 digits for python3. We + may need to update it one day, hopefully on a distant future. + """ patterns = [ "python3.[0-9]", "python3.[0-9][0-9]", @@ -200,7 +264,10 @@ class AncillaryMethods: @staticmethod def check_python(): - + """ + Check if the current python binary satisfies our minimal requirement + for Sphinx build. If not, re-run with a newer version if found. + """ cur_ver = sys.version_info[:3] if cur_ver >= MIN_PYTHON_VERSION: ver = ver_str(cur_ver) @@ -240,7 +307,10 @@ class AncillaryMethods: @staticmethod def run(*args, **kwargs): - """Excecute a command, hiding its output by default""" + """ + Excecute a command, hiding its output by default. + Preserve comatibility with older Python versions. + """ capture_output = kwargs.pop('capture_output', False) @@ -262,8 +332,15 @@ class AncillaryMethods: return subprocess.run(*args, **kwargs) class MissingCheckers(AncillaryMethods): + """ + Contains some ancillary checkers for different types of binaries and + package managers. + """ def __init__(self, args, texlive): + """ + Initialize its internal variables + """ self.pdf = args.pdf self.virtualenv = args.virtualenv self.version_check = args.version_check @@ -280,17 +357,20 @@ class MissingCheckers(AncillaryMethods): self.install = "" - # - # Methods to check if a feature exists - # - def check_missing_file(self, files, package, dtype): + """ + Does the file exists? If not, add it to missing dependencies. + """ for f in files: if os.path.exists(f): return self.deps.add_package(package, dtype) def check_program(self, prog, dtype): + """ + Does the program exists and it is at the PATH? + If not, add it to missing dependencies. + """ found = self.which(prog) if found: return found @@ -300,6 +380,18 @@ class MissingCheckers(AncillaryMethods): return None def check_perl_module(self, prog, dtype): + """ + Does perl have a dependency? Is it available? + If not, add it to missing dependencies. + + Right now, we still need Perl for doc build, as it is required + by some tools called at docs or kernel build time, like: + + scripts/documentation-file-ref-check + + Also, checkpatch is on Perl. + """ + # While testing with lxc download template, one of the # distros (Oracle) didn't have perl - nor even an option to install # before installing oraclelinux-release-el9 package. @@ -318,6 +410,10 @@ class MissingCheckers(AncillaryMethods): self.deps.add_package(prog, dtype) def check_python_module(self, module, is_optional=False): + """ + Does a python module exists outside venv? If not, add it to missing + dependencies. + """ if is_optional: dtype = DepManager.PYTHON_OPTIONAL else: @@ -329,6 +425,9 @@ class MissingCheckers(AncillaryMethods): self.deps.add_package(module, dtype) def check_rpm_missing(self, pkgs, dtype): + """ + Does a rpm package exists? If not, add it to missing dependencies. + """ for prog in pkgs: try: self.run(["rpm", "-q", prog], check=True) @@ -336,6 +435,9 @@ class MissingCheckers(AncillaryMethods): self.deps.add_package(prog, dtype) def check_pacman_missing(self, pkgs, dtype): + """ + Does a pacman package exists? If not, add it to missing dependencies. + """ for prog in pkgs: try: self.run(["pacman", "-Q", prog], check=True) @@ -343,6 +445,9 @@ class MissingCheckers(AncillaryMethods): self.deps.add_package(prog, dtype) def check_missing_tex(self, is_optional=False): + """ + Does a LaTeX package exists? If not, add it to missing dependencies. + """ if is_optional: dtype = DepManager.PDF_OPTIONAL else: @@ -371,6 +476,9 @@ class MissingCheckers(AncillaryMethods): self.deps.add_package(package, dtype) def get_sphinx_fname(self): + """ + Gets the binary filename for sphinx-build. + """ if "SPHINXBUILD" in os.environ: return os.environ["SPHINXBUILD"] @@ -386,6 +494,9 @@ class MissingCheckers(AncillaryMethods): return "" def get_sphinx_version(self, cmd): + """ + Gets sphinx-build version. + """ try: result = self.run([cmd, "--version"], stdout=subprocess.PIPE, @@ -404,6 +515,9 @@ class MissingCheckers(AncillaryMethods): return parse_version(match.group(1)) def check_sphinx(self, conf): + """ + Checks Sphinx minimal requirements + """ try: with open(conf, "r", encoding="utf-8") as f: for line in f: @@ -441,6 +555,10 @@ class MissingCheckers(AncillaryMethods): sys.exit(0) def catcheck(self, filename): + """ + Reads a file if it exists, returning as string. + If not found, returns an empty string. + """ if os.path.exists(filename): with open(filename, "r", encoding="utf-8") as f: return f.read().strip() From 6d5f4f3da1a82786650d38067bb4c5e4ed84dc61 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 12 Aug 2025 17:52:48 +0200 Subject: [PATCH 055/193] scripts: sphinx-pre-install: add docstring documentation This program is somewhat complex. Add some docstring documentation, explaining what each function and class is supposed to do. Most of the focus here were to describe the ancillary functions used to detect dependency needs. The main SphinxDependencyChecker still requires a lot of care, and probably need to be reorganized to clearly split the 4 types of output it produces: - Need to upgrade Python binary; - System install needs; - Virtual env install needs; - Python install needs via system packages, to run Sphinx natively. Yet, for now, I'm happy of having it a lot better documented than its Perl version. - While here, rename a parameter to have its usage better documented. No functional changes. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/0cadab2cab3f78ae6d9f378e92a45125fbc5188f.1754992972.git.mchehab+huawei@kernel.org --- scripts/sphinx-pre-install.py | 110 +++++++++++++++++++++++++++++++--- 1 file changed, 102 insertions(+), 8 deletions(-) diff --git a/scripts/sphinx-pre-install.py b/scripts/sphinx-pre-install.py index 1dc3f19804ab..1c96f6692e9a 100755 --- a/scripts/sphinx-pre-install.py +++ b/scripts/sphinx-pre-install.py @@ -9,6 +9,22 @@ # Don't add changes not compatible with it, it is meant to report # incompatible python versions. +""" +Dependency checker for Sphinx documentation Kernel build. + +This module provides tools to check for all required dependencies needed to +build documentation using Sphinx, including system packages, Python modules +and LaTeX packages for PDF generation. + +It detect packages for a subset of Linux distributions used by Kernel +maintainers, showing hints and missing dependencies. + +The main class SphinxDependencyChecker handles the dependency checking logic +and provides recommendations for installing missing packages. It supports both +system package installations and Python virtual environments. By default, +system pacage install is recommended. +""" + import argparse import os import re @@ -75,7 +91,7 @@ class DepManager: distro namespace, organized by type. - need: total number of needed dependencies. Never cleaned. - optional: total number of optional dependencies. Never cleaned. - - pdf: PDF support is enabled? + - pdf: Is PDF support enabled? """ self.missing = {} self.missing_pkg = {} @@ -565,6 +581,13 @@ class MissingCheckers(AncillaryMethods): return "" def check_missing(self, progs): + """ + Check for missing dependencies using the provided program mapping. + + The actual distro-specific programs are mapped via progs argument. + + Returns True if there are missing dependencies, False otherwise. + """ self.install += self.deps.check_missing(progs) if self.verbose_warn_install: self.deps.warn_install() @@ -633,8 +656,18 @@ class MissingCheckers(AncillaryMethods): return system_release class SphinxDependencyChecker(MissingCheckers): + """ + Main class for checking Sphinx documentation build dependencies. + - Check for missing system packages; + - Check for missing Python modules; + - Check for missing LaTeX packages needed by PDF generation; + - Propose Sphinx install via Python Virtual environment; + - Propose Sphinx install via distro-specific package install. + """ def __init__(self, args): + """Initialize checker variables""" + # List of required texlive packages on Fedora and OpenSuse texlive = { "amsfonts.sty": "texlive-amsfonts", @@ -705,6 +738,9 @@ class SphinxDependencyChecker(MissingCheckers): # def give_debian_hints(self): + """ + Provide package installation hints for Debian-based distros. + """ progs = { "Pod::Usage": "perl-modules", "convert": "imagemagick", @@ -745,6 +781,10 @@ class SphinxDependencyChecker(MissingCheckers): print(f"\n\tsudo apt-get install {self.install}") def give_redhat_hints(self): + """ + Provide package installation hints for RedHat-based distros + (Fedora, RHEL and RHEL-based variants). + """ progs = { "Pod::Usage": "perl-Pod-Usage", "convert": "ImageMagick", @@ -837,6 +877,10 @@ class SphinxDependencyChecker(MissingCheckers): print(f"\n\tsudo dnf install -y {self.install}") def give_opensuse_hints(self): + """ + Provide package installation hints for openSUSE-based distros + (Leap and Tumbleweed). + """ progs = { "Pod::Usage": "perl-Pod-Usage", "convert": "ImageMagick", @@ -909,6 +953,9 @@ class SphinxDependencyChecker(MissingCheckers): print(f"\n\tsudo zypper install --no-recommends {self.install}") def give_mageia_hints(self): + """ + Provide package installation hints for Mageia and OpenMandriva. + """ progs = { "Pod::Usage": "perl-Pod-Usage", "convert": "ImageMagick", @@ -956,6 +1003,9 @@ class SphinxDependencyChecker(MissingCheckers): print(f"\n\tsudo {packager_cmd} {self.install}") def give_arch_linux_hints(self): + """ + Provide package installation hints for ArchLinux. + """ progs = { "convert": "imagemagick", "dot": "graphviz", @@ -989,6 +1039,9 @@ class SphinxDependencyChecker(MissingCheckers): print(f"\n\tsudo pacman -S {self.install}") def give_gentoo_hints(self): + """ + Provide package installation hints for Gentoo. + """ progs = { "convert": "media-gfx/imagemagick", "dot": "media-gfx/graphviz", @@ -1107,7 +1160,12 @@ class SphinxDependencyChecker(MissingCheckers): # def check_distros(self): - # OS-specific hints logic + """ + OS-specific hints logic. Seeks for a hinter. If found, provide + package-manager-specific install commands. + + Otherwise, just lists the missing dependencies. + """ os_hints = { re.compile("Red Hat Enterprise Linux"): self.give_redhat_hints, re.compile("Fedora"): self.give_redhat_hints, @@ -1159,10 +1217,22 @@ class SphinxDependencyChecker(MissingCheckers): # Common dependencies # def deactivate_help(self): + """ + Print a helper message to disable a virtual environment. + """ + print("\n If you want to exit the virtualenv, you can use:") print("\tdeactivate") def get_virtenv(self): + """ + Give a hint about how to activate an already-existing virtual + environment containing sphinx-build. + + Returns a tuble with (activate_cmd_path, sphinx_version) with + the newest available virtual env. + """ + cwd = os.getcwd() activates = [] @@ -1207,6 +1277,14 @@ class SphinxDependencyChecker(MissingCheckers): return ("", ver) def recommend_sphinx_upgrade(self): + """ + Check if Sphinx needs to be upgraded. + + Returns a tuple with the higest available Sphinx version if found. + Otherwise, returns None to indicate either that no upgrade is needed + or no venv was found. + """ + # Avoid running sphinx-builds from venv if cur_version is good if self.cur_version and self.cur_version >= RECOMMENDED_VERSION: self.latest_avail_ver = self.cur_version @@ -1247,6 +1325,9 @@ class SphinxDependencyChecker(MissingCheckers): return self.latest_avail_ver def recommend_package(self): + """ + Recommend installing Sphinx as a distro-specific package. + """ print("\n2) As a package with:") @@ -1270,11 +1351,19 @@ class SphinxDependencyChecker(MissingCheckers): self.verbose_warn_install = old_verbose def recommend_sphinx_version(self, virtualenv_cmd): - # The logic here is complex, as it have to deal with different versions: - # - minimal supported version; - # - minimal PDF version; - # - recommended version. - # It also needs to work fine with both distro's package and venv/virtualenv + """ + Provide recommendations for installing or upgrading Sphinx based + on current version. + + The logic here is complex, as it have to deal with different versions: + + - minimal supported version; + - minimal PDF version; + - recommended version. + + It also needs to work fine with both distro's package and + venv/virtualenv + """ if self.recommend_python: print("\nPython version is incompatible with doc build.\n" \ @@ -1369,6 +1458,10 @@ class SphinxDependencyChecker(MissingCheckers): "\thttps://github.com/sphinx-doc/sphinx/pull/8313") def check_needs(self): + """ + Main method that checks needed dependencies and provides + recommendations. + """ self.python_cmd = sys.executable # Check if Sphinx is already accessible from current environment @@ -1451,6 +1544,7 @@ Process some flags related to Sphinx installation and documentation build. def main(): + """Main function""" parser = argparse.ArgumentParser(description=DESCRIPTION) parser.add_argument( @@ -1481,6 +1575,6 @@ def main(): checker.check_python() checker.check_needs() - +# Call main if not used as module if __name__ == "__main__": main() From 8b45effaa2ce2790e3b391e1ac4bb668e0d37560 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 12 Aug 2025 17:52:49 +0200 Subject: [PATCH 056/193] scripts: sphinx-pre-install: fix several codingstyle issues Address most pylint issues. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/5139b18535e1436e4b1773706224a9ec3a386697.1754992972.git.mchehab+huawei@kernel.org --- scripts/sphinx-pre-install.py | 52 +++++++++++++++++------------------ 1 file changed, 26 insertions(+), 26 deletions(-) diff --git a/scripts/sphinx-pre-install.py b/scripts/sphinx-pre-install.py index 1c96f6692e9a..1b11162da9fb 100755 --- a/scripts/sphinx-pre-install.py +++ b/scripts/sphinx-pre-install.py @@ -2,8 +2,8 @@ # SPDX-License-Identifier: GPL-2.0-or-later # Copyright (c) 2017-2025 Mauro Carvalho Chehab # -# pylint: disable=C0103,C0114,C0115,C0116,C0301 -# pylint: disable=R0902,R0904,R0912,R0915,R1705,R1710,E1121 +# pylint: disable=C0103,C0114,C0115,C0116,C0301,C0302 +# pylint: disable=R0902,R0904,R0911,R0912,R0914,R0915,R1705,R1710,E1121 # Note: this script requires at least Python 3.6 to run. # Don't add changes not compatible with it, it is meant to report @@ -115,7 +115,7 @@ class DepManager: if dtype[1]: return f"ERROR: {msg} mandatory deps missing" else: - out = f"Warning: {msg} optional deps missing" + return f"Warning: {msg} optional deps missing" @staticmethod def is_optional(dtype): @@ -125,7 +125,7 @@ class DepManager: @staticmethod def is_pdf(dtype): """Ancillary routine to report if a dependency is for PDF generation""" - if (dtype[0] == DepManager._PDF_TYPE): + if dtype[0] == DepManager._PDF_TYPE: return True return False @@ -191,8 +191,8 @@ class DepManager: self.missing_pkg[dtype].append(progs.get(prog, prog)) install = [] - for dtype in self.missing_pkg.keys(): - install += self.missing_pkg[dtype] + for dtype, pkgs in self.missing_pkg.items(): + install += pkgs return " ".join(sorted(set(install))) @@ -267,8 +267,6 @@ class AncillaryMethods: "python3.[0-9][0-9]", ] - new_python_cmd = None - # Seek for a python binary newer than MIN_PYTHON_VERSION for path in os.getenv("PATH", "").split(":"): for pattern in patterns: @@ -276,7 +274,7 @@ class AncillaryMethods: if os.path.isfile(cmd) and os.access(cmd, os.X_OK): version = SphinxDependencyChecker.get_python_version(cmd) if version >= MIN_PYTHON_VERSION: - return(cmd) + return cmd @staticmethod def check_python(): @@ -306,8 +304,8 @@ class AncillaryMethods: new_python_cmd = SphinxDependencyChecker.find_python() if not new_python_cmd: - print(f"ERROR: Python version {python_ver} is not spported anymore") - print(f" Can't find a new version. This script may fail") + print(f"ERROR: Python version {python_ver} is not spported anymore\n") + print(" Can't find a new version. This script may fail") return # Restart script using the newer version @@ -362,6 +360,9 @@ class MissingCheckers(AncillaryMethods): self.version_check = args.version_check self.texlive = texlive + self.min_version = (0, 0, 0) + self.cur_version = (0, 0, 0) + self.deps = DepManager(self.pdf) self.need_symlink = 0 @@ -370,8 +371,10 @@ class MissingCheckers(AncillaryMethods): self.verbose_warn_install = 1 self.virtenv_dir = "" - self.install = "" + self.python_cmd = "" + + self.virtenv_prefix = ["sphinx_", "Sphinx_" ] def check_missing_file(self, files, package, dtype): """ @@ -542,10 +545,10 @@ class MissingCheckers(AncillaryMethods): self.min_version = parse_version(match.group(1)) break except IOError: - sys.exit(f"Can't open {self.conf}") + sys.exit(f"Can't open {conf}") if not self.min_version: - sys.exit(f"Can't get needs_sphinx version from {self.conf}") + sys.exit(f"Can't get needs_sphinx version from {conf}") self.virtenv_dir = self.virtenv_prefix[0] + "latest" @@ -709,7 +712,6 @@ class SphinxDependencyChecker(MissingCheckers): self.rec_sphinx_upgrade = 0 self.system_release = self.get_system_release() - self.python_cmd = "" self.activate_cmd = "" # Some distros may not have a Sphinx shipped package compatible with @@ -722,8 +724,6 @@ class SphinxDependencyChecker(MissingCheckers): # Certain hints are meant to be shown only once self.first_hint = True - self.min_version = (0, 0, 0) - self.cur_version = (0, 0, 0) self.latest_avail_ver = (0, 0, 0) self.venv_ver = (0, 0, 0) @@ -731,7 +731,6 @@ class SphinxDependencyChecker(MissingCheckers): self.conf = prefix + "Documentation/conf.py" self.requirement_file = prefix + "Documentation/sphinx/requirements.txt" - self.virtenv_prefix = ["sphinx_", "Sphinx_" ] # # Distro-specific hints methods @@ -814,6 +813,7 @@ class SphinxDependencyChecker(MissingCheckers): if not rel: print("Couldn't identify release number") + noto_sans_redhat = None self.pdf = False elif re.search("Fedora", self.system_release): # Fedora 38 and upper use this CJK font @@ -1111,7 +1111,7 @@ class SphinxDependencyChecker(MissingCheckers): for fname, portage in portages.items(): install = False - while install == False: + while install is False: if not files: # No files under package.usage. Install all install = True @@ -1335,7 +1335,7 @@ class SphinxDependencyChecker(MissingCheckers): old_optional = self.deps.optional self.pdf = False - self.optional = 0 + self.deps.optional = 0 self.install = "" old_verbose = self.verbose_warn_install self.verbose_warn_install = 0 @@ -1346,8 +1346,8 @@ class SphinxDependencyChecker(MissingCheckers): self.check_distros() - self.need = old_need - self.optional = old_optional + self.deps.need = old_need + self.deps.optional = old_optional self.verbose_warn_install = old_verbose def recommend_sphinx_version(self, virtualenv_cmd): @@ -1528,13 +1528,13 @@ class SphinxDependencyChecker(MissingCheckers): self.recommend_sphinx_version(virtualenv_cmd) print("") - if not self.optional: + if not self.deps.optional: print("All optional dependencies are met.") - if self.need == 1: + if self.deps.need == 1: sys.exit("Can't build as 1 mandatory dependency is missing") - elif self.need: - sys.exit(f"Can't build as {self.need} mandatory dependencies are missing") + elif self.deps.need: + sys.exit(f"Can't build as {self.deps.need} mandatory dependencies are missing") print("Needed package dependencies are met.") From 24a34b3b453dc8fff0366a28c472b603f98a5c20 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 12 Aug 2025 17:52:50 +0200 Subject: [PATCH 057/193] scripts: sphinx-pre-install: rework install command logic Cleanup the code to remove some redundancy and to let it be clearer about the command install instructions. Ensure that special instructions will be shown only once, before the actual install command. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/a6120449d9cc14346e867d1ef8944ae28ddbf3f6.1754992972.git.mchehab+huawei@kernel.org --- scripts/sphinx-pre-install.py | 179 ++++++++++++++++------------------ 1 file changed, 82 insertions(+), 97 deletions(-) diff --git a/scripts/sphinx-pre-install.py b/scripts/sphinx-pre-install.py index 1b11162da9fb..7dfe5c2a6cc2 100755 --- a/scripts/sphinx-pre-install.py +++ b/scripts/sphinx-pre-install.py @@ -213,7 +213,7 @@ class DepManager: raise KeyError(f"ERROR!!!: invalid dtype for {progs}: {dtype}") if output_msg: - print(f"\n{output_msg}\n") + print(f"\n{output_msg}") class AncillaryMethods: """ @@ -583,23 +583,6 @@ class MissingCheckers(AncillaryMethods): return f.read().strip() return "" - def check_missing(self, progs): - """ - Check for missing dependencies using the provided program mapping. - - The actual distro-specific programs are mapped via progs argument. - - Returns True if there are missing dependencies, False otherwise. - """ - self.install += self.deps.check_missing(progs) - if self.verbose_warn_install: - self.deps.warn_install() - - if not self.deps.need and not self.deps.optional: - return False - - return True - def get_system_release(self): """ Determine the system type. There's no unique way that would work @@ -722,7 +705,7 @@ class SphinxDependencyChecker(MissingCheckers): self.recommend_python = None # Certain hints are meant to be shown only once - self.first_hint = True + self.distro_msg = None self.latest_avail_ver = (0, 0, 0) self.venv_ver = (0, 0, 0) @@ -732,6 +715,33 @@ class SphinxDependencyChecker(MissingCheckers): self.conf = prefix + "Documentation/conf.py" self.requirement_file = prefix + "Documentation/sphinx/requirements.txt" + def get_install_progs(self, progs, cmd, extra=None): + """ + Check for missing dependencies using the provided program mapping. + + The actual distro-specific programs are mapped via progs argument. + """ + install = self.deps.check_missing(progs) + + if self.verbose_warn_install: + self.deps.warn_install() + + if not install: + return + + if cmd: + if self.verbose_warn_install: + msg = "You should run:" + else: + msg = "" + + if extra: + msg += "\n\t" + extra.replace("\n", "\n\t") + + return(msg + "\n\tsudo " + cmd + " " + install) + + return None + # # Distro-specific hints methods # @@ -772,12 +782,7 @@ class SphinxDependencyChecker(MissingCheckers): self.check_program("dvipng", DepManager.PDF_MANDATORY) - if self.check_missing(progs): - return - - if self.verbose_warn_install: - print("You should run:") - print(f"\n\tsudo apt-get install {self.install}") + return self.get_install_progs(progs, "apt-get install") def give_redhat_hints(self): """ @@ -838,18 +843,16 @@ class SphinxDependencyChecker(MissingCheckers): self.deps.add_package("python39", DepManager.SYSTEM_MANDATORY) self.recommend_python = True - if self.first_hint: - print("Note: RHEL-based distros typically require extra repositories.\n" \ - "For most, enabling epel and crb are enough:\n" \ - "\tsudo dnf install -y epel-release", \ - "\tsudo dnf config-manager --set-enabled crb\n" \ - "Yet, some may have other required repositories. Those commands could be useful:\n" \ - "\tsudo dnf repolist all\n" \ - "\tsudo dnf repoquery --available --info \n", - "\tsudo dnf config-manager --set-enabled '*' # enable all - probably not what you want") - - self.first_hint = False - + if not self.distro_msg: + self.distro_msg = \ + "Note: RHEL-based distros typically require extra repositories.\n" \ + "For most, enabling epel and crb are enough:\n" \ + "\tsudo dnf install -y epel-release\n" \ + "\tsudo dnf config-manager --set-enabled crb\n" \ + "Yet, some may have other required repositories. Those commands could be useful:\n" \ + "\tsudo dnf repolist all\n" \ + "\tsudo dnf repoquery --available --info \n" \ + "\tsudo dnf config-manager --set-enabled '*' # enable all - probably not what you want" if self.pdf: pdf_pkgs = [ @@ -868,13 +871,7 @@ class SphinxDependencyChecker(MissingCheckers): if not fedora and rel == 8: self.deps.del_package("texlive-ctex") - if self.check_missing(progs): - return - - if self.verbose_warn_install: - print("You should run:") - - print(f"\n\tsudo dnf install -y {self.install}") + return self.get_install_progs(progs, "dnf install") def give_opensuse_hints(self): """ @@ -945,12 +942,7 @@ class SphinxDependencyChecker(MissingCheckers): if self.pdf: self.check_missing_tex() - if self.check_missing(progs): - return - - if self.verbose_warn_install: - print("You should run:") - print(f"\n\tsudo zypper install --no-recommends {self.install}") + return self.get_install_progs(progs, "zypper install --no-recommends") def give_mageia_hints(self): """ @@ -995,12 +987,7 @@ class SphinxDependencyChecker(MissingCheckers): self.check_missing_file(pdf_pkgs, noto_sans, DepManager.PDF_MANDATORY) self.check_rpm_missing(tex_pkgs, DepManager.PDF_MANDATORY) - if self.check_missing(progs): - return - - if self.verbose_warn_install: - print("You should run:") - print(f"\n\tsudo {packager_cmd} {self.install}") + return self.get_install_progs(progs, packager_cmd) def give_arch_linux_hints(self): """ @@ -1023,20 +1010,15 @@ class SphinxDependencyChecker(MissingCheckers): ] if self.pdf: - self.check_pacman_missing(archlinux_tex_pkgs, DepManager.PDF_MANDATORY) + self.check_pacman_missing(archlinux_tex_pkgs, + DepManager.PDF_MANDATORY) - self.check_missing_file( - ["/usr/share/fonts/noto-cjk/NotoSansCJK-Regular.ttc"], - "noto-fonts-cjk", - 2, - ) + self.check_missing_file(["/usr/share/fonts/noto-cjk/NotoSansCJK-Regular.ttc"], + "noto-fonts-cjk", + DepManager.PDF_MANDATORY) - if self.check_missing(progs): - return - if self.verbose_warn_install: - print("You should run:") - print(f"\n\tsudo pacman -S {self.install}") + return self.get_install_progs(progs, "pacman -S") def give_gentoo_hints(self): """ @@ -1065,13 +1047,6 @@ class SphinxDependencyChecker(MissingCheckers): for package, files in pdf_pkgs.items(): self.check_missing_file(files, package, DepManager.PDF_MANDATORY) - if self.check_missing(progs): - return - - if self.verbose_warn_install: - print("You should run:") - print("\n") - # Handling dependencies is a nightmare, as Gentoo refuses to emerge # some packages if there's no package.use file describing them. # To make it worse, compilation flags shall also be present there @@ -1104,7 +1079,10 @@ class SphinxDependencyChecker(MissingCheckers): "zziblib": "dev-libs/zziplib sdl", } - if self.first_hint: + extra_cmds = "" + if not self.distro_msg: + self.distro_msg = "Note: Gentoo requires package.use to be adjusted before emerging packages" + use_base = "/etc/portage/package.use" files = glob(f"{use_base}/*") @@ -1148,23 +1126,23 @@ class SphinxDependencyChecker(MissingCheckers): # emit a code to setup missing USE if install: - print(f"\tsudo su -c 'echo \"{portage}\" > {use_base}/{fname}'") - - self.first_hint = False + extra_cmds += (f"sudo su -c 'echo \"{portage}\" > {use_base}/{fname}'\n") # Now, we can use emerge and let it respect USE - print(f"\tsudo emerge --ask --changed-use --binpkg-respect-use=y {self.install}") + return self.get_install_progs(progs, + "emerge --ask --changed-use --binpkg-respect-use=y", + extra_cmds) - # - # Dispatch the check to an os_specific hinter - # - - def check_distros(self): + def get_install(self): """ - OS-specific hints logic. Seeks for a hinter. If found, provide - package-manager-specific install commands. + OS-specific hints logic. Seeks for a hinter. If found, use it to + provide package-manager specific install commands. - Otherwise, just lists the missing dependencies. + Otherwise, outputs install instructions for the meta-packages. + + Returns a string with the command to be executed to install the + the needed packages, if distro found. Otherwise, return just a + list of packages that require installation. """ os_hints = { re.compile("Red Hat Enterprise Linux"): self.give_redhat_hints, @@ -1195,9 +1173,7 @@ class SphinxDependencyChecker(MissingCheckers): # If the OS is detected, use per-OS hint logic for regex, os_hint in os_hints.items(): if regex.search(self.system_release): - os_hint() - - return + return os_hint() # # Fall-back to generic hint code for other distros @@ -1207,11 +1183,12 @@ class SphinxDependencyChecker(MissingCheckers): if self.pdf: self.check_missing_tex() - self.check_missing(progs) + self.distro_msg = \ + f"I don't know distro {self.system_release}.\n" \ + "So, I can't provide you a hint with the install procedure.\n" \ + "There are likely missing dependencies.\n" - print(f"I don't know distro {self.system_release}.") - print("So, I can't provide you a hint with the install procedure.") - print("There are likely missing dependencies.") + return self.get_install_progs(progs, None) # # Common dependencies @@ -1336,7 +1313,6 @@ class SphinxDependencyChecker(MissingCheckers): self.pdf = False self.deps.optional = 0 - self.install = "" old_verbose = self.verbose_warn_install self.verbose_warn_install = 0 @@ -1344,7 +1320,9 @@ class SphinxDependencyChecker(MissingCheckers): self.deps.add_package("python-sphinx", DepManager.PYTHON_MANDATORY) - self.check_distros() + cmd = self.get_install() + if cmd: + print(cmd) self.deps.need = old_need self.deps.optional = old_optional @@ -1511,7 +1489,14 @@ class SphinxDependencyChecker(MissingCheckers): self.check_program("latexmk", DepManager.PDF_MANDATORY) # Do distro-specific checks and output distro-install commands - self.check_distros() + cmd = self.get_install() + if cmd: + print(cmd) + + # If distro requires some special instructions, print here. + # Please notice that get_install() needs to be called first. + if self.distro_msg: + print("\n" + self.distro_msg) if not self.python_cmd: if self.need == 1: From d43cd965f3a646d22851192c659b787dba311d87 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 12 Aug 2025 17:52:51 +0200 Subject: [PATCH 058/193] docs: Makefile: switch to the new scripts/sphinx-pre-install.py Now that we have a better, improved Python script, use it when checking for documentation build dependencies. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/79508fb071512c33e807f5411bbff1904751b5d3.1754992972.git.mchehab+huawei@kernel.org --- Documentation/Makefile | 14 +++++++------- .../{sphinx-pre-install.py => sphinx-pre-install} | 0 2 files changed, 7 insertions(+), 7 deletions(-) rename scripts/{sphinx-pre-install.py => sphinx-pre-install} (100%) diff --git a/Documentation/Makefile b/Documentation/Makefile index c486fe3cc5e1..b98477df5ddf 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -46,7 +46,7 @@ ifeq ($(HAVE_SPHINX),0) .DEFAULT: $(warning The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed and in PATH, or set the SPHINXBUILD make variable to point to the full path of the '$(SPHINXBUILD)' executable.) @echo - @$(srctree)/scripts/sphinx-pre-install.pl + @$(srctree)/scripts/sphinx-pre-install @echo " SKIP Sphinx $@ target." else # HAVE_SPHINX @@ -121,7 +121,7 @@ $(YNL_RST_DIR)/%.rst: $(YNL_YAML_DIR)/%.yaml $(YNL_TOOL) htmldocs texinfodocs latexdocs epubdocs xmldocs: $(YNL_INDEX) htmldocs: - @$(srctree)/scripts/sphinx-pre-install.pl --version-check + @$(srctree)/scripts/sphinx-pre-install --version-check @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var))) # If Rust support is available and .config exists, add rustdoc generated contents. @@ -135,7 +135,7 @@ endif endif texinfodocs: - @$(srctree)/scripts/sphinx-pre-install.pl --version-check + @$(srctree)/scripts/sphinx-pre-install --version-check @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,texinfo,$(var),texinfo,$(var))) # Note: the 'info' Make target is generated by sphinx itself when @@ -147,7 +147,7 @@ linkcheckdocs: @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,linkcheck,$(var),,$(var))) latexdocs: - @$(srctree)/scripts/sphinx-pre-install.pl --version-check + @$(srctree)/scripts/sphinx-pre-install --version-check @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,latex,$(var),latex,$(var))) ifeq ($(HAVE_PDFLATEX),0) @@ -160,7 +160,7 @@ else # HAVE_PDFLATEX pdfdocs: DENY_VF = XDG_CONFIG_HOME=$(FONTS_CONF_DENY_VF) pdfdocs: latexdocs - @$(srctree)/scripts/sphinx-pre-install.pl --version-check + @$(srctree)/scripts/sphinx-pre-install --version-check $(foreach var,$(SPHINXDIRS), \ $(MAKE) PDFLATEX="$(PDFLATEX)" LATEXOPTS="$(LATEXOPTS)" $(DENY_VF) -C $(BUILDDIR)/$(var)/latex || sh $(srctree)/scripts/check-variable-fonts.sh || exit; \ mkdir -p $(BUILDDIR)/$(var)/pdf; \ @@ -170,11 +170,11 @@ pdfdocs: latexdocs endif # HAVE_PDFLATEX epubdocs: - @$(srctree)/scripts/sphinx-pre-install.pl --version-check + @$(srctree)/scripts/sphinx-pre-install --version-check @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,epub,$(var),epub,$(var))) xmldocs: - @$(srctree)/scripts/sphinx-pre-install.pl --version-check + @$(srctree)/scripts/sphinx-pre-install --version-check @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,xml,$(var),xml,$(var))) endif # HAVE_SPHINX diff --git a/scripts/sphinx-pre-install.py b/scripts/sphinx-pre-install similarity index 100% rename from scripts/sphinx-pre-install.py rename to scripts/sphinx-pre-install From 29e71d96837dd49ab2f35f3524a1ceda0ff21ea7 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 12 Aug 2025 17:52:52 +0200 Subject: [PATCH 059/193] scripts: sphinx-pre-install.pl: get rid of the old script All features were ported to the Python version. Plus, it supports more variants and contain fixes. So, drop the old version. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/6900872e6b89b7ff304e70f5d1c23cbb3c757d28.1754992972.git.mchehab+huawei@kernel.org --- scripts/sphinx-pre-install.pl | 1056 --------------------------------- 1 file changed, 1056 deletions(-) delete mode 100755 scripts/sphinx-pre-install.pl diff --git a/scripts/sphinx-pre-install.pl b/scripts/sphinx-pre-install.pl deleted file mode 100755 index 07234d482fa8..000000000000 --- a/scripts/sphinx-pre-install.pl +++ /dev/null @@ -1,1056 +0,0 @@ -#!/usr/bin/env perl -# SPDX-License-Identifier: GPL-2.0-or-later -use strict; - -# Copyright (c) 2017-2020 Mauro Carvalho Chehab -# - -my $prefix = "./"; -$prefix = "$ENV{'srctree'}/" if ($ENV{'srctree'}); - -my $conf = $prefix . "Documentation/conf.py"; -my $requirement_file = $prefix . "Documentation/sphinx/requirements.txt"; -my $virtenv_prefix = "sphinx_"; - -# -# Static vars -# - -my %missing; -my $system_release; -my $need = 0; -my $optional = 0; -my $need_symlink = 0; -my $need_sphinx = 0; -my $need_pip = 0; -my $need_virtualenv = 0; -my $rec_sphinx_upgrade = 0; -my $verbose_warn_install = 1; -my $install = ""; -my $virtenv_dir = ""; -my $python_cmd = ""; -my $activate_cmd; -my $min_version; -my $cur_version; -my $rec_version = "3.4.3"; -my $latest_avail_ver; - -# -# Command line arguments -# - -my $pdf = 1; -my $virtualenv = 1; -my $version_check = 0; - -# -# List of required texlive packages on Fedora and OpenSuse -# - -my %texlive = ( - 'amsfonts.sty' => 'texlive-amsfonts', - 'amsmath.sty' => 'texlive-amsmath', - 'amssymb.sty' => 'texlive-amsfonts', - 'amsthm.sty' => 'texlive-amscls', - 'anyfontsize.sty' => 'texlive-anyfontsize', - 'atbegshi.sty' => 'texlive-oberdiek', - 'bm.sty' => 'texlive-tools', - 'capt-of.sty' => 'texlive-capt-of', - 'cmap.sty' => 'texlive-cmap', - 'ecrm1000.tfm' => 'texlive-ec', - 'eqparbox.sty' => 'texlive-eqparbox', - 'eu1enc.def' => 'texlive-euenc', - 'fancybox.sty' => 'texlive-fancybox', - 'fancyvrb.sty' => 'texlive-fancyvrb', - 'float.sty' => 'texlive-float', - 'fncychap.sty' => 'texlive-fncychap', - 'footnote.sty' => 'texlive-mdwtools', - 'framed.sty' => 'texlive-framed', - 'luatex85.sty' => 'texlive-luatex85', - 'multirow.sty' => 'texlive-multirow', - 'needspace.sty' => 'texlive-needspace', - 'palatino.sty' => 'texlive-psnfss', - 'parskip.sty' => 'texlive-parskip', - 'polyglossia.sty' => 'texlive-polyglossia', - 'tabulary.sty' => 'texlive-tabulary', - 'threeparttable.sty' => 'texlive-threeparttable', - 'titlesec.sty' => 'texlive-titlesec', - 'ucs.sty' => 'texlive-ucs', - 'upquote.sty' => 'texlive-upquote', - 'wrapfig.sty' => 'texlive-wrapfig', - 'ctexhook.sty' => 'texlive-ctex', -); - -# -# Subroutines that checks if a feature exists -# - -sub check_missing(%) -{ - my %map = %{$_[0]}; - - foreach my $prog (sort keys %missing) { - my $is_optional = $missing{$prog}; - - # At least on some LTS distros like CentOS 7, texlive doesn't - # provide all packages we need. When such distros are - # detected, we have to disable PDF output. - # - # So, we need to ignore the packages that distros would - # need for LaTeX to work - if ($is_optional == 2 && !$pdf) { - $optional--; - next; - } - - if ($verbose_warn_install) { - if ($is_optional) { - print "Warning: better to also install \"$prog\".\n"; - } else { - print "ERROR: please install \"$prog\", otherwise, build won't work.\n"; - } - } - if (defined($map{$prog})) { - $install .= " " . $map{$prog}; - } else { - $install .= " " . $prog; - } - } - - $install =~ s/^\s//; -} - -sub add_package($$) -{ - my $package = shift; - my $is_optional = shift; - - $missing{$package} = $is_optional; - if ($is_optional) { - $optional++; - } else { - $need++; - } -} - -sub check_missing_file($$$) -{ - my $files = shift; - my $package = shift; - my $is_optional = shift; - - for (@$files) { - return if(-e $_); - } - - add_package($package, $is_optional); -} - -sub findprog($) -{ - foreach(split(/:/, $ENV{PATH})) { - return "$_/$_[0]" if(-x "$_/$_[0]"); - } -} - -sub find_python_no_venv() -{ - my $prog = shift; - - my $cur_dir = qx(pwd); - $cur_dir =~ s/\s+$//; - - foreach my $dir (split(/:/, $ENV{PATH})) { - next if ($dir =~ m,($cur_dir)/sphinx,); - return "$dir/python3" if(-x "$dir/python3"); - } - foreach my $dir (split(/:/, $ENV{PATH})) { - next if ($dir =~ m,($cur_dir)/sphinx,); - return "$dir/python" if(-x "$dir/python"); - } - return "python"; -} - -sub check_program($$) -{ - my $prog = shift; - my $is_optional = shift; - - return $prog if findprog($prog); - - add_package($prog, $is_optional); -} - -sub check_perl_module($$) -{ - my $prog = shift; - my $is_optional = shift; - - my $err = system("perl -M$prog -e 1 2>/dev/null /dev/null"); - return if ($err == 0); - - add_package($prog, $is_optional); -} - -sub check_python_module($$) -{ - my $prog = shift; - my $is_optional = shift; - - return if (!$python_cmd); - - my $err = system("$python_cmd -c 'import $prog' 2>/dev/null /dev/null"); - return if ($err == 0); - - add_package($prog, $is_optional); -} - -sub check_rpm_missing($$) -{ - my @pkgs = @{$_[0]}; - my $is_optional = $_[1]; - - foreach my $prog(@pkgs) { - my $err = system("rpm -q '$prog' 2>/dev/null >/dev/null"); - add_package($prog, $is_optional) if ($err); - } -} - -sub check_pacman_missing($$) -{ - my @pkgs = @{$_[0]}; - my $is_optional = $_[1]; - - foreach my $prog(@pkgs) { - my $err = system("pacman -Q '$prog' 2>/dev/null >/dev/null"); - add_package($prog, $is_optional) if ($err); - } -} - -sub check_missing_tex($) -{ - my $is_optional = shift; - my $kpsewhich = findprog("kpsewhich"); - - foreach my $prog(keys %texlive) { - my $package = $texlive{$prog}; - if (!$kpsewhich) { - add_package($package, $is_optional); - next; - } - my $file = qx($kpsewhich $prog); - add_package($package, $is_optional) if ($file =~ /^\s*$/); - } -} - -sub get_sphinx_fname() -{ - if ($ENV{'SPHINXBUILD'}) { - return $ENV{'SPHINXBUILD'}; - } - - my $fname = "sphinx-build"; - return $fname if findprog($fname); - - $fname = "sphinx-build-3"; - if (findprog($fname)) { - $need_symlink = 1; - return $fname; - } - - return ""; -} - -sub get_sphinx_version($) -{ - my $cmd = shift; - my $ver; - - open IN, "$cmd --version 2>&1 |"; - while () { - if (m/^\s*sphinx-build\s+([\d\.]+)((\+\/[\da-f]+)|(b\d+))?$/) { - $ver=$1; - last; - } - # Sphinx 1.2.x uses a different format - if (m/^\s*Sphinx.*\s+([\d\.]+)$/) { - $ver=$1; - last; - } - } - close IN; - return $ver; -} - -sub check_sphinx() -{ - open IN, $conf or die "Can't open $conf"; - while () { - if (m/^\s*needs_sphinx\s*=\s*[\'\"]([\d\.]+)[\'\"]/) { - $min_version=$1; - last; - } - } - close IN; - - die "Can't get needs_sphinx version from $conf" if (!$min_version); - - $virtenv_dir = $virtenv_prefix . "latest"; - - my $sphinx = get_sphinx_fname(); - if ($sphinx eq "") { - $need_sphinx = 1; - return; - } - - $cur_version = get_sphinx_version($sphinx); - die "$sphinx didn't return its version" if (!$cur_version); - - if ($cur_version lt $min_version) { - printf "ERROR: Sphinx version is %s. It should be >= %s\n", - $cur_version, $min_version; - $need_sphinx = 1; - return; - } - - return if ($cur_version lt $rec_version); - - # On version check mode, just assume Sphinx has all mandatory deps - exit (0) if ($version_check); -} - -# -# Ancillary subroutines -# - -sub catcheck($) -{ - my $res = ""; - $res = qx(cat $_[0]) if (-r $_[0]); - return $res; -} - -sub which($) -{ - my $file = shift; - my @path = split ":", $ENV{PATH}; - - foreach my $dir(@path) { - my $name = $dir.'/'.$file; - return $name if (-x $name ); - } - return undef; -} - -# -# Subroutines that check distro-specific hints -# - -sub give_debian_hints() -{ - my %map = ( - "python-sphinx" => "python3-sphinx", - "yaml" => "python3-yaml", - "ensurepip" => "python3-venv", - "virtualenv" => "virtualenv", - "dot" => "graphviz", - "convert" => "imagemagick", - "Pod::Usage" => "perl-modules", - "xelatex" => "texlive-xetex", - "rsvg-convert" => "librsvg2-bin", - ); - - if ($pdf) { - check_missing_file(["/usr/share/texlive/texmf-dist/tex/latex/ctex/ctexhook.sty"], - "texlive-lang-chinese", 2); - - check_missing_file(["/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf"], - "fonts-dejavu", 2); - - check_missing_file(["/usr/share/fonts/noto-cjk/NotoSansCJK-Regular.ttc", - "/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc", - "/usr/share/fonts/opentype/noto/NotoSerifCJK-Regular.ttc"], - "fonts-noto-cjk", 2); - } - - check_program("dvipng", 2) if ($pdf); - check_missing(\%map); - - return if (!$need && !$optional); - printf("You should run:\n") if ($verbose_warn_install); - printf("\n\tsudo apt-get install $install\n"); -} - -sub give_redhat_hints() -{ - my %map = ( - "python-sphinx" => "python3-sphinx", - "yaml" => "python3-pyyaml", - "virtualenv" => "python3-virtualenv", - "dot" => "graphviz", - "convert" => "ImageMagick", - "Pod::Usage" => "perl-Pod-Usage", - "xelatex" => "texlive-xetex-bin", - "rsvg-convert" => "librsvg2-tools", - ); - - my @fedora26_opt_pkgs = ( - "graphviz-gd", # Fedora 26: needed for PDF support - ); - - my @fedora_tex_pkgs = ( - "texlive-collection-fontsrecommended", - "texlive-collection-latex", - "texlive-xecjk", - "dejavu-sans-fonts", - "dejavu-serif-fonts", - "dejavu-sans-mono-fonts", - ); - - # - # Checks valid for RHEL/CentOS version 7.x. - # - my $old = 0; - my $rel; - my $noto_sans_redhat = "google-noto-sans-cjk-ttc-fonts"; - $rel = $2 if ($system_release =~ /(release|Linux)\s+(\d+)/); - - if (!($system_release =~ /Fedora/)) { - $map{"virtualenv"} = "python-virtualenv"; - - if ($rel && $rel < 8) { - $old = 1; - $pdf = 0; - - printf("Note: texlive packages on RHEL/CENTOS <= 7 are incomplete. Can't support PDF output\n"); - printf("If you want to build PDF, please read:\n"); - printf("\thttps://www.systutorials.com/241660/how-to-install-tex-live-on-centos-7-linux/\n"); - } - } else { - if ($rel && $rel < 26) { - $old = 1; - } - if ($rel && $rel >= 38) { - $noto_sans_redhat = "google-noto-sans-cjk-fonts"; - } - } - if (!$rel) { - printf("Couldn't identify release number\n"); - $old = 1; - $pdf = 0; - } - - if ($pdf) { - check_missing_file(["/usr/share/fonts/google-noto-cjk/NotoSansCJK-Regular.ttc", - "/usr/share/fonts/google-noto-sans-cjk-fonts/NotoSansCJK-Regular.ttc"], - $noto_sans_redhat, 2); - } - - check_rpm_missing(\@fedora26_opt_pkgs, 2) if ($pdf && !$old); - check_rpm_missing(\@fedora_tex_pkgs, 2) if ($pdf); - check_missing_tex(2) if ($pdf); - check_missing(\%map); - - return if (!$need && !$optional); - - if (!$old) { - # dnf, for Fedora 18+ - printf("You should run:\n") if ($verbose_warn_install); - printf("\n\tsudo dnf install -y $install\n"); - } else { - # yum, for RHEL (and clones) or Fedora version < 18 - printf("You should run:\n") if ($verbose_warn_install); - printf("\n\tsudo yum install -y $install\n"); - } -} - -sub give_opensuse_hints() -{ - my %map = ( - "python-sphinx" => "python3-sphinx", - "yaml" => "python3-pyyaml", - "virtualenv" => "python3-virtualenv", - "dot" => "graphviz", - "convert" => "ImageMagick", - "Pod::Usage" => "perl-Pod-Usage", - "xelatex" => "texlive-xetex-bin", - ); - - # On Tumbleweed, this package is also named rsvg-convert - $map{"rsvg-convert"} = "rsvg-view" if (!($system_release =~ /Tumbleweed/)); - - my @suse_tex_pkgs = ( - "texlive-babel-english", - "texlive-caption", - "texlive-colortbl", - "texlive-courier", - "texlive-dvips", - "texlive-helvetic", - "texlive-makeindex", - "texlive-metafont", - "texlive-metapost", - "texlive-palatino", - "texlive-preview", - "texlive-times", - "texlive-zapfchan", - "texlive-zapfding", - ); - - $map{"latexmk"} = "texlive-latexmk-bin"; - - # FIXME: add support for installing CJK fonts - # - # I tried hard, but was unable to find a way to install - # "Noto Sans CJK SC" on openSUSE - - check_rpm_missing(\@suse_tex_pkgs, 2) if ($pdf); - check_missing_tex(2) if ($pdf); - check_missing(\%map); - - return if (!$need && !$optional); - printf("You should run:\n") if ($verbose_warn_install); - printf("\n\tsudo zypper install --no-recommends $install\n"); -} - -sub give_mageia_hints() -{ - my %map = ( - "python-sphinx" => "python3-sphinx", - "yaml" => "python3-yaml", - "virtualenv" => "python3-virtualenv", - "dot" => "graphviz", - "convert" => "ImageMagick", - "Pod::Usage" => "perl-Pod-Usage", - "xelatex" => "texlive", - "rsvg-convert" => "librsvg2", - ); - - my @tex_pkgs = ( - "texlive-fontsextra", - ); - - $map{"latexmk"} = "texlive-collection-basic"; - - my $packager_cmd; - my $noto_sans; - if ($system_release =~ /OpenMandriva/) { - $packager_cmd = "dnf install"; - $noto_sans = "noto-sans-cjk-fonts"; - @tex_pkgs = ( "texlive-collection-fontsextra" ); - } else { - $packager_cmd = "urpmi"; - $noto_sans = "google-noto-sans-cjk-ttc-fonts"; - } - - - if ($pdf) { - check_missing_file(["/usr/share/fonts/google-noto-cjk/NotoSansCJK-Regular.ttc", - "/usr/share/fonts/TTF/NotoSans-Regular.ttf"], - $noto_sans, 2); - } - - check_rpm_missing(\@tex_pkgs, 2) if ($pdf); - check_missing(\%map); - - return if (!$need && !$optional); - printf("You should run:\n") if ($verbose_warn_install); - printf("\n\tsudo $packager_cmd $install\n"); -} - -sub give_arch_linux_hints() -{ - my %map = ( - "yaml" => "python-yaml", - "virtualenv" => "python-virtualenv", - "dot" => "graphviz", - "convert" => "imagemagick", - "xelatex" => "texlive-xetex", - "latexmk" => "texlive-core", - "rsvg-convert" => "extra/librsvg", - ); - - my @archlinux_tex_pkgs = ( - "texlive-core", - "texlive-latexextra", - "ttf-dejavu", - ); - check_pacman_missing(\@archlinux_tex_pkgs, 2) if ($pdf); - - if ($pdf) { - check_missing_file(["/usr/share/fonts/noto-cjk/NotoSansCJK-Regular.ttc"], - "noto-fonts-cjk", 2); - } - - check_missing(\%map); - - return if (!$need && !$optional); - printf("You should run:\n") if ($verbose_warn_install); - printf("\n\tsudo pacman -S $install\n"); -} - -sub give_gentoo_hints() -{ - my %map = ( - "yaml" => "dev-python/pyyaml", - "virtualenv" => "dev-python/virtualenv", - "dot" => "media-gfx/graphviz", - "convert" => "media-gfx/imagemagick", - "xelatex" => "dev-texlive/texlive-xetex media-fonts/dejavu", - "rsvg-convert" => "gnome-base/librsvg", - ); - - check_missing_file(["/usr/share/fonts/dejavu/DejaVuSans.ttf"], - "media-fonts/dejavu", 2) if ($pdf); - - if ($pdf) { - check_missing_file(["/usr/share/fonts/noto-cjk/NotoSansCJKsc-Regular.otf", - "/usr/share/fonts/noto-cjk/NotoSerifCJK-Regular.ttc"], - "media-fonts/noto-cjk", 2); - } - - check_missing(\%map); - - return if (!$need && !$optional); - - printf("You should run:\n") if ($verbose_warn_install); - printf("\n"); - - my $imagemagick = "media-gfx/imagemagick svg png"; - my $cairo = "media-gfx/graphviz cairo pdf"; - my $portage_imagemagick = "/etc/portage/package.use/imagemagick"; - my $portage_cairo = "/etc/portage/package.use/graphviz"; - - if (qx(grep imagemagick $portage_imagemagick 2>/dev/null) eq "") { - printf("\tsudo su -c 'echo \"$imagemagick\" > $portage_imagemagick'\n") - } - if (qx(grep graphviz $portage_cairo 2>/dev/null) eq "") { - printf("\tsudo su -c 'echo \"$cairo\" > $portage_cairo'\n"); - } - - printf("\tsudo emerge --ask $install\n"); - -} - -sub check_distros() -{ - # Distro-specific hints - if ($system_release =~ /Red Hat Enterprise Linux/) { - give_redhat_hints; - return; - } - if ($system_release =~ /CentOS/) { - give_redhat_hints; - return; - } - if ($system_release =~ /Scientific Linux/) { - give_redhat_hints; - return; - } - if ($system_release =~ /Oracle Linux Server/) { - give_redhat_hints; - return; - } - if ($system_release =~ /Fedora/) { - give_redhat_hints; - return; - } - if ($system_release =~ /Ubuntu/) { - give_debian_hints; - return; - } - if ($system_release =~ /Debian/) { - give_debian_hints; - return; - } - if ($system_release =~ /openSUSE/) { - give_opensuse_hints; - return; - } - if ($system_release =~ /Mageia/) { - give_mageia_hints; - return; - } - if ($system_release =~ /OpenMandriva/) { - give_mageia_hints; - return; - } - if ($system_release =~ /Arch Linux/) { - give_arch_linux_hints; - return; - } - if ($system_release =~ /Gentoo/) { - give_gentoo_hints; - return; - } - - # - # Fall-back to generic hint code for other distros - # That's far from ideal, specially for LaTeX dependencies. - # - my %map = ( - "sphinx-build" => "sphinx" - ); - check_missing_tex(2) if ($pdf); - check_missing(\%map); - print "I don't know distro $system_release.\n"; - print "So, I can't provide you a hint with the install procedure.\n"; - print "There are likely missing dependencies.\n"; -} - -# -# Common dependencies -# - -sub deactivate_help() -{ - printf "\n If you want to exit the virtualenv, you can use:\n"; - printf "\tdeactivate\n"; -} - -sub get_virtenv() -{ - my $ver; - my $min_activate = "$ENV{'PWD'}/${virtenv_prefix}${min_version}/bin/activate"; - my @activates = glob "$ENV{'PWD'}/${virtenv_prefix}*/bin/activate"; - - @activates = sort {$b cmp $a} @activates; - - foreach my $f (@activates) { - next if ($f lt $min_activate); - - my $sphinx_cmd = $f; - $sphinx_cmd =~ s/activate/sphinx-build/; - next if (! -f $sphinx_cmd); - - my $ver = get_sphinx_version($sphinx_cmd); - - if (!$ver) { - $f =~ s#/bin/activate##; - print("Warning: virtual environment $f is not working.\nPython version upgrade? Remove it with:\n\n\trm -rf $f\n\n"); - } - - if ($need_sphinx && ($ver ge $min_version)) { - return ($f, $ver); - } elsif ($ver gt $cur_version) { - return ($f, $ver); - } - } - return ("", ""); -} - -sub recommend_sphinx_upgrade() -{ - my $venv_ver; - - # Avoid running sphinx-builds from venv if $cur_version is good - if ($cur_version && ($cur_version ge $rec_version)) { - $latest_avail_ver = $cur_version; - return; - } - - # Get the highest version from sphinx_*/bin/sphinx-build and the - # corresponding command to activate the venv/virtenv - ($activate_cmd, $venv_ver) = get_virtenv(); - - # Store the highest version from Sphinx existing virtualenvs - if (($activate_cmd ne "") && ($venv_ver gt $cur_version)) { - $latest_avail_ver = $venv_ver; - } else { - $latest_avail_ver = $cur_version if ($cur_version); - } - - # As we don't know package version of Sphinx, and there's no - # virtual environments, don't check if upgrades are needed - if (!$virtualenv) { - return if (!$latest_avail_ver); - } - - # Either there are already a virtual env or a new one should be created - $need_pip = 1; - - return if (!$latest_avail_ver); - - # Return if the reason is due to an upgrade or not - if ($latest_avail_ver lt $rec_version) { - $rec_sphinx_upgrade = 1; - } - - return $latest_avail_ver; -} - -# -# The logic here is complex, as it have to deal with different versions: -# - minimal supported version; -# - minimal PDF version; -# - recommended version. -# It also needs to work fine with both distro's package and venv/virtualenv -sub recommend_sphinx_version($) -{ - my $virtualenv_cmd = shift; - - # Version is OK. Nothing to do. - if ($cur_version && ($cur_version ge $rec_version)) { - return; - }; - - if (!$need_sphinx) { - # sphinx-build is present and its version is >= $min_version - - #only recommend enabling a newer virtenv version if makes sense. - if ($latest_avail_ver gt $cur_version) { - printf "\nYou may also use the newer Sphinx version $latest_avail_ver with:\n"; - printf "\tdeactivate\n" if ($ENV{'PWD'} =~ /${virtenv_prefix}/); - printf "\t. $activate_cmd\n"; - deactivate_help(); - - return; - } - return if ($latest_avail_ver ge $rec_version); - } - - if (!$virtualenv) { - # No sphinx either via package or via virtenv. As we can't - # Compare the versions here, just return, recommending the - # user to install it from the package distro. - return if (!$latest_avail_ver); - - # User doesn't want a virtenv recommendation, but he already - # installed one via virtenv with a newer version. - # So, print commands to enable it - if ($latest_avail_ver gt $cur_version) { - printf "\nYou may also use the Sphinx virtualenv version $latest_avail_ver with:\n"; - printf "\tdeactivate\n" if ($ENV{'PWD'} =~ /${virtenv_prefix}/); - printf "\t. $activate_cmd\n"; - deactivate_help(); - - return; - } - print "\n"; - } else { - $need++ if ($need_sphinx); - } - - # Suggest newer versions if current ones are too old - if ($latest_avail_ver && $latest_avail_ver ge $min_version) { - # If there's a good enough version, ask the user to enable it - if ($latest_avail_ver ge $rec_version) { - printf "\nNeed to activate Sphinx (version $latest_avail_ver) on virtualenv with:\n"; - printf "\t. $activate_cmd\n"; - deactivate_help(); - - return; - } - - # Version is above the minimal required one, but may be - # below the recommended one. So, print warnings/notes - - if ($latest_avail_ver lt $rec_version) { - print "Warning: It is recommended at least Sphinx version $rec_version.\n"; - } - } - - # At this point, either it needs Sphinx or upgrade is recommended, - # both via pip - - if ($rec_sphinx_upgrade) { - if (!$virtualenv) { - print "Instead of install/upgrade Python Sphinx pkg, you could use pip/pypi with:\n\n"; - } else { - print "To upgrade Sphinx, use:\n\n"; - } - } else { - print "\nSphinx needs to be installed either:\n1) via pip/pypi with:\n\n"; - } - - $python_cmd = find_python_no_venv(); - - printf "\t$virtualenv_cmd $virtenv_dir\n"; - - printf "\t. $virtenv_dir/bin/activate\n"; - printf "\tpip install -r $requirement_file\n"; - deactivate_help(); - - printf "\n2) As a package with:\n"; - - my $old_need = $need; - my $old_optional = $optional; - %missing = (); - $pdf = 0; - $optional = 0; - $install = ""; - $verbose_warn_install = 0; - - add_package("python-sphinx", 0); - - check_distros(); - - $need = $old_need; - $optional = $old_optional; - - printf "\n Please note that Sphinx >= 3.0 will currently produce false-positive\n"; - printf " warning when the same name is used for more than one type (functions,\n"; - printf " structs, enums,...). This is known Sphinx bug. For more details, see:\n"; - printf "\thttps://github.com/sphinx-doc/sphinx/pull/8313\n"; -} - -sub check_needs() -{ - # Check if Sphinx is already accessible from current environment - check_sphinx(); - - if ($system_release) { - print "Detected OS: $system_release.\n"; - } else { - print "Unknown OS\n"; - } - printf "Sphinx version: %s\n\n", $cur_version if ($cur_version); - - # Check python command line, trying first python3 - $python_cmd = findprog("python3"); - $python_cmd = check_program("python", 0) if (!$python_cmd); - - # Check the type of virtual env, depending on Python version - if ($python_cmd) { - if ($virtualenv) { - my $tmp = qx($python_cmd --version 2>&1); - if ($tmp =~ m/(\d+\.)(\d+\.)/) { - if ($1 < 3) { - # Fail if it finds python2 (or worse) - die "Python 3 is required to build the kernel docs\n"; - } - if ($1 == 3 && $2 < 3) { - # Need Python 3.3 or upper for venv - $need_virtualenv = 1; - } - } else { - die "Warning: couldn't identify $python_cmd version!"; - } - } else { - add_package("python-sphinx", 0); - } - } - - my $venv_ver = recommend_sphinx_upgrade(); - - my $virtualenv_cmd; - - if ($need_pip) { - # Set virtualenv command line, if python < 3.3 - if ($need_virtualenv) { - $virtualenv_cmd = findprog("virtualenv-3"); - $virtualenv_cmd = findprog("virtualenv-3.5") if (!$virtualenv_cmd); - if (!$virtualenv_cmd) { - check_program("virtualenv", 0); - $virtualenv_cmd = "virtualenv"; - } - } else { - $virtualenv_cmd = "$python_cmd -m venv"; - check_python_module("ensurepip", 0); - } - } - - # Check for needed programs/tools - check_perl_module("Pod::Usage", 0); - check_python_module("yaml", 0); - check_program("make", 0); - check_program("gcc", 0); - check_program("dot", 1); - check_program("convert", 1); - - # Extra PDF files - should use 2 for is_optional - check_program("xelatex", 2) if ($pdf); - check_program("rsvg-convert", 2) if ($pdf); - check_program("latexmk", 2) if ($pdf); - - # Do distro-specific checks and output distro-install commands - check_distros(); - - if (!$python_cmd) { - if ($need == 1) { - die "Can't build as $need mandatory dependency is missing"; - } elsif ($need) { - die "Can't build as $need mandatory dependencies are missing"; - } - } - - # Check if sphinx-build is called sphinx-build-3 - if ($need_symlink) { - printf "\tsudo ln -sf %s /usr/bin/sphinx-build\n\n", - which("sphinx-build-3"); - } - - recommend_sphinx_version($virtualenv_cmd); - printf "\n"; - - print "All optional dependencies are met.\n" if (!$optional); - - if ($need == 1) { - die "Can't build as $need mandatory dependency is missing"; - } elsif ($need) { - die "Can't build as $need mandatory dependencies are missing"; - } - - print "Needed package dependencies are met.\n"; -} - -# -# Main -# - -while (@ARGV) { - my $arg = shift(@ARGV); - - if ($arg eq "--no-virtualenv") { - $virtualenv = 0; - } elsif ($arg eq "--no-pdf"){ - $pdf = 0; - } elsif ($arg eq "--version-check"){ - $version_check = 1; - } else { - print "Usage:\n\t$0 <--no-virtualenv> <--no-pdf> <--version-check>\n\n"; - print "Where:\n"; - print "\t--no-virtualenv\t- Recommend installing Sphinx instead of using a virtualenv\n"; - print "\t--version-check\t- if version is compatible, don't check for missing dependencies\n"; - print "\t--no-pdf\t- don't check for dependencies required to build PDF docs\n\n"; - exit -1; - } -} - -# -# Determine the system type. There's no standard unique way that would -# work with all distros with a minimal package install. So, several -# methods are used here. -# -# By default, it will use lsb_release function. If not available, it will -# fail back to reading the known different places where the distro name -# is stored -# - -$system_release = qx(lsb_release -d) if which("lsb_release"); -$system_release =~ s/Description:\s*// if ($system_release); -$system_release = catcheck("/etc/system-release") if !$system_release; -$system_release = catcheck("/etc/redhat-release") if !$system_release; -$system_release = catcheck("/etc/lsb-release") if !$system_release; -$system_release = catcheck("/etc/gentoo-release") if !$system_release; - -# This seems more common than LSB these days -if (!$system_release) { - my %os_var; - if (open IN, "cat /etc/os-release|") { - while () { - if (m/^([\w\d\_]+)=\"?([^\"]*)\"?\n/) { - $os_var{$1}=$2; - } - } - $system_release = $os_var{"NAME"}; - if (defined($os_var{"VERSION_ID"})) { - $system_release .= " " . $os_var{"VERSION_ID"} if (defined($os_var{"VERSION_ID"})); - } else { - $system_release .= " " . $os_var{"VERSION"}; - } - } -} -$system_release = catcheck("/etc/issue") if !$system_release; -$system_release =~ s/\s+$//; - -check_needs; From df4d2f966354297c94ba5e198533cc31548a12a8 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 12 Aug 2025 17:52:53 +0200 Subject: [PATCH 060/193] scripts: sphinx-pre-install: update mandatory system deps To build docs, gcc is not needed. Also, Kernel can be built nowadays with clang. So, drop it. On the other hand, which is needed. Add a system dependency for it. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/4ec979e4692c9e4acd6c31424c0e2f4bf5b80e71.1754992972.git.mchehab+huawei@kernel.org --- scripts/sphinx-pre-install | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index 7dfe5c2a6cc2..fc9dc45054d7 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -1476,7 +1476,7 @@ class SphinxDependencyChecker(MissingCheckers): self.check_perl_module("Pod::Usage", DepManager.SYSTEM_MANDATORY) self.check_program("make", DepManager.SYSTEM_MANDATORY) - self.check_program("gcc", DepManager.SYSTEM_MANDATORY) + self.check_program("which", DepManager.SYSTEM_MANDATORY) self.check_program("dot", DepManager.SYSTEM_OPTIONAL) self.check_program("convert", DepManager.SYSTEM_OPTIONAL) From 9f51a1d6966760dadf62ff1f62c614a342fb7e62 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 12 Aug 2025 17:52:54 +0200 Subject: [PATCH 061/193] scripts: sphinx-pre-install: add support for RHEL8-based distros On RHEL8, only installing with a venv is supported, as there's no Sphinx package using Python 3.7 or upper. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/bcdde20edab07be6bf447eac18eecdd88c7f947c.1754992972.git.mchehab+huawei@kernel.org --- scripts/sphinx-pre-install | 25 ++++++++++++++++--------- 1 file changed, 16 insertions(+), 9 deletions(-) diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index fc9dc45054d7..324baa98a395 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -691,7 +691,7 @@ class SphinxDependencyChecker(MissingCheckers): super().__init__(args, texlive) - self.need_pip = 0 + self.need_pip = False self.rec_sphinx_upgrade = 0 self.system_release = self.get_system_release() @@ -840,9 +840,15 @@ class SphinxDependencyChecker(MissingCheckers): # RHEL 8 uses Python 3.6, which is not compatible with # the build system anymore. Suggest Python 3.11 if rel == 8: - self.deps.add_package("python39", DepManager.SYSTEM_MANDATORY) + self.check_program("python3.9", DepManager.SYSTEM_MANDATORY) + progs["python3.9"] = "python39" + progs["yaml"] = "python39-pyyaml" + self.recommend_python = True + # There's no python39-sphinx package. Only pip is supported + self.package_supported = False + if not self.distro_msg: self.distro_msg = \ "Note: RHEL-based distros typically require extra repositories.\n" \ @@ -915,8 +921,9 @@ class SphinxDependencyChecker(MissingCheckers): # the build system anymore. Suggest Python 3.11 if rel == 15: if not self.which(self.python_cmd): + self.check_program("python3.11", DepManager.SYSTEM_MANDATORY) + progs["python3.11"] = "python311" self.recommend_python = True - self.deps.add_package(self.python_cmd, DepManager.SYSTEM_MANDATORY) progs.update({ "python-sphinx": "python311-Sphinx", @@ -1289,7 +1296,7 @@ class SphinxDependencyChecker(MissingCheckers): return self.latest_avail_ver # Either there are already a virtual env or a new one should be created - self.need_pip = 1 + self.need_pip = True if not self.latest_avail_ver: return None @@ -1344,10 +1351,11 @@ class SphinxDependencyChecker(MissingCheckers): """ if self.recommend_python: - print("\nPython version is incompatible with doc build.\n" \ - "Please upgrade it and re-run.\n") - return - + cur_ver = sys.version_info[:3] + if cur_ver < MIN_PYTHON_VERSION: + print(f"\nPython version {cur_ver} is incompatible with doc build.\n" \ + "Please upgrade it and re-run.\n") + return # Version is OK. Nothing to do. if self.cur_version != (0, 0, 0) and self.cur_version >= RECOMMENDED_VERSION: @@ -1467,7 +1475,6 @@ class SphinxDependencyChecker(MissingCheckers): if sys.version_info < MIN_PYTHON_VERSION: self.need_pip = False print("Warning: python version is not supported.") - else: virtualenv_cmd = f"{self.python_cmd} -m venv" self.check_python_module("ensurepip") From 491a99511eaf333855caf28170cfb3f6f4460b54 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 12 Aug 2025 17:52:55 +0200 Subject: [PATCH 062/193] scripts: sphinx-pre-install: add a warning for Debian-based distros On Some Debian-based distros, ImageMagick package has a broken policy that causes LaTeX to fail while building docs. Add a note about that. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/628d01784e8c24e3d93c69c436f12398e00165b3.1754992972.git.mchehab+huawei@kernel.org --- scripts/sphinx-pre-install | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index 324baa98a395..09a337509b23 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -782,6 +782,11 @@ class SphinxDependencyChecker(MissingCheckers): self.check_program("dvipng", DepManager.PDF_MANDATORY) + if not self.distro_msg: + self.distro_msg = \ + "Note: ImageMagick is broken on some distros, affecting PDF output. For more details:\n" \ + "\thttps://askubuntu.com/questions/1158894/imagemagick-still-broken-using-with-usr-bin-convert" + return self.get_install_progs(progs, "apt-get install") def give_redhat_hints(self): @@ -1193,7 +1198,7 @@ class SphinxDependencyChecker(MissingCheckers): self.distro_msg = \ f"I don't know distro {self.system_release}.\n" \ "So, I can't provide you a hint with the install procedure.\n" \ - "There are likely missing dependencies.\n" + "There are likely missing dependencies." return self.get_install_progs(progs, None) From 6170b1eacac881af5732af78f33b76bd560c441b Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 12 Aug 2025 17:52:56 +0200 Subject: [PATCH 063/193] scripts: sphinx-pre-install: some adjustments related to venv While nothing was really needed for virtualenv to work on most distros, we had an issue with OpenMandriva. While checking for it, it was noticed that there was no check if python-virtualenv was installed. This didn't solve the issues we faced there: at least with the half-broken OpenMandriva Lx 4.0 docker container we used, ensurepip was not available anywhere, causing venv to fail. Add a distro-specific note about that. Note: at least at the time we did our tests, OpenMandriva Lx 4.0 docker was shipped with wrong dnf repositories. Also, there was no repos available for it anymore. So, we had to do some hacks to upgrade to 4.3 before being able to run any tests. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/e3a0e5eccd50eb506846e3e8487a2d9124ef83e2.1754992972.git.mchehab+huawei@kernel.org --- scripts/sphinx-pre-install | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index 09a337509b23..b8474848df4e 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -983,6 +983,22 @@ class SphinxDependencyChecker(MissingCheckers): # Tested on OpenMandriva Lx 4.3 progs["convert"] = "imagemagick" progs["yaml"] = "python-pyyaml" + progs["python-virtualenv"] = "python-virtualenv" + progs["python-sphinx"] = "python-sphinx" + + self.check_program("python-virtualenv", DepManager.PYTHON_MANDATORY) + + # On my tests with openMandriva LX 4.0 docker image, upgraded + # to 4.3, python-virtualenv package is broken: it is missing + # ensurepip. Without it, the alternative would be to run: + # python3 -m venv --without-pip ~/sphinx_latest, but running + # pip there won't install sphinx at venv. + # + # Add a note about that. + + if not self.distro_msg: + self.distro_msg = \ + "Note: for venv, ensurepip could be broken, preventing its install method." else: packager_cmd = "urpmi" From fce343d8546e47053b47c30f23dd0ac4729b2f66 Mon Sep 17 00:00:00 2001 From: Iris Shi <0.0@owo.li> Date: Mon, 18 Aug 2025 17:47:48 +0800 Subject: [PATCH 064/193] Documentation/sphinx: Fix typo in automarkup.py "whan" -> "when" Signed-off-by: Iris Shi <0.0@owo.li> Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/8e5ddb7d-8faf-314f-b1b1-2d15d6900862@owo.li --- Documentation/sphinx/automarkup.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py index 563033f764bb..1d9dada40a74 100644 --- a/Documentation/sphinx/automarkup.py +++ b/Documentation/sphinx/automarkup.py @@ -244,7 +244,7 @@ def add_and_resolve_xref(app, docname, domain, reftype, target, contnode=None): return contnode # -# Variant of markup_abi_ref() that warns whan a reference is not found +# Variant of markup_abi_ref() that warns when a reference is not found # def markup_abi_file_ref(docname, app, match): return markup_abi_ref(docname, app, match, warning=True) From ed14c74ddf4932a2505afae30dac7639c96bcb0c Mon Sep 17 00:00:00 2001 From: "Nikola Z. Ivanov" Date: Sat, 16 Aug 2025 22:00:28 +0300 Subject: [PATCH 065/193] docs: Replace dead links to spectre side channel white papers The papers are published by Intel, AMD and MIPS. Signed-off-by: Nikola Z. Ivanov Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250816190028.55573-1-zlatistiv@gmail.com --- Documentation/admin-guide/hw-vuln/spectre.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Documentation/admin-guide/hw-vuln/spectre.rst b/Documentation/admin-guide/hw-vuln/spectre.rst index 132e0bc6007e..991f12adef8d 100644 --- a/Documentation/admin-guide/hw-vuln/spectre.rst +++ b/Documentation/admin-guide/hw-vuln/spectre.rst @@ -664,7 +664,7 @@ Intel white papers: .. _spec_ref1: -[1] `Intel analysis of speculative execution side channels `_. +[1] `Intel analysis of speculative execution side channels `_. .. _spec_ref2: @@ -682,7 +682,7 @@ AMD white papers: .. _spec_ref5: -[5] `AMD64 technology indirect branch control extension `_. +[5] `AMD64 technology indirect branch control extension `_. .. _spec_ref6: @@ -708,7 +708,7 @@ MIPS white paper: .. _spec_ref10: -[10] `MIPS: response on speculative execution and side channel vulnerabilities `_. +[10] `MIPS: response on speculative execution and side channel vulnerabilities `_. Academic papers: From 6865cb19082140a07da356f57d52168aec38340c Mon Sep 17 00:00:00 2001 From: Vivek Yadav Date: Sat, 16 Aug 2025 01:24:52 -0700 Subject: [PATCH 066/193] docs: remove a duplicated word from kernel-parameters.txt Fix kernel-doc warning in kernel-parameters.txt WARNING: Possible repeated word: 'is' Signed-off-by: Vivek Yadav Acked-by: Randy Dunlap Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250816082452.219009-1-vivekyadav1207731111@gmail.com --- Documentation/admin-guide/kernel-parameters.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index 747a55abf494..302145870f1c 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -7506,7 +7506,7 @@ Set a trigger on top of a specific event, with an optional filter. - The format is is "trace_trigger=.[ if ],..." + The format is "trace_trigger=.[ if ],..." Where more than one trigger may be specified that are comma deliminated. For example: From 6cf5f13ef3f1c032b48fddd4f0f9108236c7762a Mon Sep 17 00:00:00 2001 From: Ranganath V N Date: Fri, 15 Aug 2025 00:13:03 +0530 Subject: [PATCH 067/193] Documentation: Fix driver-api typos Corrected a few spelling mistakes functionalty ==> functionality in Documentation/driver-api/cxl/devices/device-types.rst adjascent ==> adjacent in Documentation/driver-api/cxl/platform/example-configurations/one-dev-per-hb.rst succeessful ==> successful in Documentation/driver-api/thermal/exynos_thermal_emulation.rst Signed-off-by: Ranganath V N Reviewed-by: Randy Dunlap Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250814184304.20448-1-vnranganath.20@gmail.com --- .../driver-api/cxl/devices/device-types.rst | 2 +- .../example-configurations/one-dev-per-hb.rst | 2 +- .../thermal/exynos_thermal_emulation.rst | 14 +++++++------- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/Documentation/driver-api/cxl/devices/device-types.rst b/Documentation/driver-api/cxl/devices/device-types.rst index 923f5d89bc04..7f69dfa4509b 100644 --- a/Documentation/driver-api/cxl/devices/device-types.rst +++ b/Documentation/driver-api/cxl/devices/device-types.rst @@ -22,7 +22,7 @@ The basic interaction protocol, similar to PCIe configuration mechanisms. Typically used for initialization, configuration, and I/O access for anything other than memory (CXL.mem) or cache (CXL.cache) operations. -The Linux CXL driver exposes access to .io functionalty via the various sysfs +The Linux CXL driver exposes access to .io functionality via the various sysfs interfaces and /dev/cxl/ devices (which exposes direct access to device mailboxes). diff --git a/Documentation/driver-api/cxl/platform/example-configurations/one-dev-per-hb.rst b/Documentation/driver-api/cxl/platform/example-configurations/one-dev-per-hb.rst index aebda0eb3e17..a4c3fb51ea7d 100644 --- a/Documentation/driver-api/cxl/platform/example-configurations/one-dev-per-hb.rst +++ b/Documentation/driver-api/cxl/platform/example-configurations/one-dev-per-hb.rst @@ -10,7 +10,7 @@ has a single CXL memory expander with a 4GB of memory. Things to note: * Cross-Bridge interleave is not being used. -* The expanders are in two separate but adjascent memory regions. +* The expanders are in two separate but adjacent memory regions. * This CEDT/SRAT describes one node per device * The expanders have the same performance and will be in the same memory tier. diff --git a/Documentation/driver-api/thermal/exynos_thermal_emulation.rst b/Documentation/driver-api/thermal/exynos_thermal_emulation.rst index c21d10838bc5..c679502f01c7 100644 --- a/Documentation/driver-api/thermal/exynos_thermal_emulation.rst +++ b/Documentation/driver-api/thermal/exynos_thermal_emulation.rst @@ -28,13 +28,13 @@ changed into it. delay of changing temperature. However, this node only uses same delay of real sensing time, 938us.) -Exynos emulation mode requires synchronous of value changing and -enabling. It means when you want to update the any value of delay or -next temperature, then you have to enable emulation mode at the same -time. (Or you have to keep the mode enabling.) If you don't, it fails to -change the value to updated one and just use last succeessful value -repeatedly. That's why this node gives users the right to change -termerpature only. Just one interface makes it more simply to use. +Exynos emulation mode requires that value changes and enabling are performed +synchronously. This means that when you want to update any value, such as the +delay or the next temperature, you must enable emulation mode at the same +time (or keep the mode enabled). If you do not, the value will fail to update +and the last successful value will continue to be used. For this reason, +this node only allows users to change the temperature. Providing a single +interface makes it simpler to use. Disabling emulation mode only requires writing value 0 to sysfs node. From 670ec7333a2c4823ac777b70f045cf731525ae5e Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Thu, 14 Aug 2025 09:40:29 -0600 Subject: [PATCH 068/193] docs: kdoc: remove dead code create_parameter_list() tests an argument against the same regex twice, in two different locations; remove the pointless extra tests and the never-executed error cases that go with them. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250814154035.328769-2-corbet@lwn.net --- scripts/lib/kdoc/kdoc_parser.py | 22 ++++++---------------- 1 file changed, 6 insertions(+), 16 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py index 9e65948f8254..96e3fe4ec431 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -564,28 +564,18 @@ class KernelDoc: args.insert(0, first_arg.pop()) dtype = ' '.join(first_arg) + bitfield_re = KernRe(r'(.*?):(\w+)') for param in args: - if KernRe(r'^(\*+)\s*(.*)').match(param): - r = KernRe(r'^(\*+)\s*(.*)') - if not r.match(param): - self.emit_msg(ln, f"Invalid param: {param}") - continue - - param = r.group(1) - + r = KernRe(r'^(\*+)\s*(.*)') + if r.match(param): self.push_parameter(ln, decl_type, r.group(2), f"{dtype} {r.group(1)}", arg, declaration_name) - elif KernRe(r'(.*?):(\w+)').search(param): - r = KernRe(r'(.*?):(\w+)') - if not r.match(param): - self.emit_msg(ln, f"Invalid param: {param}") - continue - + elif bitfield_re.search(param): if dtype != "": # Skip unnamed bit-fields - self.push_parameter(ln, decl_type, r.group(1), - f"{dtype}:{r.group(2)}", + self.push_parameter(ln, decl_type, bitfield_re.group(1), + f"{dtype}:{bitfield_re.group(2)}", arg, declaration_name) else: self.push_parameter(ln, decl_type, param, dtype, From f51b42b99e1d35698e0277337fde2c15ccc29a2b Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Thu, 14 Aug 2025 09:40:30 -0600 Subject: [PATCH 069/193] docs: kdoc: tidy up space removal in create_parameter_list() Remove a redundant test and add a comment describing what the space removal is doing. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250814154035.328769-3-corbet@lwn.net --- scripts/lib/kdoc/kdoc_parser.py | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py index 96e3fe4ec431..53051ce831ba 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -545,12 +545,14 @@ class KernelDoc: arg, declaration_name) elif arg: + # + # Clean up extraneous spaces and split the string at commas; the first + # element of the resulting list will also include the type information. + # arg = KernRe(r'\s*:\s*').sub(":", arg) arg = KernRe(r'\s*\[').sub('[', arg) - args = KernRe(r'\s*,\s*').split(arg) - if args[0] and '*' in args[0]: - args[0] = re.sub(r'(\*+)\s*', r' \1', args[0]) + args[0] = re.sub(r'(\*+)\s*', r' \1', args[0]) first_arg = [] r = KernRe(r'^(.*\s+)(.*?\[.*\].*)$') From 05d72fe07242a8e4535aa52e0858f9198e668a41 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Thu, 14 Aug 2025 09:40:31 -0600 Subject: [PATCH 070/193] docs: kdoc: clean up the create_parameter_list() "first arg" logic The logic for finding the name of the first in a series of variable names is somewhat convoluted and, in the use of .extend(), actively buggy. Document what is happening and simplify the logic. Acked-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250814154035.328769-4-corbet@lwn.net --- scripts/lib/kdoc/kdoc_parser.py | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py index 53051ce831ba..07234ce04409 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -553,18 +553,18 @@ class KernelDoc: arg = KernRe(r'\s*\[').sub('[', arg) args = KernRe(r'\s*,\s*').split(arg) args[0] = re.sub(r'(\*+)\s*', r' \1', args[0]) - - first_arg = [] - r = KernRe(r'^(.*\s+)(.*?\[.*\].*)$') - if args[0] and r.match(args[0]): - args.pop(0) - first_arg.extend(r.group(1)) - first_arg.append(r.group(2)) + # + # args[0] has a string of "type a". If "a" includes an [array] + # declaration, we want to not be fooled by any white space inside + # the brackets, so detect and handle that case specially. + # + r = KernRe(r'^([^[\]]*\s+)(.*)$') + if r.match(args[0]): + args[0] = r.group(2) + dtype = r.group(1) else: - first_arg = KernRe(r'\s+').split(args.pop(0)) - - args.insert(0, first_arg.pop()) - dtype = ' '.join(first_arg) + # No space in args[0]; this seems wrong but preserves previous behavior + dtype = '' bitfield_re = KernRe(r'(.*?):(\w+)') for param in args: From 8f05fbc5afb86f0d4dcae33f3cb0cda561d4d93e Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Thu, 14 Aug 2025 09:40:32 -0600 Subject: [PATCH 071/193] docs: kdoc: add a couple more comments in create_parameter_list() Make what the final code is doing a bit more clear to slow readers like me. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250814154035.328769-5-corbet@lwn.net --- scripts/lib/kdoc/kdoc_parser.py | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py index 07234ce04409..29881757bf1c 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -568,12 +568,18 @@ class KernelDoc: bitfield_re = KernRe(r'(.*?):(\w+)') for param in args: + # + # For pointers, shift the star(s) from the variable name to the + # type declaration. + # r = KernRe(r'^(\*+)\s*(.*)') if r.match(param): self.push_parameter(ln, decl_type, r.group(2), f"{dtype} {r.group(1)}", arg, declaration_name) - + # + # Perform a similar shift for bitfields. + # elif bitfield_re.search(param): if dtype != "": # Skip unnamed bit-fields self.push_parameter(ln, decl_type, bitfield_re.group(1), From bf6b310d1b7e31a1cd6951eb75608a1d2876c04a Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Thu, 14 Aug 2025 09:40:33 -0600 Subject: [PATCH 072/193] docs: kdoc: tighten up the array-of-pointers case Simplify one gnarly regex and remove another altogether; add a comment describing what is going on. There will be no #-substituted commas in this case, so don't bother trying to put them back. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250814154035.328769-6-corbet@lwn.net --- scripts/lib/kdoc/kdoc_parser.py | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py index 29881757bf1c..7f4d95dd47d4 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -527,23 +527,21 @@ class KernelDoc: dtype = KernRe(r'([^\(]+\(\*?)\s*' + re.escape(param)).sub(r'\1', arg) self.push_parameter(ln, decl_type, param, dtype, arg, declaration_name) - + # + # The array-of-pointers case. Dig the parameter name out from the middle + # of the declaration. + # elif KernRe(r'\(.+\)\s*\[').search(arg): - # Array-of-pointers - - arg = arg.replace('#', ',') - r = KernRe(r'[^\(]+\(\s*\*\s*([\w\[\].]*?)\s*(\s*\[\s*[\w]+\s*\]\s*)*\)') + r = KernRe(r'[^\(]+\(\s*\*\s*' # Up to "(" and maybe "*" + r'([\w.]*?)' # The actual pointer name + r'\s*(\[\s*\w+\s*\]\s*)*\)') # The [array portion] if r.match(arg): param = r.group(1) else: self.emit_msg(ln, f"Invalid param: {arg}") param = arg - - dtype = KernRe(r'([^\(]+\(\*?)\s*' + re.escape(param)).sub(r'\1', arg) - - self.push_parameter(ln, decl_type, param, dtype, - arg, declaration_name) - + dtype = arg.replace(param, '') + self.push_parameter(ln, decl_type, param, dtype, arg, declaration_name) elif arg: # # Clean up extraneous spaces and split the string at commas; the first From e5d91662fcbac251dd17f04dbacf4d997939316e Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Thu, 14 Aug 2025 09:40:34 -0600 Subject: [PATCH 073/193] docs: kdoc: tighten up the pointer-to-function case Tighten up the code and remove an unneeded regex operation. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250814154035.328769-7-corbet@lwn.net --- scripts/lib/kdoc/kdoc_parser.py | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py index 7f4d95dd47d4..998b1ece932a 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -511,22 +511,21 @@ class KernelDoc: # Treat preprocessor directive as a typeless variable self.push_parameter(ln, decl_type, arg, "", "", declaration_name) - + # + # The pointer-to-function case. + # elif KernRe(r'\(.+\)\s*\(').search(arg): - # Pointer-to-function - arg = arg.replace('#', ',') - - r = KernRe(r'[^\(]+\(\*?\s*([\w\[\].]*)\s*\)') + r = KernRe(r'[^\(]+\(\*?\s*' # Everything up to "(*" + r'([\w\[\].]*)' # Capture the name and possible [array] + r'\s*\)') # Make sure the trailing ")" is there if r.match(arg): param = r.group(1) else: self.emit_msg(ln, f"Invalid param: {arg}") param = arg - - dtype = KernRe(r'([^\(]+\(\*?)\s*' + re.escape(param)).sub(r'\1', arg) - self.push_parameter(ln, decl_type, param, dtype, - arg, declaration_name) + dtype = arg.replace(param, '') + self.push_parameter(ln, decl_type, param, dtype, arg, declaration_name) # # The array-of-pointers case. Dig the parameter name out from the middle # of the declaration. From 1d8125e27323d8a378cb38f88a6c5a0d7fdb2f6c Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Thu, 14 Aug 2025 09:40:35 -0600 Subject: [PATCH 074/193] docs: kdoc: remove redundant comment stripping By the time stuff gets to create_parameter_list(), comments have long since been stripped out, so we do not need to do it again here. Acked-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250814154035.328769-8-corbet@lwn.net --- scripts/lib/kdoc/kdoc_parser.py | 3 --- 1 file changed, 3 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py index 998b1ece932a..a560546c1867 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -493,9 +493,6 @@ class KernelDoc: args = arg_expr.sub(r"\1#", args) for arg in args.split(splitter): - # Strip comments - arg = KernRe(r'/\*.*\*/').sub('', arg) - # Ignore argument attributes arg = KernRe(r'\sPOS0?\s').sub(' ', arg) From 359ad700eb8b563461819b6227b021b280e37e3e Mon Sep 17 00:00:00 2001 From: Bagas Sanjaya Date: Thu, 14 Aug 2025 08:20:45 +0700 Subject: [PATCH 075/193] Documentation: ktap: Correct "its" spelling Fix possessive adjective "its" spelling. Signed-off-by: Bagas Sanjaya Reviewed-by: Randy Dunlap Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250814012046.21235-2-bagasdotme@gmail.com --- Documentation/dev-tools/ktap.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/dev-tools/ktap.rst b/Documentation/dev-tools/ktap.rst index 414c105b10a9..54fac3d3bf7b 100644 --- a/Documentation/dev-tools/ktap.rst +++ b/Documentation/dev-tools/ktap.rst @@ -5,7 +5,7 @@ The Kernel Test Anything Protocol (KTAP), version 1 =================================================== TAP, or the Test Anything Protocol is a format for specifying test results used -by a number of projects. It's website and specification are found at this `link +by a number of projects. Its website and specification are found at this `link `_. The Linux Kernel largely uses TAP output for test results. However, Kernel testing frameworks have special needs for test results which don't align with the original TAP specification. Thus, a "Kernel TAP" From fea71fe1f060a722f7cb26aeca27d36d9370916d Mon Sep 17 00:00:00 2001 From: Bagas Sanjaya Date: Thu, 14 Aug 2025 08:20:46 +0700 Subject: [PATCH 076/193] Documentation: ktap: Separate first bullet list items The first bullet list items are shown in htmldocs output as combined with previous paragraph due to missing blank line separator. Add it. Signed-off-by: Bagas Sanjaya Reviewed-by: Randy Dunlap Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250814012046.21235-3-bagasdotme@gmail.com --- Documentation/dev-tools/ktap.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/Documentation/dev-tools/ktap.rst b/Documentation/dev-tools/ktap.rst index 54fac3d3bf7b..a9810bed5fd4 100644 --- a/Documentation/dev-tools/ktap.rst +++ b/Documentation/dev-tools/ktap.rst @@ -20,6 +20,7 @@ machine-readable, whereas the diagnostic data is unstructured and is there to aid human debugging. KTAP output is built from four different types of lines: + - Version lines - Plan lines - Test case result lines @@ -38,6 +39,7 @@ All KTAP-formatted results begin with a "version line" which specifies which version of the (K)TAP standard the result is compliant with. For example: + - "KTAP version 1" - "TAP version 13" - "TAP version 14" @@ -276,6 +278,7 @@ Example KTAP output This output defines the following hierarchy: A single test called "main_test", which fails, and has three subtests: + - "example_test_1", which passes, and has one subtest: - "test_1", which passes, and outputs the diagnostic message "test_1: initializing test_1" From c676a536f6b5d4c423ff66a2aa27b6c4141e4895 Mon Sep 17 00:00:00 2001 From: Bjorn Helgaas Date: Wed, 13 Aug 2025 15:04:57 -0500 Subject: [PATCH 077/193] Documentation: Fix PCI typos Fix typos. Signed-off-by: Bjorn Helgaas Reviewed-by: Randy Dunlap Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250813200526.290420-2-helgaas@kernel.org --- Documentation/PCI/endpoint/pci-endpoint-cfs.rst | 4 ++-- Documentation/PCI/endpoint/pci-endpoint.rst | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/Documentation/PCI/endpoint/pci-endpoint-cfs.rst b/Documentation/PCI/endpoint/pci-endpoint-cfs.rst index fb73345cfb8a..e69c2872ce3b 100644 --- a/Documentation/PCI/endpoint/pci-endpoint-cfs.rst +++ b/Documentation/PCI/endpoint/pci-endpoint-cfs.rst @@ -86,7 +86,7 @@ The directory can have a list of symbolic links be created by the user to represent the virtual functions that are bound to the physical function. In the above directory structure is a physical function and is a virtual function. An EPF device once -it's linked to another EPF device, cannot be linked to a EPC device. +it's linked to another EPF device, cannot be linked to an EPC device. EPC Device ========== @@ -108,7 +108,7 @@ entries corresponding to EPC device will be created by the EPC core. The directory will have a list of symbolic links to . These symbolic links should be created by the user to represent the functions present in the endpoint device. Only -that represents a physical function can be linked to a EPC device. +that represents a physical function can be linked to an EPC device. The directory will also have a *start* field. Once "1" is written to this field, the endpoint device will be ready to diff --git a/Documentation/PCI/endpoint/pci-endpoint.rst b/Documentation/PCI/endpoint/pci-endpoint.rst index 599763aa01ca..0741c8cbd74e 100644 --- a/Documentation/PCI/endpoint/pci-endpoint.rst +++ b/Documentation/PCI/endpoint/pci-endpoint.rst @@ -197,8 +197,8 @@ by the PCI endpoint function driver. * pci_epf_register_driver() The PCI Endpoint Function driver should implement the following ops: - * bind: ops to perform when a EPC device has been bound to EPF device - * unbind: ops to perform when a binding has been lost between a EPC + * bind: ops to perform when an EPC device has been bound to EPF device + * unbind: ops to perform when a binding has been lost between an EPC device and EPF device * add_cfs: optional ops to create function specific configfs attributes @@ -251,7 +251,7 @@ pci-ep-cfs.c can be used as reference for using these APIs. * pci_epf_bind() pci_epf_bind() should be invoked when the EPF device has been bound to - a EPC device. + an EPC device. * pci_epf_unbind() From aa7acf34c50b991702a0d052aa2b99b434e8a01c Mon Sep 17 00:00:00 2001 From: Bjorn Helgaas Date: Wed, 13 Aug 2025 15:04:58 -0500 Subject: [PATCH 078/193] Documentation: Fix RCU typos Fix typos. Signed-off-by: Bjorn Helgaas Reviewed-by: Randy Dunlap Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250813200526.290420-3-helgaas@kernel.org --- Documentation/RCU/lockdep.rst | 2 +- Documentation/RCU/stallwarn.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/RCU/lockdep.rst b/Documentation/RCU/lockdep.rst index 69e73a39bd11..741b157bbacb 100644 --- a/Documentation/RCU/lockdep.rst +++ b/Documentation/RCU/lockdep.rst @@ -106,7 +106,7 @@ or the RCU-protected data that it points to can change concurrently. Like rcu_dereference(), when lockdep is enabled, RCU list and hlist traversal primitives check for being called from within an RCU read-side critical section. However, a lockdep expression can be passed to them -as a additional optional argument. With this lockdep expression, these +as an additional optional argument. With this lockdep expression, these traversal primitives will complain only if the lockdep expression is false and they are called from outside any RCU read-side critical section. diff --git a/Documentation/RCU/stallwarn.rst b/Documentation/RCU/stallwarn.rst index d1ccd6039a8c..d7c8eff63317 100644 --- a/Documentation/RCU/stallwarn.rst +++ b/Documentation/RCU/stallwarn.rst @@ -119,7 +119,7 @@ warnings: uncommon in large datacenter. In one memorable case some decades back, a CPU failed in a running system, becoming unresponsive, but not causing an immediate crash. This resulted in a series - of RCU CPU stall warnings, eventually leading the realization + of RCU CPU stall warnings, eventually leading to the realization that the CPU had failed. The RCU, RCU-sched, RCU-tasks, and RCU-tasks-trace implementations have From c349216707362a8c2376995296cb55604d4c0ee9 Mon Sep 17 00:00:00 2001 From: Bjorn Helgaas Date: Wed, 13 Aug 2025 15:04:59 -0500 Subject: [PATCH 079/193] Documentation: Fix admin-guide typos Fix typos. Signed-off-by: Bjorn Helgaas Reviewed-by: Randy Dunlap Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250813200526.290420-4-helgaas@kernel.org --- Documentation/admin-guide/LSM/SafeSetID.rst | 2 +- Documentation/admin-guide/RAS/main.rst | 2 +- Documentation/admin-guide/blockdev/paride.rst | 2 +- .../admin-guide/device-mapper/vdo-design.rst | 2 +- Documentation/admin-guide/hw-vuln/mds.rst | 2 +- Documentation/admin-guide/kdump/kdump.rst | 2 +- Documentation/admin-guide/kernel-parameters.txt | 12 ++++++------ Documentation/admin-guide/laptops/sonypi.rst | 2 +- Documentation/admin-guide/media/imx.rst | 2 +- Documentation/admin-guide/media/si4713.rst | 6 +++--- Documentation/admin-guide/mm/damon/usage.rst | 2 +- Documentation/admin-guide/perf/hisi-pmu.rst | 4 ++-- .../admin-guide/quickly-build-trimmed-linux.rst | 4 ++-- Documentation/admin-guide/reporting-issues.rst | 4 ++-- .../verify-bugs-and-bisect-regressions.rst | 2 +- 15 files changed, 25 insertions(+), 25 deletions(-) diff --git a/Documentation/admin-guide/LSM/SafeSetID.rst b/Documentation/admin-guide/LSM/SafeSetID.rst index 0ec34863c674..6d439c987563 100644 --- a/Documentation/admin-guide/LSM/SafeSetID.rst +++ b/Documentation/admin-guide/LSM/SafeSetID.rst @@ -41,7 +41,7 @@ namespace). The higher level goal is to allow for uid-based sandboxing of system services without having to give out CAP_SETUID all over the place just so that non-root programs can drop to even-lesser-privileged uids. This is especially relevant when one non-root daemon on the system should be allowed to spawn other -processes as different uids, but its undesirable to give the daemon a +processes as different uids, but it's undesirable to give the daemon a basically-root-equivalent CAP_SETUID. diff --git a/Documentation/admin-guide/RAS/main.rst b/Documentation/admin-guide/RAS/main.rst index 7ac1d4ccc509..447bfde509fb 100644 --- a/Documentation/admin-guide/RAS/main.rst +++ b/Documentation/admin-guide/RAS/main.rst @@ -253,7 +253,7 @@ interface. Some architectures have ECC detectors for L1, L2 and L3 caches, along with DMA engines, fabric switches, main data path switches, interconnections, and various other hardware data paths. If the hardware -reports it, then a edac_device device probably can be constructed to +reports it, then an edac_device device probably can be constructed to harvest and present that to userspace. diff --git a/Documentation/admin-guide/blockdev/paride.rst b/Documentation/admin-guide/blockdev/paride.rst index e85ad37cc0e5..b2f627d4c2f8 100644 --- a/Documentation/admin-guide/blockdev/paride.rst +++ b/Documentation/admin-guide/blockdev/paride.rst @@ -118,7 +118,7 @@ and high-level drivers that you would use: ================ ============ ======== All parports and all protocol drivers are probed automatically unless probe=0 -parameter is used. So just "modprobe epat" is enough for a Imation SuperDisk +parameter is used. So just "modprobe epat" is enough for an Imation SuperDisk drive to work. Manual device creation:: diff --git a/Documentation/admin-guide/device-mapper/vdo-design.rst b/Documentation/admin-guide/device-mapper/vdo-design.rst index 3cd59decbec0..faa0ecd4a5ae 100644 --- a/Documentation/admin-guide/device-mapper/vdo-design.rst +++ b/Documentation/admin-guide/device-mapper/vdo-design.rst @@ -600,7 +600,7 @@ lock and return itself to the pool. All storage within vdo is managed as 4KB blocks, but it can accept writes as small as 512 bytes. Processing a write that is smaller than 4K requires a read-modify-write operation that reads the relevant 4K block, copies the -new data over the approriate sectors of the block, and then launches a +new data over the appropriate sectors of the block, and then launches a write operation for the modified data block. The read and write stages of this operation are nearly identical to the normal read and write operations, and a single data_vio is used throughout this operation. diff --git a/Documentation/admin-guide/hw-vuln/mds.rst b/Documentation/admin-guide/hw-vuln/mds.rst index 48c7b0b72aed..754679db0ce8 100644 --- a/Documentation/admin-guide/hw-vuln/mds.rst +++ b/Documentation/admin-guide/hw-vuln/mds.rst @@ -214,7 +214,7 @@ XEON PHI specific considerations command line with the 'ring3mwait=disable' command line option. XEON PHI is not affected by the other MDS variants and MSBDS is mitigated - before the CPU enters a idle state. As XEON PHI is not affected by L1TF + before the CPU enters an idle state. As XEON PHI is not affected by L1TF either disabling SMT is not required for full protection. .. _mds_smt_control: diff --git a/Documentation/admin-guide/kdump/kdump.rst b/Documentation/admin-guide/kdump/kdump.rst index 9c6cd52f69cf..7b011eb116a7 100644 --- a/Documentation/admin-guide/kdump/kdump.rst +++ b/Documentation/admin-guide/kdump/kdump.rst @@ -471,7 +471,7 @@ Notes on loading the dump-capture kernel: performance degradation. To enable multi-cpu support, you should bring up an SMP dump-capture kernel and specify maxcpus/nr_cpus options while loading it. -* For s390x there are two kdump modes: If a ELF header is specified with +* For s390x there are two kdump modes: If an ELF header is specified with the elfcorehdr= kernel parameter, it is used by the kdump kernel as it is done on all other architectures. If no elfcorehdr= kernel parameter is specified, the s390x kdump kernel dynamically creates the header. The diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index 747a55abf494..d4a91dec20b8 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -3700,7 +3700,7 @@ looking for corruption. Enabling this will both detect corruption and prevent the kernel from using the memory being corrupted. - However, its intended as a diagnostic tool; if + However, it's intended as a diagnostic tool; if repeatable BIOS-originated corruption always affects the same memory, you can use memmap= to prevent the kernel from using that memory. @@ -7382,7 +7382,7 @@ (converted into nanoseconds). Fast, but depending on the architecture, may not be in sync between CPUs. - global - Event time stamps are synchronize across + global - Event time stamps are synchronized across CPUs. May be slower than the local clock, but better for some race conditions. counter - Simple counting of events (1, 2, ..) @@ -7502,12 +7502,12 @@ section. trace_trigger=[trigger-list] - [FTRACE] Add a event trigger on specific events. + [FTRACE] Add an event trigger on specific events. Set a trigger on top of a specific event, with an optional filter. - The format is is "trace_trigger=.[ if ],..." - Where more than one trigger may be specified that are comma deliminated. + The format is "trace_trigger=.[ if ],..." + Where more than one trigger may be specified that are comma delimited. For example: @@ -7515,7 +7515,7 @@ The above will enable the "stacktrace" trigger on the "sched_switch" event but only trigger it if the "prev_state" of the "sched_switch" - event is "2" (TASK_UNINTERUPTIBLE). + event is "2" (TASK_UNINTERRUPTIBLE). See also "Event triggers" in Documentation/trace/events.rst diff --git a/Documentation/admin-guide/laptops/sonypi.rst b/Documentation/admin-guide/laptops/sonypi.rst index 190da1234314..7541f56e0007 100644 --- a/Documentation/admin-guide/laptops/sonypi.rst +++ b/Documentation/admin-guide/laptops/sonypi.rst @@ -25,7 +25,7 @@ generate, like: (when available) Those events (see linux/sonypi.h) can be polled using the character device node -/dev/sonypi (major 10, minor auto allocated or specified as a option). +/dev/sonypi (major 10, minor auto allocated or specified as an option). A simple daemon which translates the jogdial movements into mouse wheel events can be downloaded at: diff --git a/Documentation/admin-guide/media/imx.rst b/Documentation/admin-guide/media/imx.rst index b8fa70f854fd..bb68100d8acb 100644 --- a/Documentation/admin-guide/media/imx.rst +++ b/Documentation/admin-guide/media/imx.rst @@ -96,7 +96,7 @@ Some of the features of this driver include: motion compensation modes: low, medium, and high motion. Pipelines are defined that allow sending frames to the VDIC subdev directly from the CSI. There is also support in the future for sending frames to the - VDIC from memory buffers via a output/mem2mem devices. + VDIC from memory buffers via output/mem2mem devices. - Includes a Frame Interval Monitor (FIM) that can correct vertical sync problems with the ADV718x video decoders. diff --git a/Documentation/admin-guide/media/si4713.rst b/Documentation/admin-guide/media/si4713.rst index be8e6b49b7b4..85dcf1cd2df8 100644 --- a/Documentation/admin-guide/media/si4713.rst +++ b/Documentation/admin-guide/media/si4713.rst @@ -13,7 +13,7 @@ Contact: Eduardo Valentin Information about the Device ---------------------------- -This chip is a Silicon Labs product. It is a I2C device, currently on 0x63 address. +This chip is a Silicon Labs product. It is an I2C device, currently on 0x63 address. Basically, it has transmission and signal noise level measurement features. The Si4713 integrates transmit functions for FM broadcast stereo transmission. @@ -28,7 +28,7 @@ Users must comply with local regulations on radio frequency (RF) transmission. Device driver description ------------------------- -There are two modules to handle this device. One is a I2C device driver +There are two modules to handle this device. One is an I2C device driver and the other is a platform driver. The I2C device driver exports a v4l2-subdev interface to the kernel. @@ -113,7 +113,7 @@ Here is a summary of them: - acomp_attack_time - Sets the attack time for audio dynamic range control. - acomp_release_time - Sets the release time for audio dynamic range control. -* Limiter setups audio deviation limiter feature. Once a over deviation occurs, +* Limiter sets up the audio deviation limiter feature. Once an over deviation occurs, it is possible to adjust the front-end gain of the audio input and always prevent over deviation. diff --git a/Documentation/admin-guide/mm/damon/usage.rst b/Documentation/admin-guide/mm/damon/usage.rst index ff3a2dda1f02..5cd42d428c89 100644 --- a/Documentation/admin-guide/mm/damon/usage.rst +++ b/Documentation/admin-guide/mm/damon/usage.rst @@ -357,7 +357,7 @@ The directory for the :ref:`quotas ` of the given DAMON-based operation scheme. Under ``quotas`` directory, four files (``ms``, ``bytes``, -``reset_interval_ms``, ``effective_bytes``) and two directores (``weights`` and +``reset_interval_ms``, ``effective_bytes``) and two directories (``weights`` and ``goals``) exist. You can set the ``time quota`` in milliseconds, ``size quota`` in bytes, and diff --git a/Documentation/admin-guide/perf/hisi-pmu.rst b/Documentation/admin-guide/perf/hisi-pmu.rst index 48992a0b8e94..721eb1623ca7 100644 --- a/Documentation/admin-guide/perf/hisi-pmu.rst +++ b/Documentation/admin-guide/perf/hisi-pmu.rst @@ -109,8 +109,8 @@ uring channel. It is 2 bits. Some important codes are as follows: - 2'b11: count the events which sent to the uring_ext (MATA) channel; - 2'b01: is the same as 2'b11; - 2'b10: count the events which sent to the uring (non-MATA) channel; -- 2'b00: default value, count the events which sent to the both uring and - uring_ext channel; +- 2'b00: default value, count the events which sent to both uring and + uring_ext channels; Users could configure IDs to count data come from specific CCL/ICL, by setting srcid_cmd & srcid_msk, and data desitined for specific CCL/ICL by setting diff --git a/Documentation/admin-guide/quickly-build-trimmed-linux.rst b/Documentation/admin-guide/quickly-build-trimmed-linux.rst index 4a5ffb0996a3..cb4b78468a93 100644 --- a/Documentation/admin-guide/quickly-build-trimmed-linux.rst +++ b/Documentation/admin-guide/quickly-build-trimmed-linux.rst @@ -273,7 +273,7 @@ again. does nothing at all; in that case you have to manually install your kernel, as outlined in the reference section. - If you are running a immutable Linux distribution, check its documentation + If you are running an immutable Linux distribution, check its documentation and the web to find out how to install your own kernel there. [:ref:`details`] @@ -884,7 +884,7 @@ When a build error occurs, it might be caused by some aspect of your machine's setup that often can be fixed quickly; other times though the problem lies in the code and can only be fixed by a developer. A close examination of the failure messages coupled with some research on the internet will often tell you -which of the two it is. To perform such a investigation, restart the build +which of the two it is. To perform such an investigation, restart the build process like this:: make V=1 diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation/admin-guide/reporting-issues.rst index 9a847506f6ec..a68e6d909274 100644 --- a/Documentation/admin-guide/reporting-issues.rst +++ b/Documentation/admin-guide/reporting-issues.rst @@ -611,7 +611,7 @@ better place. How to read the MAINTAINERS file ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To illustrate how to use the :ref:`MAINTAINERS ` file, lets assume +To illustrate how to use the :ref:`MAINTAINERS ` file, let's assume the WiFi in your Laptop suddenly misbehaves after updating the kernel. In that case it's likely an issue in the WiFi driver. Obviously it could also be some code it builds upon, but unless you suspect something like that stick to the @@ -1543,7 +1543,7 @@ as well, because that will speed things up. And note, it helps developers a great deal if you can specify the exact version that introduced the problem. Hence if possible within a reasonable time frame, -try to find that version using vanilla kernels. Lets assume something broke when +try to find that version using vanilla kernels. Let's assume something broke when your distributor released a update from Linux kernel 5.10.5 to 5.10.8. Then as instructed above go and check the latest kernel from that version line, say 5.10.9. If it shows the problem, try a vanilla 5.10.5 to ensure that no patches diff --git a/Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst b/Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst index d8946b084b1e..d83601f2a459 100644 --- a/Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst +++ b/Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst @@ -1757,7 +1757,7 @@ or all of these tasks: to your bootloader's configuration. You have to take care of some or all of the tasks yourself, if your -distribution lacks a installkernel script or does only handle part of them. +distribution lacks an installkernel script or does only handle part of them. Consult the distribution's documentation for details. If in doubt, install the kernel manually:: From 8900f9ad90c05d0c44a21786cfef08061230f5b7 Mon Sep 17 00:00:00 2001 From: Bjorn Helgaas Date: Wed, 13 Aug 2025 15:05:00 -0500 Subject: [PATCH 080/193] Documentation: Fix core-api typos Fix typos. Signed-off-by: Bjorn Helgaas Reviewed-by: Randy Dunlap Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250813200526.290420-5-helgaas@kernel.org --- Documentation/core-api/irq/irq-affinity.rst | 6 ++-- Documentation/core-api/irq/irq-domain.rst | 38 ++++++++++----------- 2 files changed, 22 insertions(+), 22 deletions(-) diff --git a/Documentation/core-api/irq/irq-affinity.rst b/Documentation/core-api/irq/irq-affinity.rst index 29da5000836a..9cb460cf60b6 100644 --- a/Documentation/core-api/irq/irq-affinity.rst +++ b/Documentation/core-api/irq/irq-affinity.rst @@ -9,9 +9,9 @@ ChangeLog: /proc/irq/IRQ#/smp_affinity and /proc/irq/IRQ#/smp_affinity_list specify which target CPUs are permitted for a given IRQ source. It's a bitmask -(smp_affinity) or cpu list (smp_affinity_list) of allowed CPUs. It's not +(smp_affinity) or CPU list (smp_affinity_list) of allowed CPUs. It's not allowed to turn off all CPUs, and if an IRQ controller does not support -IRQ affinity then the value will not change from the default of all cpus. +IRQ affinity then the value will not change from the default of all CPUs. /proc/irq/default_smp_affinity specifies default affinity mask that applies to all non-active IRQs. Once IRQ is allocated/activated its affinity bitmask @@ -60,7 +60,7 @@ Now lets restrict that IRQ to CPU(4-7). This time around IRQ44 was delivered only to the last four processors. i.e counters for the CPU0-3 did not change. -Here is an example of limiting that same irq (44) to cpus 1024 to 1031:: +Here is an example of limiting that same IRQ (44) to CPUs 1024 to 1031:: [root@moon 44]# echo 1024-1031 > smp_affinity_list [root@moon 44]# cat smp_affinity_list diff --git a/Documentation/core-api/irq/irq-domain.rst b/Documentation/core-api/irq/irq-domain.rst index a01c6ead1bc0..68eb2612e8a4 100644 --- a/Documentation/core-api/irq/irq-domain.rst +++ b/Documentation/core-api/irq/irq-domain.rst @@ -18,8 +18,8 @@ handlers as irqchips. I.e. in effect cascading interrupt controllers. So in the past, IRQ numbers could be chosen so that they match the hardware IRQ line into the root interrupt controller (i.e. the component actually firing the interrupt line to the CPU). Nowadays, -this number is just a number and the number loose all kind of -correspondence to hardware interrupt numbers. +this number is just a number and the number has no +relationship to hardware interrupt numbers. For this reason, we need a mechanism to separate controller-local interrupt numbers, called hardware IRQs, from Linux IRQ numbers. @@ -77,15 +77,15 @@ Once a mapping has been established, it can be retrieved or used via a variety of methods: - irq_resolve_mapping() returns a pointer to the irq_desc structure - for a given domain and hwirq number, and NULL if there was no + for a given domain and hwirq number, or NULL if there was no mapping. - irq_find_mapping() returns a Linux IRQ number for a given domain and - hwirq number, and 0 if there was no mapping + hwirq number, or 0 if there was no mapping - generic_handle_domain_irq() handles an interrupt described by a domain and a hwirq number -Note that irq domain lookups must happen in contexts that are -compatible with a RCU read-side critical section. +Note that irq_domain lookups must happen in contexts that are +compatible with an RCU read-side critical section. The irq_create_mapping() function must be called *at least once* before any call to irq_find_mapping(), lest the descriptor will not @@ -100,7 +100,7 @@ Types of irq_domain Mappings ============================ There are several mechanisms available for reverse mapping from hwirq -to Linux irq, and each mechanism uses a different allocation function. +to Linux IRQ, and each mechanism uses a different allocation function. Which reverse map type should be used depends on the use case. Each of the reverse map types are described below: @@ -111,13 +111,13 @@ Linear irq_domain_create_linear() -The linear reverse map maintains a fixed size table indexed by the +The linear reverse map maintains a fixed-size table indexed by the hwirq number. When a hwirq is mapped, an irq_desc is allocated for the hwirq, and the IRQ number is stored in the table. The Linear map is a good choice when the maximum number of hwirqs is fixed and a relatively small number (~ < 256). The advantages of this -map are fixed time lookup for IRQ numbers, and irq_descs are only +map are fixed-time lookup for IRQ numbers, and irq_descs are only allocated for in-use IRQs. The disadvantage is that the table must be as large as the largest possible hwirq number. @@ -134,7 +134,7 @@ The irq_domain maintains a radix tree map from hwirq numbers to Linux IRQs. When an hwirq is mapped, an irq_desc is allocated and the hwirq is used as the lookup key for the radix tree. -The tree map is a good choice if the hwirq number can be very large +The Tree map is a good choice if the hwirq number can be very large since it doesn't need to allocate a table as large as the largest hwirq number. The disadvantage is that hwirq to IRQ number lookup is dependent on how many entries are in the table. @@ -169,10 +169,10 @@ Legacy The Legacy mapping is a special case for drivers that already have a range of irq_descs allocated for the hwirqs. It is used when the -driver cannot be immediately converted to use the linear mapping. For +driver cannot be immediately converted to use the Linear mapping. For example, many embedded system board support files use a set of #defines for IRQ numbers that are passed to struct device registrations. In that -case the Linux IRQ numbers cannot be dynamically assigned and the legacy +case the Linux IRQ numbers cannot be dynamically assigned and the Legacy mapping should be used. As the name implies, the \*_legacy() functions are deprecated and only @@ -180,15 +180,15 @@ exist to ease the support of ancient platforms. No new users should be added. Same goes for the \*_simple() functions when their use results in the legacy behaviour. -The legacy map assumes a contiguous range of IRQ numbers has already +The Legacy map assumes a contiguous range of IRQ numbers has already been allocated for the controller and that the IRQ number can be calculated by adding a fixed offset to the hwirq number, and visa-versa. The disadvantage is that it requires the interrupt controller to manage IRQ allocations and it requires an irq_desc to be allocated for every hwirq, even if it is unused. -The legacy map should only be used if fixed IRQ mappings must be -supported. For example, ISA controllers would use the legacy map for +The Legacy map should only be used if fixed IRQ mappings must be +supported. For example, ISA controllers would use the Legacy map for mapping Linux IRQs 0-15 so that existing ISA drivers get the correct IRQ numbers. @@ -197,7 +197,7 @@ which will use a legacy domain only if an IRQ range is supplied by the system and will otherwise use a linear domain mapping. The semantics of this call are such that if an IRQ range is specified then descriptors will be allocated on-the-fly for it, and if no range is specified it -will fall through to irq_domain_create_linear() which means *no* irq +will fall through to irq_domain_create_linear() which means *no* IRQ descriptors will be allocated. A typical use case for simple domains is where an irqchip provider @@ -214,7 +214,7 @@ Hierarchy IRQ Domain On some architectures, there may be multiple interrupt controllers involved in delivering an interrupt from the device to the target CPU. -Let's look at a typical interrupt delivering path on x86 platforms:: +Let's look at a typical interrupt delivery path on x86 platforms:: Device --> IOAPIC -> Interrupt remapping Controller -> Local APIC -> CPU @@ -227,8 +227,8 @@ There are three interrupt controllers involved: To support such a hardware topology and make software architecture match hardware architecture, an irq_domain data structure is built for each interrupt controller and those irq_domains are organized into hierarchy. -When building irq_domain hierarchy, the irq_domain near to the device is -child and the irq_domain near to CPU is parent. So a hierarchy structure +When building irq_domain hierarchy, the irq_domain nearest the device is +child and the irq_domain nearest the CPU is parent. So a hierarchy structure as below will be built for the example above:: CPU Vector irq_domain (root irq_domain to manage CPU vectors) From 81fd803b5a5da3fad0140163091e12b3ac2ae484 Mon Sep 17 00:00:00 2001 From: Bjorn Helgaas Date: Wed, 13 Aug 2025 15:05:01 -0500 Subject: [PATCH 081/193] Documentation: Fix filesystems typos Fix typos. Signed-off-by: Bjorn Helgaas Reviewed-by: Randy Dunlap Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250813200526.290420-6-helgaas@kernel.org --- Documentation/filesystems/erofs.rst | 2 +- Documentation/filesystems/gfs2-glocks.rst | 2 +- Documentation/filesystems/hpfs.rst | 2 +- Documentation/filesystems/resctrl.rst | 2 +- Documentation/filesystems/xfs/xfs-online-fsck-design.rst | 4 ++-- 5 files changed, 6 insertions(+), 6 deletions(-) diff --git a/Documentation/filesystems/erofs.rst b/Documentation/filesystems/erofs.rst index 7ddb235aee9d..08194f194b94 100644 --- a/Documentation/filesystems/erofs.rst +++ b/Documentation/filesystems/erofs.rst @@ -116,7 +116,7 @@ cache_strategy=%s Select a strategy for cached decompression from now on: cluster for further reading. It still does in-place I/O decompression for the rest compressed physical clusters; - readaround Cache the both ends of incomplete compressed + readaround Cache both ends of incomplete compressed physical clusters for further reading. It still does in-place I/O decompression for the rest compressed physical clusters. diff --git a/Documentation/filesystems/gfs2-glocks.rst b/Documentation/filesystems/gfs2-glocks.rst index adc0d4c4d979..ce5ff08cbd59 100644 --- a/Documentation/filesystems/gfs2-glocks.rst +++ b/Documentation/filesystems/gfs2-glocks.rst @@ -105,7 +105,7 @@ go_unlocked Yes No Operations must not drop either the bit lock or the spinlock if its held on entry. go_dump and do_demote_ok must never block. Note that go_dump will only be called if the glock's state - indicates that it is caching uptodate data. + indicates that it is caching up-to-date data. Glock locking order within GFS2: diff --git a/Documentation/filesystems/hpfs.rst b/Documentation/filesystems/hpfs.rst index 7e0dd2f4373e..0f9516b5eb07 100644 --- a/Documentation/filesystems/hpfs.rst +++ b/Documentation/filesystems/hpfs.rst @@ -65,7 +65,7 @@ are case sensitive, so for example when you create a file FOO, you can use 'cat FOO', 'cat Foo', 'cat foo' or 'cat F*' but not 'cat f*'. Note, that you also won't be able to compile linux kernel (and maybe other things) on HPFS because kernel creates different files with names like bootsect.S and -bootsect.s. When searching for file thats name has characters >= 128, codepages +bootsect.s. When searching for file whose name has characters >= 128, codepages are used - see below. OS/2 ignores dots and spaces at the end of file name, so this driver does as well. If you create 'a. ...', the file 'a' will be created, but you can still diff --git a/Documentation/filesystems/resctrl.rst b/Documentation/filesystems/resctrl.rst index c7949dd44f2f..4db3b07c16c5 100644 --- a/Documentation/filesystems/resctrl.rst +++ b/Documentation/filesystems/resctrl.rst @@ -563,7 +563,7 @@ this would be dependent on number of cores the benchmark is run on. depending on # of threads: For the same SKU in #1, a 'single thread, with 10% bandwidth' and '4 -thread, with 10% bandwidth' can consume upto 10GBps and 40GBps although +thread, with 10% bandwidth' can consume up to 10GBps and 40GBps although they have same percentage bandwidth of 10%. This is simply because as threads start using more cores in an rdtgroup, the actual bandwidth may increase or vary although user specified bandwidth percentage is same. diff --git a/Documentation/filesystems/xfs/xfs-online-fsck-design.rst b/Documentation/filesystems/xfs/xfs-online-fsck-design.rst index e231d127cd40..9fe994353395 100644 --- a/Documentation/filesystems/xfs/xfs-online-fsck-design.rst +++ b/Documentation/filesystems/xfs/xfs-online-fsck-design.rst @@ -454,7 +454,7 @@ filesystem so that it can apply pending filesystem updates to the staging information. Once the scan is done, the owning object is re-locked, the live data is used to write a new ondisk structure, and the repairs are committed atomically. -The hooks are disabled and the staging staging area is freed. +The hooks are disabled and the staging area is freed. Finally, the storage from the old data structure are carefully reaped. Introducing concurrency helps online repair avoid various locking problems, but @@ -2185,7 +2185,7 @@ The chapter about :ref:`secondary metadata` mentioned that checking and repairing of secondary metadata commonly requires coordination between a live metadata scan of the filesystem and writer threads that are updating that metadata. -Keeping the scan data up to date requires requires the ability to propagate +Keeping the scan data up to date requires the ability to propagate metadata updates from the filesystem into the data being collected by the scan. This *can* be done by appending concurrent updates into a separate log file and applying them before writing the new metadata to disk, but this leads to From e855d7e5e2e9ed311930d557f7ed033e200fcdef Mon Sep 17 00:00:00 2001 From: Bjorn Helgaas Date: Wed, 13 Aug 2025 15:05:02 -0500 Subject: [PATCH 082/193] Documentation: Fix networking typos Fix typos. Signed-off-by: Bjorn Helgaas Reviewed-by: Randy Dunlap Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250813200526.290420-7-helgaas@kernel.org --- Documentation/networking/can.rst | 2 +- .../device_drivers/ethernet/ti/am65_nuss_cpsw_switchdev.rst | 2 +- .../networking/device_drivers/ethernet/ti/cpsw_switchdev.rst | 2 +- Documentation/networking/rds.rst | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/Documentation/networking/can.rst b/Documentation/networking/can.rst index bc1b585355f7..680dc7451493 100644 --- a/Documentation/networking/can.rst +++ b/Documentation/networking/can.rst @@ -539,7 +539,7 @@ CAN Filter Usage Optimisation The CAN filters are processed in per-device filter lists at CAN frame reception time. To reduce the number of checks that need to be performed while walking through the filter lists the CAN core provides an optimized -filter handling when the filter subscription focusses on a single CAN ID. +filter handling when the filter subscription focuses on a single CAN ID. For the possible 2048 SFF CAN identifiers the identifier is used as an index to access the corresponding subscription list without any further checks. diff --git a/Documentation/networking/device_drivers/ethernet/ti/am65_nuss_cpsw_switchdev.rst b/Documentation/networking/device_drivers/ethernet/ti/am65_nuss_cpsw_switchdev.rst index 25fd9aa284e2..f0424597aac1 100644 --- a/Documentation/networking/device_drivers/ethernet/ti/am65_nuss_cpsw_switchdev.rst +++ b/Documentation/networking/device_drivers/ethernet/ti/am65_nuss_cpsw_switchdev.rst @@ -42,7 +42,7 @@ Port's netdev devices have to be in UP before joining to the bridge to avoid overwriting of bridge configuration as CPSW switch driver completely reloads its configuration when first port changes its state to UP. -When the both interfaces joined the bridge - CPSW switch driver will enable +When both interfaces have joined the bridge - CPSW switch driver will enable marking packets with offload_fwd_mark flag. All configuration is implemented via switchdev API. diff --git a/Documentation/networking/device_drivers/ethernet/ti/cpsw_switchdev.rst b/Documentation/networking/device_drivers/ethernet/ti/cpsw_switchdev.rst index 464dce938ed1..2f3c43a32bfc 100644 --- a/Documentation/networking/device_drivers/ethernet/ti/cpsw_switchdev.rst +++ b/Documentation/networking/device_drivers/ethernet/ti/cpsw_switchdev.rst @@ -92,7 +92,7 @@ Port's netdev devices have to be in UP before joining to the bridge to avoid overwriting of bridge configuration as CPSW switch driver copletly reloads its configuration when first Port changes its state to UP. -When the both interfaces joined the bridge - CPSW switch driver will enable +When both interfaces have joined the bridge - CPSW switch driver will enable marking packets with offload_fwd_mark flag unless "ale_bypass=0" All configuration is implemented via switchdev API. diff --git a/Documentation/networking/rds.rst b/Documentation/networking/rds.rst index 41b0a6182fe4..4261146e9d92 100644 --- a/Documentation/networking/rds.rst +++ b/Documentation/networking/rds.rst @@ -339,7 +339,7 @@ The send path rds_sendmsg() - struct rds_message built from incoming data - CMSGs parsed (e.g. RDMA ops) - - transport connection alloced and connected if not already + - transport connection allocated and connected if not already - rds_message placed on send queue - send worker awoken From 3dae66aec6b0bd847e5056fb5174dfc325162734 Mon Sep 17 00:00:00 2001 From: Bjorn Helgaas Date: Wed, 13 Aug 2025 15:05:03 -0500 Subject: [PATCH 083/193] Documentation: Fix power typos Fix typos. Signed-off-by: Bjorn Helgaas Reviewed-by: Randy Dunlap Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250813200526.290420-8-helgaas@kernel.org --- Documentation/power/pci.rst | 4 ++-- Documentation/power/suspend-and-cpuhotplug.rst | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/Documentation/power/pci.rst b/Documentation/power/pci.rst index 9ebecb7b00b2..38e614d92a4a 100644 --- a/Documentation/power/pci.rst +++ b/Documentation/power/pci.rst @@ -472,7 +472,7 @@ in the device tree from the root bridge to a leaf device contains both of them). The pci_pm_suspend_noirq() routine is executed after suspend_device_irqs() has been called, which means that the device driver's interrupt handler won't be invoked while this routine is running. It first checks if the device's driver -implements legacy PCI suspends routines (Section 3), in which case the legacy +implements legacy PCI suspend routines (Section 3), in which case the legacy late suspend routine is called and its result is returned (the standard configuration registers of the device are saved if the driver's callback hasn't done that). Second, if the device driver's struct dev_pm_ops object is not @@ -544,7 +544,7 @@ result is then returned). The resume phase is carried out asynchronously for PCI devices, like the suspend phase described above, which means that if two PCI devices don't depend on each other in a known way, the pci_pm_resume() routine may be executed for -the both of them in parallel. +both of them in parallel. The pci_pm_complete() routine only executes the device driver's pm->complete() callback, if defined. diff --git a/Documentation/power/suspend-and-cpuhotplug.rst b/Documentation/power/suspend-and-cpuhotplug.rst index ebedb6c75db9..641d09a6546b 100644 --- a/Documentation/power/suspend-and-cpuhotplug.rst +++ b/Documentation/power/suspend-and-cpuhotplug.rst @@ -13,7 +13,7 @@ infrastructure uses it internally? And where do they share common code? Well, a picture is worth a thousand words... So ASCII art follows :-) -[This depicts the current design in the kernel, and focusses only on the +[This depicts the current design in the kernel, and focuses only on the interactions involving the freezer and CPU hotplug and also tries to explain the locking involved. It outlines the notifications involved as well. But please note that here, only the call paths are illustrated, with the aim From 29fe206065f3784397252c7f6aa28dc6d413fb94 Mon Sep 17 00:00:00 2001 From: Bjorn Helgaas Date: Wed, 13 Aug 2025 15:05:04 -0500 Subject: [PATCH 084/193] Documentation: Fix trace typos Fix typos. Signed-off-by: Bjorn Helgaas Reviewed-by: Randy Dunlap Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250813200526.290420-9-helgaas@kernel.org --- Documentation/trace/fprobe.rst | 2 +- Documentation/trace/ftrace-uses.rst | 2 +- Documentation/trace/ftrace.rst | 14 +++++++------- Documentation/trace/histogram.rst | 2 +- 4 files changed, 10 insertions(+), 10 deletions(-) diff --git a/Documentation/trace/fprobe.rst b/Documentation/trace/fprobe.rst index 71cd40472d36..06b0edad0179 100644 --- a/Documentation/trace/fprobe.rst +++ b/Documentation/trace/fprobe.rst @@ -81,7 +81,7 @@ Same as ftrace, the registered callbacks will start being called some time after the register_fprobe() is called and before it returns. See :file:`Documentation/trace/ftrace.rst`. -Also, the unregister_fprobe() will guarantee that the both enter and exit +Also, the unregister_fprobe() will guarantee that both enter and exit handlers are no longer being called by functions after unregister_fprobe() returns as same as unregister_ftrace_function(). diff --git a/Documentation/trace/ftrace-uses.rst b/Documentation/trace/ftrace-uses.rst index e198854ace79..e225cc46b71e 100644 --- a/Documentation/trace/ftrace-uses.rst +++ b/Documentation/trace/ftrace-uses.rst @@ -193,7 +193,7 @@ FTRACE_OPS_FL_RECURSION Note, if this flag is set, then the callback will always be called with preemption disabled. If it is not set, then it is possible (but not guaranteed) that the callback will be called in - preemptable context. + preemptible context. FTRACE_OPS_FL_IPMODIFY Requires FTRACE_OPS_FL_SAVE_REGS set. If the callback is to "hijack" diff --git a/Documentation/trace/ftrace.rst b/Documentation/trace/ftrace.rst index af66a05e18cc..aef674df3afd 100644 --- a/Documentation/trace/ftrace.rst +++ b/Documentation/trace/ftrace.rst @@ -30,7 +30,7 @@ disabled and enabled, as well as for preemption and from a time a task is woken to the task is actually scheduled in. One of the most common uses of ftrace is the event tracing. -Throughout the kernel is hundreds of static event points that +Throughout the kernel are hundreds of static event points that can be enabled via the tracefs file system to see what is going on in certain parts of the kernel. @@ -383,7 +383,7 @@ of ftrace. Here is a list of some of the key files: not be listed in this count. If the callback registered to be traced by a function with - the "save regs" attribute (thus even more overhead), a 'R' + the "save regs" attribute (thus even more overhead), an 'R' will be displayed on the same line as the function that is returning registers. @@ -392,7 +392,7 @@ of ftrace. Here is a list of some of the key files: an 'I' will be displayed on the same line as the function that can be overridden. - If a non ftrace trampoline is attached (BPF) a 'D' will be displayed. + If a non-ftrace trampoline is attached (BPF) a 'D' will be displayed. Note, normal ftrace trampolines can also be attached, but only one "direct" trampoline can be attached to a given function at a time. @@ -402,7 +402,7 @@ of ftrace. Here is a list of some of the key files: If a function had either the "ip modify" or a "direct" call attached to it in the past, a 'M' will be shown. This flag is never cleared. It is - used to know if a function was every modified by the ftrace infrastructure, + used to know if a function was ever modified by the ftrace infrastructure, and can be used for debugging. If the architecture supports it, it will also show what callback @@ -418,7 +418,7 @@ of ftrace. Here is a list of some of the key files: This file contains all the functions that ever had a function callback to it via the ftrace infrastructure. It has the same format as - enabled_functions but shows all functions that have every been + enabled_functions but shows all functions that have ever been traced. To see any function that has every been modified by "ip modify" or a @@ -517,7 +517,7 @@ of ftrace. Here is a list of some of the key files: Whenever an event is recorded into the ring buffer, a "timestamp" is added. This stamp comes from a specified clock. By default, ftrace uses the "local" clock. This - clock is very fast and strictly per cpu, but on some + clock is very fast and strictly per CPU, but on some systems it may not be monotonic with respect to other CPUs. In other words, the local clocks may not be in sync with local clocks on other CPUs. @@ -868,7 +868,7 @@ Here is the list of current tracers that may be configured. "mmiotrace" - A special tracer that is used to trace binary module. + A special tracer that is used to trace binary modules. It will trace all the calls that a module makes to the hardware. Everything it writes and reads from the I/O as well. diff --git a/Documentation/trace/histogram.rst b/Documentation/trace/histogram.rst index 2b98c1720a54..af6d2e15568e 100644 --- a/Documentation/trace/histogram.rst +++ b/Documentation/trace/histogram.rst @@ -840,7 +840,7 @@ Extended error information The compound key examples used a key and a sum value (hitcount) to sort the output, but we can just as easily use two keys instead. - Here's an example where we use a compound key composed of the the + Here's an example where we use a compound key composed of the common_pid and size event fields. Sorting with pid as the primary key and 'size' as the secondary key allows us to display an ordered summary of the recvfrom sizes, with counts, received by From 37c52167b007d9d0bb8c5ed53dd6efc4969a1356 Mon Sep 17 00:00:00 2001 From: David Sterba Date: Wed, 13 Aug 2025 12:00:52 +0200 Subject: [PATCH 085/193] docs: Remove remainders of reiserfs Reiserfs has been removed in 6.13, there are still some mentions in the documentation about it and the tools. Remove those that don't seem relevant anymore but keep references to reiserfs' r5 hash used by some code. There's one change in a script scripts/selinux/install_policy.sh but it does not seem to be relevant either. Signed-off-by: David Sterba Acked-by: Paul Moore Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250813100053.1291961-1-dsterba@suse.com --- Documentation/admin-guide/ext4.rst | 2 +- Documentation/admin-guide/laptops/laptop-mode.rst | 8 ++++---- .../arch/powerpc/eeh-pci-error-recovery.rst | 1 - .../translations/it_IT/process/changes.rst | 14 -------------- fs/btrfs/tree-log.c | 2 +- scripts/selinux/install_policy.sh | 2 +- 6 files changed, 7 insertions(+), 22 deletions(-) diff --git a/Documentation/admin-guide/ext4.rst b/Documentation/admin-guide/ext4.rst index b857eb6ca1b6..ac0c709ea9e7 100644 --- a/Documentation/admin-guide/ext4.rst +++ b/Documentation/admin-guide/ext4.rst @@ -398,7 +398,7 @@ There are 3 different data modes: * writeback mode In data=writeback mode, ext4 does not journal data at all. This mode provides - a similar level of journaling as that of XFS, JFS, and ReiserFS in its default + a similar level of journaling as that of XFS and JFS in its default mode - metadata journaling. A crash+recovery can cause incorrect data to appear in files which were written shortly before the crash. This mode will typically provide the best ext4 performance. diff --git a/Documentation/admin-guide/laptops/laptop-mode.rst b/Documentation/admin-guide/laptops/laptop-mode.rst index b61cc601d298..66eb9cd918b5 100644 --- a/Documentation/admin-guide/laptops/laptop-mode.rst +++ b/Documentation/admin-guide/laptops/laptop-mode.rst @@ -61,7 +61,7 @@ Caveats Check your drive's rating, and don't wear down your drive's lifetime if you don't need to. -* If you mount some of your ext3/reiserfs filesystems with the -n option, then +* If you mount some of your ext3 filesystems with the -n option, then the control script will not be able to remount them correctly. You must set DO_REMOUNTS=0 in the control script, otherwise it will remount them with the wrong options -- or it will fail because it cannot write to /etc/mtab. @@ -96,7 +96,7 @@ control script increases dirty_expire_centisecs and dirty_writeback_centisecs in dirtied are not forced to be written to disk as often. The control script also changes the dirty background ratio, so that background writeback of dirty pages is not done anymore. Combined with a higher commit value (also 10 minutes) for -ext3 or ReiserFS filesystems (also done automatically by the control script), +ext3 filesystem (also done automatically by the control script), this results in concentration of disk activity in a small time interval which occurs only once every 10 minutes, or whenever the disk is forced to spin up by a cache miss. The disk can then be spun down in the periods of inactivity. @@ -587,7 +587,7 @@ Control script:: FST=$(deduce_fstype $MP) fi case "$FST" in - "ext3"|"reiserfs") + "ext3") PARSEDOPTS="$(parse_mount_opts commit "$OPTS")" mount $DEV -t $FST $MP -o remount,$PARSEDOPTS,commit=$MAX_AGE$NOATIME_OPT ;; @@ -647,7 +647,7 @@ Control script:: FST=$(deduce_fstype $MP) fi case "$FST" in - "ext3"|"reiserfs") + "ext3") PARSEDOPTS="$(parse_mount_opts_wfstab $DEV commit $OPTS)" PARSEDOPTS="$(parse_yesno_opts_wfstab $DEV atime atime $PARSEDOPTS)" mount $DEV -t $FST $MP -o remount,$PARSEDOPTS diff --git a/Documentation/arch/powerpc/eeh-pci-error-recovery.rst b/Documentation/arch/powerpc/eeh-pci-error-recovery.rst index d6643a91bdf8..153d0af055b6 100644 --- a/Documentation/arch/powerpc/eeh-pci-error-recovery.rst +++ b/Documentation/arch/powerpc/eeh-pci-error-recovery.rst @@ -315,7 +315,6 @@ network daemons and file systems that didn't need to be disturbed. ideally, the reset should happen at or below the block layer, so that the file systems are not disturbed. - Reiserfs does not tolerate errors returned from the block device. Ext3fs seems to be tolerant, retrying reads/writes until it does succeed. Both have been only lightly tested in this scenario. diff --git a/Documentation/translations/it_IT/process/changes.rst b/Documentation/translations/it_IT/process/changes.rst index 77db13c4022b..7e93833b4511 100644 --- a/Documentation/translations/it_IT/process/changes.rst +++ b/Documentation/translations/it_IT/process/changes.rst @@ -46,7 +46,6 @@ util-linux 2.10o mount --version kmod 13 depmod -V e2fsprogs 1.41.4 e2fsck -V jfsutils 1.1.3 fsck.jfs -V -reiserfsprogs 3.6.3 reiserfsck -V xfsprogs 2.6.0 xfs_db -V squashfs-tools 4.0 mksquashfs -version btrfs-progs 0.18 btrfsck @@ -260,14 +259,6 @@ Sono disponibili i seguenti strumenti: - sono disponibili altri strumenti per il file-system. -Reiserfsprogs -------------- - -Il pacchetto reiserfsprogs dovrebbe essere usato con reiserfs-3.6.x (Linux -kernel 2.4.x). Questo è un pacchetto combinato che contiene versioni -funzionanti di ``mkreiserfs``, ``resize_reiserfs``, ``debugreiserfs`` e -``reiserfsck``. Questi programmi funzionano sulle piattaforme i386 e alpha. - Xfsprogs -------- @@ -479,11 +470,6 @@ JFSutils - -Reiserfsprogs -------------- - -- - Xfsprogs -------- diff --git a/fs/btrfs/tree-log.c b/fs/btrfs/tree-log.c index 2186e87fb61b..f72ce393f480 100644 --- a/fs/btrfs/tree-log.c +++ b/fs/btrfs/tree-log.c @@ -5460,7 +5460,7 @@ struct btrfs_dir_list { * See process_dir_items_leaf() for details about why it is needed. * This is a recursive operation - if an existing dentry corresponds to a * directory, that directory's new entries are logged too (same behaviour as - * ext3/4, xfs, f2fs, reiserfs, nilfs2). Note that when logging the inodes + * ext3/4, xfs, f2fs, nilfs2). Note that when logging the inodes * the dentries point to we do not acquire their VFS lock, otherwise lockdep * complains about the following circular lock dependency / possible deadlock: * diff --git a/scripts/selinux/install_policy.sh b/scripts/selinux/install_policy.sh index db40237e60ce..77368a73f111 100755 --- a/scripts/selinux/install_policy.sh +++ b/scripts/selinux/install_policy.sh @@ -74,7 +74,7 @@ cd /etc/selinux/dummy/contexts/files $SF -F file_contexts / mounts=`cat /proc/$$/mounts | \ - grep -E "ext[234]|jfs|xfs|reiserfs|jffs2|gfs2|btrfs|f2fs|ocfs2" | \ + grep -E "ext[234]|jfs|xfs|jffs2|gfs2|btrfs|f2fs|ocfs2" | \ awk '{ print $2 '}` $SF -F file_contexts $mounts From 168a4742aff1da4166ce12e294b2094126cac2b9 Mon Sep 17 00:00:00 2001 From: Albin Babu Varghese Date: Wed, 20 Aug 2025 15:47:15 -0400 Subject: [PATCH 086/193] Documentation: conf.py: remove repeated word in comment Remove a repeated "are" from a comment in conf.py Signed-off-by: Albin Babu Varghese Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250820194714.130513-2-albinbabuvarghese20@gmail.com --- Documentation/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/conf.py b/Documentation/conf.py index f9828f3862f9..856c04a2abb7 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -234,7 +234,7 @@ author = "The kernel development community" # |version| and |release|, also used in various other places throughout the # built documents. # -# In a normal build, version and release are are set to KERNELVERSION and +# In a normal build, version and release are set to KERNELVERSION and # KERNELRELEASE, respectively, from the Makefile via Sphinx command line # arguments. # From af4ed17fa0c4789b8d0f035a4c21abfa63b7e902 Mon Sep 17 00:00:00 2001 From: Bagas Sanjaya Date: Wed, 20 Aug 2025 12:04:16 +0700 Subject: [PATCH 087/193] Documentation: driver-api: usb: Limit toctree depth toctree index in USB driver api docs currently spoils the entire docs headings due to lack of :maxdepth: option. Add the option to limit toctree depth to 1, mirroring usb subsystem docs in Documentation/usb/index.rst. Signed-off-by: Bagas Sanjaya Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250820050416.25219-1-bagasdotme@gmail.com --- Documentation/driver-api/usb/index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/Documentation/driver-api/usb/index.rst b/Documentation/driver-api/usb/index.rst index cfa8797ea614..fcb24d0500d9 100644 --- a/Documentation/driver-api/usb/index.rst +++ b/Documentation/driver-api/usb/index.rst @@ -3,6 +3,7 @@ Linux USB API ============= .. toctree:: + :maxdepth: 1 usb gadget From e56878b4770ba237cf487c881a59a779016f93de Mon Sep 17 00:00:00 2001 From: Bartlomiej Kubik Date: Tue, 19 Aug 2025 13:35:51 +0200 Subject: [PATCH 088/193] docs: kernel-parameters: typo fix and add missing SPDX-License tag Fix documentation issues by removing a duplicated word and adding the missing SPDX-License identifier. Signed-off-by: Bartlomiej Kubik Reviewed-by: Randy Dunlap Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250819113551.34356-1-kubik.bartlomiej@gmail.com --- Documentation/admin-guide/kernel-parameters.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Documentation/admin-guide/kernel-parameters.rst b/Documentation/admin-guide/kernel-parameters.rst index 39d0e7ff0965..7bf8cc7df6b5 100644 --- a/Documentation/admin-guide/kernel-parameters.rst +++ b/Documentation/admin-guide/kernel-parameters.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + .. _kernelparameters: The kernel's command-line parameters @@ -213,7 +215,7 @@ need or coordination with . There are also arch-specific kernel-parameters not documented here. Note that ALL kernel parameters listed below are CASE SENSITIVE, and that -a trailing = on the name of any parameter states that that parameter will +a trailing = on the name of any parameter states that the parameter will be entered as an environment variable, whereas its absence indicates that it will appear as a kernel argument readable via /proc/cmdline by programs running once the system is up. From 915fb5caad7e569329e376dd7dd9a22afbd27636 Mon Sep 17 00:00:00 2001 From: Mehdi Ben Hadj Khelifa Date: Tue, 19 Aug 2025 09:49:00 +0100 Subject: [PATCH 089/193] docs: Corrected typo in trace/events -Changed 'Dyamically' to 'Dynamically' in trace/events.rst under sections 7.1 and 7.3 Signed-off-by: Mehdi Ben Hadj Khelifa Reviewed-by: Randy Dunlap Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250819085040.974388-1-mehdi.benhadjkhelifa@gmail.com --- Documentation/trace/events.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Documentation/trace/events.rst b/Documentation/trace/events.rst index 2d88a2acacc0..18d112963dec 100644 --- a/Documentation/trace/events.rst +++ b/Documentation/trace/events.rst @@ -629,8 +629,8 @@ following: - tracing synthetic events from in-kernel code - the low-level "dynevent_cmd" API -7.1 Dyamically creating synthetic event definitions ---------------------------------------------------- +7.1 Dynamically creating synthetic event definitions +---------------------------------------------------- There are a couple ways to create a new synthetic event from a kernel module or other kernel code. @@ -944,8 +944,8 @@ Note that synth_event_trace_end() must be called at the end regardless of whether any of the add calls failed (say due to a bad field name being passed in). -7.3 Dyamically creating kprobe and kretprobe event definitions --------------------------------------------------------------- +7.3 Dynamically creating kprobe and kretprobe event definitions +--------------------------------------------------------------- To create a kprobe or kretprobe trace event from kernel code, the kprobe_event_gen_cmd_start() or kretprobe_event_gen_cmd_start() From 4cc7dce79725689d8dd229e13c857aeb97b1c7cf Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Tue, 19 Aug 2025 00:54:56 -0700 Subject: [PATCH 090/193] docs: sysctl: add a few more top-level /proc/sys entries Add a few missing directories under /proc/sys. Fix punctuation and doubled words. Signed-off-by: Randy Dunlap Cc: Rik van Riel Cc: Jonathan Corbet Cc: linux-doc@vger.kernel.org Reviewed-by: Rik van Riel Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250819075456.113623-1-rdunlap@infradead.org --- Documentation/admin-guide/sysctl/index.rst | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/Documentation/admin-guide/sysctl/index.rst b/Documentation/admin-guide/sysctl/index.rst index 03346f98c7b9..4dd2c9b5d752 100644 --- a/Documentation/admin-guide/sysctl/index.rst +++ b/Documentation/admin-guide/sysctl/index.rst @@ -66,25 +66,31 @@ This documentation is about: =============== =============================================================== abi/ execution domains & personalities -debug/ -dev/ device specific information (eg dev/cdrom/info) +<$ARCH> tuning controls for various CPU architecture (e.g. csky, s390) +crypto/ +debug/ +dev/ device specific information (e.g. dev/cdrom/info) fs/ specific filesystems filehandle, inode, dentry and quota tuning binfmt_misc kernel/ global kernel info / tuning miscellaneous stuff + some architecture-specific controls + security (LSM) stuff net/ networking stuff, for documentation look in: proc/ sunrpc/ SUN Remote Procedure Call (NFS) +user/ Per user namespace limits vm/ memory management tuning buffer and cache management -user/ Per user per user namespace limits +xen/ =============== =============================================================== -These are the subdirs I have on my system. There might be more -or other subdirs in another setup. If you see another dir, I'd -really like to hear about it :-) +These are the subdirs I have on my system or have been discovered by +searching through the source code. There might be more or other subdirs +in another setup. If you see another dir, I'd really like to hear about +it :-) .. toctree:: :maxdepth: 1 From 41ecad8b233bf480a1f39b76462dcb2c2d3cdfed Mon Sep 17 00:00:00 2001 From: Raphael Pinsonneault-Thibeault Date: Mon, 18 Aug 2025 14:19:34 -0400 Subject: [PATCH 091/193] docs: fix trailing whitespace error and remove repeated words in propagate_umount.txt in Documentation/filesystems/propagate_umount.txt: line 289: remove whitespace on blank line line 315: remove duplicate "that" line 364: remove duplicate "in" Signed-off-by: Raphael Pinsonneault-Thibeault Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250818181934.55491-2-rpthibeault@gmail.com --- Documentation/filesystems/propagate_umount.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Documentation/filesystems/propagate_umount.txt b/Documentation/filesystems/propagate_umount.txt index c90349e5b889..9a7eb96df300 100644 --- a/Documentation/filesystems/propagate_umount.txt +++ b/Documentation/filesystems/propagate_umount.txt @@ -286,7 +286,7 @@ Trim_one(m) strip the "seen by Trim_ancestors" mark from m remove m from the Candidates list return - + remove_this = false found = false for each n in children(m) @@ -312,7 +312,7 @@ Trim_ancestors(m) } Terminating condition in the loop in Trim_ancestors() is correct, -since that that loop will never run into p belonging to U - p is always +since that loop will never run into p belonging to U - p is always an ancestor of argument of Trim_one() and since U is closed, the argument of Trim_one() would also have to belong to U. But Trim_one() is never called for elements of U. In other words, p belongs to S if and only @@ -361,7 +361,7 @@ such removals. Proof: suppose S was non-shifting, x is a locked element of S, parent of x is not in S and S - {x} is not non-shifting. Then there is an element m in S - {x} and a subtree mounted strictly inside m, such that m contains -an element not in in S - {x}. Since S is non-shifting, everything in +an element not in S - {x}. Since S is non-shifting, everything in that subtree must belong to S. But that means that this subtree must contain x somewhere *and* that parent of x either belongs that subtree or is equal to m. Either way it must belong to S. Contradiction. From 9256019241c9afdd7b27d4b97e9568f5721d97e3 Mon Sep 17 00:00:00 2001 From: Sebastian Andrzej Siewior Date: Fri, 15 Aug 2025 11:38:55 +0200 Subject: [PATCH 092/193] Documentation: seqlock: Add a SPDX license identifier Add a SPDX identifier. The majority of the document has been written by Ahmed S. Darwish. Cc: Ahmed S. Darwish Acked-by: Ahmed S. Darwish Signed-off-by: Sebastian Andrzej Siewior Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250815093858.930751-2-bigeasy@linutronix.de --- Documentation/locking/seqlock.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Documentation/locking/seqlock.rst b/Documentation/locking/seqlock.rst index ec6411d02ac8..3fb7ea3ab22a 100644 --- a/Documentation/locking/seqlock.rst +++ b/Documentation/locking/seqlock.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + ====================================== Sequence counters and sequential locks ====================================== From f41c808c43883d3d7b46e7742a93127acb81d60b Mon Sep 17 00:00:00 2001 From: Sebastian Andrzej Siewior Date: Fri, 15 Aug 2025 11:38:56 +0200 Subject: [PATCH 093/193] Documentation: locking: Add local_lock_nested_bh() to locktypes local_lock_nested_bh() is used within networking where applicable. Document why it is used and how it behaves. Signed-off-by: Sebastian Andrzej Siewior Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250815093858.930751-3-bigeasy@linutronix.de --- Documentation/locking/locktypes.rst | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/Documentation/locking/locktypes.rst b/Documentation/locking/locktypes.rst index 80c914f6eae7..37b6a5670c2f 100644 --- a/Documentation/locking/locktypes.rst +++ b/Documentation/locking/locktypes.rst @@ -204,6 +204,27 @@ per-CPU data structures on a non PREEMPT_RT kernel. local_lock is not suitable to protect against preemption or interrupts on a PREEMPT_RT kernel due to the PREEMPT_RT specific spinlock_t semantics. +CPU local scope and bottom-half +------------------------------- + +Per-CPU variables that are accessed only in softirq context should not rely on +the assumption that this context is implicitly protected due to being +non-preemptible. In a PREEMPT_RT kernel, softirq context is preemptible, and +synchronizing every bottom-half-disabled section via implicit context results +in an implicit per-CPU "big kernel lock." + +A local_lock_t together with local_lock_nested_bh() and +local_unlock_nested_bh() for locking operations help to identify the locking +scope. + +When lockdep is enabled, these functions verify that data structure access +occurs within softirq context. +Unlike local_lock(), local_unlock_nested_bh() does not disable preemption and +does not add overhead when used without lockdep. + +On a PREEMPT_RT kernel, local_lock_t behaves as a real lock and +local_unlock_nested_bh() serializes access to the data structure, which allows +removal of serialization via local_bh_disable(). raw_spinlock_t and spinlock_t ============================= From f51fe3b7e48ca81a9cee15c0146e4fb7d3000d3a Mon Sep 17 00:00:00 2001 From: Sebastian Andrzej Siewior Date: Fri, 15 Aug 2025 11:38:57 +0200 Subject: [PATCH 094/193] Documentation: Add real-time to core-api The documents explain the design concepts behind PREEMPT_RT and highlight key differences necessary to achieve it. It also include a list of requirements that must be fulfilled to support PREEMPT_RT on a given architecture. Signed-off-by: Sebastian Andrzej Siewior [jc: tweaked "how they differ" section head] Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250815093858.930751-4-bigeasy@linutronix.de --- Documentation/core-api/index.rst | 1 + .../real-time/architecture-porting.rst | 109 ++++++++ .../core-api/real-time/differences.rst | 242 ++++++++++++++++++ Documentation/core-api/real-time/index.rst | 16 ++ Documentation/core-api/real-time/theory.rst | 116 +++++++++ 5 files changed, 484 insertions(+) create mode 100644 Documentation/core-api/real-time/architecture-porting.rst create mode 100644 Documentation/core-api/real-time/differences.rst create mode 100644 Documentation/core-api/real-time/index.rst create mode 100644 Documentation/core-api/real-time/theory.rst diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst index a03a99c2cac5..6cbdcbfa79c3 100644 --- a/Documentation/core-api/index.rst +++ b/Documentation/core-api/index.rst @@ -24,6 +24,7 @@ it. printk-index symbol-namespaces asm-annotations + real-time/index Data structures and low-level utilities ======================================= diff --git a/Documentation/core-api/real-time/architecture-porting.rst b/Documentation/core-api/real-time/architecture-porting.rst new file mode 100644 index 000000000000..d822fac29922 --- /dev/null +++ b/Documentation/core-api/real-time/architecture-porting.rst @@ -0,0 +1,109 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================================= +Porting an architecture to support PREEMPT_RT +============================================= + +:Author: Sebastian Andrzej Siewior + +This list outlines the architecture specific requirements that must be +implemented in order to enable PREEMPT_RT. Once all required features are +implemented, ARCH_SUPPORTS_RT can be selected in architecture’s Kconfig to make +PREEMPT_RT selectable. +Many prerequisites (genirq support for example) are enforced by the common code +and are omitted here. + +The optional features are not strictly required but it is worth to consider +them. + +Requirements +------------ + +Forced threaded interrupts + CONFIG_IRQ_FORCED_THREADING must be selected. Any interrupts that must + remain in hard-IRQ context must be marked with IRQF_NO_THREAD. This + requirement applies for instance to clocksource event interrupts, + perf interrupts and cascading interrupt-controller handlers. + +PREEMPTION support + Kernel preemption must be supported and requires that + CONFIG_ARCH_NO_PREEMPT remain unselected. Scheduling requests, such as those + issued from an interrupt or other exception handler, must be processed + immediately. + +POSIX CPU timers and KVM + POSIX CPU timers must expire from thread context rather than directly within + the timer interrupt. This behavior is enabled by setting the configuration + option CONFIG_HAVE_POSIX_CPU_TIMERS_TASK_WORK. + When KVM is enabled, CONFIG_KVM_XFER_TO_GUEST_WORK must also be set to ensure + that any pending work, such as POSIX timer expiration, is handled before + transitioning into guest mode. + +Hard-IRQ and Soft-IRQ stacks + Soft interrupts are handled in the thread context in which they are raised. If + a soft interrupt is triggered from hard-IRQ context, its execution is deferred + to the ksoftirqd thread. Preemption is never disabled during soft interrupt + handling, which makes soft interrupts preemptible. + If an architecture provides a custom __do_softirq() implementation that uses a + separate stack, it must select CONFIG_HAVE_SOFTIRQ_ON_OWN_STACK. The + functionality should only be enabled when CONFIG_SOFTIRQ_ON_OWN_STACK is set. + +FPU and SIMD access in kernel mode + FPU and SIMD registers are typically not used in kernel mode and are therefore + not saved during kernel preemption. As a result, any kernel code that uses + these registers must be enclosed within a kernel_fpu_begin() and + kernel_fpu_end() section. + The kernel_fpu_begin() function usually invokes local_bh_disable() to prevent + interruptions from softirqs and to disable regular preemption. This allows the + protected code to run safely in both thread and softirq contexts. + On PREEMPT_RT kernels, however, kernel_fpu_begin() must not call + local_bh_disable(). Instead, it should use preempt_disable(), since softirqs + are always handled in thread context under PREEMPT_RT. In this case, disabling + preemption alone is sufficient. + The crypto subsystem operates on memory pages and requires users to "walk and + map" these pages while processing a request. This operation must occur outside + the kernel_fpu_begin()/ kernel_fpu_end() section because it requires preemption + to be enabled. These preemption points are generally sufficient to avoid + excessive scheduling latency. + +Exception handlers + Exception handlers, such as the page fault handler, typically enable interrupts + early, before invoking any generic code to process the exception. This is + necessary because handling a page fault may involve operations that can sleep. + Enabling interrupts is especially important on PREEMPT_RT, where certain + locks, such as spinlock_t, become sleepable. For example, handling an + invalid opcode may result in sending a SIGILL signal to the user task. A + debug excpetion will send a SIGTRAP signal. + In both cases, if the exception occurred in user space, it is safe to enable + interrupts early. Sending a signal requires both interrupts and kernel + preemption to be enabled. + +Optional features +----------------- + +Timer and clocksource + A high-resolution clocksource and clockevents device are recommended. The + clockevents device should support the CLOCK_EVT_FEAT_ONESHOT feature for + optimal timer behavior. In most cases, microsecond-level accuracy is + sufficient + +Lazy preemption + This mechanism allows an in-kernel scheduling request for non-real-time tasks + to be delayed until the task is about to return to user space. It helps avoid + preempting a task that holds a sleeping lock at the time of the scheduling + request. + With CONFIG_GENERIC_IRQ_ENTRY enabled, supporting this feature requires + defining a bit for TIF_NEED_RESCHED_LAZY, preferably near TIF_NEED_RESCHED. + +Serial console with NBCON + With PREEMPT_RT enabled, all console output is handled by a dedicated thread + rather than directly from the context in which printk() is invoked. This design + allows printk() to be safely used in atomic contexts. + However, this also means that if the kernel crashes and cannot switch to the + printing thread, no output will be visible preventing the system from printing + its final messages. + There are exceptions for immediate output, such as during panic() handling. To + support this, the console driver must implement new-style lock handling. This + involves setting the CON_NBCON flag in console::flags and providing + implementations for the write_atomic, write_thread, device_lock, and + device_unlock callbacks. diff --git a/Documentation/core-api/real-time/differences.rst b/Documentation/core-api/real-time/differences.rst new file mode 100644 index 000000000000..83ec9aa1c61a --- /dev/null +++ b/Documentation/core-api/real-time/differences.rst @@ -0,0 +1,242 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=========================== +How realtime kernels differ +=========================== + +:Author: Sebastian Andrzej Siewior + +Preface +======= + +With forced-threaded interrupts and sleeping spin locks, code paths that +previously caused long scheduling latencies have been made preemptible and +moved into process context. This allows the scheduler to manage them more +effectively and respond to higher-priority tasks with reduced latency. + +The following chapters provide an overview of key differences between a +PREEMPT_RT kernel and a standard, non-PREEMPT_RT kernel. + +Locking +======= + +Spinning locks such as spinlock_t are used to provide synchronization for data +structures accessed from both interrupt context and process context. For this +reason, locking functions are also available with the _irq() or _irqsave() +suffixes, which disable interrupts before acquiring the lock. This ensures that +the lock can be safely acquired in process context when interrupts are enabled. + +However, on a PREEMPT_RT system, interrupts are forced-threaded and no longer +run in hard IRQ context. As a result, there is no need to disable interrupts as +part of the locking procedure when using spinlock_t. + +For low-level core components such as interrupt handling, the scheduler, or the +timer subsystem the kernel uses raw_spinlock_t. This lock type preserves +traditional semantics: it disables preemption and, when used with _irq() or +_irqsave(), also disables interrupts. This ensures proper synchronization in +critical sections that must remain non-preemptible or with interrupts disabled. + +Execution context +================= + +Interrupt handling in a PREEMPT_RT system is invoked in process context through +the use of threaded interrupts. Other parts of the kernel also shift their +execution into threaded context by different mechanisms. The goal is to keep +execution paths preemptible, allowing the scheduler to interrupt them when a +higher-priority task needs to run. + +Below is an overview of the kernel subsystems involved in this transition to +threaded, preemptible execution. + +Interrupt handling +------------------ + +All interrupts are forced-threaded in a PREEMPT_RT system. The exceptions are +interrupts that are requested with the IRQF_NO_THREAD, IRQF_PERCPU, or +IRQF_ONESHOT flags. + +The IRQF_ONESHOT flag is used together with threaded interrupts, meaning those +registered using request_threaded_irq() and providing only a threaded handler. +Its purpose is to keep the interrupt line masked until the threaded handler has +completed. + +If a primary handler is also provided in this case, it is essential that the +handler does not acquire any sleeping locks, as it will not be threaded. The +handler should be minimal and must avoid introducing delays, such as +busy-waiting on hardware registers. + + +Soft interrupts, bottom half handling +------------------------------------- + +Soft interrupts are raised by the interrupt handler and are executed after the +handler returns. Since they run in thread context, they can be preempted by +other threads. Do not assume that softirq context runs with preemption +disabled. This means you must not rely on mechanisms like local_bh_disable() in +process context to protect per-CPU variables. Because softirq handlers are +preemptible under PREEMPT_RT, this approach does not provide reliable +synchronization. + +If this kind of protection is required for performance reasons, consider using +local_lock_nested_bh(). On non-PREEMPT_RT kernels, this allows lockdep to +verify that bottom halves are disabled. On PREEMPT_RT systems, it adds the +necessary locking to ensure proper protection. + +Using local_lock_nested_bh() also makes the locking scope explicit and easier +for readers and maintainers to understand. + + +per-CPU variables +----------------- + +Protecting access to per-CPU variables solely by using preempt_disable() should +be avoided, especially if the critical section has unbounded runtime or may +call APIs that can sleep. + +If using a spinlock_t is considered too costly for performance reasons, +consider using local_lock_t. On non-PREEMPT_RT configurations, this introduces +no runtime overhead when lockdep is disabled. With lockdep enabled, it verifies +that the lock is only acquired in process context and never from softirq or +hard IRQ context. + +On a PREEMPT_RT kernel, local_lock_t is implemented using a per-CPU spinlock_t, +which provides safe local protection for per-CPU data while keeping the system +preemptible. + +Because spinlock_t on PREEMPT_RT does not disable preemption, it cannot be used +to protect per-CPU data by relying on implicit preemption disabling. If this +inherited preemption disabling is essential and if local_lock_t cannot be used +due to performance constraints, brevity of the code, or abstraction boundaries +within an API then preempt_disable_nested() may be a suitable alternative. On +non-PREEMPT_RT kernels, it verifies with lockdep that preemption is already +disabled. On PREEMPT_RT, it explicitly disables preemption. + +Timers +------ + +By default, an hrtimer is executed in hard interrupt context. The exception is +timers initialized with the HRTIMER_MODE_SOFT flag, which are executed in +softirq context. + +On a PREEMPT_RT kernel, this behavior is reversed: hrtimers are executed in +softirq context by default, typically within the ktimersd thread. This thread +runs at the lowest real-time priority, ensuring it executes before any +SCHED_OTHER tasks but does not interfere with higher-priority real-time +threads. To explicitly request execution in hard interrupt context on +PREEMPT_RT, the timer must be marked with the HRTIMER_MODE_HARD flag. + +Memory allocation +----------------- + +The memory allocation APIs, such as kmalloc() and alloc_pages(), require a +gfp_t flag to indicate the allocation context. On non-PREEMPT_RT kernels, it is +necessary to use GFP_ATOMIC when allocating memory from interrupt context or +from sections where preemption is disabled. This is because the allocator must +not sleep in these contexts waiting for memory to become available. + +However, this approach does not work on PREEMPT_RT kernels. The memory +allocator in PREEMPT_RT uses sleeping locks internally, which cannot be +acquired when preemption is disabled. Fortunately, this is generally not a +problem, because PREEMPT_RT moves most contexts that would traditionally run +with preemption or interrupts disabled into threaded context, where sleeping is +allowed. + +What remains problematic is code that explicitly disables preemption or +interrupts. In such cases, memory allocation must be performed outside the +critical section. + +This restriction also applies to memory deallocation routines such as kfree() +and free_pages(), which may also involve internal locking and must not be +called from non-preemptible contexts. + +IRQ work +-------- + +The irq_work API provides a mechanism to schedule a callback in interrupt +context. It is designed for use in contexts where traditional scheduling is not +possible, such as from within NMI handlers or from inside the scheduler, where +using a workqueue would be unsafe. + +On non-PREEMPT_RT systems, all irq_work items are executed immediately in +interrupt context. Items marked with IRQ_WORK_LAZY are deferred until the next +timer tick but are still executed in interrupt context. + +On PREEMPT_RT systems, the execution model changes. Because irq_work callbacks +may acquire sleeping locks or have unbounded execution time, they are handled +in thread context by a per-CPU irq_work kernel thread. This thread runs at the +lowest real-time priority, ensuring it executes before any SCHED_OTHER tasks +but does not interfere with higher-priority real-time threads. + +The exception are work items marked with IRQ_WORK_HARD_IRQ, which are still +executed in hard interrupt context. Lazy items (IRQ_WORK_LAZY) continue to be +deferred until the next timer tick and are also executed by the irq_work/ +thread. + +RCU callbacks +------------- + +RCU callbacks are invoked by default in softirq context. Their execution is +important because, depending on the use case, they either free memory or ensure +progress in state transitions. Running these callbacks as part of the softirq +chain can lead to undesired situations, such as contention for CPU resources +with other SCHED_OTHER tasks when executed within ksoftirqd. + +To avoid running callbacks in softirq context, the RCU subsystem provides a +mechanism to execute them in process context instead. This behavior can be +enabled by setting the boot command-line parameter rcutree.use_softirq=0. This +setting is enforced in kernels configured with PREEMPT_RT. + +Spin until ready +================ + +The "spin until ready" pattern involves repeatedly checking (spinning on) the +state of a data structure until it becomes available. This pattern assumes that +preemption, soft interrupts, or interrupts are disabled. If the data structure +is marked busy, it is presumed to be in use by another CPU, and spinning should +eventually succeed as that CPU makes progress. + +Some examples are hrtimer_cancel() or timer_delete_sync(). These functions +cancel timers that execute with interrupts or soft interrupts disabled. If a +thread attempts to cancel a timer and finds it active, spinning until the +callback completes is safe because the callback can only run on another CPU and +will eventually finish. + +On PREEMPT_RT kernels, however, timer callbacks run in thread context. This +introduces a challenge: a higher-priority thread attempting to cancel the timer +may preempt the timer callback thread. Since the scheduler cannot migrate the +callback thread to another CPU due to affinity constraints, spinning can result +in livelock even on multiprocessor systems. + +To avoid this, both the canceling and callback sides must use a handshake +mechanism that supports priority inheritance. This allows the canceling thread +to suspend until the callback completes, ensuring forward progress without +risking livelock. + +In order to solve the problem at the API level, the sequence locks were extended +to allow a proper handover between the the spinning reader and the maybe +blocked writer. + +Sequence locks +-------------- + +Sequence counters and sequential locks are documented in +Documentation/locking/seqlock.rst. + +The interface has been extended to ensure proper preemption states for the +writer and spinning reader contexts. This is achieved by embedding the writer +serialization lock directly into the sequence counter type, resulting in +composite types such as seqcount_spinlock_t or seqcount_mutex_t. + +These composite types allow readers to detect an ongoing write and actively +boost the writer’s priority to help it complete its update instead of spinning +and waiting for its completion. + +If the plain seqcount_t is used, extra care must be taken to synchronize the +reader with the writer during updates. The writer must ensure its update is +serialized and non-preemptible relative to the reader. This cannot be achieved +using a regular spinlock_t because spinlock_t on PREEMPT_RT does not disable +preemption. In such cases, using seqcount_spinlock_t is the preferred solution. + +However, if there is no spinning involved i.e., if the reader only needs to +detect whether a write has started and not serialize against it then using +seqcount_t is reasonable. diff --git a/Documentation/core-api/real-time/index.rst b/Documentation/core-api/real-time/index.rst new file mode 100644 index 000000000000..7e14c4ea3d59 --- /dev/null +++ b/Documentation/core-api/real-time/index.rst @@ -0,0 +1,16 @@ +.. SPDX-License-Identifier: GPL-2.0 + +===================== +Real-time preemption +===================== + +This documentation is intended for Linux kernel developers and contributors +interested in the inner workings of PREEMPT_RT. It explains key concepts and +the required changes compared to a non-PREEMPT_RT configuration. + +.. toctree:: + :maxdepth: 2 + + theory + differences + architecture-porting diff --git a/Documentation/core-api/real-time/theory.rst b/Documentation/core-api/real-time/theory.rst new file mode 100644 index 000000000000..43d0120737f8 --- /dev/null +++ b/Documentation/core-api/real-time/theory.rst @@ -0,0 +1,116 @@ +.. SPDX-License-Identifier: GPL-2.0 + +===================== +Theory of operation +===================== + +:Author: Sebastian Andrzej Siewior + +Preface +======= + +PREEMPT_RT transforms the Linux kernel into a real-time kernel. It achieves +this by replacing locking primitives, such as spinlock_t, with a preemptible +and priority-inheritance aware implementation known as rtmutex, and by enforcing +the use of threaded interrupts. As a result, the kernel becomes fully +preemptible, with the exception of a few critical code paths, including entry +code, the scheduler, and low-level interrupt handling routines. + +This transformation places the majority of kernel execution contexts under the +control of the scheduler and significantly increasing the number of preemption +points. Consequently, it reduces the latency between a high-priority task +becoming runnable and its actual execution on the CPU. + +Scheduling +========== + +The core principles of Linux scheduling and the associated user-space API are +documented in the man page sched(7) +`sched(7) `_. +By default, the Linux kernel uses the SCHED_OTHER scheduling policy. Under +this policy, a task is preempted when the scheduler determines that it has +consumed a fair share of CPU time relative to other runnable tasks. However, +the policy does not guarantee immediate preemption when a new SCHED_OTHER task +becomes runnable. The currently running task may continue executing. + +This behavior differs from that of real-time scheduling policies such as +SCHED_FIFO. When a task with a real-time policy becomes runnable, the +scheduler immediately selects it for execution if it has a higher priority than +the currently running task. The task continues to run until it voluntarily +yields the CPU, typically by blocking on an event. + +Sleeping spin locks +=================== + +The various lock types and their behavior under real-time configurations are +described in detail in Documentation/locking/locktypes.rst. +In a non-PREEMPT_RT configuration, a spinlock_t is acquired by first disabling +preemption and then actively spinning until the lock becomes available. Once +the lock is released, preemption is enabled. From a real-time perspective, +this approach is undesirable because disabling preemption prevents the +scheduler from switching to a higher-priority task, potentially increasing +latency. + +To address this, PREEMPT_RT replaces spinning locks with sleeping spin locks +that do not disable preemption. On PREEMPT_RT, spinlock_t is implemented using +rtmutex. Instead of spinning, a task attempting to acquire a contended lock +disables CPU migration, donates its priority to the lock owner (priority +inheritance), and voluntarily schedules out while waiting for the lock to +become available. + +Disabling CPU migration provides the same effect as disabling preemption, while +still allowing preemption and ensuring that the task continues to run on the +same CPU while holding a sleeping lock. + +Priority inheritance +==================== + +Lock types such as spinlock_t and mutex_t in a PREEMPT_RT enabled kernel are +implemented on top of rtmutex, which provides support for priority inheritance +(PI). When a task blocks on such a lock, the PI mechanism temporarily +propagates the blocked task’s scheduling parameters to the lock owner. + +For example, if a SCHED_FIFO task A blocks on a lock currently held by a +SCHED_OTHER task B, task A’s scheduling policy and priority are temporarily +inherited by task B. After this inheritance, task A is put to sleep while +waiting for the lock, and task B effectively becomes the highest-priority task +in the system. This allows B to continue executing, make progress, and +eventually release the lock. + +Once B releases the lock, it reverts to its original scheduling parameters, and +task A can resume execution. + +Threaded interrupts +=================== + +Interrupt handlers are another source of code that executes with preemption +disabled and outside the control of the scheduler. To bring interrupt handling +under scheduler control, PREEMPT_RT enforces threaded interrupt handlers. + +With forced threading, interrupt handling is split into two stages. The first +stage, the primary handler, is executed in IRQ context with interrupts disabled. +Its sole responsibility is to wake the associated threaded handler. The second +stage, the threaded handler, is the function passed to request_irq() as the +interrupt handler. It runs in process context, scheduled by the kernel. + +From waking the interrupt thread until threaded handling is completed, the +interrupt source is masked in the interrupt controller. This ensures that the +device interrupt remains pending but does not retrigger the CPU, allowing the +system to exit IRQ context and handle the interrupt in a scheduled thread. + +By default, the threaded handler executes with the SCHED_FIFO scheduling policy +and a priority of 50 (MAX_RT_PRIO / 2), which is midway between the minimum and +maximum real-time priorities. + +If the threaded interrupt handler raises any soft interrupts during its +execution, those soft interrupt routines are invoked after the threaded handler +completes, within the same thread. Preemption remains enabled during the +execution of the soft interrupt handler. + +Summary +======= + +By using sleeping locks and forced-threaded interrupts, PREEMPT_RT +significantly reduces sections of code where interrupts or preemption is +disabled, allowing the scheduler to preempt the current execution context and +switch to a higher-priority task. From 30c33b62eb875e9840e151f8ba2f7d2558d7e3ba Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 21 Aug 2025 10:16:37 +0200 Subject: [PATCH 095/193] docs: Makefile: Fix LaTeX paper size settings According with: https://www.sphinx-doc.org/en/master/latex.html The variable that handles paper size changed during version 1.5, as pointed at: https://www.sphinx-doc.org/en/master/changes/1.5.html Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/c50db42ead36010fd42ce1e6a2b9da766c11927b.1755763127.git.mchehab+huawei@kernel.org --- Documentation/Makefile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/Makefile b/Documentation/Makefile index 820f07e0afe6..2ed334971acd 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -60,8 +60,8 @@ ifeq ($(HAVE_LATEXMK),1) endif #HAVE_LATEXMK # Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter +PAPEROPT_a4 = -D latex_elements.papersize=a4paper +PAPEROPT_letter = -D latex_elements.papersize=letterpaper ALLSPHINXOPTS = -D kerneldoc_srctree=$(srctree) -D kerneldoc_bin=$(KERNELDOC) ALLSPHINXOPTS += $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) ifneq ($(wildcard $(srctree)/.config),) From f62ed7688cfe1a09b61776216380b56221a17c5c Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 21 Aug 2025 10:16:38 +0200 Subject: [PATCH 096/193] docs: conf.py: better handle latex documents The original logic assumed that app.srcdir is identical to the current working dir. This is the case for a normal build, but, when SPHINXDIRS="some dir" is used, this is not the case anymore. Adjust the logic to fill the LaTeX documents considering app.srcdir, in a way that it will work properly on all cases. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/de23b35a770210950c609deaa32b98cb3673a53a.1755763127.git.mchehab+huawei@kernel.org --- Documentation/conf.py | 54 +++++++++++++++++++++---------------------- 1 file changed, 26 insertions(+), 28 deletions(-) diff --git a/Documentation/conf.py b/Documentation/conf.py index 856c04a2abb7..217c3c778e1e 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -51,11 +51,13 @@ else: dyn_exclude_patterns.append("devicetree/bindings/**.yaml") dyn_exclude_patterns.append("core-api/kho/bindings/**.yaml") -# Properly handle include/exclude patterns -# ---------------------------------------- +# Properly handle directory patterns and LaTeX docs +# ------------------------------------------------- -def update_patterns(app, config): +def config_init(app, config): """ + Initialize path-dependent variabled + On Sphinx, all directories are relative to what it is passed as SOURCEDIR parameter for sphinx-build. Due to that, all patterns that have directory names on it need to be dynamically set, after @@ -86,6 +88,25 @@ def update_patterns(app, config): config.exclude_patterns.append(rel_path) + # LaTeX and PDF output require a list of documents with are dependent + # of the app.srcdir. Add them here + + for fn in os.listdir(app.srcdir): + doc = os.path.join(fn, "index") + if not os.path.exists(os.path.join(app.srcdir, doc + ".rst")): + continue + + has = False + for l in latex_documents: + if l[0] == doc: + has = True + break + + if not has: + latex_documents.append((doc, fn + ".tex", + "Linux %s Documentation" % fn.capitalize(), + "The kernel development community", + "manual")) # helper # ------ @@ -456,32 +477,9 @@ latex_elements["preamble"] += """ \\input{kerneldoc-preamble.sty} """ -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, -# author, documentclass [howto, manual, or own class]). -# Sorted in alphabetical order +# This will be filled up by config-inited event latex_documents = [] -# Add all other index files from Documentation/ subdirectories -for fn in os.listdir("."): - doc = os.path.join(fn, "index") - if os.path.exists(doc + ".rst"): - has = False - for l in latex_documents: - if l[0] == doc: - has = True - break - if not has: - latex_documents.append( - ( - doc, - fn + ".tex", - "Linux %s Documentation" % fn.capitalize(), - "The kernel development community", - "manual", - ) - ) - # The name of an image file (relative to this directory) to place at the top of # the title page. # latex_logo = None @@ -577,4 +575,4 @@ loadConfig(globals()) def setup(app): """Patterns need to be updated at init time on older Sphinx versions""" - app.connect('config-inited', update_patterns) + app.connect('config-inited', config_init) From 280fa75c2cf51793313400d5e3737d5c3131dd5b Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 21 Aug 2025 10:16:39 +0200 Subject: [PATCH 097/193] docs: conf.py: fix doc name with SPHINXDIRS When SPHINXDIRS is used, the current logic produces a wrong list of files, as it will not pick the SPHINXDIRS directory, picking instead their children. Add a rule to detect it and create the PDF doc with the right name. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/183f630643eacf414cfa8d892f03dd1b1055c21e.1755763127.git.mchehab+huawei@kernel.org --- Documentation/conf.py | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/Documentation/conf.py b/Documentation/conf.py index 217c3c778e1e..69290cadc2db 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -91,6 +91,19 @@ def config_init(app, config): # LaTeX and PDF output require a list of documents with are dependent # of the app.srcdir. Add them here + # When SPHINXDIRS is used, we just need to get index.rst, if it exists + if not os.path.samefile(doctree, app.srcdir): + doc = "index" + doc_name = os.path.basename(app.srcdir) + if os.path.exists(os.path.join(app.srcdir, doc + ".rst")): + latex_documents.append((doc, doc_name + ".tex", + "Linux %s Documentation" % doc_name.capitalize(), + "The kernel development community", + "manual")) + return + + # When building all docs, or when a main index.rst doesn't exist, seek + # for it on subdirectories for fn in os.listdir(app.srcdir): doc = os.path.join(fn, "index") if not os.path.exists(os.path.join(app.srcdir, doc + ".rst")): From 9fd4e4ce7e937e4a750a5dc49bd285641e977c5e Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 21 Aug 2025 10:16:40 +0200 Subject: [PATCH 098/193] docs: conf.py: rename some vars at latex_documents logic Currently, the logic uses fn and doc vars, but they don't properly describe what such vars do. Make them clearer: - fname: points to the file name to search (index.rst); - doc: contains the name of the LaTeX or PDF doc to be produced. With that, the checks for SPHINXDIRS and for subdirs will be more coherent. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/b030d9bc53550905adbe9367b2a3915d7331b4c5.1755763127.git.mchehab+huawei@kernel.org --- Documentation/conf.py | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/Documentation/conf.py b/Documentation/conf.py index 69290cadc2db..4db4883901f4 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -93,31 +93,31 @@ def config_init(app, config): # When SPHINXDIRS is used, we just need to get index.rst, if it exists if not os.path.samefile(doctree, app.srcdir): - doc = "index" - doc_name = os.path.basename(app.srcdir) - if os.path.exists(os.path.join(app.srcdir, doc + ".rst")): - latex_documents.append((doc, doc_name + ".tex", - "Linux %s Documentation" % doc_name.capitalize(), + doc = os.path.basename(app.srcdir) + fname = "index" + if os.path.exists(os.path.join(app.srcdir, fname + ".rst")): + latex_documents.append((fname, doc + ".tex", + "Linux %s Documentation" % doc.capitalize(), "The kernel development community", "manual")) return # When building all docs, or when a main index.rst doesn't exist, seek # for it on subdirectories - for fn in os.listdir(app.srcdir): - doc = os.path.join(fn, "index") - if not os.path.exists(os.path.join(app.srcdir, doc + ".rst")): + for doc in os.listdir(app.srcdir): + fname = os.path.join(doc, "index") + if not os.path.exists(os.path.join(app.srcdir, fname + ".rst")): continue has = False for l in latex_documents: - if l[0] == doc: + if l[0] == fname: has = True break if not has: - latex_documents.append((doc, fn + ".tex", - "Linux %s Documentation" % fn.capitalize(), + latex_documents.append((fname, doc + ".tex", + "Linux %s Documentation" % doc.capitalize(), "The kernel development community", "manual")) From e7880da7ed881c160a60784b6e011ad8b16aeb33 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 21 Aug 2025 10:16:41 +0200 Subject: [PATCH 099/193] docs: conf.py: use dedent and r-strings for LaTeX macros Instead of adding extra weird indentation at the tex file, use dedent(). While here, also use r-strings, to make easier to make its content identical to the .tex output. While here, also merge "preamble" that was added on two separate parts of the code (in the past, there were some version-specific checks). No functional changes, just cosmetic ones. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/0d245fbd872ab3ec21bd8fe78b01340ba77ce365.1755763127.git.mchehab+huawei@kernel.org --- Documentation/conf.py | 26 ++++++++++++-------------- 1 file changed, 12 insertions(+), 14 deletions(-) diff --git a/Documentation/conf.py b/Documentation/conf.py index 4db4883901f4..e00ec8f59f25 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -9,6 +9,8 @@ import os import shutil import sys +from textwrap import dedent + import sphinx # If extensions (or modules to document with autodoc) are in another directory, @@ -462,11 +464,11 @@ latex_elements = { "inputenc": "", "utf8extra": "", # Set document margins - "sphinxsetup": """ + "sphinxsetup": dedent(r""" hmargin=0.5in, vmargin=1in, parsedliteralwraps=true, verbatimhintsturnover=false, - """, + """), # # Some of our authors are fond of deep nesting; tell latex to # cope. @@ -475,20 +477,16 @@ latex_elements = { # For CJK One-half spacing, need to be in front of hyperref "extrapackages": r"\usepackage{setspace}", # Additional stuff for the LaTeX preamble. - "preamble": """ + "preamble": dedent(r""" % Use some font with UTF-8 support with XeLaTeX - \\usepackage{fontspec} - \\setsansfont{DejaVu Sans} - \\setromanfont{DejaVu Serif} - \\setmonofont{DejaVu Sans Mono} - """, -} - -# Load kerneldoc specific LaTeX settings -latex_elements["preamble"] += """ + \usepackage{fontspec} + \setsansfont{DejaVu Sans} + \setromanfont{DejaVu Serif} + \setmonofont{DejaVu Sans Mono} % Load kerneldoc specific LaTeX settings - \\input{kerneldoc-preamble.sty} -""" + \input{kerneldoc-preamble.sty} + """) +} # This will be filled up by config-inited event latex_documents = [] From d3265de62fb7e9f30c6ad1195d0bf12edcf3d20f Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 21 Aug 2025 10:16:42 +0200 Subject: [PATCH 100/193] docs: conf.py: fix some troubles for LaTeX output While PDF docs work fine on RPM-based distros, it causes conflicts on Debian & friends. There are multiple root causes here: - the latex_elements still resambles the one from Sphinx 1.x times, where font configurations were stored under "preamble". It doesn't follow the current recommended way from Sphinx documentation: https://www.sphinx-doc.org/en/master/latex.html - instead of setting the main font, from where other fonts are derivated, it sets romanfont; - "fontenc" is not set. This allows the *.tex output file to contain an UTF-8 incompatible fontset: \usepackage[T1]{fontenc} Address such issues to help preventing incompatible usage of both T1 font and UTF-8 ones that comes from DejaVu font family. On some distros, this even generate a LaTeX font warning about corrupted NFSS tables like this (I got it when running it in interactive mode): Package: fontenc 2021/04/29 v2.0v Standard LaTeX package LaTeX Font Info: Trying to load font information for T1+lmr on input line 11 6. LaTeX Font Info: No file T1lmr.fd. on input line 116. LaTeX Font Warning: Font shape `T1/lmr/m/n' undefined (Font) using `T1/lmr/m/n' instead on input line 116. ! Corrupted NFSS tables. wrong@fontshape ...message {Corrupted NFSS tables} error@fontshape else let f... l.116 ...\familydefault\seriesdefault\shapedefault Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/8104ce56a5ea3509fbb56a8163b779d38a6aaa9c.1755763127.git.mchehab+huawei@kernel.org --- Documentation/conf.py | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/Documentation/conf.py b/Documentation/conf.py index e00ec8f59f25..020ecfa05a07 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -461,6 +461,7 @@ latex_elements = { # Latex figure (float) alignment # 'figure_align': 'htbp', # Don't mangle with UTF-8 chars + "fontenc": "", "inputenc": "", "utf8extra": "", # Set document margins @@ -476,13 +477,14 @@ latex_elements = { "maxlistdepth": "10", # For CJK One-half spacing, need to be in front of hyperref "extrapackages": r"\usepackage{setspace}", - # Additional stuff for the LaTeX preamble. - "preamble": dedent(r""" - % Use some font with UTF-8 support with XeLaTeX + "fontpkg": dedent(r""" \usepackage{fontspec} + \setmainfont{DejaVu Serif} \setsansfont{DejaVu Sans} - \setromanfont{DejaVu Serif} \setmonofont{DejaVu Sans Mono} + \newfontfamily\headingfont{DejaVu Serif} + """), + "preamble": dedent(r""" % Load kerneldoc specific LaTeX settings \input{kerneldoc-preamble.sty} """) From d242e2569f10e03dea1d13d54b45d8bb5bbeb614 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 21 Aug 2025 10:16:43 +0200 Subject: [PATCH 101/193] docs: conf.py: extra cleanups and fixes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Makes it more adehent with modern Sphinx LaTeX build setup as defined at: https://www.sphinx-doc.org/en/master/latex.html There, it suggests: 1) to add: 'printindex' “printindex” call, the last thing in the file. Override if you want to generate the index differently, append some content after the index, or change the font. As LaTeX uses two-column mode for the index it is often advisable to set this key to r'\footnotesize\raggedright\printindex'. This indeed solved a corner case on a distro where the index was not properly generated. 2) to add at the main example: \PassOptionsToPackage{svgnames}{xcolor} 3) I got a corner case on one of the distros was using xindy to produce indexes. This ended causing the build logic to incorretly try to use T1 fontenc, which is not UTF-8 compatible. This patch adds: \PassOptionsToPackage{xindy}{language=english,codepage=utf8,noautomatic} to cover such case. It should be noticed that, as the config doesn't have \usepackage{xindy}, this will be used only if latexmk ends using xindy. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/08d16c2ad817910eb5606842f776d3f77d83282f.1755763127.git.mchehab+huawei@kernel.org --- Documentation/conf.py | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/Documentation/conf.py b/Documentation/conf.py index 020ecfa05a07..8fcecdb927b1 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -456,8 +456,15 @@ htmlhelp_basename = "TheLinuxKerneldoc" latex_elements = { # The paper size ('letterpaper' or 'a4paper'). "papersize": "a4paper", + "passoptionstopackages": dedent(r""" + \PassOptionsToPackage{svgnames}{xcolor} + % Avoid encoding troubles when creating indexes + \PassOptionsToPackage{xindy}{language=english,codepage=utf8,noautomatic} + """), # The font size ('10pt', '11pt' or '12pt'). "pointsize": "11pt", + # Needed to generate a .ind file + "printindex": r"\footnotesize\raggedright\printindex", # Latex figure (float) alignment # 'figure_align': 'htbp', # Don't mangle with UTF-8 chars From 4e9a563f0774fdd6f1bd68235314b4b8298fc0a9 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 21 Aug 2025 10:16:44 +0200 Subject: [PATCH 102/193] scripts: sphinx-pre-install: fix PDF build issues on Ubuntu PDF output with current Debian-based distros require other packages for it to work. The main one is pzdr.tfm. Without that, \sphinxhyphen{} won't work, affecting multiple docs. For CJK, tex-gyre is required. Add the missing packages to the list. After the change, all PDF files build on latest Ubuntu: Ubuntu 25.04: ------------- PASSED: OS detection: Ubuntu 25.04 SKIPPED (Sphinx Sphinx 8.1.3): System packages SKIPPED (Sphinx already installed either as venv or as native package): Sphinx on venv SKIPPED (Sphinx already installed either as venv or as native package): Sphinx package PASSED: Clean documentation: Build time: 0:00, return code: 0 PASSED: Build HTML documentation: Build time: 3:28, return code: 0 PASSED: Build PDF documentation: Build time: 11:08, return code: 0 PDF docs: --------- PASSED: dev-tools: pdf/dev-tools.pdf PASSED: tools: pdf/tools.pdf PASSED: filesystems: pdf/filesystems.pdf PASSED: w1: pdf/w1.pdf PASSED: maintainer: pdf/maintainer.pdf PASSED: process: pdf/process.pdf PASSED: isdn: pdf/isdn.pdf PASSED: fault-injection: pdf/fault-injection.pdf PASSED: iio: pdf/iio.pdf PASSED: scheduler: pdf/scheduler.pdf PASSED: staging: pdf/staging.pdf PASSED: fpga: pdf/fpga.pdf PASSED: power: pdf/power.pdf PASSED: leds: pdf/leds.pdf PASSED: edac: pdf/edac.pdf PASSED: PCI: pdf/PCI.pdf PASSED: firmware-guide: pdf/firmware-guide.pdf PASSED: cpu-freq: pdf/cpu-freq.pdf PASSED: mhi: pdf/mhi.pdf PASSED: wmi: pdf/wmi.pdf PASSED: timers: pdf/timers.pdf PASSED: accel: pdf/accel.pdf PASSED: hid: pdf/hid.pdf PASSED: userspace-api: pdf/userspace-api.pdf PASSED: spi: pdf/spi.pdf PASSED: networking: pdf/networking.pdf PASSED: virt: pdf/virt.pdf PASSED: nvme: pdf/nvme.pdf PASSED: translations: pdf/translations.pdf PASSED: input: pdf/input.pdf PASSED: tee: pdf/tee.pdf PASSED: doc-guide: pdf/doc-guide.pdf PASSED: cdrom: pdf/cdrom.pdf PASSED: gpu: pdf/gpu.pdf PASSED: i2c: pdf/i2c.pdf PASSED: RCU: pdf/RCU.pdf PASSED: watchdog: pdf/watchdog.pdf PASSED: usb: pdf/usb.pdf PASSED: rust: pdf/rust.pdf PASSED: crypto: pdf/crypto.pdf PASSED: kbuild: pdf/kbuild.pdf PASSED: livepatch: pdf/livepatch.pdf PASSED: mm: pdf/mm.pdf PASSED: locking: pdf/locking.pdf PASSED: infiniband: pdf/infiniband.pdf PASSED: driver-api: pdf/driver-api.pdf PASSED: bpf: pdf/bpf.pdf PASSED: devicetree: pdf/devicetree.pdf PASSED: block: pdf/block.pdf PASSED: target: pdf/target.pdf PASSED: arch: pdf/arch.pdf PASSED: pcmcia: pdf/pcmcia.pdf PASSED: scsi: pdf/scsi.pdf PASSED: netlabel: pdf/netlabel.pdf PASSED: sound: pdf/sound.pdf PASSED: security: pdf/security.pdf PASSED: accounting: pdf/accounting.pdf PASSED: admin-guide: pdf/admin-guide.pdf PASSED: core-api: pdf/core-api.pdf PASSED: fb: pdf/fb.pdf PASSED: peci: pdf/peci.pdf PASSED: trace: pdf/trace.pdf PASSED: misc-devices: pdf/misc-devices.pdf PASSED: kernel-hacking: pdf/kernel-hacking.pdf PASSED: hwmon: pdf/hwmon.pdf Reported-by: Akira Yokosawa Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/b5e2e0df68b377b148fdbdd721f6c1cbefe6f861.1755763127.git.mchehab+huawei@kernel.org --- scripts/sphinx-pre-install | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index b8474848df4e..b24a6f91ec0a 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -764,9 +764,6 @@ class SphinxDependencyChecker(MissingCheckers): if self.pdf: pdf_pkgs = { - "texlive-lang-chinese": [ - "/usr/share/texlive/texmf-dist/tex/latex/ctex/ctexhook.sty", - ], "fonts-dejavu": [ "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf", ], @@ -775,6 +772,15 @@ class SphinxDependencyChecker(MissingCheckers): "/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc", "/usr/share/fonts/opentype/noto/NotoSerifCJK-Regular.ttc", ], + "tex-gyre": [ + "/usr/share/texmf/tex/latex/tex-gyre/tgtermes.sty" + ], + "texlive-fonts-recommended": [ + "/usr/share/texlive/texmf-dist/fonts/tfm/adobe/zapfding/pzdr.tfm", + ], + "texlive-lang-chinese": [ + "/usr/share/texlive/texmf-dist/tex/latex/ctex/ctexhook.sty", + ], } for package, files in pdf_pkgs.items(): From 9ff5c2f51da284906c2f89e7d594f31be69e7abe Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 21 Aug 2025 10:16:45 +0200 Subject: [PATCH 103/193] scripts: sphinx-pre-install: add missing gentoo pdf dependencies There are two packages that are required to build PDF at gentoo: dev-texlive/texlive-latexextra media-fonts/lm Place latex_dependencies on a list to make it easier to maintain and add the missing ones. With that, most PDF documents now build on Gentoo: Gentoo Base System release 2.17: -------------------------------- PASSED: OS detection: Gentoo Base System release 2.17 SKIPPED (Sphinx Sphinx 8.2.3): System packages SKIPPED (Sphinx already installed either as venv or as native package): Sphinx on venv SKIPPED (Sphinx already installed either as venv or as native package): Sphinx package PASSED: Clean documentation: Build time: 0:00, return code: 0 PASSED: Build HTML documentation: Build time: 5:28, return code: 0 PARTIAL: Build PDF documentation: Test failed (Build time: 9:19, return code: 2) PDF docs: --------- PASSED: dev-tools: pdf/dev-tools.pdf PASSED: tools: pdf/tools.pdf PASSED: filesystems: pdf/filesystems.pdf PASSED: w1: pdf/w1.pdf PASSED: maintainer: pdf/maintainer.pdf PASSED: process: pdf/process.pdf PASSED: isdn: pdf/isdn.pdf PASSED: fault-injection: pdf/fault-injection.pdf PASSED: iio: pdf/iio.pdf PASSED: scheduler: pdf/scheduler.pdf PASSED: staging: pdf/staging.pdf PASSED: fpga: pdf/fpga.pdf PASSED: power: pdf/power.pdf PASSED: leds: pdf/leds.pdf PASSED: edac: pdf/edac.pdf PASSED: PCI: pdf/PCI.pdf PASSED: firmware-guide: pdf/firmware-guide.pdf PASSED: cpu-freq: pdf/cpu-freq.pdf PASSED: mhi: pdf/mhi.pdf PASSED: wmi: pdf/wmi.pdf PASSED: timers: pdf/timers.pdf PASSED: accel: pdf/accel.pdf PASSED: hid: pdf/hid.pdf FAILED: userspace-api: Build failed (FAILED) PASSED: spi: pdf/spi.pdf PASSED: networking: pdf/networking.pdf PASSED: virt: pdf/virt.pdf PASSED: nvme: pdf/nvme.pdf FAILED: translations: Build failed (FAILED) PASSED: input: pdf/input.pdf PASSED: tee: pdf/tee.pdf PASSED: doc-guide: pdf/doc-guide.pdf PASSED: cdrom: pdf/cdrom.pdf FAILED: gpu: Build failed (FAILED) FAILED: i2c: Build failed (FAILED) FAILED: RCU: Build failed (FAILED) PASSED: watchdog: pdf/watchdog.pdf PASSED: usb: pdf/usb.pdf PASSED: rust: pdf/rust.pdf PASSED: crypto: pdf/crypto.pdf PASSED: kbuild: pdf/kbuild.pdf PASSED: livepatch: pdf/livepatch.pdf PASSED: mm: pdf/mm.pdf PASSED: locking: pdf/locking.pdf PASSED: infiniband: pdf/infiniband.pdf PASSED: driver-api: pdf/driver-api.pdf PASSED: bpf: pdf/bpf.pdf PASSED: devicetree: pdf/devicetree.pdf PASSED: block: pdf/block.pdf PASSED: target: pdf/target.pdf FAILED: arch: Build failed (FAILED) PASSED: pcmcia: pdf/pcmcia.pdf PASSED: scsi: pdf/scsi.pdf PASSED: netlabel: pdf/netlabel.pdf PASSED: sound: pdf/sound.pdf PASSED: security: pdf/security.pdf PASSED: accounting: pdf/accounting.pdf PASSED: admin-guide: pdf/admin-guide.pdf FAILED: core-api: Build failed (FAILED) PASSED: fb: pdf/fb.pdf PASSED: peci: pdf/peci.pdf PASSED: trace: pdf/trace.pdf PASSED: misc-devices: pdf/misc-devices.pdf PASSED: kernel-hacking: pdf/kernel-hacking.pdf PASSED: hwmon: pdf/hwmon.pdf Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/0ac8d6b7484aaf930917c8edde53742d425e7e8f.1755763127.git.mchehab+huawei@kernel.org --- scripts/sphinx-pre-install | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index b24a6f91ec0a..f987abfec802 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -1058,12 +1058,19 @@ class SphinxDependencyChecker(MissingCheckers): """ Provide package installation hints for Gentoo. """ + texlive_deps = [ + "dev-texlive/texlive-latexextra", + "dev-texlive/texlive-xetex", + "media-fonts/dejavu", + "media-fonts/lm", + ] + progs = { "convert": "media-gfx/imagemagick", "dot": "media-gfx/graphviz", "rsvg-convert": "gnome-base/librsvg", "virtualenv": "dev-python/virtualenv", - "xelatex": "dev-texlive/texlive-xetex media-fonts/dejavu", + "xelatex": " ".join(texlive_deps), "yaml": "dev-python/pyyaml", "python-sphinx": "dev-python/sphinx", } From b2d5d61c1371dc6e0ddda69a0a2c921e3ceb928e Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 21 Aug 2025 10:16:46 +0200 Subject: [PATCH 104/193] scripts: sphinx-pre-install: fix PDF dependencies for openSuse The dependencies are outdated: both versions need texlive-dejavu fonts. Also, for PDF generation, python311-Sphinx-latex is required. With that, all PDF files are now tuilt on both: openSUSE Leap 15.6: ------------------- PASSED: OS detection: openSUSE Leap 15.6 SKIPPED (Sphinx Sphinx 7.2.6): System packages SKIPPED (Sphinx already installed either as venv or as native package): Sphinx on venv SKIPPED (Sphinx already installed either as venv or as native package): Sphinx package PASSED: Clean documentation: Build time: 0:00, return code: 0 PASSED: Build HTML documentation: Build time: 5:29, return code: 0 PASSED: Build PDF documentation: Build time: 13:45, return code: 0 openSUSE Tumbleweed: -------------------- PASSED: OS detection: openSUSE Tumbleweed SKIPPED (Sphinx Sphinx 8.2.3): System packages SKIPPED (Sphinx already installed either as venv or as native package): Sphinx on venv SKIPPED (Sphinx already installed either as venv or as native package): Sphinx package PASSED: Clean documentation: Build time: 0:00, return code: 0 PASSED: Build HTML documentation: Build time: 4:33, return code: 0 PASSED: Build PDF documentation: Build time: 13:18, return code: 0 Summary ======= PASSED - openSUSE Leap 15.6 (7 tests) PASSED - openSUSE Tumbleweed (7 tests) Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/d78457376f9dfd24cb7ac3a32895c654412715f3.1755763127.git.mchehab+huawei@kernel.org --- scripts/sphinx-pre-install | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index f987abfec802..86f129c76ecd 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -901,7 +901,7 @@ class SphinxDependencyChecker(MissingCheckers): "dot": "graphviz", "python-sphinx": "python3-sphinx", "virtualenv": "python3-virtualenv", - "xelatex": "texlive-xetex-bin", + "xelatex": "texlive-xetex-bin texlive-dejavu", "yaml": "python3-pyyaml", } @@ -937,7 +937,7 @@ class SphinxDependencyChecker(MissingCheckers): self.recommend_python = True progs.update({ - "python-sphinx": "python311-Sphinx", + "python-sphinx": "python311-Sphinx python311-Sphinx-latex", "virtualenv": "python311-virtualenv", "yaml": "python311-PyYAML", }) @@ -945,7 +945,7 @@ class SphinxDependencyChecker(MissingCheckers): # Tumbleweed defaults to Python 3.11 progs.update({ - "python-sphinx": "python313-Sphinx", + "python-sphinx": "python313-Sphinx python313-Sphinx-latex", "virtualenv": "python313-virtualenv", "yaml": "python313-PyYAML", }) From b51f8c12d16bcf29496ebaf1d7cf3587ca28ba0a Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 21 Aug 2025 10:16:47 +0200 Subject: [PATCH 105/193] scripts: sphinx-pre-install: fix dependencies for OpenMandriva The dependeny list for OpenMandriva is wrong. Update it. Yet, on my tests with OpenMandriva LX 4.3, the texlive packages are broken: xelatex can't build anything there, as it lacks xelatex.sfm. Yet, this could be a problem at the way I created the container. Just in case, add a note about that. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/669e759ba366328e5c8d5b14a591ba45a1f58176.1755763127.git.mchehab+huawei@kernel.org --- scripts/sphinx-pre-install | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index 86f129c76ecd..224db3af17db 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -984,13 +984,19 @@ class SphinxDependencyChecker(MissingCheckers): if re.search(r"OpenMandriva", self.system_release): packager_cmd = "dnf install" noto_sans = "noto-sans-cjk-fonts" - tex_pkgs = ["texlive-collection-fontsextra"] + tex_pkgs = [ + "texlive-collection-basic", + "texlive-collection-langcjk", + "texlive-collection-fontsextra", + "texlive-collection-fontsrecommended" + ] # Tested on OpenMandriva Lx 4.3 progs["convert"] = "imagemagick" progs["yaml"] = "python-pyyaml" progs["python-virtualenv"] = "python-virtualenv" progs["python-sphinx"] = "python-sphinx" + progs["xelatex"] = "texlive" self.check_program("python-virtualenv", DepManager.PYTHON_MANDATORY) @@ -1004,7 +1010,9 @@ class SphinxDependencyChecker(MissingCheckers): if not self.distro_msg: self.distro_msg = \ - "Note: for venv, ensurepip could be broken, preventing its install method." + "Notes:\n"\ + "1. for venv, ensurepip could be broken, preventing its install method.\n" \ + "2. at least on OpenMandriva LX 4.3, texlive packages seem broken" else: packager_cmd = "urpmi" From c71c5d6dcb34423c0f15c146240b25a0e78f65aa Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 21 Aug 2025 10:16:48 +0200 Subject: [PATCH 106/193] scripts: sphinx-pre-install: fix pdf dependencies for Mageia 9 On Mageia 9, two packages are missing. Add them. With that, all PDF packages now build: Mageia 9: --------- PASSED: OS detection: Mageia 9 PASSED: System packages: Packages installed PASSED: Sphinx on venv: Sphinx Sphinx 8.1.3 PASSED: Sphinx package: Sphinx Sphinx 6.1.3 PASSED: Clean documentation: Build time: 0:00, return code: 0 PASSED: Build HTML documentation: Build time: 5:17, return code: 0 PASSED: Build PDF documentation: Build time: 14:28, return code: 0 PDF docs: --------- PASSED: dev-tools: pdf/dev-tools.pdf PASSED: tools: pdf/tools.pdf PASSED: filesystems: pdf/filesystems.pdf PASSED: w1: pdf/w1.pdf PASSED: maintainer: pdf/maintainer.pdf PASSED: process: pdf/process.pdf PASSED: isdn: pdf/isdn.pdf PASSED: fault-injection: pdf/fault-injection.pdf PASSED: iio: pdf/iio.pdf PASSED: scheduler: pdf/scheduler.pdf PASSED: staging: pdf/staging.pdf PASSED: fpga: pdf/fpga.pdf PASSED: power: pdf/power.pdf PASSED: leds: pdf/leds.pdf PASSED: edac: pdf/edac.pdf PASSED: PCI: pdf/PCI.pdf PASSED: firmware-guide: pdf/firmware-guide.pdf PASSED: cpu-freq: pdf/cpu-freq.pdf PASSED: mhi: pdf/mhi.pdf PASSED: wmi: pdf/wmi.pdf PASSED: timers: pdf/timers.pdf PASSED: accel: pdf/accel.pdf PASSED: hid: pdf/hid.pdf PASSED: userspace-api: pdf/userspace-api.pdf PASSED: spi: pdf/spi.pdf PASSED: networking: pdf/networking.pdf PASSED: virt: pdf/virt.pdf PASSED: nvme: pdf/nvme.pdf PASSED: translations: pdf/translations.pdf PASSED: input: pdf/input.pdf PASSED: tee: pdf/tee.pdf PASSED: doc-guide: pdf/doc-guide.pdf PASSED: cdrom: pdf/cdrom.pdf PASSED: gpu: pdf/gpu.pdf PASSED: i2c: pdf/i2c.pdf PASSED: RCU: pdf/RCU.pdf PASSED: watchdog: pdf/watchdog.pdf PASSED: usb: pdf/usb.pdf PASSED: rust: pdf/rust.pdf PASSED: crypto: pdf/crypto.pdf PASSED: kbuild: pdf/kbuild.pdf PASSED: livepatch: pdf/livepatch.pdf PASSED: mm: pdf/mm.pdf PASSED: locking: pdf/locking.pdf PASSED: infiniband: pdf/infiniband.pdf PASSED: driver-api: pdf/driver-api.pdf PASSED: bpf: pdf/bpf.pdf PASSED: devicetree: pdf/devicetree.pdf PASSED: block: pdf/block.pdf PASSED: target: pdf/target.pdf PASSED: arch: pdf/arch.pdf PASSED: pcmcia: pdf/pcmcia.pdf PASSED: scsi: pdf/scsi.pdf PASSED: netlabel: pdf/netlabel.pdf PASSED: sound: pdf/sound.pdf PASSED: security: pdf/security.pdf PASSED: accounting: pdf/accounting.pdf PASSED: admin-guide: pdf/admin-guide.pdf PASSED: core-api: pdf/core-api.pdf PASSED: fb: pdf/fb.pdf PASSED: peci: pdf/peci.pdf PASSED: trace: pdf/trace.pdf PASSED: misc-devices: pdf/misc-devices.pdf PASSED: kernel-hacking: pdf/kernel-hacking.pdf PASSED: hwmon: pdf/hwmon.pdf Summary ======= PASSED - Mageia 9 (7 tests) Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/bd6e03c79b890ad0168493cdb4cdaf610bbc8c45.1755763127.git.mchehab+huawei@kernel.org --- scripts/sphinx-pre-install | 2 ++ 1 file changed, 2 insertions(+) diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index 224db3af17db..758a84ae6347 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -979,6 +979,8 @@ class SphinxDependencyChecker(MissingCheckers): tex_pkgs = [ "texlive-fontsextra", + "texlive-fonts-asian", + "fonts-ttf-dejavu", ] if re.search(r"OpenMandriva", self.system_release): From 4509d36ceea288a78bb256416d9ca38d3298c7cb Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 21 Aug 2025 10:16:49 +0200 Subject: [PATCH 107/193] scripts: sphinx-pre-install: fix PDF dependencies for gentoo Package fonts are wrong. Fix it. With that, most PDF files now builds. PDF docs: --------- PASSED: dev-tools: pdf/dev-tools.pdf PASSED: tools: pdf/tools.pdf PASSED: filesystems: pdf/filesystems.pdf PASSED: w1: pdf/w1.pdf PASSED: maintainer: pdf/maintainer.pdf PASSED: process: pdf/process.pdf PASSED: isdn: pdf/isdn.pdf PASSED: fault-injection: pdf/fault-injection.pdf PASSED: iio: pdf/iio.pdf PASSED: scheduler: pdf/scheduler.pdf PASSED: staging: pdf/staging.pdf PASSED: fpga: pdf/fpga.pdf PASSED: power: pdf/power.pdf PASSED: leds: pdf/leds.pdf PASSED: edac: pdf/edac.pdf PASSED: PCI: pdf/PCI.pdf PASSED: firmware-guide: pdf/firmware-guide.pdf PASSED: cpu-freq: pdf/cpu-freq.pdf PASSED: mhi: pdf/mhi.pdf PASSED: wmi: pdf/wmi.pdf PASSED: timers: pdf/timers.pdf PASSED: accel: pdf/accel.pdf PASSED: hid: pdf/hid.pdf FAILED: userspace-api: Build failed (FAILED) PASSED: spi: pdf/spi.pdf PASSED: networking: pdf/networking.pdf PASSED: virt: pdf/virt.pdf PASSED: nvme: pdf/nvme.pdf FAILED: translations: Build failed (FAILED) PASSED: input: pdf/input.pdf PASSED: tee: pdf/tee.pdf PASSED: doc-guide: pdf/doc-guide.pdf PASSED: cdrom: pdf/cdrom.pdf FAILED: gpu: Build failed (FAILED) FAILED: i2c: Build failed (FAILED) FAILED: RCU: Build failed (FAILED) PASSED: watchdog: pdf/watchdog.pdf PASSED: usb: pdf/usb.pdf PASSED: rust: pdf/rust.pdf PASSED: crypto: pdf/crypto.pdf PASSED: kbuild: pdf/kbuild.pdf PASSED: livepatch: pdf/livepatch.pdf PASSED: mm: pdf/mm.pdf PASSED: locking: pdf/locking.pdf PASSED: infiniband: pdf/infiniband.pdf PASSED: driver-api: pdf/driver-api.pdf PASSED: bpf: pdf/bpf.pdf PASSED: devicetree: pdf/devicetree.pdf PASSED: block: pdf/block.pdf PASSED: target: pdf/target.pdf FAILED: arch: Build failed (FAILED) PASSED: pcmcia: pdf/pcmcia.pdf PASSED: scsi: pdf/scsi.pdf PASSED: netlabel: pdf/netlabel.pdf PASSED: sound: pdf/sound.pdf PASSED: security: pdf/security.pdf PASSED: accounting: pdf/accounting.pdf PASSED: admin-guide: pdf/admin-guide.pdf FAILED: core-api: Build failed (FAILED) PASSED: fb: pdf/fb.pdf PASSED: peci: pdf/peci.pdf PASSED: trace: pdf/trace.pdf PASSED: misc-devices: pdf/misc-devices.pdf PASSED: kernel-hacking: pdf/kernel-hacking.pdf PASSED: hwmon: pdf/hwmon.pdf Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/1ccbac9fd1f4e598dda82e775b64768ec3696248.1755763127.git.mchehab+huawei@kernel.org --- scripts/sphinx-pre-install | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index 758a84ae6347..c46d7b76f93c 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -1069,10 +1069,10 @@ class SphinxDependencyChecker(MissingCheckers): Provide package installation hints for Gentoo. """ texlive_deps = [ + "dev-texlive/texlive-fontsrecommended", "dev-texlive/texlive-latexextra", "dev-texlive/texlive-xetex", "media-fonts/dejavu", - "media-fonts/lm", ] progs = { From c6e23912855d4848883080200e09551b6dcbc7df Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 21 Aug 2025 10:16:50 +0200 Subject: [PATCH 108/193] scripts/sphinx-pre-install: fix Archlinux PDF dependencies There are some missing packages causing PDF build to fail on Archlinux and add latexmk (from texlive-binextra package). Yet, at least today, PDF builds are failing on a very late stage, when trying to run xdvipdfmx: $ xdvipdfmx -E -o "peci.pdf" "peci.xdv" xdvipdfmx:fatal: Unrecognized paper format: # Simply write the paper name. See man 1 paper and "paper --no-size --all" for possible values Despite its message, even using a very simple document like: \def\sphinxdocclass{report} \documentclass[a4paper,11pt,english]{sphinxmanual} \begin{document} Test \end{document} or even: \def\sphinxdocclass{report} \documentclass{sphinxmanual} \begin{document} Test \end{document} Is causing xdvipdfmx to complain about geometry. As Archlinux is a rolling release distro, maybe I got it on a bad day. So, let's fix it in the hope that soon enough someone would fix the issues there. Such broken scenario happens with those packages installed: texlive-basic 2025.2-1 texlive-bin 2025.2-1 texlive-binextra 2025.2-1 texlive-fontsrecommended 2025.2-1 texlive-langchinese 2025.2-1 texlive-langcjk 2025.2-1 texlive-latex 2025.2-1 texlive-latexextra 2025.2-1 texlive-latexrecommended 2025.2-1 texlive-pictures 2025.2-1 texlive-xetex 2025.2-1 python-docutils 1:0.21.2-3 python-sphinx 8.2.3-1 python-sphinx-alabaster-theme 1.0.0-4 python-sphinxcontrib-applehelp 2.0.0-3 python-sphinxcontrib-devhelp 2.0.0-4 python-sphinxcontrib-htmlhelp 2.1.0-3 python-sphinxcontrib-jsmath 1.0.1-19 python-sphinxcontrib-qthelp 2.0.0-3 python-sphinxcontrib-serializinghtml 2.0.0-3 Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/574d902f7691861e18339217f42409850ee58791.1755763127.git.mchehab+huawei@kernel.org --- scripts/sphinx-pre-install | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index c46d7b76f93c..954ed3dc0645 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -1048,7 +1048,12 @@ class SphinxDependencyChecker(MissingCheckers): } archlinux_tex_pkgs = [ + "texlive-basic", + "texlive-binextra", "texlive-core", + "texlive-fontsrecommended", + "texlive-langchinese", + "texlive-langcjk", "texlive-latexextra", "ttf-dejavu", ] From 2dddb2792b2ea6571ff44e46a6f7f11400073c9a Mon Sep 17 00:00:00 2001 From: Alex Tran Date: Wed, 27 Aug 2025 00:45:25 -0700 Subject: [PATCH 109/193] docs: driver-api pinctrl cleanup Replace FIXME comments in the pinctrl documentation example with proper cleanup code: - Add devm_pinctrl_put() calls in error paths (pinctrl_lookup_state, pinctrl_select_state) after successful devm_pinctrl_get() - Set foo->p to NULL when devm_pinctrl_get() fails - Add ret variable for cleaner error handling - provides proper example of pinctrl resource management on failure Signed-off-by: Alex Tran Reviewed-by: Linus Walleij Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250827074525.685863-1-alex.t.tran@gmail.com --- Documentation/driver-api/pin-control.rst | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/Documentation/driver-api/pin-control.rst b/Documentation/driver-api/pin-control.rst index 27ea1236307e..281533c33914 100644 --- a/Documentation/driver-api/pin-control.rst +++ b/Documentation/driver-api/pin-control.rst @@ -1202,22 +1202,24 @@ default state like this: { /* Allocate a state holder named "foo" etc */ struct foo_state *foo = ...; + int ret; foo->p = devm_pinctrl_get(&device); if (IS_ERR(foo->p)) { - /* FIXME: clean up "foo" here */ - return PTR_ERR(foo->p); + ret = PTR_ERR(foo->p); + foo->p = NULL; + return ret; } foo->s = pinctrl_lookup_state(foo->p, PINCTRL_STATE_DEFAULT); if (IS_ERR(foo->s)) { - /* FIXME: clean up "foo" here */ + devm_pinctrl_put(foo->p); return PTR_ERR(foo->s); } ret = pinctrl_select_state(foo->p, foo->s); if (ret < 0) { - /* FIXME: clean up "foo" here */ + devm_pinctrl_put(foo->p); return ret; } } From 61578493ca7f9d4acd804544f3f5651f5124b12f Mon Sep 17 00:00:00 2001 From: Bagas Sanjaya Date: Tue, 26 Aug 2025 09:47:56 +0700 Subject: [PATCH 110/193] Documentation: ocfs2: Properly reindent filecheck operations list Some of texts in filecheck operations list are indented out of the list. In particular, the third operation is shown not as the third list item but rather as a separate paragraph. Reindent the list so that gets properly rendered as such. Signed-off-by: Bagas Sanjaya Acked-by: Joseph Qi Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250826024756.16073-1-bagasdotme@gmail.com --- .../filesystems/ocfs2-online-filecheck.rst | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/Documentation/filesystems/ocfs2-online-filecheck.rst b/Documentation/filesystems/ocfs2-online-filecheck.rst index 2257bb53edc1..9e8449416e0b 100644 --- a/Documentation/filesystems/ocfs2-online-filecheck.rst +++ b/Documentation/filesystems/ocfs2-online-filecheck.rst @@ -58,33 +58,33 @@ inode, fixing inode and setting the size of result record history. # echo "" > /sys/fs/ocfs2//filecheck/check # cat /sys/fs/ocfs2//filecheck/check -The output is like this:: + The output is like this:: INO DONE ERROR 39502 1 GENERATION - lists the inode numbers. - indicates whether the operation has been finished. - says what kind of errors was found. For the detailed error numbers, - please refer to the file linux/fs/ocfs2/filecheck.h. + lists the inode numbers. + indicates whether the operation has been finished. + says what kind of errors was found. For the detailed error numbers, + please refer to the file linux/fs/ocfs2/filecheck.h. 2. If you determine to fix this inode, do:: # echo "" > /sys/fs/ocfs2//filecheck/fix # cat /sys/fs/ocfs2//filecheck/fix -The output is like this::: + The output is like this:: INO DONE ERROR 39502 1 SUCCESS -This time, the column indicates whether this fix is successful or not. + This time, the column indicates whether this fix is successful or not. 3. The record cache is used to store the history of check/fix results. It's -default size is 10, and can be adjust between the range of 10 ~ 100. You can -adjust the size like this:: + default size is 10, and can be adjust between the range of 10 ~ 100. You can + adjust the size like this:: - # echo "" > /sys/fs/ocfs2//filecheck/set + # echo "" > /sys/fs/ocfs2//filecheck/set Fixing stuff ============ From b5698da669401ed3f51add92f80457703f0937e3 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 22 Aug 2025 16:19:13 +0200 Subject: [PATCH 111/193] docs: parse-headers.pl: improve its debug output format Change the --debug logic to help comparing its results with a new python script. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/1064011717951eac257889a3032303c9d4440711.1755872208.git.mchehab+huawei@kernel.org --- Documentation/sphinx/parse-headers.pl | 31 ++++++++++++++++++++------- 1 file changed, 23 insertions(+), 8 deletions(-) diff --git a/Documentation/sphinx/parse-headers.pl b/Documentation/sphinx/parse-headers.pl index 7b1458544e2e..560685926cdb 100755 --- a/Documentation/sphinx/parse-headers.pl +++ b/Documentation/sphinx/parse-headers.pl @@ -31,8 +31,6 @@ my %enums; my %enum_symbols; my %structs; -require Data::Dumper if ($debug); - # # read the file and get identifiers # @@ -197,6 +195,9 @@ if ($file_exceptions) { } else { $reftype = $def_reftype{$type}; } + if (!$reftype) { + print STDERR "Warning: can't find ref type for $type"; + } $new = "$reftype:`$old <$new>`"; if ($type eq "ioctl") { @@ -229,12 +230,26 @@ if ($file_exceptions) { } if ($debug) { - print Data::Dumper->Dump([\%ioctls], [qw(*ioctls)]) if (%ioctls); - print Data::Dumper->Dump([\%typedefs], [qw(*typedefs)]) if (%typedefs); - print Data::Dumper->Dump([\%enums], [qw(*enums)]) if (%enums); - print Data::Dumper->Dump([\%structs], [qw(*structs)]) if (%structs); - print Data::Dumper->Dump([\%defines], [qw(*defines)]) if (%defines); - print Data::Dumper->Dump([\%enum_symbols], [qw(*enum_symbols)]) if (%enum_symbols); + my @all_hashes = ( + {ioctl => \%ioctls}, + {typedef => \%typedefs}, + {enum => \%enums}, + {struct => \%structs}, + {define => \%defines}, + {symbol => \%enum_symbols} + ); + + foreach my $hash (@all_hashes) { + while (my ($name, $hash_ref) = each %$hash) { + next unless %$hash_ref; # Skip empty hashes + + print "$name:\n"; + for my $key (sort keys %$hash_ref) { + print " $key -> $hash_ref->{$key}\n"; + } + print "\n"; + } + } } # From 8a5a85be4df1ab0642d4a3610691dbaed443d4d0 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 22 Aug 2025 16:19:14 +0200 Subject: [PATCH 112/193] docs: parse-headers.py: convert parse-headers.pl When the Kernel started to use Sphinx, we had to come up with a solution to parse media headers. On that time, we didn't have much experience with Sphinx extensions. So, we came up with our own script-based solution that were basically implementing a set of rules we used to have at the Makefile. Convert it to Python, keeping it bug-compatible with the original script. While here, try to better document it. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/ae5cfa8dff37e280cc9493fc95a51cd0cc0ba127.1755872208.git.mchehab+huawei@kernel.org --- Documentation/sphinx/parse-headers.py | 429 ++++++++++++++++++++++++++ 1 file changed, 429 insertions(+) create mode 100755 Documentation/sphinx/parse-headers.py diff --git a/Documentation/sphinx/parse-headers.py b/Documentation/sphinx/parse-headers.py new file mode 100755 index 000000000000..b39284d21090 --- /dev/null +++ b/Documentation/sphinx/parse-headers.py @@ -0,0 +1,429 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: GPL-2.0 +# Copyright (c) 2016 by Mauro Carvalho Chehab . +# pylint: disable=C0103,R0902,R0912,R0914,R0915 + +""" +Convert a C header or source file (C_FILE), into a ReStructured Text +included via ..parsed-literal block with cross-references for the +documentation files that describe the API. It accepts an optional +EXCEPTIONS_FILE with describes what elements will be either ignored or +be pointed to a non-default reference. + +The output is written at the (OUT_FILE). + +It is capable of identifying defines, functions, structs, typedefs, +enums and enum symbols and create cross-references for all of them. +It is also capable of distinguish #define used for specifying a Linux +ioctl. + +The EXCEPTIONS_FILE 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` +""" + +import argparse +import os +import re +import sys + + +class ParseHeader: + """ + Creates an enriched version of a Kernel header file with cross-links + to each C data structure type. + + It is meant to allow having a more comprehensive documentation, where + uAPI headers will create cross-reference links to the code. + + It is capable of identifying defines, functions, structs, typedefs, + enums and enum symbols and create cross-references for all of them. + It is also capable of distinguish #define used for specifying a Linux + ioctl. + + 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 ` + + Removes the symbol from reference generation. + + 2. Replace rules: + + replace + + Replaces how old_symbol with a new reference. The new_reference can be: + - A simple symbol name; + - A full Sphinx reference. + + On both cases, can be: + - ioctl: for defines that end with _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 define __LINUX_MEDIA_H + 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` + """ + + # Parser regexes with multiple ways to capture enums and structs + RE_ENUMS = [ + re.compile(r"^\s*enum\s+([\w_]+)\s*\{"), + re.compile(r"^\s*enum\s+([\w_]+)\s*$"), + re.compile(r"^\s*typedef\s*enum\s+([\w_]+)\s*\{"), + re.compile(r"^\s*typedef\s*enum\s+([\w_]+)\s*$"), + ] + RE_STRUCTS = [ + re.compile(r"^\s*struct\s+([_\w][\w\d_]+)\s*\{"), + re.compile(r"^\s*struct\s+([_\w][\w\d_]+)$"), + re.compile(r"^\s*typedef\s*struct\s+([_\w][\w\d_]+)\s*\{"), + re.compile(r"^\s*typedef\s*struct\s+([_\w][\w\d_]+)$"), + ] + + # FIXME: the original code was written a long time before Sphinx C + # domain to have multiple namespaces. To avoid to much turn at the + # existing hyperlinks, the code kept using "c:type" instead of the + # right types. To change that, we need to change the types not only + # here, but also at the uAPI media documentation. + DEF_SYMBOL_TYPES = { + "ioctl": { + "prefix": "\\ ", + "suffix": "\\ ", + "ref_type": ":ref", + }, + "define": { + "prefix": "\\ ", + "suffix": "\\ ", + "ref_type": ":ref", + }, + # We're calling each definition inside an enum as "symbol" + "symbol": { + "prefix": "\\ ", + "suffix": "\\ ", + "ref_type": ":ref", + }, + "typedef": { + "prefix": "\\ ", + "suffix": "\\ ", + "ref_type": ":c:type", + }, + # This is the name of the enum itself + "enum": { + "prefix": "", + "suffix": "\\ ", + "ref_type": ":c:type", + }, + "struct": { + "prefix": "", + "suffix": "\\ ", + "ref_type": ":c:type", + }, + } + + def __init__(self, debug: bool = False): + """Initialize internal vars""" + self.debug = debug + self.data = "" + + self.symbols = {} + + for symbol_type in self.DEF_SYMBOL_TYPES: + self.symbols[symbol_type] = {} + + def store_type(self, symbol_type: str, symbol: str, + ref_name: str = None, replace_underscores: bool = True): + """ + Stores a new symbol at self.symbols under symbol_type. + + By default, underscores are replaced by "-" + """ + defs = self.DEF_SYMBOL_TYPES[symbol_type] + + prefix = defs.get("prefix", "") + suffix = defs.get("suffix", "") + ref_type = defs.get("ref_type") + + # Determine ref_link based on symbol type + if ref_type: + if symbol_type == "enum": + ref_link = f"{ref_type}:`{symbol}`" + else: + if not ref_name: + ref_name = symbol.lower() + + if replace_underscores: + ref_name = ref_name.replace("_", "-") + + ref_link = f"{ref_type}:`{symbol} <{ref_name}>`" + else: + ref_link = symbol + + self.symbols[symbol_type][symbol] = f"{prefix}{ref_link}{suffix}" + + def store_line(self, line): + """Stores a line at self.data, properly indented""" + line = " " + line.expandtabs() + self.data += line.rstrip(" ") + + def parse_file(self, file_in: str): + """Reads a C source file and get identifiers""" + self.data = "" + is_enum = False + is_comment = False + multiline = "" + + with open(file_in, "r", + encoding="utf-8", errors="backslashreplace") as f: + for line_no, line in enumerate(f): + self.store_line(line) + line = line.strip("\n") + + # Handle continuation lines + if line.endswith(r"\\"): + multiline += line[-1] + continue + + if multiline: + line = multiline + line + multiline = "" + + # Handle comments. They can be multilined + if not is_comment: + if re.search(r"/\*.*", line): + is_comment = True + else: + # Strip C99-style comments + line = re.sub(r"(//.*)", "", line) + + if is_comment: + if re.search(r".*\*/", line): + is_comment = False + else: + multiline = line + continue + + # At this point, line variable may be a multilined statement, + # if lines end with \ or if they have multi-line comments + # With that, it can safely remove the entire comments, + # and there's no need to use re.DOTALL for the logic below + + line = re.sub(r"(/\*.*\*/)", "", line) + if not line.strip(): + continue + + # It can be useful for debug purposes to print the file after + # having comments stripped and multi-lines grouped. + if self.debug > 1: + print(f"line {line_no + 1}: {line}") + + # Now the fun begins: parse each type and store it. + + # We opted for a two parsing logic here due to: + # 1. it makes easier to debug issues not-parsed symbols; + # 2. we want symbol replacement at the entire content, not + # just when the symbol is detected. + + if is_enum: + match = re.match(r"^\s*([_\w][\w\d_]+)\s*[\,=]?", line) + if match: + self.store_type("symbol", match.group(1)) + if "}" in line: + is_enum = False + continue + + match = re.match(r"^\s*#\s*define\s+([\w_]+)\s+_IO", line) + if match: + self.store_type("ioctl", match.group(1), + replace_underscores=False) + continue + + match = re.match(r"^\s*#\s*define\s+([\w_]+)(\s+|$)", line) + if match: + self.store_type("define", match.group(1)) + continue + + match = re.match(r"^\s*typedef\s+([_\w][\w\d_]+)\s+(.*)\s+([_\w][\w\d_]+);", + line) + if match: + name = match.group(2).strip() + symbol = match.group(3) + self.store_type("typedef", symbol, ref_name=name, + replace_underscores=False) + continue + + for re_enum in self.RE_ENUMS: + match = re_enum.match(line) + if match: + self.store_type("enum", match.group(1)) + is_enum = True + break + + for re_struct in self.RE_STRUCTS: + match = re_struct.match(line) + if match: + self.store_type("struct", match.group(1), + replace_underscores=False) + break + + def process_exceptions(self, fname: str): + """ + Process exceptions file with rules to ignore or replace references. + """ + if not fname: + return + + name = os.path.basename(fname) + + with open(fname, "r", encoding="utf-8", errors="backslashreplace") as f: + for ln, line in enumerate(f): + ln += 1 + line = line.strip() + if not line or line.startswith("#"): + continue + + # Handle ignore rules + match = re.match(r"^ignore\s+(\w+)\s+(\S+)", line) + if match: + c_type = match.group(1) + symbol = match.group(2) + + if c_type not in self.DEF_SYMBOL_TYPES: + sys.exit(f"{name}:{ln}: {c_type} is invalid") + + d = self.symbols[c_type] + if symbol in d: + del d[symbol] + + continue + + # Handle replace rules + match = re.match(r"^replace\s+(\S+)\s+(\S+)\s+(\S+)", line) + if not match: + sys.exit(f"{name}:{ln}: invalid line: {line}") + + c_type, old, new = match.groups() + + if c_type not in self.DEF_SYMBOL_TYPES: + sys.exit(f"{name}:{ln}: {c_type} is invalid") + + reftype = None + + # Parse reference type when the type is specified + + match = re.match(r"^\:c\:(data|func|macro|type)\:\`(.+)\`", new) + if match: + reftype = f":c:{match.group(1)}" + new = match.group(2) + else: + match = re.search(r"(\:ref)\:\`(.+)\`", new) + if match: + reftype = match.group(1) + new = match.group(2) + + # If the replacement rule doesn't have a type, get default + if not reftype: + reftype = self.DEF_SYMBOL_TYPES[c_type].get("ref_type") + if not reftype: + reftype = self.DEF_SYMBOL_TYPES[c_type].get("real_type") + + new_ref = f"{reftype}:`{old} <{new}>`" + + # Change self.symbols to use the replacement rule + if old in self.symbols[c_type]: + self.symbols[c_type][old] = new_ref + else: + print(f"{name}:{ln}: Warning: can't find {old} {c_type}") + + def debug_print(self): + """ + Print debug information containing the replacement rules per symbol. + To make easier to check, group them per type. + """ + if not self.debug: + return + + for c_type, refs in self.symbols.items(): + if not refs: # Skip empty dictionaries + continue + + print(f"{c_type}:") + + for symbol, ref in sorted(refs.items()): + print(f" {symbol} -> {ref}") + + print() + + def write_output(self, file_in: str, file_out: str): + """Write the formatted output to a file.""" + + # Avoid extra blank lines + text = re.sub(r"\s+$", "", self.data) + "\n" + text = re.sub(r"\n\s+\n", "\n\n", text) + + # Escape Sphinx special characters + text = re.sub(r"([\_\`\*\<\>\&\\\\:\/\|\%\$\#\{\}\~\^])", r"\\\1", text) + + # Source uAPI files may have special notes. Use bold font for them + text = re.sub(r"DEPRECATED", "**DEPRECATED**", text) + + # Delimiters to catch the entire symbol after escaped + start_delim = r"([ \n\t\(=\*\@])" + end_delim = r"(\s|,|\\=|\\:|\;|\)|\}|\{)" + + # Process all reference types + for ref_dict in self.symbols.values(): + for symbol, replacement in ref_dict.items(): + symbol = re.escape(re.sub(r"([\_\`\*\<\>\&\\\\:\/])", r"\\\1", symbol)) + text = re.sub(fr'{start_delim}{symbol}{end_delim}', + fr'\1{replacement}\2', text) + + # Remove "\ " where not needed: before spaces and at the end of lines + text = re.sub(r"\\ ([\n ])", r"\1", text) + + title = os.path.basename(file_in) + + with open(file_out, "w", encoding="utf-8", errors="backslashreplace") as f: + f.write(".. -*- coding: utf-8; mode: rst -*-\n\n") + f.write(f"{title}\n") + f.write("=" * len(title)) + f.write("\n\n.. parsed-literal::\n\n") + f.write(text) + + +def main(): + """Main function""" + parser = argparse.ArgumentParser(description=__doc__, + formatter_class=argparse.RawDescriptionHelpFormatter) + + parser.add_argument("-d", "--debug", action="count", default=0, + help="Increase debug level. Can be used multiple times") + parser.add_argument("file_in", help="Input C file") + parser.add_argument("file_out", help="Output RST file") + parser.add_argument("file_exceptions", nargs="?", + help="Exceptions file (optional)") + + args = parser.parse_args() + + parser = ParseHeader(debug=args.debug) + parser.parse_file(args.file_in) + + if args.file_exceptions: + parser.process_exceptions(args.file_exceptions) + + parser.debug_print() + parser.write_output(args.file_in, args.file_out) + + +if __name__ == "__main__": + main() From a2d58c917c3e0d0cd161e343261717dbe96ffe22 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 22 Aug 2025 16:19:15 +0200 Subject: [PATCH 113/193] docs: parse-headers.py: improve --help logic When printing --help, we'd like the name of the files from __doc__ to match the displayed positional arguments at both usage and argument description lines. Use a custom formatter class to convert ``foo`` into ANSI SGR code to bold the argument, if is TTY, and adjust the help text to match the argument names. Here on Plasma, that makes it display it colored, wich is really cool. Yet, I opted for SGR, as the best is to follow the terminal color schema for bold. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/2c1e61d1fb1b2a2838b443beee89c1528831997f.1755872208.git.mchehab+huawei@kernel.org --- Documentation/sphinx/parse-headers.py | 67 +++++++++++++++++++++++---- 1 file changed, 58 insertions(+), 9 deletions(-) diff --git a/Documentation/sphinx/parse-headers.py b/Documentation/sphinx/parse-headers.py index b39284d21090..650f9c9a68d1 100755 --- a/Documentation/sphinx/parse-headers.py +++ b/Documentation/sphinx/parse-headers.py @@ -4,20 +4,20 @@ # pylint: disable=C0103,R0902,R0912,R0914,R0915 """ -Convert a C header or source file (C_FILE), into a ReStructured Text +Convert 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 -EXCEPTIONS_FILE with describes what elements will be either ignored or -be pointed to a non-default reference. +``FILE_RULES`` file to describes what elements will be either ignored or +be pointed to a non-default reference type/name. -The output is written at the (OUT_FILE). +The output is written at ``FILE_OUT``. It is capable of identifying defines, functions, structs, typedefs, enums and enum symbols and create cross-references for all of them. It is also capable of distinguish #define used for specifying a Linux ioctl. -The EXCEPTIONS_FILE contains a set of rules like: +The optional ``FILE_RULES`` contains a set of rules like: ignore ioctl VIDIOC_ENUM_FMT replace ioctl VIDIOC_DQBUF vidioc_qbuf @@ -400,17 +400,66 @@ class ParseHeader: f.write("\n\n.. parsed-literal::\n\n") f.write(text) +class EnrichFormatter(argparse.HelpFormatter): + """ + Better format the output, making easier to identify the positional args + and how they're used at the __doc__ description. + """ + def __init__(self, *args, **kwargs): + """Initialize class and check if is TTY""" + super().__init__(*args, **kwargs) + self._tty = sys.stdout.isatty() + + def enrich_text(self, text): + """Handle ReST markups (currently, only ``foo``)""" + if self._tty and text: + # Replace ``text`` with ANSI bold + return re.sub(r'\`\`(.+?)\`\`', + lambda m: f'\033[1m{m.group(1)}\033[0m', text) + return text + + def _fill_text(self, text, width, indent): + """Enrich descriptions with markups on it""" + enriched = self.enrich_text(text) + return "\n".join(indent + line for line in enriched.splitlines()) + + def _format_usage(self, usage, actions, groups, prefix): + """Enrich positional arguments at usage: line""" + + prog = self._prog + parts = [] + + for action in actions: + if action.option_strings: + opt = action.option_strings[0] + if action.nargs != 0: + opt += f" {action.dest.upper()}" + parts.append(f"[{opt}]") + else: + # Positional argument + parts.append(self.enrich_text(f"``{action.dest.upper()}``")) + + usage_text = f"{prefix or 'usage: '} {prog} {' '.join(parts)}\n" + return usage_text + + def _format_action_invocation(self, action): + """Enrich argument names""" + if not action.option_strings: + return self.enrich_text(f"``{action.dest.upper()}``") + else: + return ", ".join(action.option_strings) + def main(): """Main function""" parser = argparse.ArgumentParser(description=__doc__, - formatter_class=argparse.RawDescriptionHelpFormatter) + formatter_class=EnrichFormatter) parser.add_argument("-d", "--debug", action="count", default=0, help="Increase debug level. Can be used multiple times") parser.add_argument("file_in", help="Input C file") parser.add_argument("file_out", help="Output RST file") - parser.add_argument("file_exceptions", nargs="?", + parser.add_argument("file_rules", nargs="?", help="Exceptions file (optional)") args = parser.parse_args() @@ -418,8 +467,8 @@ def main(): parser = ParseHeader(debug=args.debug) parser.parse_file(args.file_in) - if args.file_exceptions: - parser.process_exceptions(args.file_exceptions) + if args.file_rules: + parser.process_exceptions(args.file_rules) parser.debug_print() parser.write_output(args.file_in, args.file_out) From 285b8d3db2bae79c01d604701c3faddb456aca93 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 22 Aug 2025 16:19:16 +0200 Subject: [PATCH 114/193] docs: parse-headers.py: better handle @var arguments The kernel-doc markups inside headers may contain @var markups. With the current rule, this would be converted into: \* @:c:type:`DMX_BUFFER_FLAG_DISCONTINUITY_INDICATOR `\: Fix it adding a non-printed space if needed. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/8d06bb713d6ec8de65179dd93defe479715409b6.1755872208.git.mchehab+huawei@kernel.org --- Documentation/sphinx/parse-headers.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/Documentation/sphinx/parse-headers.py b/Documentation/sphinx/parse-headers.py index 650f9c9a68d1..f4ab9c49d2f5 100755 --- a/Documentation/sphinx/parse-headers.py +++ b/Documentation/sphinx/parse-headers.py @@ -120,12 +120,12 @@ class ParseHeader: }, # This is the name of the enum itself "enum": { - "prefix": "", + "prefix": "\\ ", "suffix": "\\ ", "ref_type": ":c:type", }, "struct": { - "prefix": "", + "prefix": "\\ ", "suffix": "\\ ", "ref_type": ":c:type", }, @@ -390,6 +390,8 @@ class ParseHeader: # Remove "\ " where not needed: before spaces and at the end of lines text = re.sub(r"\\ ([\n ])", r"\1", text) + text = re.sub(r" \\ ", " ", text) + title = os.path.basename(file_in) From 37497a4dc5ecd40f861fad3a436978394d1e97fa Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 22 Aug 2025 16:19:17 +0200 Subject: [PATCH 115/193] docs: parse-headers.py: simplify the rules for hashes Normal :ref domain accept either hashes or underscores, but c-domain ones don't. Fix it and remove unneeded places where we opt to disable underscore transformation. Ideally, we should have a rule about the default, or change the way media docs have their references. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/0c011090272f7a1068545409222f970ddb1ed431.1755872208.git.mchehab+huawei@kernel.org --- Documentation/sphinx/parse-headers.py | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/Documentation/sphinx/parse-headers.py b/Documentation/sphinx/parse-headers.py index f4ab9c49d2f5..344090ef259c 100755 --- a/Documentation/sphinx/parse-headers.py +++ b/Documentation/sphinx/parse-headers.py @@ -162,7 +162,8 @@ class ParseHeader: if not ref_name: ref_name = symbol.lower() - if replace_underscores: + # c-type references don't support hash + if ref_type == ":ref" and replace_underscores: ref_name = ref_name.replace("_", "-") ref_link = f"{ref_type}:`{symbol} <{ref_name}>`" @@ -258,8 +259,7 @@ class ParseHeader: if match: name = match.group(2).strip() symbol = match.group(3) - self.store_type("typedef", symbol, ref_name=name, - replace_underscores=False) + self.store_type("typedef", symbol, ref_name=name) continue for re_enum in self.RE_ENUMS: @@ -272,8 +272,7 @@ class ParseHeader: for re_struct in self.RE_STRUCTS: match = re_struct.match(line) if match: - self.store_type("struct", match.group(1), - replace_underscores=False) + self.store_type("struct", match.group(1)) break def process_exceptions(self, fname: str): From cde494660f561909ad44a27037c7155454159136 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 22 Aug 2025 16:19:18 +0200 Subject: [PATCH 116/193] tools: docs: parse-headers.py: move it from sphinx dir As suggested by Jon, we should start having a tools/docs directory, instead of placing everything under scripts. In the specific case of parse-headers.py, the previous location is where we're placing Sphinx extensions, which is not the right place for execs. Move it to tools/docs/parse-headers.py. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/0f5ac2d704cffe9834e589b39549d2393e1237ef.1755872208.git.mchehab+huawei@kernel.org --- .pylintrc | 2 +- tools/docs/lib/__init__.py | 0 tools/docs/lib/enrich_formatter.py | 70 ++++++++++++++ .../docs/lib/parse_data_structs.py | 95 ++----------------- tools/docs/parse-headers.py | 57 +++++++++++ 5 files changed, 135 insertions(+), 89 deletions(-) create mode 100644 tools/docs/lib/__init__.py create mode 100644 tools/docs/lib/enrich_formatter.py rename Documentation/sphinx/parse-headers.py => tools/docs/lib/parse_data_structs.py (80%) create mode 100755 tools/docs/parse-headers.py diff --git a/.pylintrc b/.pylintrc index 30b8ae1659f8..89eaf2100edd 100644 --- a/.pylintrc +++ b/.pylintrc @@ -1,2 +1,2 @@ [MASTER] -init-hook='import sys; sys.path += ["scripts/lib/kdoc", "scripts/lib/abi"]' +init-hook='import sys; sys.path += ["scripts/lib/kdoc", "scripts/lib/abi", "tools/docs/lib"]' diff --git a/tools/docs/lib/__init__.py b/tools/docs/lib/__init__.py new file mode 100644 index 000000000000..e69de29bb2d1 diff --git a/tools/docs/lib/enrich_formatter.py b/tools/docs/lib/enrich_formatter.py new file mode 100644 index 000000000000..bb171567a4ca --- /dev/null +++ b/tools/docs/lib/enrich_formatter.py @@ -0,0 +1,70 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: GPL-2.0 +# Copyright (c) 2025 by Mauro Carvalho Chehab . + +""" +Ancillary argparse HelpFormatter class that works on a similar way as +argparse.RawDescriptionHelpFormatter, e.g. description maintains line +breaks, but it also implement transformations to the help text. The +actual transformations ar given by enrich_text(), if the output is tty. + +Currently, the follow transformations are done: + + - Positional arguments are shown in upper cases; + - if output is TTY, ``var`` and positional arguments are shown prepended + by an ANSI SGR code. This is usually translated to bold. On some + terminals, like, konsole, this is translated into a colored bold text. +""" + +import argparse +import re +import sys + +class EnrichFormatter(argparse.HelpFormatter): + """ + Better format the output, making easier to identify the positional args + and how they're used at the __doc__ description. + """ + def __init__(self, *args, **kwargs): + """Initialize class and check if is TTY""" + super().__init__(*args, **kwargs) + self._tty = sys.stdout.isatty() + + def enrich_text(self, text): + """Handle ReST markups (currently, only ``foo``)""" + if self._tty and text: + # Replace ``text`` with ANSI SGR (bold) + return re.sub(r'\`\`(.+?)\`\`', + lambda m: f'\033[1m{m.group(1)}\033[0m', text) + return text + + def _fill_text(self, text, width, indent): + """Enrich descriptions with markups on it""" + enriched = self.enrich_text(text) + return "\n".join(indent + line for line in enriched.splitlines()) + + def _format_usage(self, usage, actions, groups, prefix): + """Enrich positional arguments at usage: line""" + + prog = self._prog + parts = [] + + for action in actions: + if action.option_strings: + opt = action.option_strings[0] + if action.nargs != 0: + opt += f" {action.dest.upper()}" + parts.append(f"[{opt}]") + else: + # Positional argument + parts.append(self.enrich_text(f"``{action.dest.upper()}``")) + + usage_text = f"{prefix or 'usage: '} {prog} {' '.join(parts)}\n" + return usage_text + + def _format_action_invocation(self, action): + """Enrich argument names""" + if not action.option_strings: + return self.enrich_text(f"``{action.dest.upper()}``") + + return ", ".join(action.option_strings) diff --git a/Documentation/sphinx/parse-headers.py b/tools/docs/lib/parse_data_structs.py similarity index 80% rename from Documentation/sphinx/parse-headers.py rename to tools/docs/lib/parse_data_structs.py index 344090ef259c..2b7fa6bd8321 100755 --- a/Documentation/sphinx/parse-headers.py +++ b/tools/docs/lib/parse_data_structs.py @@ -1,36 +1,32 @@ #!/usr/bin/env python3 # SPDX-License-Identifier: GPL-2.0 -# Copyright (c) 2016 by Mauro Carvalho Chehab . -# pylint: disable=C0103,R0902,R0912,R0914,R0915 +# Copyright (c) 2016-2025 by Mauro Carvalho Chehab . +# pylint: disable=R0912,R0915 """ -Convert 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 describes what elements will be either ignored or -be pointed to a non-default reference type/name. +Parse a source file or header, creating ReStructured Text cross references. -The output is written at ``FILE_OUT``. +It accepts an optional file to change the default symbol reference or to +suppress symbols from the output. It is capable of identifying defines, functions, structs, typedefs, enums and enum symbols and create cross-references for all of them. It is also capable of distinguish #define used for specifying a Linux ioctl. -The optional ``FILE_RULES`` contains a set of rules like: +The optional rules file 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` """ -import argparse import os import re import sys -class ParseHeader: +class ParseDataStructs: """ Creates an enriched version of a Kernel header file with cross-links to each C data structure type. @@ -400,80 +396,3 @@ class ParseHeader: f.write("=" * len(title)) f.write("\n\n.. parsed-literal::\n\n") f.write(text) - -class EnrichFormatter(argparse.HelpFormatter): - """ - Better format the output, making easier to identify the positional args - and how they're used at the __doc__ description. - """ - def __init__(self, *args, **kwargs): - """Initialize class and check if is TTY""" - super().__init__(*args, **kwargs) - self._tty = sys.stdout.isatty() - - def enrich_text(self, text): - """Handle ReST markups (currently, only ``foo``)""" - if self._tty and text: - # Replace ``text`` with ANSI bold - return re.sub(r'\`\`(.+?)\`\`', - lambda m: f'\033[1m{m.group(1)}\033[0m', text) - return text - - def _fill_text(self, text, width, indent): - """Enrich descriptions with markups on it""" - enriched = self.enrich_text(text) - return "\n".join(indent + line for line in enriched.splitlines()) - - def _format_usage(self, usage, actions, groups, prefix): - """Enrich positional arguments at usage: line""" - - prog = self._prog - parts = [] - - for action in actions: - if action.option_strings: - opt = action.option_strings[0] - if action.nargs != 0: - opt += f" {action.dest.upper()}" - parts.append(f"[{opt}]") - else: - # Positional argument - parts.append(self.enrich_text(f"``{action.dest.upper()}``")) - - usage_text = f"{prefix or 'usage: '} {prog} {' '.join(parts)}\n" - return usage_text - - def _format_action_invocation(self, action): - """Enrich argument names""" - if not action.option_strings: - return self.enrich_text(f"``{action.dest.upper()}``") - else: - return ", ".join(action.option_strings) - - -def main(): - """Main function""" - parser = argparse.ArgumentParser(description=__doc__, - formatter_class=EnrichFormatter) - - parser.add_argument("-d", "--debug", action="count", default=0, - help="Increase debug level. Can be used multiple times") - parser.add_argument("file_in", help="Input C file") - parser.add_argument("file_out", help="Output RST file") - parser.add_argument("file_rules", nargs="?", - help="Exceptions file (optional)") - - args = parser.parse_args() - - parser = ParseHeader(debug=args.debug) - parser.parse_file(args.file_in) - - if args.file_rules: - parser.process_exceptions(args.file_rules) - - parser.debug_print() - parser.write_output(args.file_in, args.file_out) - - -if __name__ == "__main__": - main() diff --git a/tools/docs/parse-headers.py b/tools/docs/parse-headers.py new file mode 100755 index 000000000000..07d3b47c4834 --- /dev/null +++ b/tools/docs/parse-headers.py @@ -0,0 +1,57 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: GPL-2.0 +# Copyright (c) 2016, 2025 by Mauro Carvalho Chehab . +# pylint: disable=C0103 + +""" +Convert 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 describes 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 defines, functions, structs, typedefs, +enums and enum symbols and create cross-references for all of them. +It is also capable of distinguish #define used for specifying a Linux +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` +""" + +import argparse + +from lib.parse_data_structs import ParseDataStructs +from lib.enrich_formatter import EnrichFormatter + +def main(): + """Main function""" + parser = argparse.ArgumentParser(description=__doc__, + formatter_class=EnrichFormatter) + + parser.add_argument("-d", "--debug", action="count", default=0, + help="Increase debug level. Can be used multiple times") + parser.add_argument("file_in", help="Input C file") + parser.add_argument("file_out", help="Output RST file") + parser.add_argument("file_rules", nargs="?", + help="Exceptions file (optional)") + + args = parser.parse_args() + + parser = ParseDataStructs(debug=args.debug) + parser.parse_file(args.file_in) + + if args.file_rules: + parser.process_exceptions(args.file_rules) + + parser.debug_print() + parser.write_output(args.file_in, args.file_out) + + +if __name__ == "__main__": + main() From 242cfe3f774e8a41d0b27d4664247f58d0a8d039 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 22 Aug 2025 16:19:19 +0200 Subject: [PATCH 117/193] tools: docs: parse_data_structs.py: add methods to return output When running it from command line, we want to write an output file, but when used as a class, one may just want the output content returned as a string. Split write_output() on two methods to allow both usecases. Also add an extra method to produce a TOC. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/c98bdec3380aad54178baf2751a2f1fcd128576b.1755872208.git.mchehab+huawei@kernel.org --- tools/docs/lib/parse_data_structs.py | 62 ++++++++++++++++++++++++++-- tools/docs/parse-headers.py | 5 ++- 2 files changed, 62 insertions(+), 5 deletions(-) diff --git a/tools/docs/lib/parse_data_structs.py b/tools/docs/lib/parse_data_structs.py index 2b7fa6bd8321..a5aa2e182052 100755 --- a/tools/docs/lib/parse_data_structs.py +++ b/tools/docs/lib/parse_data_structs.py @@ -97,33 +97,39 @@ class ParseDataStructs: "prefix": "\\ ", "suffix": "\\ ", "ref_type": ":ref", + "description": "IOCTL Commands", }, "define": { "prefix": "\\ ", "suffix": "\\ ", "ref_type": ":ref", + "description": "Macros and Definitions", }, # We're calling each definition inside an enum as "symbol" "symbol": { "prefix": "\\ ", "suffix": "\\ ", "ref_type": ":ref", + "description": "Enumeration values", }, "typedef": { "prefix": "\\ ", "suffix": "\\ ", "ref_type": ":c:type", + "description": "Type Definitions", }, - # This is the name of the enum itself + # This is the description of the enum itself "enum": { "prefix": "\\ ", "suffix": "\\ ", "ref_type": ":c:type", + "description": "Enumerations", }, "struct": { "prefix": "\\ ", "suffix": "\\ ", "ref_type": ":c:type", + "description": "Structures", }, } @@ -359,7 +365,7 @@ class ParseDataStructs: print() - def write_output(self, file_in: str, file_out: str): + def gen_output(self): """Write the formatted output to a file.""" # Avoid extra blank lines @@ -387,12 +393,60 @@ class ParseDataStructs: text = re.sub(r"\\ ([\n ])", r"\1", text) text = re.sub(r" \\ ", " ", text) + return text + def gen_toc(self): + """ + Create a TOC table pointing to each symbol from the header + """ + text = [] + + # Add header + text.append(".. contents:: Table of Contents") + text.append(" :depth: 2") + text.append(" :local:") + text.append("") + + # Sort symbol types per description + symbol_descriptions = [] + for k, v in self.DEF_SYMBOL_TYPES.items(): + symbol_descriptions.append((v['description'], k)) + + symbol_descriptions.sort() + + # Process each category + for description, c_type in symbol_descriptions: + + refs = self.symbols[c_type] + if not refs: # Skip empty categories + continue + + text.append(f"{description}") + text.append("-" * len(description)) + text.append("") + + # Sort symbols alphabetically + for symbol, ref in sorted(refs.items()): + text.append(f"* :{ref}:") + + text.append("") # Add empty line between categories + + return "\n".join(text) + + def write_output(self, file_in: str, file_out: str, toc: bool): title = os.path.basename(file_in) + if toc: + text = self.gen_toc() + else: + text = self.gen_output() + with open(file_out, "w", encoding="utf-8", errors="backslashreplace") as f: f.write(".. -*- coding: utf-8; mode: rst -*-\n\n") f.write(f"{title}\n") - f.write("=" * len(title)) - f.write("\n\n.. parsed-literal::\n\n") + f.write("=" * len(title) + "\n\n") + + if not toc: + f.write(".. parsed-literal::\n\n") + f.write(text) diff --git a/tools/docs/parse-headers.py b/tools/docs/parse-headers.py index 07d3b47c4834..bfa4e46a53e3 100755 --- a/tools/docs/parse-headers.py +++ b/tools/docs/parse-headers.py @@ -36,6 +36,9 @@ def main(): parser.add_argument("-d", "--debug", action="count", default=0, help="Increase debug level. Can be used multiple times") + parser.add_argument("-t", "--toc", action="store_true", + help="instead of a literal block, outputs a TOC table at the RST file") + parser.add_argument("file_in", help="Input C file") parser.add_argument("file_out", help="Output RST file") parser.add_argument("file_rules", nargs="?", @@ -50,7 +53,7 @@ def main(): parser.process_exceptions(args.file_rules) parser.debug_print() - parser.write_output(args.file_in, args.file_out) + parser.write_output(args.file_in, args.file_out, args.toc) if __name__ == "__main__": From 99198814e5b307d2748f82d12c1c91129f0aead5 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 22 Aug 2025 16:19:20 +0200 Subject: [PATCH 118/193] MAINTAINERS: add files from tools/docs to documentation entry As we now have a tools directory for docs, add it to its corresponding entry. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/87bbb94e442fe747e24f801d7685856b392b2568.1755872208.git.mchehab+huawei@kernel.org --- MAINTAINERS | 1 + 1 file changed, 1 insertion(+) diff --git a/MAINTAINERS b/MAINTAINERS index dafc11712544..ef87548b8f88 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -7308,6 +7308,7 @@ F: scripts/get_abi.py F: scripts/kernel-doc* F: scripts/lib/abi/* F: scripts/lib/kdoc/* +F: tools/docs/* F: tools/net/ynl/pyynl/lib/doc_generator.py F: scripts/sphinx-pre-install X: Documentation/ABI/ From 319d2a7ebe8ecf3377099a84d49f9b0043242c23 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 22 Aug 2025 16:19:21 +0200 Subject: [PATCH 119/193] docs: uapi: media: Makefile: use parse-headers.py Now that we have a new parser, use it. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/7025759744f74058eee55c35e8cd8cb5a2953fca.1755872208.git.mchehab+huawei@kernel.org --- Documentation/userspace-api/media/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/userspace-api/media/Makefile b/Documentation/userspace-api/media/Makefile index 3d8aaf5c253b..accc734d045a 100644 --- a/Documentation/userspace-api/media/Makefile +++ b/Documentation/userspace-api/media/Makefile @@ -3,7 +3,7 @@ # Rules to convert a .h file to inline RST documentation SRC_DIR=$(srctree)/Documentation/userspace-api/media -PARSER = $(srctree)/Documentation/sphinx/parse-headers.pl +PARSER = $(srctree)/tools/docs/parse-headers.py UAPI = $(srctree)/include/uapi/linux KAPI = $(srctree)/include/linux From bb979965008793635a630ecdc7a3869c2fccd283 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 22 Aug 2025 16:19:22 +0200 Subject: [PATCH 120/193] docs: kernel_include.py: Update its coding style With the help of tools like black, pylint, autopep8 and flake, improve the code style in preparation for further changes. No functional changes. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/f64c3af47fdfd632bb5f8eb88e3c7d94b0b84a66.1755872208.git.mchehab+huawei@kernel.org --- Documentation/sphinx/kernel_include.py | 100 ++++++++++++------------- 1 file changed, 47 insertions(+), 53 deletions(-) diff --git a/Documentation/sphinx/kernel_include.py b/Documentation/sphinx/kernel_include.py index 1e566e87ebcd..1212786ac516 100755 --- a/Documentation/sphinx/kernel_include.py +++ b/Documentation/sphinx/kernel_include.py @@ -1,7 +1,6 @@ #!/usr/bin/env python3 -# -*- coding: utf-8; mode: python -*- # SPDX-License-Identifier: GPL-2.0 -# pylint: disable=R0903, C0330, R0914, R0912, E0401 +# pylint: disable=R0903, R0912, R0914, R0915, C0209,W0707 """ kernel-include @@ -40,41 +39,38 @@ from docutils.parsers.rst import directives from docutils.parsers.rst.directives.body import CodeBlock, NumberLines from docutils.parsers.rst.directives.misc import Include -__version__ = '1.0' +__version__ = "1.0" + # ============================================================================== def setup(app): -# ============================================================================== - + """Setup Sphinx exension""" app.add_directive("kernel-include", KernelInclude) - return dict( - version = __version__, - parallel_read_safe = True, - parallel_write_safe = True - ) + return { + "version": __version__, + "parallel_read_safe": True, + "parallel_write_safe": True, + } + # ============================================================================== class KernelInclude(Include): -# ============================================================================== - """KernelInclude (``kernel-include``) directive""" def run(self): env = self.state.document.settings.env - path = os.path.realpath( - os.path.expandvars(self.arguments[0])) + path = os.path.realpath(os.path.expandvars(self.arguments[0])) # to get a bit security back, prohibit /etc: if path.startswith(os.sep + "etc"): - raise self.severe( - 'Problems with "%s" directive, prohibited path: %s' - % (self.name, path)) + raise self.severe('Problems with "%s" directive, prohibited path: %s' % + (self.name, path)) self.arguments[0] = path env.note_dependency(os.path.abspath(path)) - #return super(KernelInclude, self).run() # won't work, see HINTs in _run() + # return super(KernelInclude, self).run() # won't work, see HINTs in _run() return self._run() def _run(self): @@ -87,41 +83,39 @@ class KernelInclude(Include): if not self.state.document.settings.file_insertion_enabled: raise self.warning('"%s" directive disabled.' % self.name) - source = self.state_machine.input_lines.source( - self.lineno - self.state_machine.input_offset - 1) + source = self.state_machine.input_lines.source(self.lineno - + self.state_machine.input_offset - 1) source_dir = os.path.dirname(os.path.abspath(source)) path = directives.path(self.arguments[0]) - if path.startswith('<') and path.endswith('>'): + if path.startswith("<") and path.endswith(">"): path = os.path.join(self.standard_include_path, path[1:-1]) path = os.path.normpath(os.path.join(source_dir, path)) # HINT: this is the only line I had to change / commented out: - #path = utils.relative_path(None, path) + # path = utils.relative_path(None, path) - encoding = self.options.get( - 'encoding', self.state.document.settings.input_encoding) - e_handler=self.state.document.settings.input_encoding_error_handler - tab_width = self.options.get( - 'tab-width', self.state.document.settings.tab_width) + encoding = self.options.get("encoding", + self.state.document.settings.input_encoding) + e_handler = self.state.document.settings.input_encoding_error_handler + tab_width = self.options.get("tab-width", + self.state.document.settings.tab_width) try: self.state.document.settings.record_dependencies.add(path) - include_file = io.FileInput(source_path=path, - encoding=encoding, + include_file = io.FileInput(source_path=path, encoding=encoding, error_handler=e_handler) - except UnicodeEncodeError as error: + except UnicodeEncodeError: raise self.severe('Problems with "%s" directive path:\n' 'Cannot encode input file path "%s" ' - '(wrong locale?).' % - (self.name, SafeString(path))) + "(wrong locale?)." % (self.name, SafeString(path))) except IOError as error: - raise self.severe('Problems with "%s" directive path:\n%s.' % - (self.name, ErrorString(error))) - startline = self.options.get('start-line', None) - endline = self.options.get('end-line', None) + raise self.severe('Problems with "%s" directive path:\n%s.' + % (self.name, ErrorString(error))) + startline = self.options.get("start-line", None) + endline = self.options.get("end-line", None) try: if startline or (endline is not None): lines = include_file.readlines() - rawtext = ''.join(lines[startline:endline]) + rawtext = "".join(lines[startline:endline]) else: rawtext = include_file.read() except UnicodeError as error: @@ -129,43 +123,43 @@ class KernelInclude(Include): (self.name, ErrorString(error))) # start-after/end-before: no restrictions on newlines in match-text, # and no restrictions on matching inside lines vs. line boundaries - after_text = self.options.get('start-after', None) + after_text = self.options.get("start-after", None) if after_text: # skip content in rawtext before *and incl.* a matching text after_index = rawtext.find(after_text) if after_index < 0: raise self.severe('Problem with "start-after" option of "%s" ' - 'directive:\nText not found.' % self.name) - rawtext = rawtext[after_index + len(after_text):] - before_text = self.options.get('end-before', None) + "directive:\nText not found." % self.name) + rawtext = rawtext[after_index + len(after_text) :] + before_text = self.options.get("end-before", None) if before_text: # skip content in rawtext after *and incl.* a matching text before_index = rawtext.find(before_text) if before_index < 0: raise self.severe('Problem with "end-before" option of "%s" ' - 'directive:\nText not found.' % self.name) + "directive:\nText not found." % self.name) rawtext = rawtext[:before_index] include_lines = statemachine.string2lines(rawtext, tab_width, convert_whitespace=True) - if 'literal' in self.options: + if "literal" in self.options: # Convert tabs to spaces, if `tab_width` is positive. if tab_width >= 0: text = rawtext.expandtabs(tab_width) else: text = rawtext literal_block = nodes.literal_block(rawtext, source=path, - classes=self.options.get('class', [])) + classes=self.options.get("class", []) + ) literal_block.line = 1 self.add_name(literal_block) - if 'number-lines' in self.options: + if "number-lines" in self.options: try: - startline = int(self.options['number-lines'] or 1) + startline = int(self.options["number-lines"] or 1) except ValueError: - raise self.error(':number-lines: with non-integer ' - 'start value') + raise self.error(":number-lines: with non-integer start value") endline = startline + len(include_lines) - if text.endswith('\n'): + if text.endswith("\n"): text = text[:-1] tokens = NumberLines([([], text)], startline, endline) for classes, value in tokens: @@ -177,12 +171,12 @@ class KernelInclude(Include): else: literal_block += nodes.Text(text, text) return [literal_block] - if 'code' in self.options: - self.options['source'] = path + if "code" in self.options: + self.options["source"] = path codeblock = CodeBlock(self.name, - [self.options.pop('code')], # arguments + [self.options.pop("code")], # arguments self.options, - include_lines, # content + include_lines, # content self.lineno, self.content_offset, self.block_text, From 0cb6aee3584604ceecdbc3bcc00d017f9a827873 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 22 Aug 2025 16:19:23 +0200 Subject: [PATCH 121/193] docs: kernel_include.py: allow cross-reference generation kernel_include extension was originally designed to be used by the media comprehensive uAPI documentation, where, instead of simpler kernel-doc markups, the uAPI documentation is enriched with a larger text, with images, complex tables, graphs, etc. There, we wanted to include the much simpler yet documented .h file. This extension is needed to include files from other parts of the Kernel tree outside Documentation, because the original Sphinx include tag doesn't allow going outside of the directory passed via sphinx-build command line. Yet, the cross-references themselves to the full documentation were using a perl script to create cross-references against the comprehensive documentation. As the perl script is now converted to Phython and there is a Python class producing an include-compatible output with cross references, add two optional arguments to kernel_include.py: 1. :generate-cross-refs: If present, instead of reading the file, it calls ParseDataStructs() class, which converts C data structures into cross-references to be linked to ReST files containing a more comprehensive documentation; Don't use it together with :start-line: and/or :end-line:, as filtering input file line range is currently not supported. 2. :exception-file: Used together with :generate-cross-refs:. Points to a file containing rules to ignore C data structs or to use a different reference name, optionally using a different reference type. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/efc39c8e54a2056ae2fdb94d5006fcb19e227198.1755872208.git.mchehab+huawei@kernel.org --- Documentation/sphinx/kernel_include.py | 94 ++++++++++++++++++++------ 1 file changed, 74 insertions(+), 20 deletions(-) diff --git a/Documentation/sphinx/kernel_include.py b/Documentation/sphinx/kernel_include.py index 1212786ac516..fc37e6fa9d96 100755 --- a/Documentation/sphinx/kernel_include.py +++ b/Documentation/sphinx/kernel_include.py @@ -25,6 +25,24 @@ Substrings of the form $name or ${name} are replaced by the value of environment variable name. Malformed variable names and references to non-existing variables are left unchanged. + + This extension overrides Sphinx include directory, adding two extra + arguments: + + 1. :generate-cross-refs: + + If present, instead of reading the file, it calls ParseDataStructs() + class, which converts C data structures into cross-references to + be linked to ReST files containing a more comprehensive documentation; + + Don't use it together with :start-line: and/or :end-line:, as + filtering input file line range is currently not supported. + + 2. :exception-file: + + Used together with :generate-cross-refs:. Points to a file containing + rules to ignore C data structs or to use a different reference name, + optionally using a different reference type. """ # ============================================================================== @@ -32,6 +50,7 @@ # ============================================================================== import os.path +import sys from docutils import io, nodes, statemachine from docutils.utils.error_reporting import SafeString, ErrorString @@ -39,6 +58,11 @@ from docutils.parsers.rst import directives from docutils.parsers.rst.directives.body import CodeBlock, NumberLines from docutils.parsers.rst.directives.misc import Include +srctree = os.path.abspath(os.environ["srctree"]) +sys.path.insert(0, os.path.join(srctree, "tools/docs/lib")) + +from parse_data_structs import ParseDataStructs + __version__ = "1.0" @@ -57,6 +81,14 @@ def setup(app): class KernelInclude(Include): """KernelInclude (``kernel-include``) directive""" + # Add extra options + option_spec = Include.option_spec.copy() + + option_spec.update({ + 'generate-cross-refs': directives.flag, + 'exception-file': directives.unchanged, + }) + def run(self): env = self.state.document.settings.env path = os.path.realpath(os.path.expandvars(self.arguments[0])) @@ -99,28 +131,49 @@ class KernelInclude(Include): e_handler = self.state.document.settings.input_encoding_error_handler tab_width = self.options.get("tab-width", self.state.document.settings.tab_width) - try: - self.state.document.settings.record_dependencies.add(path) - include_file = io.FileInput(source_path=path, encoding=encoding, - error_handler=e_handler) - except UnicodeEncodeError: - raise self.severe('Problems with "%s" directive path:\n' - 'Cannot encode input file path "%s" ' - "(wrong locale?)." % (self.name, SafeString(path))) - except IOError as error: - raise self.severe('Problems with "%s" directive path:\n%s.' - % (self.name, ErrorString(error))) startline = self.options.get("start-line", None) endline = self.options.get("end-line", None) - try: - if startline or (endline is not None): - lines = include_file.readlines() - rawtext = "".join(lines[startline:endline]) - else: - rawtext = include_file.read() - except UnicodeError as error: - raise self.severe('Problem with "%s" directive:\n%s' % - (self.name, ErrorString(error))) + + # Get optional arguments to related to cross-references generation + if 'generate-cross-refs' in self.options: + parser = ParseDataStructs() + parser.parse_file(path) + + exceptions_file = self.options.get('exception-file') + if exceptions_file: + exceptions_file = os.path.join(source_dir, exceptions_file) + parser.process_exceptions(exceptions_file) + + title = os.path.basename(path) + rawtext = parser.gen_output() + if startline or endline: + raise self.severe('generate-cross-refs can\'t be used together with "start-line" or "end-line"') + + if "code" not in self.options: + rawtext = ".. parsed-literal::\n\n" + rawtext + else: + try: + self.state.document.settings.record_dependencies.add(path) + include_file = io.FileInput(source_path=path, encoding=encoding, + error_handler=e_handler) + except UnicodeEncodeError: + raise self.severe('Problems with "%s" directive path:\n' + 'Cannot encode input file path "%s" ' + "(wrong locale?)." % (self.name, SafeString(path))) + except IOError as error: + raise self.severe('Problems with "%s" directive path:\n%s.' + % (self.name, ErrorString(error))) + + try: + if startline or (endline is not None): + lines = include_file.readlines() + rawtext = "".join(lines[startline:endline]) + else: + rawtext = include_file.read() + except UnicodeError as error: + raise self.severe('Problem with "%s" directive:\n%s' % + (self.name, ErrorString(error))) + # start-after/end-before: no restrictions on newlines in match-text, # and no restrictions on matching inside lines vs. line boundaries after_text = self.options.get("start-after", None) @@ -171,6 +224,7 @@ class KernelInclude(Include): else: literal_block += nodes.Text(text, text) return [literal_block] + if "code" in self.options: self.options["source"] = path codeblock = CodeBlock(self.name, From 39f5f2fa8c959eb897416e928d12f6aec1e7d5e4 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 22 Aug 2025 16:19:24 +0200 Subject: [PATCH 122/193] docs: kernel_include.py: generate warnings for broken refs In the past, Sphinx used to warn about broken references. That's basically the rationale for adding media uAPI files: to get warnings about missed symbols. This is not true anymore. So, we need to explicitly check them after doctree-resolved event. While here, move setup() to the end, to make it closer to what we do on other extensions. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/73be9a198746421687e2eee916ccf8bf67980b7d.1755872208.git.mchehab+huawei@kernel.org --- Documentation/sphinx/kernel_include.py | 108 ++++++++++++++++++++----- 1 file changed, 89 insertions(+), 19 deletions(-) diff --git a/Documentation/sphinx/kernel_include.py b/Documentation/sphinx/kernel_include.py index fc37e6fa9d96..0a3e5377dd1e 100755 --- a/Documentation/sphinx/kernel_include.py +++ b/Documentation/sphinx/kernel_include.py @@ -26,7 +26,7 @@ environment variable name. Malformed variable names and references to non-existing variables are left unchanged. - This extension overrides Sphinx include directory, adding two extra + This extension overrides Sphinx include directory, adding some extra arguments: 1. :generate-cross-refs: @@ -35,14 +35,20 @@ class, which converts C data structures into cross-references to be linked to ReST files containing a more comprehensive documentation; - Don't use it together with :start-line: and/or :end-line:, as - filtering input file line range is currently not supported. - 2. :exception-file: - Used together with :generate-cross-refs:. Points to a file containing - rules to ignore C data structs or to use a different reference name, - optionally using a different reference type. + Used together with :generate-cross-refs + + Points to a file containing rules to ignore C data structs or to + use a different reference name, optionally using a different + reference type. + + 3. :warn-broken: + + Used together with :generate-cross-refs: + + Detect if the auto-generated cross references doesn't exist. + """ # ============================================================================== @@ -50,6 +56,7 @@ # ============================================================================== import os.path +import re import sys from docutils import io, nodes, statemachine @@ -58,23 +65,18 @@ from docutils.parsers.rst import directives from docutils.parsers.rst.directives.body import CodeBlock, NumberLines from docutils.parsers.rst.directives.misc import Include +from sphinx.util import logging + srctree = os.path.abspath(os.environ["srctree"]) sys.path.insert(0, os.path.join(srctree, "tools/docs/lib")) from parse_data_structs import ParseDataStructs __version__ = "1.0" +logger = logging.getLogger(__name__) - -# ============================================================================== -def setup(app): - """Setup Sphinx exension""" - app.add_directive("kernel-include", KernelInclude) - return { - "version": __version__, - "parallel_read_safe": True, - "parallel_write_safe": True, - } +RE_DOMAIN_REF = re.compile(r'\\ :(ref|c:type|c:func):`([^<`]+)(?:<([^>]+)>)?`\\') +RE_SIMPLE_REF = re.compile(r'`([^`]+)`') # ============================================================================== @@ -86,6 +88,7 @@ class KernelInclude(Include): option_spec.update({ 'generate-cross-refs': directives.flag, + 'warn-broken': directives.flag, 'exception-file': directives.unchanged, }) @@ -103,9 +106,9 @@ class KernelInclude(Include): env.note_dependency(os.path.abspath(path)) # return super(KernelInclude, self).run() # won't work, see HINTs in _run() - return self._run() + return self._run(env) - def _run(self): + def _run(self, env): """Include a file as part of the content of this reST file.""" # HINT: I had to copy&paste the whole Include.run method. I'am not happy @@ -151,6 +154,10 @@ class KernelInclude(Include): if "code" not in self.options: rawtext = ".. parsed-literal::\n\n" + rawtext + + # Store references on a symbol dict to be used at check time + if 'warn-broken' in self.options: + env._xref_files.add(path) else: try: self.state.document.settings.record_dependencies.add(path) @@ -239,3 +246,66 @@ class KernelInclude(Include): return codeblock.run() self.state_machine.insert_input(include_lines, path) return [] + +# ============================================================================== + +reported = set() + +def check_missing_refs(app, env, node, contnode): + """Check broken refs for the files it creates xrefs""" + if not node.source: + return None + + try: + xref_files = env._xref_files + except AttributeError: + logger.critical("FATAL: _xref_files not initialized!") + raise + + # Only show missing references for kernel-include reference-parsed files + if node.source not in xref_files: + return None + + target = node.get('reftarget', '') + domain = node.get('refdomain', 'std') + reftype = node.get('reftype', '') + + msg = f"can't link to: {domain}:{reftype}:: {target}" + + # Don't duplicate warnings + data = (node.source, msg) + if data in reported: + return None + reported.add(data) + + logger.warning(msg, location=node, type='ref', subtype='missing') + + return None + +def merge_xref_info(app, env, docnames, other): + """ + As each process modify env._xref_files, we need to merge them back. + """ + if not hasattr(other, "_xref_files"): + return + env._xref_files.update(getattr(other, "_xref_files", set())) + +def init_xref_docs(app, env, docnames): + """Initialize a list of files that we're generating cross references¨""" + app.env._xref_files = set() + +# ============================================================================== + +def setup(app): + """Setup Sphinx exension""" + + app.connect("env-before-read-docs", init_xref_docs) + app.connect("env-merge-info", merge_xref_info) + app.add_directive("kernel-include", KernelInclude) + app.connect("missing-reference", check_missing_refs) + + return { + "version": __version__, + "parallel_read_safe": True, + "parallel_write_safe": True, + } From 012e00dda347e72a6079c6d21f0c8f97333cc477 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 22 Aug 2025 16:19:25 +0200 Subject: [PATCH 123/193] docs: kernel_include.py: move rawtext logic to separate functions The run function is too complex. merge run() and _run() into a single function and move the read logic to separate functions. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/04776a94c85b6c931c198a149f08b299c9f571a3.1755872208.git.mchehab+huawei@kernel.org --- Documentation/sphinx/kernel_include.py | 82 ++++++++++++++------------ 1 file changed, 43 insertions(+), 39 deletions(-) diff --git a/Documentation/sphinx/kernel_include.py b/Documentation/sphinx/kernel_include.py index 0a3e5377dd1e..ef86ee9e79d6 100755 --- a/Documentation/sphinx/kernel_include.py +++ b/Documentation/sphinx/kernel_include.py @@ -92,7 +92,47 @@ class KernelInclude(Include): 'exception-file': directives.unchanged, }) + def read_rawtext(self, path, encoding): + """Read and process file content with error handling""" + try: + self.state.document.settings.record_dependencies.add(path) + include_file = io.FileInput(source_path=path, + encoding=encoding, + error_handler=self.state.document.settings.input_encoding_error_handler) + except UnicodeEncodeError: + raise self.severe('Problems with directive path:\n' + 'Cannot encode input file path "%s" ' + '(wrong locale?).' % SafeString(path)) + except IOError as error: + raise self.severe('Problems with directive path:\n%s.' % ErrorString(error)) + + try: + return include_file.read() + except UnicodeError as error: + raise self.severe('Problem with directive:\n%s' % ErrorString(error)) + + def read_rawtext_with_xrefs(self, env, path): + parser = ParseDataStructs() + parser.parse_file(path) + + if 'exception-file' in self.options: + source_dir = os.path.dirname(os.path.abspath( + self.state_machine.input_lines.source( + self.lineno - self.state_machine.input_offset - 1))) + exceptions_file = os.path.join(source_dir, self.options['exception-file']) + parser.process_exceptions(exceptions_file) + + if self.options.get("start-line") or self.options.get("end-line"): + raise self.severe('generate-cross-refs can\'t be used with "start-line" or "end-line"') + + # Store references on a symbol dict to be used at check time + if 'warn-broken' in self.options: + env._xref_files.add(path) + + return parser.gen_output() + def run(self): + """Include a file as part of the content of this reST file.""" env = self.state.document.settings.env path = os.path.realpath(os.path.expandvars(self.arguments[0])) @@ -105,12 +145,6 @@ class KernelInclude(Include): env.note_dependency(os.path.abspath(path)) - # return super(KernelInclude, self).run() # won't work, see HINTs in _run() - return self._run(env) - - def _run(self, env): - """Include a file as part of the content of this reST file.""" - # HINT: I had to copy&paste the whole Include.run method. I'am not happy # with this, but due to security reasons, the Include.run method does # not allow absolute or relative pathnames pointing to locations *above* @@ -139,47 +173,17 @@ class KernelInclude(Include): # Get optional arguments to related to cross-references generation if 'generate-cross-refs' in self.options: - parser = ParseDataStructs() - parser.parse_file(path) - - exceptions_file = self.options.get('exception-file') - if exceptions_file: - exceptions_file = os.path.join(source_dir, exceptions_file) - parser.process_exceptions(exceptions_file) + rawtext = self.read_rawtext_with_xrefs(env, path) title = os.path.basename(path) - rawtext = parser.gen_output() + if startline or endline: raise self.severe('generate-cross-refs can\'t be used together with "start-line" or "end-line"') if "code" not in self.options: rawtext = ".. parsed-literal::\n\n" + rawtext - - # Store references on a symbol dict to be used at check time - if 'warn-broken' in self.options: - env._xref_files.add(path) else: - try: - self.state.document.settings.record_dependencies.add(path) - include_file = io.FileInput(source_path=path, encoding=encoding, - error_handler=e_handler) - except UnicodeEncodeError: - raise self.severe('Problems with "%s" directive path:\n' - 'Cannot encode input file path "%s" ' - "(wrong locale?)." % (self.name, SafeString(path))) - except IOError as error: - raise self.severe('Problems with "%s" directive path:\n%s.' - % (self.name, ErrorString(error))) - - try: - if startline or (endline is not None): - lines = include_file.readlines() - rawtext = "".join(lines[startline:endline]) - else: - rawtext = include_file.read() - except UnicodeError as error: - raise self.severe('Problem with "%s" directive:\n%s' % - (self.name, ErrorString(error))) + rawtext = self.read_rawtext(path, encoding) # start-after/end-before: no restrictions on newlines in match-text, # and no restrictions on matching inside lines vs. line boundaries From 3f7f3d494119170dc6636228e8425048effa2931 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 22 Aug 2025 16:19:26 +0200 Subject: [PATCH 124/193] docs: kernel_include.py: move range logic to a separate function Cleanup run() function by moving the range logic to a separate function. Here, I ended checking the current Sphinx implementation, as it has some extra logic for the range check. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/12fa2204a9e7e309ae4b8694a37ebad9327ca634.1755872208.git.mchehab+huawei@kernel.org --- Documentation/sphinx/kernel_include.py | 51 +++++++++++++++++--------- 1 file changed, 33 insertions(+), 18 deletions(-) diff --git a/Documentation/sphinx/kernel_include.py b/Documentation/sphinx/kernel_include.py index ef86ee9e79d6..c5f4f34e22cb 100755 --- a/Documentation/sphinx/kernel_include.py +++ b/Documentation/sphinx/kernel_include.py @@ -131,6 +131,38 @@ class KernelInclude(Include): return parser.gen_output() + def apply_range(self, rawtext): + # Get to-be-included content + startline = self.options.get('start-line', None) + endline = self.options.get('end-line', None) + try: + if startline or (endline is not None): + lines = rawtext.splitlines() + rawtext = '\n'.join(lines[startline:endline]) + except UnicodeError as error: + raise self.severe(f'Problem with "{self.name}" directive:\n' + + io.error_string(error)) + # start-after/end-before: no restrictions on newlines in match-text, + # and no restrictions on matching inside lines vs. line boundaries + after_text = self.options.get("start-after", None) + if after_text: + # skip content in rawtext before *and incl.* a matching text + after_index = rawtext.find(after_text) + if after_index < 0: + raise self.severe('Problem with "start-after" option of "%s" ' + "directive:\nText not found." % self.name) + rawtext = rawtext[after_index + len(after_text) :] + before_text = self.options.get("end-before", None) + if before_text: + # skip content in rawtext after *and incl.* a matching text + before_index = rawtext.find(before_text) + if before_index < 0: + raise self.severe('Problem with "end-before" option of "%s" ' + "directive:\nText not found." % self.name) + rawtext = rawtext[:before_index] + + return rawtext + def run(self): """Include a file as part of the content of this reST file.""" env = self.state.document.settings.env @@ -185,24 +217,7 @@ class KernelInclude(Include): else: rawtext = self.read_rawtext(path, encoding) - # start-after/end-before: no restrictions on newlines in match-text, - # and no restrictions on matching inside lines vs. line boundaries - after_text = self.options.get("start-after", None) - if after_text: - # skip content in rawtext before *and incl.* a matching text - after_index = rawtext.find(after_text) - if after_index < 0: - raise self.severe('Problem with "start-after" option of "%s" ' - "directive:\nText not found." % self.name) - rawtext = rawtext[after_index + len(after_text) :] - before_text = self.options.get("end-before", None) - if before_text: - # skip content in rawtext after *and incl.* a matching text - before_index = rawtext.find(before_text) - if before_index < 0: - raise self.severe('Problem with "end-before" option of "%s" ' - "directive:\nText not found." % self.name) - rawtext = rawtext[:before_index] + rawtext = self.apply_range(rawtext) include_lines = statemachine.string2lines(rawtext, tab_width, convert_whitespace=True) From 67faed5d213d87f3b5bdfc78a12d1d9d3e7aac46 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 22 Aug 2025 16:19:27 +0200 Subject: [PATCH 125/193] docs: kernel_include.py: remove range restriction for gen docs Originally, parse-readers were generating an output where the first two lines were setting a literal block. The script now gets only the actual parsed data without that, so it is now safe to allow start-line and end-line parameters to be handled. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/5dff693860a6a3faade15c24abdc380f09db468d.1755872208.git.mchehab+huawei@kernel.org --- Documentation/sphinx/kernel_include.py | 6 ------ 1 file changed, 6 deletions(-) diff --git a/Documentation/sphinx/kernel_include.py b/Documentation/sphinx/kernel_include.py index c5f4f34e22cb..4cdd1c77982e 100755 --- a/Documentation/sphinx/kernel_include.py +++ b/Documentation/sphinx/kernel_include.py @@ -122,9 +122,6 @@ class KernelInclude(Include): exceptions_file = os.path.join(source_dir, self.options['exception-file']) parser.process_exceptions(exceptions_file) - if self.options.get("start-line") or self.options.get("end-line"): - raise self.severe('generate-cross-refs can\'t be used with "start-line" or "end-line"') - # Store references on a symbol dict to be used at check time if 'warn-broken' in self.options: env._xref_files.add(path) @@ -209,9 +206,6 @@ class KernelInclude(Include): title = os.path.basename(path) - if startline or endline: - raise self.severe('generate-cross-refs can\'t be used together with "start-line" or "end-line"') - if "code" not in self.options: rawtext = ".. parsed-literal::\n\n" + rawtext else: From 9be2a5c3c8b7aad78341677002c428c996cc9570 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 22 Aug 2025 16:19:28 +0200 Subject: [PATCH 126/193] docs: kernel_include.py: move code and literal functions Simplify run() even more by moving the code which handles with code and literal blocks to their own functions. No functional changes. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/78d08dfa3f08adabc30bf93b8a1cde4e19b7bd41.1755872208.git.mchehab+huawei@kernel.org --- Documentation/sphinx/kernel_include.py | 100 +++++++++++++++---------- 1 file changed, 59 insertions(+), 41 deletions(-) diff --git a/Documentation/sphinx/kernel_include.py b/Documentation/sphinx/kernel_include.py index 4cdd1c77982e..0909eb3a07ea 100755 --- a/Documentation/sphinx/kernel_include.py +++ b/Documentation/sphinx/kernel_include.py @@ -160,6 +160,52 @@ class KernelInclude(Include): return rawtext + def literal(self, path, tab_width, rawtext): + """Output a literal block""" + + # Convert tabs to spaces, if `tab_width` is positive. + if tab_width >= 0: + text = rawtext.expandtabs(tab_width) + else: + text = rawtext + literal_block = nodes.literal_block(rawtext, source=path, + classes=self.options.get("class", [])) + literal_block.line = 1 + self.add_name(literal_block) + if "number-lines" in self.options: + try: + startline = int(self.options["number-lines"] or 1) + except ValueError: + raise self.error(":number-lines: with non-integer start value") + endline = startline + len(include_lines) + if text.endswith("\n"): + text = text[:-1] + tokens = NumberLines([([], text)], startline, endline) + for classes, value in tokens: + if classes: + literal_block += nodes.inline(value, value, + classes=classes) + else: + literal_block += nodes.Text(value, value) + else: + literal_block += nodes.Text(text, text) + return [literal_block] + + def code(self, path, include_lines): + """Output a code block""" + + self.options["source"] = path + codeblock = CodeBlock(self.name, + [self.options.pop("code")], # arguments + self.options, + include_lines, + self.lineno, + self.content_offset, + self.block_text, + self.state, + self.state_machine) + return codeblock.run() + def run(self): """Include a file as part of the content of this reST file.""" env = self.state.document.settings.env @@ -200,6 +246,13 @@ class KernelInclude(Include): startline = self.options.get("start-line", None) endline = self.options.get("end-line", None) + if "literal" in self.options: + ouptut_type = "literal" + elif "code" in self.options: + ouptut_type = "code" + else: + ouptut_type = "normal" + # Get optional arguments to related to cross-references generation if 'generate-cross-refs' in self.options: rawtext = self.read_rawtext_with_xrefs(env, path) @@ -213,50 +266,15 @@ class KernelInclude(Include): rawtext = self.apply_range(rawtext) + if ouptut_type == "literal": + return self.literal(path, tab_width, rawtext) + include_lines = statemachine.string2lines(rawtext, tab_width, convert_whitespace=True) - if "literal" in self.options: - # Convert tabs to spaces, if `tab_width` is positive. - if tab_width >= 0: - text = rawtext.expandtabs(tab_width) - else: - text = rawtext - literal_block = nodes.literal_block(rawtext, source=path, - classes=self.options.get("class", []) - ) - literal_block.line = 1 - self.add_name(literal_block) - if "number-lines" in self.options: - try: - startline = int(self.options["number-lines"] or 1) - except ValueError: - raise self.error(":number-lines: with non-integer start value") - endline = startline + len(include_lines) - if text.endswith("\n"): - text = text[:-1] - tokens = NumberLines([([], text)], startline, endline) - for classes, value in tokens: - if classes: - literal_block += nodes.inline(value, value, - classes=classes) - else: - literal_block += nodes.Text(value, value) - else: - literal_block += nodes.Text(text, text) - return [literal_block] - if "code" in self.options: - self.options["source"] = path - codeblock = CodeBlock(self.name, - [self.options.pop("code")], # arguments - self.options, - include_lines, # content - self.lineno, - self.content_offset, - self.block_text, - self.state, - self.state_machine) - return codeblock.run() + if ouptut_type == "code": + return self.code(path, include_lines) + self.state_machine.insert_input(include_lines, path) return [] From e4d91787deffffa64abd397315d4f7e4a3cf02f3 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 22 Aug 2025 16:19:29 +0200 Subject: [PATCH 127/193] docs: kernel_include.py: add support to generate a TOC table When generate-cross-refs is used, instead of just implementing the default of generating a literal block, we can also generate a ReST file as a TOC. The advantage is that, by being a ReST file, missing references will point to the place inside the header file that has the broken link. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/c0d32cd1ef94017e05984b0a38bd2516f7db21e2.1755872208.git.mchehab+huawei@kernel.org --- Documentation/sphinx/kernel_include.py | 36 ++++++++++++++++---------- 1 file changed, 22 insertions(+), 14 deletions(-) diff --git a/Documentation/sphinx/kernel_include.py b/Documentation/sphinx/kernel_include.py index 0909eb3a07ea..79682408105e 100755 --- a/Documentation/sphinx/kernel_include.py +++ b/Documentation/sphinx/kernel_include.py @@ -89,6 +89,7 @@ class KernelInclude(Include): option_spec.update({ 'generate-cross-refs': directives.flag, 'warn-broken': directives.flag, + 'toc': directives.flag, 'exception-file': directives.unchanged, }) @@ -111,7 +112,7 @@ class KernelInclude(Include): except UnicodeError as error: raise self.severe('Problem with directive:\n%s' % ErrorString(error)) - def read_rawtext_with_xrefs(self, env, path): + def read_rawtext_with_xrefs(self, env, path, output_type): parser = ParseDataStructs() parser.parse_file(path) @@ -126,7 +127,10 @@ class KernelInclude(Include): if 'warn-broken' in self.options: env._xref_files.add(path) - return parser.gen_output() + if output_type == "toc": + return parser.gen_toc() + + return ".. parsed-literal::\n\n" + parser.gen_output() def apply_range(self, rawtext): # Get to-be-included content @@ -243,39 +247,43 @@ class KernelInclude(Include): e_handler = self.state.document.settings.input_encoding_error_handler tab_width = self.options.get("tab-width", self.state.document.settings.tab_width) - startline = self.options.get("start-line", None) - endline = self.options.get("end-line", None) if "literal" in self.options: - ouptut_type = "literal" + output_type = "literal" elif "code" in self.options: - ouptut_type = "code" + output_type = "code" else: - ouptut_type = "normal" + output_type = "rst" # Get optional arguments to related to cross-references generation - if 'generate-cross-refs' in self.options: - rawtext = self.read_rawtext_with_xrefs(env, path) + if "generate-cross-refs" in self.options: + if "toc" in self.options: + output_type = "toc" + + rawtext = self.read_rawtext_with_xrefs(env, path, output_type) + + # When :generate-cross-refs: is used, the input is always a C + # file, so it has to be handled as a parsed-literal + if output_type == "rst": + output_type = "literal" title = os.path.basename(path) - - if "code" not in self.options: - rawtext = ".. parsed-literal::\n\n" + rawtext else: rawtext = self.read_rawtext(path, encoding) rawtext = self.apply_range(rawtext) - if ouptut_type == "literal": + if output_type == "literal": return self.literal(path, tab_width, rawtext) include_lines = statemachine.string2lines(rawtext, tab_width, convert_whitespace=True) - if ouptut_type == "code": + if output_type == "code": return self.code(path, include_lines) self.state_machine.insert_input(include_lines, path) + return [] # ============================================================================== From 4ad9cabc34d1b45ef77fa9c70e446658f6f5934b Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 22 Aug 2025 16:19:30 +0200 Subject: [PATCH 128/193] docs: kernel_include.py: append line numbers to better report errors It is best to point to the original line of code that generated an error than to point to the beginning of a directive. Add support for it. It should be noticed that this won't work for literal or code blocks, as Sphinx will ignore it, pointing to the beginning of the directive. Yet, when the output is known to be in ReST format, like on TOC, this makes the error a lot more easier to be handled. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/a0953af8b71e64aaf2e0ba4593ad39e19587d50a.1755872208.git.mchehab+huawei@kernel.org --- Documentation/sphinx/kernel_include.py | 81 ++++++++++++++------------ 1 file changed, 44 insertions(+), 37 deletions(-) diff --git a/Documentation/sphinx/kernel_include.py b/Documentation/sphinx/kernel_include.py index 79682408105e..90ed8428f776 100755 --- a/Documentation/sphinx/kernel_include.py +++ b/Documentation/sphinx/kernel_include.py @@ -60,6 +60,7 @@ import re import sys from docutils import io, nodes, statemachine +from docutils.statemachine import ViewList from docutils.utils.error_reporting import SafeString, ErrorString from docutils.parsers.rst import directives from docutils.parsers.rst.directives.body import CodeBlock, NumberLines @@ -112,7 +113,14 @@ class KernelInclude(Include): except UnicodeError as error: raise self.severe('Problem with directive:\n%s' % ErrorString(error)) - def read_rawtext_with_xrefs(self, env, path, output_type): + def xref_text(self, env, path, tab_width): + """ + Read and add contents from a C file parsed to have cross references. + + There are two types of supported output here: + - A C source code with cross-references; + - a TOC table containing cross references. + """ parser = ParseDataStructs() parser.parse_file(path) @@ -127,10 +135,33 @@ class KernelInclude(Include): if 'warn-broken' in self.options: env._xref_files.add(path) - if output_type == "toc": - return parser.gen_toc() + if "toc" in self.options: + rawtext = parser.gen_toc() + else: + rawtext = ".. parsed-literal::\n\n" + parser.gen_output() + self.apply_range(rawtext) - return ".. parsed-literal::\n\n" + parser.gen_output() + title = os.path.basename(path) + + include_lines = statemachine.string2lines(rawtext, tab_width, + convert_whitespace=True) + + # Append line numbers data + + startline = self.options.get('start-line', None) + + result = ViewList() + if startline and startline > 0: + offset = startline - 1 + else: + offset = 0 + + for ln, line in enumerate(include_lines, start=offset): + result.append(line, path, ln) + + self.state_machine.insert_input(result, path) + + return [] def apply_range(self, rawtext): # Get to-be-included content @@ -195,9 +226,12 @@ class KernelInclude(Include): literal_block += nodes.Text(text, text) return [literal_block] - def code(self, path, include_lines): + def code(self, path, tab_width): """Output a code block""" + include_lines = statemachine.string2lines(rawtext, tab_width, + convert_whitespace=True) + self.options["source"] = path codeblock = CodeBlock(self.name, [self.options.pop("code")], # arguments @@ -244,47 +278,20 @@ class KernelInclude(Include): encoding = self.options.get("encoding", self.state.document.settings.input_encoding) - e_handler = self.state.document.settings.input_encoding_error_handler tab_width = self.options.get("tab-width", self.state.document.settings.tab_width) - if "literal" in self.options: - output_type = "literal" - elif "code" in self.options: - output_type = "code" - else: - output_type = "rst" - # Get optional arguments to related to cross-references generation if "generate-cross-refs" in self.options: - if "toc" in self.options: - output_type = "toc" - - rawtext = self.read_rawtext_with_xrefs(env, path, output_type) - - # When :generate-cross-refs: is used, the input is always a C - # file, so it has to be handled as a parsed-literal - if output_type == "rst": - output_type = "literal" - - title = os.path.basename(path) - else: - rawtext = self.read_rawtext(path, encoding) + return self.xref_text(env, path, tab_width) + rawtext = self.read_rawtext(path, encoding) rawtext = self.apply_range(rawtext) - if output_type == "literal": - return self.literal(path, tab_width, rawtext) + if "code" in self.options: + return self.code(path, tab_width, rawtext) - include_lines = statemachine.string2lines(rawtext, tab_width, - convert_whitespace=True) - - if output_type == "code": - return self.code(path, include_lines) - - self.state_machine.insert_input(include_lines, path) - - return [] + return self.literal(path, tab_width, rawtext) # ============================================================================== From 01dba1680cb4047d4f6e057276f805f93b7eea00 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 22 Aug 2025 16:19:31 +0200 Subject: [PATCH 129/193] docs: kernel_include.py: move apply_range() and add a docstring While not required, better to have caller functions at the end. As apply_range() is now called by xref_text(), move it to be before the latter. No functional changes. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/a6ce0fd7c03a01338753fd81ed0c4631f78311d6.1755872208.git.mchehab+huawei@kernel.org --- Documentation/sphinx/kernel_include.py | 68 ++++++++++++++------------ 1 file changed, 36 insertions(+), 32 deletions(-) diff --git a/Documentation/sphinx/kernel_include.py b/Documentation/sphinx/kernel_include.py index 90ed8428f776..fd4887f80577 100755 --- a/Documentation/sphinx/kernel_include.py +++ b/Documentation/sphinx/kernel_include.py @@ -113,6 +113,42 @@ class KernelInclude(Include): except UnicodeError as error: raise self.severe('Problem with directive:\n%s' % ErrorString(error)) + def apply_range(self, rawtext): + """ + Handles start-line, end-line, start-after and end-before parameters + """ + + # Get to-be-included content + startline = self.options.get('start-line', None) + endline = self.options.get('end-line', None) + try: + if startline or (endline is not None): + lines = rawtext.splitlines() + rawtext = '\n'.join(lines[startline:endline]) + except UnicodeError as error: + raise self.severe(f'Problem with "{self.name}" directive:\n' + + io.error_string(error)) + # start-after/end-before: no restrictions on newlines in match-text, + # and no restrictions on matching inside lines vs. line boundaries + after_text = self.options.get("start-after", None) + if after_text: + # skip content in rawtext before *and incl.* a matching text + after_index = rawtext.find(after_text) + if after_index < 0: + raise self.severe('Problem with "start-after" option of "%s" ' + "directive:\nText not found." % self.name) + rawtext = rawtext[after_index + len(after_text) :] + before_text = self.options.get("end-before", None) + if before_text: + # skip content in rawtext after *and incl.* a matching text + before_index = rawtext.find(before_text) + if before_index < 0: + raise self.severe('Problem with "end-before" option of "%s" ' + "directive:\nText not found." % self.name) + rawtext = rawtext[:before_index] + + return rawtext + def xref_text(self, env, path, tab_width): """ Read and add contents from a C file parsed to have cross references. @@ -163,38 +199,6 @@ class KernelInclude(Include): return [] - def apply_range(self, rawtext): - # Get to-be-included content - startline = self.options.get('start-line', None) - endline = self.options.get('end-line', None) - try: - if startline or (endline is not None): - lines = rawtext.splitlines() - rawtext = '\n'.join(lines[startline:endline]) - except UnicodeError as error: - raise self.severe(f'Problem with "{self.name}" directive:\n' - + io.error_string(error)) - # start-after/end-before: no restrictions on newlines in match-text, - # and no restrictions on matching inside lines vs. line boundaries - after_text = self.options.get("start-after", None) - if after_text: - # skip content in rawtext before *and incl.* a matching text - after_index = rawtext.find(after_text) - if after_index < 0: - raise self.severe('Problem with "start-after" option of "%s" ' - "directive:\nText not found." % self.name) - rawtext = rawtext[after_index + len(after_text) :] - before_text = self.options.get("end-before", None) - if before_text: - # skip content in rawtext after *and incl.* a matching text - before_index = rawtext.find(before_text) - if before_index < 0: - raise self.severe('Problem with "end-before" option of "%s" ' - "directive:\nText not found." % self.name) - rawtext = rawtext[:before_index] - - return rawtext - def literal(self, path, tab_width, rawtext): """Output a literal block""" From 4aa578f9c087d58d841e3dfbde1bf57483d9e696 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 22 Aug 2025 16:19:32 +0200 Subject: [PATCH 130/193] docs: kernel_include.py: remove line numbers from parsed-literal When parsed-literal directive is added to rawtext, while cross references will be properly displayed, Sphinx will ignore line numbers. So, it is not worth adding them. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/b484fe5fcbf6e5217f112f205fbf54f0bbc3dcca.1755872208.git.mchehab+huawei@kernel.org --- Documentation/sphinx/kernel_include.py | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) diff --git a/Documentation/sphinx/kernel_include.py b/Documentation/sphinx/kernel_include.py index fd4887f80577..3a1753486319 100755 --- a/Documentation/sphinx/kernel_include.py +++ b/Documentation/sphinx/kernel_include.py @@ -171,13 +171,24 @@ class KernelInclude(Include): if 'warn-broken' in self.options: env._xref_files.add(path) - if "toc" in self.options: - rawtext = parser.gen_toc() - else: + if "toc" not in self.options: + rawtext = ".. parsed-literal::\n\n" + parser.gen_output() self.apply_range(rawtext) - title = os.path.basename(path) + include_lines = statemachine.string2lines(rawtext, tab_width, + convert_whitespace=True) + + # Sphinx always blame the ".. ", so placing + # line numbers here won't make any difference + + self.state_machine.insert_input(include_lines, path) + return [] + + # TOC output is a ReST file, not a literal. So, we can add line + # numbers + + rawtext = parser.gen_toc() include_lines = statemachine.string2lines(rawtext, tab_width, convert_whitespace=True) From 428c1d35118fb755e12a0e5d2745632d4cf3a76e Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 22 Aug 2025 16:19:33 +0200 Subject: [PATCH 131/193] docs: kernel_include.py: remove Include class inheritance While the original code came from the Sphinx Include class, such class is monolithic: it has only one function that does everything, and 3 variables that are used: - required_arguments - optional_arguments - option_spec So, basically those are the only members that remain from the original class, but hey! Those are the same vars that every other Sphinx directive extension has to define! In summary, keeping inheritance here doesn't make much sense. Worse than that, kernel-include doesn't support the current set of options that the original Include class has, but it also has its own set of options. So, let's fill in the argument vars with what it does support, dropping the rest. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/a9f2eebf11c6b0c3a2e3bf42e71392cdfd2835d1.1755872208.git.mchehab+huawei@kernel.org --- Documentation/sphinx/kernel_include.py | 40 ++++++++++++++++++++------ 1 file changed, 32 insertions(+), 8 deletions(-) diff --git a/Documentation/sphinx/kernel_include.py b/Documentation/sphinx/kernel_include.py index 3a1753486319..e6f734476ab3 100755 --- a/Documentation/sphinx/kernel_include.py +++ b/Documentation/sphinx/kernel_include.py @@ -62,9 +62,8 @@ import sys from docutils import io, nodes, statemachine from docutils.statemachine import ViewList from docutils.utils.error_reporting import SafeString, ErrorString -from docutils.parsers.rst import directives +from docutils.parsers.rst import Directive, directives from docutils.parsers.rst.directives.body import CodeBlock, NumberLines -from docutils.parsers.rst.directives.misc import Include from sphinx.util import logging @@ -81,18 +80,43 @@ RE_SIMPLE_REF = re.compile(r'`([^`]+)`') # ============================================================================== -class KernelInclude(Include): - """KernelInclude (``kernel-include``) directive""" +class KernelInclude(Directive): + """ + KernelInclude (``kernel-include``) directive - # Add extra options - option_spec = Include.option_spec.copy() + Most of the stuff here came from Include directive defined at: + docutils/parsers/rst/directives/misc.py - option_spec.update({ + Yet, overriding the class don't has any benefits: the original class + only have run() and argument list. Not all of them are implemented, + when checked against latest Sphinx version, as with time more arguments + were added. + + So, keep its own list of supported arguments + """ + + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = True + option_spec = { + 'literal': directives.flag, + 'code': directives.unchanged, + 'encoding': directives.encoding, + 'tab-width': int, + 'start-line': int, + 'end-line': int, + 'start-after': directives.unchanged_required, + 'end-before': directives.unchanged_required, + # ignored except for 'literal' or 'code': + 'number-lines': directives.unchanged, # integer or None + 'class': directives.class_option, + + # Arguments that aren't from Sphinx Include directive 'generate-cross-refs': directives.flag, 'warn-broken': directives.flag, 'toc': directives.flag, 'exception-file': directives.unchanged, - }) + } def read_rawtext(self, path, encoding): """Read and process file content with error handling""" From a49adfab496f7720fcd588d454b36bfb7922051e Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 22 Aug 2025 16:19:34 +0200 Subject: [PATCH 132/193] docs: kernel_include.py: document all supported parameters As we're actually a fork of Sphinx Include, update its docstring to contain the documentation for the actual implemented parameters. Let's use :param: for parameters, as defined at: https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/f193160889a2dc296b4df2cc7ebc9934d717ccef.1755872208.git.mchehab+huawei@kernel.org --- Documentation/sphinx/kernel_include.py | 88 +++++++++++++++++--------- 1 file changed, 58 insertions(+), 30 deletions(-) diff --git a/Documentation/sphinx/kernel_include.py b/Documentation/sphinx/kernel_include.py index e6f734476ab3..23566ab74866 100755 --- a/Documentation/sphinx/kernel_include.py +++ b/Documentation/sphinx/kernel_include.py @@ -2,53 +2,81 @@ # SPDX-License-Identifier: GPL-2.0 # pylint: disable=R0903, R0912, R0914, R0915, C0209,W0707 + """ - kernel-include - ~~~~~~~~~~~~~~ +Implementation of the ``kernel-include`` reST-directive. - Implementation of the ``kernel-include`` reST-directive. +:copyright: Copyright (C) 2016 Markus Heiser +:license: GPL Version 2, June 1991 see linux/COPYING for details. - :copyright: Copyright (C) 2016 Markus Heiser - :license: GPL Version 2, June 1991 see linux/COPYING for details. +The ``kernel-include`` reST-directive is a replacement for the ``include`` +directive. The ``kernel-include`` directive expand environment variables in +the path name and allows to include files from arbitrary locations. - The ``kernel-include`` reST-directive is a replacement for the ``include`` - directive. The ``kernel-include`` directive expand environment variables in - the path name and allows to include files from arbitrary locations. +.. hint:: - .. hint:: + Including files from arbitrary locations (e.g. from ``/etc``) is a + security risk for builders. This is why the ``include`` directive from + docutils *prohibit* pathnames pointing to locations *above* the filesystem + tree where the reST document with the include directive is placed. - Including files from arbitrary locations (e.g. from ``/etc``) is a - security risk for builders. This is why the ``include`` directive from - docutils *prohibit* pathnames pointing to locations *above* the filesystem - tree where the reST document with the include directive is placed. +Substrings of the form $name or ${name} are replaced by the value of +environment variable name. Malformed variable names and references to +non-existing variables are left unchanged. - Substrings of the form $name or ${name} are replaced by the value of - environment variable name. Malformed variable names and references to - non-existing variables are left unchanged. +**Supported Sphinx Include Options**: - This extension overrides Sphinx include directory, adding some extra - arguments: +:param literal: + If present, the included file is inserted as a literal block. - 1. :generate-cross-refs: +:param code: + Specify the language for syntax highlighting (e.g., 'c', 'python'). - If present, instead of reading the file, it calls ParseDataStructs() - class, which converts C data structures into cross-references to - be linked to ReST files containing a more comprehensive documentation; +:param encoding: + Specify the encoding of the included file (default: 'utf-8'). - 2. :exception-file: +:param tab-width: + Specify the number of spaces that a tab represents. - Used together with :generate-cross-refs +:param start-line: + Line number at which to start including the file (1-based). - Points to a file containing rules to ignore C data structs or to - use a different reference name, optionally using a different - reference type. +:param end-line: + Line number at which to stop including the file (inclusive). - 3. :warn-broken: +:param start-after: + Include lines after the first line matching this text. - Used together with :generate-cross-refs: +:param end-before: + Include lines before the first line matching this text. - Detect if the auto-generated cross references doesn't exist. +:param number-lines: + Number the included lines (integer specifies start number). + Only effective with 'literal' or 'code' options. +:param class: + Specify HTML class attribute for the included content. + +**Kernel-specific Extensions**: + +:param generate-cross-refs: + If present, instead of directly including the file, it calls + ParseDataStructs() to convert C data structures into cross-references + that link to comprehensive documentation in other ReST files. + +:param exception-file: + (Used with generate-cross-refs) + + Path to a file containing rules for handling special cases: + - Ignore specific C data structures + - Use alternative reference names + - Specify different reference types + +:param warn-broken: + (Used with generate-cross-refs) + + Enables warnings when auto-generated cross-references don't point to + existing documentation targets. """ # ============================================================================== From 8a298579cdfcfdbcb70bb7af5e30769387494f37 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 22 Aug 2025 16:19:35 +0200 Subject: [PATCH 133/193] scripts: sphinx-build-wrapper: get rid of uapi/media Makefile Now that kernel-include directive supports parsing data structs directly, we can finally get rid of the horrible hack we added to support parsing media uAPI symbols. As a side effect, Documentation/output doesn't have anymore media auto-generated .rst files on it. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/5dbb257a4b283697271c9c7b8f4713857e8191c8.1755872208.git.mchehab+huawei@kernel.org --- Documentation/Makefile | 3 +- Documentation/userspace-api/media/Makefile | 64 -- .../userspace-api/media/cec/cec-header.rst | 5 +- .../media/{ => cec}/cec.h.rst.exceptions | 0 .../media/{ => dvb}/ca.h.rst.exceptions | 0 .../media/{ => dvb}/dmx.h.rst.exceptions | 0 .../media/{ => dvb}/frontend.h.rst.exceptions | 0 .../userspace-api/media/dvb/headers.rst | 17 +- .../media/{ => dvb}/net.h.rst.exceptions | 0 .../media/mediactl/media-header.rst | 5 +- .../{ => mediactl}/media.h.rst.exceptions | 0 .../userspace-api/media/rc/lirc-header.rst | 4 +- .../media/{ => rc}/lirc.h.rst.exceptions | 0 .../userspace-api/media/v4l/videodev.rst | 4 +- .../{ => v4l}/videodev2.h.rst.exceptions | 0 scripts/sphinx-build-wrapper | 719 ++++++++++++++++++ 16 files changed, 745 insertions(+), 76 deletions(-) delete mode 100644 Documentation/userspace-api/media/Makefile rename Documentation/userspace-api/media/{ => cec}/cec.h.rst.exceptions (100%) rename Documentation/userspace-api/media/{ => dvb}/ca.h.rst.exceptions (100%) rename Documentation/userspace-api/media/{ => dvb}/dmx.h.rst.exceptions (100%) rename Documentation/userspace-api/media/{ => dvb}/frontend.h.rst.exceptions (100%) rename Documentation/userspace-api/media/{ => dvb}/net.h.rst.exceptions (100%) rename Documentation/userspace-api/media/{ => mediactl}/media.h.rst.exceptions (100%) rename Documentation/userspace-api/media/{ => rc}/lirc.h.rst.exceptions (100%) rename Documentation/userspace-api/media/{ => v4l}/videodev2.h.rst.exceptions (100%) create mode 100755 scripts/sphinx-build-wrapper diff --git a/Documentation/Makefile b/Documentation/Makefile index 2ed334971acd..5c20c68be89a 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -87,7 +87,7 @@ loop_cmd = $(echo-cmd) $(cmd_$(1)) || exit; PYTHONPYCACHEPREFIX ?= $(abspath $(BUILDDIR)/__pycache__) quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4) - cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/userspace-api/media $2 && \ + cmd_sphinx = \ PYTHONPYCACHEPREFIX="$(PYTHONPYCACHEPREFIX)" \ BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(src)/$5/$(SPHINX_CONF)) \ $(PYTHON3) $(srctree)/scripts/jobserver-exec \ @@ -171,7 +171,6 @@ refcheckdocs: cleandocs: $(Q)rm -rf $(BUILDDIR) - $(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/userspace-api/media clean dochelp: @echo ' Linux kernel internal documentation in different formats from ReST:' diff --git a/Documentation/userspace-api/media/Makefile b/Documentation/userspace-api/media/Makefile deleted file mode 100644 index accc734d045a..000000000000 --- a/Documentation/userspace-api/media/Makefile +++ /dev/null @@ -1,64 +0,0 @@ -# SPDX-License-Identifier: GPL-2.0 - -# Rules to convert a .h file to inline RST documentation - -SRC_DIR=$(srctree)/Documentation/userspace-api/media -PARSER = $(srctree)/tools/docs/parse-headers.py -UAPI = $(srctree)/include/uapi/linux -KAPI = $(srctree)/include/linux - -FILES = ca.h.rst dmx.h.rst frontend.h.rst net.h.rst \ - videodev2.h.rst media.h.rst cec.h.rst lirc.h.rst - -TARGETS := $(addprefix $(BUILDDIR)/, $(FILES)) - -gen_rst = \ - echo ${PARSER} $< $@ $(SRC_DIR)/$(notdir $@).exceptions; \ - ${PARSER} $< $@ $(SRC_DIR)/$(notdir $@).exceptions - -quiet_gen_rst = echo ' PARSE $(patsubst $(srctree)/%,%,$<)'; \ - ${PARSER} $< $@ $(SRC_DIR)/$(notdir $@).exceptions - -silent_gen_rst = ${gen_rst} - -$(BUILDDIR)/ca.h.rst: ${UAPI}/dvb/ca.h ${PARSER} $(SRC_DIR)/ca.h.rst.exceptions - @$($(quiet)gen_rst) - -$(BUILDDIR)/dmx.h.rst: ${UAPI}/dvb/dmx.h ${PARSER} $(SRC_DIR)/dmx.h.rst.exceptions - @$($(quiet)gen_rst) - -$(BUILDDIR)/frontend.h.rst: ${UAPI}/dvb/frontend.h ${PARSER} $(SRC_DIR)/frontend.h.rst.exceptions - @$($(quiet)gen_rst) - -$(BUILDDIR)/net.h.rst: ${UAPI}/dvb/net.h ${PARSER} $(SRC_DIR)/net.h.rst.exceptions - @$($(quiet)gen_rst) - -$(BUILDDIR)/videodev2.h.rst: ${UAPI}/videodev2.h ${PARSER} $(SRC_DIR)/videodev2.h.rst.exceptions - @$($(quiet)gen_rst) - -$(BUILDDIR)/media.h.rst: ${UAPI}/media.h ${PARSER} $(SRC_DIR)/media.h.rst.exceptions - @$($(quiet)gen_rst) - -$(BUILDDIR)/cec.h.rst: ${UAPI}/cec.h ${PARSER} $(SRC_DIR)/cec.h.rst.exceptions - @$($(quiet)gen_rst) - -$(BUILDDIR)/lirc.h.rst: ${UAPI}/lirc.h ${PARSER} $(SRC_DIR)/lirc.h.rst.exceptions - @$($(quiet)gen_rst) - -# Media build rules - -.PHONY: all html texinfo epub xml latex - -all: $(IMGDOT) $(BUILDDIR) ${TARGETS} -html: all -texinfo: all -epub: all -xml: all -latex: $(IMGPDF) all -linkcheck: - -clean: - -rm -f $(DOTTGT) $(IMGTGT) ${TARGETS} 2>/dev/null - -$(BUILDDIR): - $(Q)mkdir -p $@ diff --git a/Documentation/userspace-api/media/cec/cec-header.rst b/Documentation/userspace-api/media/cec/cec-header.rst index d70736ac2b1d..f67003bb8740 100644 --- a/Documentation/userspace-api/media/cec/cec-header.rst +++ b/Documentation/userspace-api/media/cec/cec-header.rst @@ -6,5 +6,6 @@ CEC Header File *************** -.. kernel-include:: $BUILDDIR/cec.h.rst - +.. kernel-include:: include/uapi/linux/cec.h + :generate-cross-refs: + :exception-file: cec.h.rst.exceptions diff --git a/Documentation/userspace-api/media/cec.h.rst.exceptions b/Documentation/userspace-api/media/cec/cec.h.rst.exceptions similarity index 100% rename from Documentation/userspace-api/media/cec.h.rst.exceptions rename to Documentation/userspace-api/media/cec/cec.h.rst.exceptions diff --git a/Documentation/userspace-api/media/ca.h.rst.exceptions b/Documentation/userspace-api/media/dvb/ca.h.rst.exceptions similarity index 100% rename from Documentation/userspace-api/media/ca.h.rst.exceptions rename to Documentation/userspace-api/media/dvb/ca.h.rst.exceptions diff --git a/Documentation/userspace-api/media/dmx.h.rst.exceptions b/Documentation/userspace-api/media/dvb/dmx.h.rst.exceptions similarity index 100% rename from Documentation/userspace-api/media/dmx.h.rst.exceptions rename to Documentation/userspace-api/media/dvb/dmx.h.rst.exceptions diff --git a/Documentation/userspace-api/media/frontend.h.rst.exceptions b/Documentation/userspace-api/media/dvb/frontend.h.rst.exceptions similarity index 100% rename from Documentation/userspace-api/media/frontend.h.rst.exceptions rename to Documentation/userspace-api/media/dvb/frontend.h.rst.exceptions diff --git a/Documentation/userspace-api/media/dvb/headers.rst b/Documentation/userspace-api/media/dvb/headers.rst index 88c3eb33a89e..c75f64cf21d5 100644 --- a/Documentation/userspace-api/media/dvb/headers.rst +++ b/Documentation/userspace-api/media/dvb/headers.rst @@ -7,10 +7,19 @@ Digital TV uAPI header files Digital TV uAPI headers *********************** -.. kernel-include:: $BUILDDIR/frontend.h.rst +.. kernel-include:: include/uapi/linux/dvb/frontend.h + :generate-cross-refs: + :exception-file: frontend.h.rst.exceptions -.. kernel-include:: $BUILDDIR/dmx.h.rst +.. kernel-include:: include/uapi/linux/dvb/dmx.h + :generate-cross-refs: + :exception-file: dmx.h.rst.exceptions -.. kernel-include:: $BUILDDIR/ca.h.rst +.. kernel-include:: include/uapi/linux/dvb/ca.h + :generate-cross-refs: + :exception-file: ca.h.rst.exceptions + +.. kernel-include:: include/uapi/linux/dvb/net.h + :generate-cross-refs: + :exception-file: net.h.rst.exceptions -.. kernel-include:: $BUILDDIR/net.h.rst diff --git a/Documentation/userspace-api/media/net.h.rst.exceptions b/Documentation/userspace-api/media/dvb/net.h.rst.exceptions similarity index 100% rename from Documentation/userspace-api/media/net.h.rst.exceptions rename to Documentation/userspace-api/media/dvb/net.h.rst.exceptions diff --git a/Documentation/userspace-api/media/mediactl/media-header.rst b/Documentation/userspace-api/media/mediactl/media-header.rst index c674271c93f5..d561d2845f3d 100644 --- a/Documentation/userspace-api/media/mediactl/media-header.rst +++ b/Documentation/userspace-api/media/mediactl/media-header.rst @@ -6,5 +6,6 @@ Media Controller Header File **************************** -.. kernel-include:: $BUILDDIR/media.h.rst - +.. kernel-include:: include/uapi/linux/media.h + :generate-cross-refs: + :exception-file: media.h.rst.exceptions diff --git a/Documentation/userspace-api/media/media.h.rst.exceptions b/Documentation/userspace-api/media/mediactl/media.h.rst.exceptions similarity index 100% rename from Documentation/userspace-api/media/media.h.rst.exceptions rename to Documentation/userspace-api/media/mediactl/media.h.rst.exceptions diff --git a/Documentation/userspace-api/media/rc/lirc-header.rst b/Documentation/userspace-api/media/rc/lirc-header.rst index 54cb40b8a065..a53328327847 100644 --- a/Documentation/userspace-api/media/rc/lirc-header.rst +++ b/Documentation/userspace-api/media/rc/lirc-header.rst @@ -6,5 +6,7 @@ LIRC Header File **************** -.. kernel-include:: $BUILDDIR/lirc.h.rst +.. kernel-include:: include/uapi/linux/lirc.h + :generate-cross-refs: + :exception-file: lirc.h.rst.exceptions diff --git a/Documentation/userspace-api/media/lirc.h.rst.exceptions b/Documentation/userspace-api/media/rc/lirc.h.rst.exceptions similarity index 100% rename from Documentation/userspace-api/media/lirc.h.rst.exceptions rename to Documentation/userspace-api/media/rc/lirc.h.rst.exceptions diff --git a/Documentation/userspace-api/media/v4l/videodev.rst b/Documentation/userspace-api/media/v4l/videodev.rst index c866fec417eb..cde485bc9a5f 100644 --- a/Documentation/userspace-api/media/v4l/videodev.rst +++ b/Documentation/userspace-api/media/v4l/videodev.rst @@ -6,4 +6,6 @@ Video For Linux Two Header File ******************************* -.. kernel-include:: $BUILDDIR/videodev2.h.rst +.. kernel-include:: include/uapi/linux/videodev2.h + :generate-cross-refs: + :exception-file: videodev2.h.rst.exceptions diff --git a/Documentation/userspace-api/media/videodev2.h.rst.exceptions b/Documentation/userspace-api/media/v4l/videodev2.h.rst.exceptions similarity index 100% rename from Documentation/userspace-api/media/videodev2.h.rst.exceptions rename to Documentation/userspace-api/media/v4l/videodev2.h.rst.exceptions diff --git a/scripts/sphinx-build-wrapper b/scripts/sphinx-build-wrapper new file mode 100755 index 000000000000..abe8c26ae137 --- /dev/null +++ b/scripts/sphinx-build-wrapper @@ -0,0 +1,719 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: GPL-2.0 +# Copyright (C) 2025 Mauro Carvalho Chehab +# +# pylint: disable=R0902, R0912, R0913, R0914, R0915, R0917, C0103 +# +# Converted from docs Makefile and parallel-wrapper.sh, both under +# GPLv2, copyrighted since 2008 by the following authors: +# +# Akira Yokosawa +# Arnd Bergmann +# Breno Leitao +# Carlos Bilbao +# Dave Young +# Donald Hunter +# Geert Uytterhoeven +# Jani Nikula +# Jan Stancek +# Jonathan Corbet +# Joshua Clayton +# Kees Cook +# Linus Torvalds +# Magnus Damm +# Masahiro Yamada +# Mauro Carvalho Chehab +# Maxim Cournoyer +# Peter Foley +# Randy Dunlap +# Rob Herring +# Shuah Khan +# Thorsten Blum +# Tomas Winkler + + +""" +Sphinx build wrapper that handles Kernel-specific business rules: + +- it gets the Kernel build environment vars; +- it determines what's the best parallelism; +- it handles SPHINXDIRS + +This tool ensures that MIN_PYTHON_VERSION is satisfied. If version is +below that, it seeks for a new Python version. If found, it re-runs using +the newer version. +""" + +import argparse +import locale +import os +import re +import shlex +import shutil +import subprocess +import sys + +from concurrent import futures +from glob import glob + +LIB_DIR = "lib" +SRC_DIR = os.path.dirname(os.path.realpath(__file__)) + +sys.path.insert(0, os.path.join(SRC_DIR, LIB_DIR)) + +from jobserver import JobserverExec # pylint: disable=C0413 + + +def parse_version(version): + """Convert a major.minor.patch version into a tuple""" + return tuple(int(x) for x in version.split(".")) + +def ver_str(version): + """Returns a version tuple as major.minor.patch""" + + return ".".join([str(x) for x in version]) + +# Minimal supported Python version needed by Sphinx and its extensions +MIN_PYTHON_VERSION = parse_version("3.7") + +# Default value for --venv parameter +VENV_DEFAULT = "sphinx_latest" + +# List of make targets and its corresponding builder and output directory +TARGETS = { + "cleandocs": { + "builder": "clean", + }, + "htmldocs": { + "builder": "html", + }, + "epubdocs": { + "builder": "epub", + "out_dir": "epub", + }, + "texinfodocs": { + "builder": "texinfo", + "out_dir": "texinfo", + }, + "infodocs": { + "builder": "texinfo", + "out_dir": "texinfo", + }, + "latexdocs": { + "builder": "latex", + "out_dir": "latex", + }, + "pdfdocs": { + "builder": "latex", + "out_dir": "latex", + }, + "xmldocs": { + "builder": "xml", + "out_dir": "xml", + }, + "linkcheckdocs": { + "builder": "linkcheck" + }, +} + +# Paper sizes. An empty value will pick the default +PAPER = ["", "a4", "letter"] + +class SphinxBuilder: + """ + Handles a sphinx-build target, adding needed arguments to build + with the Kernel. + """ + + def is_rust_enabled(self): + """Check if rust is enabled at .config""" + config_path = os.path.join(self.srctree, ".config") + if os.path.isfile(config_path): + with open(config_path, "r", encoding="utf-8") as f: + return "CONFIG_RUST=y" in f.read() + return False + + def get_path(self, path, abs_path=False): + """ + Ancillary routine to handle patches the right way, as shell does. + + It first expands "~" and "~user". Then, if patch is not absolute, + join self.srctree. Finally, if requested, convert to abspath. + """ + + path = os.path.expanduser(path) + if not path.startswith("/"): + path = os.path.join(self.srctree, path) + + if abs_path: + return os.path.abspath(path) + + return path + + def __init__(self, venv=None, verbose=False, n_jobs=None, interactive=None): + """Initialize internal variables""" + self.venv = venv + self.verbose = None + + # Normal variables passed from Kernel's makefile + self.kernelversion = os.environ.get("KERNELVERSION", "unknown") + self.kernelrelease = os.environ.get("KERNELRELEASE", "unknown") + self.pdflatex = os.environ.get("PDFLATEX", "xelatex") + + if not interactive: + self.latexopts = os.environ.get("LATEXOPTS", "-interaction=batchmode -no-shell-escape") + else: + self.latexopts = os.environ.get("LATEXOPTS", "") + + if not verbose: + verbose = bool(os.environ.get("KBUILD_VERBOSE", "") != "") + + # Handle SPHINXOPTS evironment + sphinxopts = shlex.split(os.environ.get("SPHINXOPTS", "")) + + # As we handle number of jobs and quiet in separate, we need to pick + # it the same way as sphinx-build would pick, so let's use argparse + # do to the right argument expansion + parser = argparse.ArgumentParser() + parser.add_argument('-j', '--jobs', type=int) + parser.add_argument('-q', '--quiet', type=int) + + # Other sphinx-build arguments go as-is, so place them + # at self.sphinxopts + sphinx_args, self.sphinxopts = parser.parse_known_args(sphinxopts) + if sphinx_args.quiet == True: + self.verbose = False + + if sphinx_args.jobs: + self.n_jobs = sphinx_args.jobs + + # Command line arguments was passed, override SPHINXOPTS + if verbose is not None: + self.verbose = verbose + + self.n_jobs = n_jobs + + # Source tree directory. This needs to be at os.environ, as + # Sphinx extensions and media uAPI makefile needs it + self.srctree = os.environ.get("srctree") + if not self.srctree: + self.srctree = "." + os.environ["srctree"] = self.srctree + + # Now that we can expand srctree, get other directories as well + self.sphinxbuild = os.environ.get("SPHINXBUILD", "sphinx-build") + self.kerneldoc = self.get_path(os.environ.get("KERNELDOC", + "scripts/kernel-doc.py")) + self.obj = os.environ.get("obj", "Documentation") + self.builddir = self.get_path(os.path.join(self.obj, "output"), + abs_path=True) + + # Media uAPI needs it + os.environ["BUILDDIR"] = self.builddir + + # Detect if rust is enabled + self.config_rust = self.is_rust_enabled() + + # Get directory locations for LaTeX build toolchain + self.pdflatex_cmd = shutil.which(self.pdflatex) + self.latexmk_cmd = shutil.which("latexmk") + + self.env = os.environ.copy() + + # If venv parameter is specified, run Sphinx from venv + if venv: + bin_dir = os.path.join(venv, "bin") + if os.path.isfile(os.path.join(bin_dir, "activate")): + # "activate" virtual env + self.env["PATH"] = bin_dir + ":" + self.env["PATH"] + self.env["VIRTUAL_ENV"] = venv + if "PYTHONHOME" in self.env: + del self.env["PYTHONHOME"] + print(f"Setting venv to {venv}") + else: + sys.exit(f"Venv {venv} not found.") + + def run_sphinx(self, sphinx_build, build_args, *args, **pwargs): + """ + Executes sphinx-build using current python3 command and setting + -j parameter if possible to run the build in parallel. + """ + + with JobserverExec() as jobserver: + if jobserver.claim: + n_jobs = str(jobserver.claim) + else: + n_jobs = "auto" # Supported since Sphinx 1.7 + + cmd = [] + + if self.venv: + cmd.append("python") + else: + cmd.append(sys.executable) + + cmd.append(sphinx_build) + + # if present, SPHINXOPTS or command line --jobs overrides default + if self.n_jobs: + n_jobs = str(self.n_jobs) + + if n_jobs: + cmd += [f"-j{n_jobs}"] + + if not self.verbose: + cmd.append("-q") + + cmd += self.sphinxopts + + cmd += build_args + + if self.verbose: + print(" ".join(cmd)) + + rc = subprocess.call(cmd, *args, **pwargs) + + def handle_html(self, css, output_dir): + """ + Extra steps for HTML and epub output. + + For such targets, we need to ensure that CSS will be properly + copied to the output _static directory + """ + + if not css: + return + + css = os.path.expanduser(css) + if not css.startswith("/"): + css = os.path.join(self.srctree, css) + + static_dir = os.path.join(output_dir, "_static") + os.makedirs(static_dir, exist_ok=True) + + try: + shutil.copy2(css, static_dir) + except (OSError, IOError) as e: + print(f"Warning: Failed to copy CSS: {e}", file=sys.stderr) + + def build_pdf_file(self, latex_cmd, from_dir, path): + """Builds a single pdf file using latex_cmd""" + try: + subprocess.run(latex_cmd + [path], + cwd=from_dir, check=True) + + return True + except subprocess.CalledProcessError: + # LaTeX PDF error code is almost useless: it returns + # error codes even when build succeeds but has warnings. + # So, we'll ignore the results + return False + + def pdf_parallel_build(self, tex_suffix, latex_cmd, tex_files, n_jobs): + """Build PDF files in parallel if possible""" + builds = {} + build_failed = False + max_len = 0 + has_tex = False + + # Process files in parallel + with futures.ThreadPoolExecutor(max_workers=n_jobs) as executor: + jobs = {} + + for from_dir, pdf_dir, entry in tex_files: + name = entry.name + + if not name.endswith(tex_suffix): + continue + + name = name[:-len(tex_suffix)] + + max_len = max(max_len, len(name)) + + has_tex = True + + future = executor.submit(self.build_pdf_file, latex_cmd, + from_dir, entry.path) + jobs[future] = (from_dir, name, entry.path) + + for future in futures.as_completed(jobs): + from_dir, name, path = jobs[future] + + pdf_name = name + ".pdf" + pdf_from = os.path.join(from_dir, pdf_name) + + try: + success = future.result() + + if success and os.path.exists(pdf_from): + pdf_to = os.path.join(pdf_dir, pdf_name) + + os.rename(pdf_from, pdf_to) + builds[name] = os.path.relpath(pdf_to, self.builddir) + else: + builds[name] = "FAILED" + build_failed = True + except Exception as e: + builds[name] = f"FAILED ({str(e)})" + build_failed = True + + # Handle case where no .tex files were found + if not has_tex: + name = "Sphinx LaTeX builder" + max_len = max(max_len, len(name)) + builds[name] = "FAILED (no .tex file was generated)" + build_failed = True + + return builds, build_failed, max_len + + def handle_pdf(self, output_dirs): + """ + Extra steps for PDF output. + + As PDF is handled via a LaTeX output, after building the .tex file, + a new build is needed to create the PDF output from the latex + directory. + """ + builds = {} + max_len = 0 + tex_suffix = ".tex" + + # Get all tex files that will be used for PDF build + tex_files = [] + for from_dir in output_dirs: + pdf_dir = os.path.join(from_dir, "../pdf") + os.makedirs(pdf_dir, exist_ok=True) + + if self.latexmk_cmd: + latex_cmd = [self.latexmk_cmd, f"-{self.pdflatex}"] + else: + latex_cmd = [self.pdflatex] + + latex_cmd.extend(shlex.split(self.latexopts)) + + # Get a list of tex files to process + with os.scandir(from_dir) as it: + for entry in it: + if entry.name.endswith(tex_suffix): + tex_files.append((from_dir, pdf_dir, entry)) + + # When using make, this won't be used, as the number of jobs comes + # from POSIX jobserver. So, this covers the case where build comes + # from command line. On such case, serialize by default, except if + # the user explicitly sets the number of jobs. + n_jobs = 1 + + # n_jobs is either an integer or "auto". Only use it if it is a number + if self.n_jobs: + try: + n_jobs = int(self.n_jobs) + except ValueError: + pass + + # When using make, jobserver.claim is the number of jobs that were + # used with "-j" and that aren't used by other make targets + with JobserverExec() as jobserver: + n_jobs = 1 + + # Handle the case when a parameter is passed via command line, + # using it as default, if jobserver doesn't claim anything + if self.n_jobs: + try: + n_jobs = int(self.n_jobs) + except ValueError: + pass + + if jobserver.claim: + n_jobs = jobserver.claim + + # Build files in parallel + builds, build_failed, max_len = self.pdf_parallel_build(tex_suffix, + latex_cmd, + tex_files, + n_jobs) + + msg = "Summary" + msg += "\n" + "=" * len(msg) + print() + print(msg) + + for pdf_name, pdf_file in builds.items(): + print(f"{pdf_name:<{max_len}}: {pdf_file}") + + print() + + # return an error if a PDF file is missing + + if build_failed: + sys.exit(f"PDF build failed: not all PDF files were created.") + else: + print("All PDF files were built.") + + def handle_info(self, output_dirs): + """ + Extra steps for Info output. + + For texinfo generation, an additional make is needed from the + texinfo directory. + """ + + for output_dir in output_dirs: + try: + subprocess.run(["make", "info"], cwd=output_dir, check=True) + except subprocess.CalledProcessError as e: + sys.exit(f"Error generating info docs: {e}") + + def cleandocs(self, builder): + + shutil.rmtree(self.builddir, ignore_errors=True) + + def build(self, target, sphinxdirs=None, conf="conf.py", + theme=None, css=None, paper=None): + """ + Build documentation using Sphinx. This is the core function of this + module. It prepares all arguments required by sphinx-build. + """ + + builder = TARGETS[target]["builder"] + out_dir = TARGETS[target].get("out_dir", "") + + # Cleandocs doesn't require sphinx-build + if target == "cleandocs": + self.cleandocs(builder) + return + + # Other targets require sphinx-build + sphinxbuild = shutil.which(self.sphinxbuild, path=self.env["PATH"]) + if not sphinxbuild: + sys.exit(f"Error: {self.sphinxbuild} not found in PATH.\n") + + if builder == "latex": + if not self.pdflatex_cmd and not self.latexmk_cmd: + sys.exit("Error: pdflatex or latexmk required for PDF generation") + + docs_dir = os.path.abspath(os.path.join(self.srctree, "Documentation")) + + # Prepare base arguments for Sphinx build + kerneldoc = self.kerneldoc + if kerneldoc.startswith(self.srctree): + kerneldoc = os.path.relpath(kerneldoc, self.srctree) + + # Prepare common Sphinx options + args = [ + "-b", builder, + "-c", docs_dir, + ] + + if builder == "latex": + if not paper: + paper = PAPER[1] + + args.extend(["-D", f"latex_elements.papersize={paper}paper"]) + + if self.config_rust: + args.extend(["-t", "rustdoc"]) + + if conf: + self.env["SPHINX_CONF"] = self.get_path(conf, abs_path=True) + + if not sphinxdirs: + sphinxdirs = os.environ.get("SPHINXDIRS", ".") + + # The sphinx-build tool has a bug: internally, it tries to set + # locale with locale.setlocale(locale.LC_ALL, ''). This causes a + # crash if language is not set. Detect and fix it. + try: + locale.setlocale(locale.LC_ALL, '') + except Exception: + self.env["LC_ALL"] = "C" + self.env["LANG"] = "C" + + # sphinxdirs can be a list or a whitespace-separated string + sphinxdirs_list = [] + for sphinxdir in sphinxdirs: + if isinstance(sphinxdir, list): + sphinxdirs_list += sphinxdir + else: + for name in sphinxdir.split(" "): + sphinxdirs_list.append(name) + + # Build each directory + output_dirs = [] + for sphinxdir in sphinxdirs_list: + src_dir = os.path.join(docs_dir, sphinxdir) + doctree_dir = os.path.join(self.builddir, ".doctrees") + output_dir = os.path.join(self.builddir, sphinxdir, out_dir) + + # Make directory names canonical + src_dir = os.path.normpath(src_dir) + doctree_dir = os.path.normpath(doctree_dir) + output_dir = os.path.normpath(output_dir) + + os.makedirs(doctree_dir, exist_ok=True) + os.makedirs(output_dir, exist_ok=True) + + output_dirs.append(output_dir) + + build_args = args + [ + "-d", doctree_dir, + "-D", f"kerneldoc_bin={kerneldoc}", + "-D", f"version={self.kernelversion}", + "-D", f"release={self.kernelrelease}", + "-D", f"kerneldoc_srctree={self.srctree}", + src_dir, + output_dir, + ] + + # Execute sphinx-build + try: + self.run_sphinx(sphinxbuild, build_args, env=self.env) + except Exception as e: + sys.exit(f"Build failed: {e}") + + # Ensure that html/epub will have needed static files + if target in ["htmldocs", "epubdocs"]: + self.handle_html(css, output_dir) + + # PDF and Info require a second build step + if target == "pdfdocs": + self.handle_pdf(output_dirs) + elif target == "infodocs": + self.handle_info(output_dirs) + + @staticmethod + def get_python_version(cmd): + """ + Get python version from a Python binary. As we need to detect if + are out there newer python binaries, we can't rely on sys.release here. + """ + + result = subprocess.run([cmd, "--version"], check=True, + stdout=subprocess.PIPE, stderr=subprocess.PIPE, + universal_newlines=True) + version = result.stdout.strip() + + match = re.search(r"(\d+\.\d+\.\d+)", version) + if match: + return parse_version(match.group(1)) + + print(f"Can't parse version {version}") + return (0, 0, 0) + + @staticmethod + def find_python(): + """ + Detect if are out there any python 3.xy version newer than the + current one. + + Note: this routine is limited to up to 2 digits for python3. We + may need to update it one day, hopefully on a distant future. + """ + patterns = [ + "python3.[0-9]", + "python3.[0-9][0-9]", + ] + + # Seek for a python binary newer than MIN_PYTHON_VERSION + for path in os.getenv("PATH", "").split(":"): + for pattern in patterns: + for cmd in glob(os.path.join(path, pattern)): + if os.path.isfile(cmd) and os.access(cmd, os.X_OK): + version = SphinxBuilder.get_python_version(cmd) + if version >= MIN_PYTHON_VERSION: + return cmd + + return None + + @staticmethod + def check_python(): + """ + Check if the current python binary satisfies our minimal requirement + for Sphinx build. If not, re-run with a newer version if found. + """ + cur_ver = sys.version_info[:3] + if cur_ver >= MIN_PYTHON_VERSION: + return + + python_ver = ver_str(cur_ver) + + new_python_cmd = SphinxBuilder.find_python() + if not new_python_cmd: + sys.exit(f"Python version {python_ver} is not supported anymore.") + + # Restart script using the newer version + script_path = os.path.abspath(sys.argv[0]) + args = [new_python_cmd, script_path] + sys.argv[1:] + + print(f"Python {python_ver} not supported. Changing to {new_python_cmd}") + + try: + os.execv(new_python_cmd, args) + except OSError as e: + sys.exit(f"Failed to restart with {new_python_cmd}: {e}") + +def jobs_type(value): + """ + Handle valid values for -j. Accepts Sphinx "-jauto", plus a number + equal or bigger than one. + """ + if value is None: + return None + + if value.lower() == 'auto': + return value.lower() + + try: + if int(value) >= 1: + return value + + raise argparse.ArgumentTypeError(f"Minimum jobs is 1, got {value}") + except ValueError: + raise argparse.ArgumentTypeError(f"Must be 'auto' or positive integer, got {value}") + +def main(): + """ + Main function. The only mandatory argument is the target. If not + specified, the other arguments will use default values if not + specified at os.environ. + """ + parser = argparse.ArgumentParser(description="Kernel documentation builder") + + parser.add_argument("target", choices=list(TARGETS.keys()), + help="Documentation target to build") + parser.add_argument("--sphinxdirs", nargs="+", + help="Specific directories to build") + parser.add_argument("--conf", default="conf.py", + help="Sphinx configuration file") + + parser.add_argument("--theme", help="Sphinx theme to use") + + parser.add_argument("--css", help="Custom CSS file for HTML/EPUB") + + parser.add_argument("--paper", choices=PAPER, default=PAPER[0], + help="Paper size for LaTeX/PDF output") + + parser.add_argument("-v", "--verbose", action='store_true', + help="place build in verbose mode") + + parser.add_argument('-j', '--jobs', type=jobs_type, + help="Sets number of jobs to use with sphinx-build") + + parser.add_argument('-i', '--interactive', action='store_true', + help="Change latex default to run in interactive mode") + + parser.add_argument("-V", "--venv", nargs='?', const=f'{VENV_DEFAULT}', + default=None, + help=f'If used, run Sphinx from a venv dir (default dir: {VENV_DEFAULT})') + + args = parser.parse_args() + + SphinxBuilder.check_python() + + builder = SphinxBuilder(venv=args.venv, verbose=args.verbose, + n_jobs=args.jobs, interactive=args.interactive) + + builder.build(args.target, sphinxdirs=args.sphinxdirs, conf=args.conf, + theme=args.theme, css=args.css, paper=args.paper) + +if __name__ == "__main__": + main() From aebcc3009ed55564b74378945206642a372c3e27 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 22 Aug 2025 16:19:36 +0200 Subject: [PATCH 134/193] docs: sphinx: drop parse-headers.pl Now that we have a replacement in place, drop the old version. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/d3a5397df44e53b02fa62f782d1e7ce6e08ed04f.1755872208.git.mchehab+huawei@kernel.org --- Documentation/sphinx/parse-headers.pl | 419 -------------------------- 1 file changed, 419 deletions(-) delete mode 100755 Documentation/sphinx/parse-headers.pl diff --git a/Documentation/sphinx/parse-headers.pl b/Documentation/sphinx/parse-headers.pl deleted file mode 100755 index 560685926cdb..000000000000 --- a/Documentation/sphinx/parse-headers.pl +++ /dev/null @@ -1,419 +0,0 @@ -#!/usr/bin/env perl -# SPDX-License-Identifier: GPL-2.0 -# Copyright (c) 2016 by Mauro Carvalho Chehab . - -use strict; -use Text::Tabs; -use Getopt::Long; -use Pod::Usage; - -my $debug; -my $help; -my $man; - -GetOptions( - "debug" => \$debug, - 'usage|?' => \$help, - 'help' => \$man -) or pod2usage(2); - -pod2usage(1) if $help; -pod2usage(-exitstatus => 0, -verbose => 2) if $man; -pod2usage(2) if (scalar @ARGV < 2 || scalar @ARGV > 3); - -my ($file_in, $file_out, $file_exceptions) = @ARGV; - -my $data; -my %ioctls; -my %defines; -my %typedefs; -my %enums; -my %enum_symbols; -my %structs; - -# -# read the file and get identifiers -# - -my $is_enum = 0; -my $is_comment = 0; -open IN, $file_in or die "Can't open $file_in"; -while () { - $data .= $_; - - my $ln = $_; - if (!$is_comment) { - $ln =~ s,/\*.*(\*/),,g; - - $is_comment = 1 if ($ln =~ s,/\*.*,,); - } else { - if ($ln =~ s,^(.*\*/),,) { - $is_comment = 0; - } else { - next; - } - } - - if ($is_enum && $ln =~ m/^\s*([_\w][\w\d_]+)\s*[\,=]?/) { - my $s = $1; - my $n = $1; - $n =~ tr/A-Z/a-z/; - $n =~ tr/_/-/; - - $enum_symbols{$s} = "\\ :ref:`$s <$n>`\\ "; - - $is_enum = 0 if ($is_enum && m/\}/); - next; - } - $is_enum = 0 if ($is_enum && m/\}/); - - if ($ln =~ m/^\s*#\s*define\s+([_\w][\w\d_]+)\s+_IO/) { - my $s = $1; - my $n = $1; - $n =~ tr/A-Z/a-z/; - - $ioctls{$s} = "\\ :ref:`$s <$n>`\\ "; - next; - } - - if ($ln =~ m/^\s*#\s*define\s+([_\w][\w\d_]+)\s+/) { - my $s = $1; - my $n = $1; - $n =~ tr/A-Z/a-z/; - $n =~ tr/_/-/; - - $defines{$s} = "\\ :ref:`$s <$n>`\\ "; - next; - } - - if ($ln =~ m/^\s*typedef\s+([_\w][\w\d_]+)\s+(.*)\s+([_\w][\w\d_]+);/) { - my $s = $2; - my $n = $3; - - $typedefs{$n} = "\\ :c:type:`$n <$s>`\\ "; - next; - } - if ($ln =~ m/^\s*enum\s+([_\w][\w\d_]+)\s+\{/ - || $ln =~ m/^\s*enum\s+([_\w][\w\d_]+)$/ - || $ln =~ m/^\s*typedef\s*enum\s+([_\w][\w\d_]+)\s+\{/ - || $ln =~ m/^\s*typedef\s*enum\s+([_\w][\w\d_]+)$/) { - my $s = $1; - - $enums{$s} = "enum :c:type:`$s`\\ "; - - $is_enum = $1; - next; - } - if ($ln =~ m/^\s*struct\s+([_\w][\w\d_]+)\s+\{/ - || $ln =~ m/^\s*struct\s+([[_\w][\w\d_]+)$/ - || $ln =~ m/^\s*typedef\s*struct\s+([_\w][\w\d_]+)\s+\{/ - || $ln =~ m/^\s*typedef\s*struct\s+([[_\w][\w\d_]+)$/ - ) { - my $s = $1; - - $structs{$s} = "struct $s\\ "; - next; - } -} -close IN; - -# -# Handle multi-line typedefs -# - -my @matches = ($data =~ m/typedef\s+struct\s+\S+?\s*\{[^\}]+\}\s*(\S+)\s*\;/g, - $data =~ m/typedef\s+enum\s+\S+?\s*\{[^\}]+\}\s*(\S+)\s*\;/g,); -foreach my $m (@matches) { - my $s = $m; - - $typedefs{$s} = "\\ :c:type:`$s`\\ "; - next; -} - -# -# Handle exceptions, if any -# - -my %def_reftype = ( - "ioctl" => ":ref", - "define" => ":ref", - "symbol" => ":ref", - "typedef" => ":c:type", - "enum" => ":c:type", - "struct" => ":c:type", -); - -if ($file_exceptions) { - open IN, $file_exceptions or die "Can't read $file_exceptions"; - while () { - next if (m/^\s*$/ || m/^\s*#/); - - # Parsers to ignore a symbol - - if (m/^ignore\s+ioctl\s+(\S+)/) { - delete $ioctls{$1} if (exists($ioctls{$1})); - next; - } - if (m/^ignore\s+define\s+(\S+)/) { - delete $defines{$1} if (exists($defines{$1})); - next; - } - if (m/^ignore\s+typedef\s+(\S+)/) { - delete $typedefs{$1} if (exists($typedefs{$1})); - next; - } - if (m/^ignore\s+enum\s+(\S+)/) { - delete $enums{$1} if (exists($enums{$1})); - next; - } - if (m/^ignore\s+struct\s+(\S+)/) { - delete $structs{$1} if (exists($structs{$1})); - next; - } - if (m/^ignore\s+symbol\s+(\S+)/) { - delete $enum_symbols{$1} if (exists($enum_symbols{$1})); - next; - } - - # Parsers to replace a symbol - my ($type, $old, $new, $reftype); - - if (m/^replace\s+(\S+)\s+(\S+)\s+(\S+)/) { - $type = $1; - $old = $2; - $new = $3; - } else { - die "Can't parse $file_exceptions: $_"; - } - - if ($new =~ m/^\:c\:(data|func|macro|type)\:\`(.+)\`/) { - $reftype = ":c:$1"; - $new = $2; - } elsif ($new =~ m/\:ref\:\`(.+)\`/) { - $reftype = ":ref"; - $new = $1; - } else { - $reftype = $def_reftype{$type}; - } - if (!$reftype) { - print STDERR "Warning: can't find ref type for $type"; - } - $new = "$reftype:`$old <$new>`"; - - if ($type eq "ioctl") { - $ioctls{$old} = $new if (exists($ioctls{$old})); - next; - } - if ($type eq "define") { - $defines{$old} = $new if (exists($defines{$old})); - next; - } - if ($type eq "symbol") { - $enum_symbols{$old} = $new if (exists($enum_symbols{$old})); - next; - } - if ($type eq "typedef") { - $typedefs{$old} = $new if (exists($typedefs{$old})); - next; - } - if ($type eq "enum") { - $enums{$old} = $new if (exists($enums{$old})); - next; - } - if ($type eq "struct") { - $structs{$old} = $new if (exists($structs{$old})); - next; - } - - die "Can't parse $file_exceptions: $_"; - } -} - -if ($debug) { - my @all_hashes = ( - {ioctl => \%ioctls}, - {typedef => \%typedefs}, - {enum => \%enums}, - {struct => \%structs}, - {define => \%defines}, - {symbol => \%enum_symbols} - ); - - foreach my $hash (@all_hashes) { - while (my ($name, $hash_ref) = each %$hash) { - next unless %$hash_ref; # Skip empty hashes - - print "$name:\n"; - for my $key (sort keys %$hash_ref) { - print " $key -> $hash_ref->{$key}\n"; - } - print "\n"; - } - } -} - -# -# Align block -# -$data = expand($data); -$data = " " . $data; -$data =~ s/\n/\n /g; -$data =~ s/\n\s+$/\n/g; -$data =~ s/\n\s+\n/\n\n/g; - -# -# Add escape codes for special characters -# -$data =~ s,([\_\`\*\<\>\&\\\\:\/\|\%\$\#\{\}\~\^]),\\$1,g; - -$data =~ s,DEPRECATED,**DEPRECATED**,g; - -# -# Add references -# - -my $start_delim = "[ \n\t\(\=\*\@]"; -my $end_delim = "(\\s|,|\\\\=|\\\\:|\\;|\\\)|\\}|\\{)"; - -foreach my $r (keys %ioctls) { - my $s = $ioctls{$r}; - - $r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g; - - print "$r -> $s\n" if ($debug); - - $data =~ s/($start_delim)($r)$end_delim/$1$s$3/g; -} - -foreach my $r (keys %defines) { - my $s = $defines{$r}; - - $r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g; - - print "$r -> $s\n" if ($debug); - - $data =~ s/($start_delim)($r)$end_delim/$1$s$3/g; -} - -foreach my $r (keys %enum_symbols) { - my $s = $enum_symbols{$r}; - - $r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g; - - print "$r -> $s\n" if ($debug); - - $data =~ s/($start_delim)($r)$end_delim/$1$s$3/g; -} - -foreach my $r (keys %enums) { - my $s = $enums{$r}; - - $r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g; - - print "$r -> $s\n" if ($debug); - - $data =~ s/enum\s+($r)$end_delim/$s$2/g; -} - -foreach my $r (keys %structs) { - my $s = $structs{$r}; - - $r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g; - - print "$r -> $s\n" if ($debug); - - $data =~ s/struct\s+($r)$end_delim/$s$2/g; -} - -foreach my $r (keys %typedefs) { - my $s = $typedefs{$r}; - - $r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g; - - print "$r -> $s\n" if ($debug); - $data =~ s/($start_delim)($r)$end_delim/$1$s$3/g; -} - -$data =~ s/\\ ([\n\s])/\1/g; - -# -# Generate output file -# - -my $title = $file_in; -$title =~ s,.*/,,; - -open OUT, "> $file_out" or die "Can't open $file_out"; -print OUT ".. -*- coding: utf-8; mode: rst -*-\n\n"; -print OUT "$title\n"; -print OUT "=" x length($title); -print OUT "\n\n.. parsed-literal::\n\n"; -print OUT $data; -close OUT; - -__END__ - -=head1 NAME - -parse_headers.pl - parse a C file, in order to identify functions, structs, -enums and defines and create cross-references to a Sphinx book. - -=head1 SYNOPSIS - -B [] [] - -Where can be: --debug, --help or --usage. - -=head1 OPTIONS - -=over 8 - -=item B<--debug> - -Put the script in verbose mode, useful for debugging. - -=item B<--usage> - -Prints a brief help message and exits. - -=item B<--help> - -Prints a more detailed help message and exits. - -=back - -=head1 DESCRIPTION - -Convert a C header or source file (C_FILE), into a ReStructured Text -included via ..parsed-literal block with cross-references for the -documentation files that describe the API. It accepts an optional -EXCEPTIONS_FILE with describes what elements will be either ignored or -be pointed to a non-default reference. - -The output is written at the (OUT_FILE). - -It is capable of identifying defines, functions, structs, typedefs, -enums and enum symbols and create cross-references for all of them. -It is also capable of distinguish #define used for specifying a Linux -ioctl. - -The EXCEPTIONS_FILE contain two rules to allow ignoring a symbol or -to replace the default references by a custom one. - -Please read Documentation/doc-guide/parse-headers.rst at the Kernel's -tree for more details. - -=head1 BUGS - -Report bugs to Mauro Carvalho Chehab - -=head1 COPYRIGHT - -Copyright (c) 2016 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. - -=cut From ba653158f40deccb3f79005bf1d5c6c37d45b247 Mon Sep 17 00:00:00 2001 From: Alperen Aksu Date: Thu, 21 Aug 2025 13:13:47 +0000 Subject: [PATCH 135/193] Documentation/filesystems/xfs: Fix typo error Fixed typo error in referring to the section's headline Fixed to correct spelling of "mapping" Signed-off-by: Alperen Aksu Reviewed-by: Randy Dunlap Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250821131404.25461-1-aksulperen@gmail.com --- Documentation/filesystems/xfs/xfs-online-fsck-design.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/filesystems/xfs/xfs-online-fsck-design.rst b/Documentation/filesystems/xfs/xfs-online-fsck-design.rst index 9fe994353395..8cbcd3c26434 100644 --- a/Documentation/filesystems/xfs/xfs-online-fsck-design.rst +++ b/Documentation/filesystems/xfs/xfs-online-fsck-design.rst @@ -475,7 +475,7 @@ operation, which may cause application failure or an unplanned filesystem shutdown. Inspiration for the secondary metadata repair strategy was drawn from section -2.4 of Srinivasan above, and sections 2 ("NSF: Inded Build Without Side-File") +2.4 of Srinivasan above, and sections 2 ("NSF: Index Build Without Side-File") and 3.1.1 ("Duplicate Key Insert Problem") in C. Mohan, `"Algorithms for Creating Indexes for Very Large Tables Without Quiescing Updates" `_, 1992. @@ -4179,7 +4179,7 @@ When the exchange is initiated, the sequence of operations is as follows: This will be discussed in more detail in subsequent sections. If the filesystem goes down in the middle of an operation, log recovery will -find the most recent unfinished maping exchange log intent item and restart +find the most recent unfinished mapping exchange log intent item and restart from there. This is how atomic file mapping exchanges guarantees that an outside observer will either see the old broken structure or the new one, and never a mismash of From ddfaddc27724fddc07eaf2365ffdd23702f8d8e4 Mon Sep 17 00:00:00 2001 From: Vivek Alurkar Date: Wed, 20 Aug 2025 22:16:21 -0700 Subject: [PATCH 136/193] Fix typo in RAID arrays documentation Changed "write-throuth" to "write-through". Signed-off-by: Vivek Alurkar Reviewed-by: Randy Dunlap Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250821051622.8341-2-primalkenja@gmail.com --- Documentation/admin-guide/md.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/admin-guide/md.rst b/Documentation/admin-guide/md.rst index 4ff2cc291d18..04668272c0ee 100644 --- a/Documentation/admin-guide/md.rst +++ b/Documentation/admin-guide/md.rst @@ -758,7 +758,7 @@ These currently include: journal_mode (currently raid5 only) The cache mode for raid5. raid5 could include an extra disk for - caching. The mode can be "write-throuth" and "write-back". The + caching. The mode can be "write-through" or "write-back". The default is "write-through". ppl_write_hint From 7d1c5e52ec1549adc4394b6e2f38278fc671e522 Mon Sep 17 00:00:00 2001 From: Mallikarjun Thammanavar Date: Tue, 19 Aug 2025 12:46:04 +0000 Subject: [PATCH 137/193] docs: fix spelling and grammar in atomic_writes Fix minor spelling and grammatical issues in the ext4 atomic_writes documentation. Signed-off-by: Mallikarjun Thammanavar Reviewed-by: Randy Dunlap Reviewed-by: Darrick J. Wong Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250819124604.8995-1-mallikarjunst09@gmail.com --- Documentation/filesystems/ext4/atomic_writes.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Documentation/filesystems/ext4/atomic_writes.rst b/Documentation/filesystems/ext4/atomic_writes.rst index aeb47ace738d..ae8995740aa8 100644 --- a/Documentation/filesystems/ext4/atomic_writes.rst +++ b/Documentation/filesystems/ext4/atomic_writes.rst @@ -14,7 +14,7 @@ I/O) on regular files with extents, provided the underlying storage device supports hardware atomic writes. This is supported in the following two ways: 1. **Single-fsblock Atomic Writes**: - EXT4's supports atomic write operations with a single filesystem block since + EXT4 supports atomic write operations with a single filesystem block since v6.13. In this the atomic write unit minimum and maximum sizes are both set to filesystem blocksize. e.g. doing atomic write of 16KB with 16KB filesystem blocksize on 64KB @@ -50,7 +50,7 @@ Multi-fsblock Implementation Details The bigalloc feature changes ext4 to allocate in units of multiple filesystem blocks, also known as clusters. With bigalloc each bit within block bitmap -represents cluster (power of 2 number of blocks) rather than individual +represents a cluster (power of 2 number of blocks) rather than individual filesystem blocks. EXT4 supports multi-fsblock atomic writes with bigalloc, subject to the following constraints. The minimum atomic write size is the larger of the fs @@ -189,7 +189,7 @@ The write must be aligned to the filesystem's block size and not exceed the filesystem's maximum atomic write unit size. See ``generic_atomic_write_valid()`` for more details. -``statx()`` system call with ``STATX_WRITE_ATOMIC`` flag can provides following +``statx()`` system call with ``STATX_WRITE_ATOMIC`` flag can provide following details: * ``stx_atomic_write_unit_min``: Minimum size of an atomic write request. From 69c6739d671df58b9f034b94ac8310f569e2b632 Mon Sep 17 00:00:00 2001 From: Bagas Sanjaya Date: Tue, 19 Aug 2025 13:12:49 +0700 Subject: [PATCH 138/193] Documentation: sharedsubtree: Format remaining of shell snippets as literal code blcoks Fix formatting inconsistency of shell snippets by wrapping the remaining of them in literal code blocks. Signed-off-by: Bagas Sanjaya Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250819061254.31220-2-bagasdotme@gmail.com --- Documentation/filesystems/sharedsubtree.rst | 68 +++++++++++---------- 1 file changed, 37 insertions(+), 31 deletions(-) diff --git a/Documentation/filesystems/sharedsubtree.rst b/Documentation/filesystems/sharedsubtree.rst index 1cf56489ed48..06497c4455b4 100644 --- a/Documentation/filesystems/sharedsubtree.rst +++ b/Documentation/filesystems/sharedsubtree.rst @@ -90,37 +90,42 @@ replicas continue to be exactly same. Here is an example: - Let's say /mnt has a mount which is shared. - # mount --make-shared /mnt + Let's say /mnt has a mount which is shared:: - Let's bind mount /mnt to /tmp - # mount --bind /mnt /tmp + # mount --make-shared /mnt + + Let's bind mount /mnt to /tmp:: + + # mount --bind /mnt /tmp the new mount at /tmp becomes a shared mount and it is a replica of the mount at /mnt. - Now let's make the mount at /tmp; a slave of /mnt - # mount --make-slave /tmp + Now let's make the mount at /tmp; a slave of /mnt:: - let's mount /dev/sd0 on /mnt/a - # mount /dev/sd0 /mnt/a + # mount --make-slave /tmp - #ls /mnt/a - t1 t2 t3 + let's mount /dev/sd0 on /mnt/a:: - #ls /tmp/a - t1 t2 t3 + # mount /dev/sd0 /mnt/a + + # ls /mnt/a + t1 t2 t3 + + # ls /tmp/a + t1 t2 t3 Note the mount event has propagated to the mount at /tmp - However let's see what happens if we mount something on the mount at /tmp + However let's see what happens if we mount something on the mount at + /tmp:: - # mount /dev/sd1 /tmp/b + # mount /dev/sd1 /tmp/b - #ls /tmp/b - s1 s2 s3 + # ls /tmp/b + s1 s2 s3 - #ls /mnt/b + # ls /mnt/b Note how the mount event has not propagated to the mount at /mnt @@ -137,7 +142,7 @@ replicas continue to be exactly same. # mount --make-unbindable /mnt - Let's try to bind mount this mount somewhere else:: + Let's try to bind mount this mount somewhere else:: # mount --bind /mnt /tmp mount: wrong fs type, bad option, bad superblock on /mnt, @@ -471,9 +476,9 @@ replicas continue to be exactly same. 5d) Move semantics - Consider the following command + Consider the following command:: - mount --move A B/b + mount --move A B/b where 'A' is the source mount, 'B' is the destination mount and 'b' is the dentry in the destination mount. @@ -663,9 +668,9 @@ replicas continue to be exactly same. 'B' is the slave of 'A' and 'C' is a slave of 'B' A -> B -> C - at this point if we execute the following command + at this point if we execute the following command:: - mount --bind /bin /tmp/test + mount --bind /bin /tmp/test The mount is attempted on 'A' @@ -706,8 +711,8 @@ replicas continue to be exactly same. / \ tmp usr - And we want to replicate the tree at multiple - mountpoints under /root/tmp + And we want to replicate the tree at multiple + mountpoints under /root/tmp step 2: :: @@ -731,7 +736,7 @@ replicas continue to be exactly same. / m1 - it has two vfsmounts + it has two vfsmounts step 3: :: @@ -739,7 +744,7 @@ replicas continue to be exactly same. mkdir -p /tmp/m2 mount --rbind /root /tmp/m2 - the new tree now looks like this:: + the new tree now looks like this:: root / \ @@ -759,14 +764,15 @@ replicas continue to be exactly same. / \ m1 m2 - it has 6 vfsmounts + it has 6 vfsmounts step 4: - :: + :: + mkdir -p /tmp/m3 mount --rbind /root /tmp/m3 - I won't draw the tree..but it has 24 vfsmounts + I won't draw the tree..but it has 24 vfsmounts at step i the number of vfsmounts is V[i] = i*V[i-1]. @@ -785,8 +791,8 @@ replicas continue to be exactly same. / \ tmp usr - How do we set up the same tree at multiple locations under - /root/tmp + How do we set up the same tree at multiple locations under + /root/tmp step 2: :: From a8886b42d57b8280e0c064779d87030266d9c7ce Mon Sep 17 00:00:00 2001 From: Bagas Sanjaya Date: Tue, 19 Aug 2025 13:12:50 +0700 Subject: [PATCH 139/193] Documentation: sharedsubtree: Use proper enumerator sequence for enumerated lists Sphinx does not recognize mixed-letter sequences (e.g. 2a) as enumerator for enumerated lists. As such, lists that use such sequences end up as definition lists instead. Use proper enumeration sequences for this purpose. Signed-off-by: Bagas Sanjaya Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250819061254.31220-3-bagasdotme@gmail.com --- Documentation/filesystems/sharedsubtree.rst | 40 ++++++++++----------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/Documentation/filesystems/sharedsubtree.rst b/Documentation/filesystems/sharedsubtree.rst index 06497c4455b4..7ad5101b4c03 100644 --- a/Documentation/filesystems/sharedsubtree.rst +++ b/Documentation/filesystems/sharedsubtree.rst @@ -39,8 +39,8 @@ precise d. unbindable mount -2a) A shared mount can be replicated to as many mountpoints and all the -replicas continue to be exactly same. +a) A shared mount can be replicated to as many mountpoints and all the + replicas continue to be exactly same. Here is an example: @@ -83,8 +83,8 @@ replicas continue to be exactly same. contents will be visible under /tmp/a too. -2b) A slave mount is like a shared mount except that mount and umount events - only propagate towards it. +b) A slave mount is like a shared mount except that mount and umount events + only propagate towards it. All slave mounts have a master mount which is a shared. @@ -131,12 +131,12 @@ replicas continue to be exactly same. /mnt -2c) A private mount does not forward or receive propagation. +c) A private mount does not forward or receive propagation. This is the mount we are familiar with. Its the default type. -2d) A unbindable mount is a unbindable private mount +d) A unbindable mount is a unbindable private mount let's say we have a mount at /mnt and we make it unbindable:: @@ -185,7 +185,7 @@ replicas continue to be exactly same. namespaces. B) A process wants its mounts invisible to any other process, but - still be able to see the other system mounts. + still be able to see the other system mounts. Solution: @@ -250,7 +250,7 @@ replicas continue to be exactly same. Note: the word 'vfsmount' and the noun 'mount' have been used to mean the same thing, throughout this document. -5a) Mount states +a) Mount states A given mount can be in one of the following states @@ -360,7 +360,7 @@ replicas continue to be exactly same. the state of a mount depending on type of the destination mount. Its explained in section 5d. -5b) Bind semantics +b) Bind semantics Consider the following command:: @@ -437,7 +437,7 @@ replicas continue to be exactly same. 8. 'A' is a unbindable mount and 'B' is a non-shared mount. This is a invalid operation. A unbindable mount cannot be bind mounted. -5c) Rbind semantics +c) Rbind semantics rbind is same as bind. Bind replicates the specified mount. Rbind replicates all the mounts in the tree belonging to the specified mount. @@ -474,7 +474,7 @@ replicas continue to be exactly same. -5d) Move semantics +d) Move semantics Consider the following command:: @@ -551,7 +551,7 @@ replicas continue to be exactly same. 'A' is mounted on mount 'B' at dentry 'b'. Mount 'A' continues to be a unbindable mount. -5e) Mount semantics +e) Mount semantics Consider the following command:: @@ -564,7 +564,7 @@ replicas continue to be exactly same. that the source mount is always a private mount. -5f) Unmount semantics +f) Unmount semantics Consider the following command:: @@ -598,7 +598,7 @@ replicas continue to be exactly same. to be unmounted and 'C1' has some sub-mounts, the umount operation is failed entirely. -5g) Clone Namespace +g) Clone Namespace A cloned namespace contains all the mounts as that of the parent namespace. @@ -682,18 +682,18 @@ replicas continue to be exactly same. 7) FAQ ------ - Q1. Why is bind mount needed? How is it different from symbolic links? + 1. Why is bind mount needed? How is it different from symbolic links? symbolic links can get stale if the destination mount gets unmounted or moved. Bind mounts continue to exist even if the other mount is unmounted or moved. - Q2. Why can't the shared subtree be implemented using exportfs? + 2. Why can't the shared subtree be implemented using exportfs? exportfs is a heavyweight way of accomplishing part of what shared subtree can do. I cannot imagine a way to implement the semantics of slave mount using exportfs? - Q3 Why is unbindable mount needed? + 3. Why is unbindable mount needed? Let's say we want to replicate the mount tree at multiple locations within the same subtree. @@ -852,7 +852,7 @@ replicas continue to be exactly same. 8) Implementation ----------------- -8A) Datastructure +A) Datastructure 4 new fields are introduced to struct vfsmount: @@ -941,7 +941,7 @@ replicas continue to be exactly same. NOTE: The propagation tree is orthogonal to the mount tree. -8B Locking: +B) Locking: ->mnt_share, ->mnt_slave, ->mnt_slave_list, ->mnt_master are protected by namespace_sem (exclusive for modifications, shared for reading). @@ -953,7 +953,7 @@ replicas continue to be exactly same. The latter holds namespace_sem and the only references to vfsmount are in lists that can't be traversed without namespace_sem. -8C Algorithm: +C) Algorithm: The crux of the implementation resides in rbind/move operation. From 570924bf17de3e0c86c0502e8a20f6017e17bbb2 Mon Sep 17 00:00:00 2001 From: Bagas Sanjaya Date: Tue, 19 Aug 2025 13:12:51 +0700 Subject: [PATCH 140/193] Documentation: sharedsubtree: Don't repeat lists with explanation Don't repeat lists only mentioning the items when a corresponding list with item's explanations suffices. Signed-off-by: Bagas Sanjaya Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250819061254.31220-4-bagasdotme@gmail.com --- Documentation/filesystems/sharedsubtree.rst | 106 ++++++++------------ 1 file changed, 44 insertions(+), 62 deletions(-) diff --git a/Documentation/filesystems/sharedsubtree.rst b/Documentation/filesystems/sharedsubtree.rst index 7ad5101b4c03..64858ff0471b 100644 --- a/Documentation/filesystems/sharedsubtree.rst +++ b/Documentation/filesystems/sharedsubtree.rst @@ -31,15 +31,10 @@ and versioned filesystem. ----------- Shared subtree provides four different flavors of mounts; struct vfsmount to be -precise - - a. shared mount - b. slave mount - c. private mount - d. unbindable mount +precise: -a) A shared mount can be replicated to as many mountpoints and all the +a) A **shared mount** can be replicated to as many mountpoints and all the replicas continue to be exactly same. Here is an example: @@ -83,7 +78,7 @@ a) A shared mount can be replicated to as many mountpoints and all the contents will be visible under /tmp/a too. -b) A slave mount is like a shared mount except that mount and umount events +b) A **slave mount** is like a shared mount except that mount and umount events only propagate towards it. All slave mounts have a master mount which is a shared. @@ -131,12 +126,13 @@ b) A slave mount is like a shared mount except that mount and umount events /mnt -c) A private mount does not forward or receive propagation. +c) A **private mount** does not forward or receive propagation. This is the mount we are familiar with. Its the default type. -d) A unbindable mount is a unbindable private mount +d) An **unbindable mount** is, as the name suggests, an unbindable private + mount. let's say we have a mount at /mnt and we make it unbindable:: @@ -252,24 +248,18 @@ d) A unbindable mount is a unbindable private mount a) Mount states - A given mount can be in one of the following states - - 1) shared - 2) slave - 3) shared and slave - 4) private - 5) unbindable - - A 'propagation event' is defined as event generated on a vfsmount + A **propagation event** is defined as event generated on a vfsmount that leads to mount or unmount actions in other vfsmounts. - A 'peer group' is defined as a group of vfsmounts that propagate + A **peer group** is defined as a group of vfsmounts that propagate events to each other. + A given mount can be in one of the following states: + (1) Shared mounts - A 'shared mount' is defined as a vfsmount that belongs to a - 'peer group'. + A **shared mount** is defined as a vfsmount that belongs to a + peer group. For example:: @@ -284,7 +274,7 @@ a) Mount states (2) Slave mounts - A 'slave mount' is defined as a vfsmount that receives + A **slave mount** is defined as a vfsmount that receives propagation events and does not forward propagation events. A slave mount as the name implies has a master mount from which @@ -299,7 +289,7 @@ a) Mount states (3) Shared and Slave - A vfsmount can be both shared as well as slave. This state + A vfsmount can be both **shared** as well as **slave**. This state indicates that the mount is a slave of some vfsmount, and has its own peer group too. This vfsmount receives propagation events from its master vfsmount, and also forwards propagation @@ -318,12 +308,12 @@ a) Mount states (4) Private mount - A 'private mount' is defined as vfsmount that does not + A **private mount** is defined as vfsmount that does not receive or forward any propagation events. (5) Unbindable mount - A 'unbindable mount' is defined as vfsmount that does not + A **unbindable mount** is defined as vfsmount that does not receive or forward any propagation events and cannot be bind mounted. @@ -854,31 +844,26 @@ g) Clone Namespace A) Datastructure - 4 new fields are introduced to struct vfsmount: - - * ->mnt_share - * ->mnt_slave_list - * ->mnt_slave - * ->mnt_master + Several new fields are introduced to struct vfsmount: ->mnt_share - links together all the mount to/from which this vfsmount + Links together all the mount to/from which this vfsmount send/receives propagation events. ->mnt_slave_list - links all the mounts to which this vfsmount propagates + Links all the mounts to which this vfsmount propagates to. ->mnt_slave - links together all the slaves that its master vfsmount + Links together all the slaves that its master vfsmount propagates to. ->mnt_master - points to the master vfsmount from which this vfsmount + Points to the master vfsmount from which this vfsmount receives propagation. ->mnt_flags - takes two more flags to indicate the propagation status of + Takes two more flags to indicate the propagation status of the vfsmount. MNT_SHARE indicates that the vfsmount is a shared vfsmount. MNT_UNCLONABLE indicates that the vfsmount cannot be replicated. @@ -960,39 +945,36 @@ C) Algorithm: The overall algorithm breaks the operation into 3 phases: (look at attach_recursive_mnt() and propagate_mnt()) - 1. prepare phase. - 2. commit phases. - 3. abort phases. + 1. Prepare phase. - Prepare phase: + For each mount in the source tree: - for each mount in the source tree: + a) Create the necessary number of mount trees to + be attached to each of the mounts that receive + propagation from the destination mount. + b) Do not attach any of the trees to its destination. + However note down its ->mnt_parent and ->mnt_mountpoint + c) Link all the new mounts to form a propagation tree that + is identical to the propagation tree of the destination + mount. - a) Create the necessary number of mount trees to - be attached to each of the mounts that receive - propagation from the destination mount. - b) Do not attach any of the trees to its destination. - However note down its ->mnt_parent and ->mnt_mountpoint - c) Link all the new mounts to form a propagation tree that - is identical to the propagation tree of the destination - mount. + If this phase is successful, there should be 'n' new + propagation trees; where 'n' is the number of mounts in the + source tree. Go to the commit phase - If this phase is successful, there should be 'n' new - propagation trees; where 'n' is the number of mounts in the - source tree. Go to the commit phase + Also there should be 'm' new mount trees, where 'm' is + the number of mounts to which the destination mount + propagates to. - Also there should be 'm' new mount trees, where 'm' is - the number of mounts to which the destination mount - propagates to. + If any memory allocations fail, go to the abort phase. - if any memory allocations fail, go to the abort phase. + 2. Commit phase. - Commit phase - attach each of the mount trees to their corresponding - destination mounts. + Attach each of the mount trees to their corresponding + destination mounts. - Abort phase - delete all the newly created trees. + 3. Abort phase. + Delete all the newly created trees. .. Note:: all the propagation related functionality resides in the file pnode.c From b293fd55a1b8925b9b0578dca88d93eaaa6942c5 Mon Sep 17 00:00:00 2001 From: Bagas Sanjaya Date: Tue, 19 Aug 2025 13:12:52 +0700 Subject: [PATCH 141/193] Documentation: sharedsubtree: Align text The docs make heavy use of lists. As it is currently written, these generate a lot of unnecessary hanging indents since these are not semantically meant to be definition lists by accident. Align text to trim these indents. Signed-off-by: Bagas Sanjaya Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250819061254.31220-5-bagasdotme@gmail.com --- Documentation/filesystems/sharedsubtree.rst | 1247 ++++++++++--------- 1 file changed, 624 insertions(+), 623 deletions(-) diff --git a/Documentation/filesystems/sharedsubtree.rst b/Documentation/filesystems/sharedsubtree.rst index 64858ff0471b..b09650e28534 100644 --- a/Documentation/filesystems/sharedsubtree.rst +++ b/Documentation/filesystems/sharedsubtree.rst @@ -37,947 +37,948 @@ precise: a) A **shared mount** can be replicated to as many mountpoints and all the replicas continue to be exactly same. - Here is an example: + Here is an example: - Let's say /mnt has a mount that is shared:: + Let's say /mnt has a mount that is shared:: - mount --make-shared /mnt + # mount --make-shared /mnt - Note: mount(8) command now supports the --make-shared flag, - so the sample 'smount' program is no longer needed and has been - removed. + Note: mount(8) command now supports the --make-shared flag, + so the sample 'smount' program is no longer needed and has been + removed. - :: + :: - # mount --bind /mnt /tmp + # mount --bind /mnt /tmp - The above command replicates the mount at /mnt to the mountpoint /tmp - and the contents of both the mounts remain identical. + The above command replicates the mount at /mnt to the mountpoint /tmp + and the contents of both the mounts remain identical. - :: + :: - #ls /mnt - a b c + #ls /mnt + a b c - #ls /tmp - a b c + #ls /tmp + a b c - Now let's say we mount a device at /tmp/a:: + Now let's say we mount a device at /tmp/a:: - # mount /dev/sd0 /tmp/a + # mount /dev/sd0 /tmp/a - #ls /tmp/a - t1 t2 t3 + # ls /tmp/a + t1 t2 t3 - #ls /mnt/a - t1 t2 t3 + # ls /mnt/a + t1 t2 t3 - Note that the mount has propagated to the mount at /mnt as well. + Note that the mount has propagated to the mount at /mnt as well. - And the same is true even when /dev/sd0 is mounted on /mnt/a. The - contents will be visible under /tmp/a too. + And the same is true even when /dev/sd0 is mounted on /mnt/a. The + contents will be visible under /tmp/a too. b) A **slave mount** is like a shared mount except that mount and umount events only propagate towards it. - All slave mounts have a master mount which is a shared. + All slave mounts have a master mount which is a shared. - Here is an example: + Here is an example: - Let's say /mnt has a mount which is shared:: + Let's say /mnt has a mount which is shared:: - # mount --make-shared /mnt + # mount --make-shared /mnt - Let's bind mount /mnt to /tmp:: + Let's bind mount /mnt to /tmp:: - # mount --bind /mnt /tmp + # mount --bind /mnt /tmp - the new mount at /tmp becomes a shared mount and it is a replica of - the mount at /mnt. + the new mount at /tmp becomes a shared mount and it is a replica of + the mount at /mnt. - Now let's make the mount at /tmp; a slave of /mnt:: + Now let's make the mount at /tmp; a slave of /mnt:: - # mount --make-slave /tmp + # mount --make-slave /tmp - let's mount /dev/sd0 on /mnt/a:: + let's mount /dev/sd0 on /mnt/a:: - # mount /dev/sd0 /mnt/a + # mount /dev/sd0 /mnt/a - # ls /mnt/a - t1 t2 t3 + # ls /mnt/a + t1 t2 t3 - # ls /tmp/a - t1 t2 t3 + # ls /tmp/a + t1 t2 t3 - Note the mount event has propagated to the mount at /tmp + Note the mount event has propagated to the mount at /tmp - However let's see what happens if we mount something on the mount at - /tmp:: + However let's see what happens if we mount something on the mount at + /tmp:: - # mount /dev/sd1 /tmp/b + # mount /dev/sd1 /tmp/b - # ls /tmp/b - s1 s2 s3 + # ls /tmp/b + s1 s2 s3 - # ls /mnt/b + # ls /mnt/b - Note how the mount event has not propagated to the mount at - /mnt + Note how the mount event has not propagated to the mount at + /mnt c) A **private mount** does not forward or receive propagation. - This is the mount we are familiar with. Its the default type. + This is the mount we are familiar with. Its the default type. d) An **unbindable mount** is, as the name suggests, an unbindable private mount. - let's say we have a mount at /mnt and we make it unbindable:: + let's say we have a mount at /mnt and we make it unbindable:: - # mount --make-unbindable /mnt + # mount --make-unbindable /mnt - Let's try to bind mount this mount somewhere else:: + Let's try to bind mount this mount somewhere else:: - # mount --bind /mnt /tmp - mount: wrong fs type, bad option, bad superblock on /mnt, - or too many mounted file systems + # mount --bind /mnt /tmp mount: wrong fs type, bad option, bad + superblock on /mnt, or too many mounted file systems - Binding a unbindable mount is a invalid operation. + Binding a unbindable mount is a invalid operation. 3) Setting mount states ----------------------- - The mount command (util-linux package) can be used to set mount - states:: +The mount command (util-linux package) can be used to set mount +states:: - mount --make-shared mountpoint - mount --make-slave mountpoint - mount --make-private mountpoint - mount --make-unbindable mountpoint + mount --make-shared mountpoint + mount --make-slave mountpoint + mount --make-private mountpoint + mount --make-unbindable mountpoint 4) Use cases ------------ - A) A process wants to clone its own namespace, but still wants to - access the CD that got mounted recently. +A) A process wants to clone its own namespace, but still wants to + access the CD that got mounted recently. - Solution: + Solution: - The system administrator can make the mount at /cdrom shared:: + The system administrator can make the mount at /cdrom shared:: - mount --bind /cdrom /cdrom - mount --make-shared /cdrom + mount --bind /cdrom /cdrom + mount --make-shared /cdrom - Now any process that clones off a new namespace will have a - mount at /cdrom which is a replica of the same mount in the - parent namespace. + Now any process that clones off a new namespace will have a + mount at /cdrom which is a replica of the same mount in the + parent namespace. - So when a CD is inserted and mounted at /cdrom that mount gets - propagated to the other mount at /cdrom in all the other clone - namespaces. + So when a CD is inserted and mounted at /cdrom that mount gets + propagated to the other mount at /cdrom in all the other clone + namespaces. - B) A process wants its mounts invisible to any other process, but - still be able to see the other system mounts. +B) A process wants its mounts invisible to any other process, but + still be able to see the other system mounts. - Solution: + Solution: - To begin with, the administrator can mark the entire mount tree - as shareable:: + To begin with, the administrator can mark the entire mount tree + as shareable:: - mount --make-rshared / + mount --make-rshared / - A new process can clone off a new namespace. And mark some part - of its namespace as slave:: + A new process can clone off a new namespace. And mark some part + of its namespace as slave:: - mount --make-rslave /myprivatetree + mount --make-rslave /myprivatetree - Hence forth any mounts within the /myprivatetree done by the - process will not show up in any other namespace. However mounts - done in the parent namespace under /myprivatetree still shows - up in the process's namespace. + Hence forth any mounts within the /myprivatetree done by the + process will not show up in any other namespace. However mounts + done in the parent namespace under /myprivatetree still shows + up in the process's namespace. - Apart from the above semantics this feature provides the - building blocks to solve the following problems: +Apart from the above semantics this feature provides the +building blocks to solve the following problems: - C) Per-user namespace +C) Per-user namespace - The above semantics allows a way to share mounts across - namespaces. But namespaces are associated with processes. If - namespaces are made first class objects with user API to - associate/disassociate a namespace with userid, then each user - could have his/her own namespace and tailor it to his/her - requirements. This needs to be supported in PAM. + The above semantics allows a way to share mounts across + namespaces. But namespaces are associated with processes. If + namespaces are made first class objects with user API to + associate/disassociate a namespace with userid, then each user + could have his/her own namespace and tailor it to his/her + requirements. This needs to be supported in PAM. - D) Versioned files +D) Versioned files - If the entire mount tree is visible at multiple locations, then - an underlying versioning file system can return different - versions of the file depending on the path used to access that - file. + If the entire mount tree is visible at multiple locations, then + an underlying versioning file system can return different + versions of the file depending on the path used to access that + file. - An example is:: + An example is:: - mount --make-shared / - mount --rbind / /view/v1 - mount --rbind / /view/v2 - mount --rbind / /view/v3 - mount --rbind / /view/v4 + mount --make-shared / + mount --rbind / /view/v1 + mount --rbind / /view/v2 + mount --rbind / /view/v3 + mount --rbind / /view/v4 - and if /usr has a versioning filesystem mounted, then that - mount appears at /view/v1/usr, /view/v2/usr, /view/v3/usr and - /view/v4/usr too + and if /usr has a versioning filesystem mounted, then that + mount appears at /view/v1/usr, /view/v2/usr, /view/v3/usr and + /view/v4/usr too - A user can request v3 version of the file /usr/fs/namespace.c - by accessing /view/v3/usr/fs/namespace.c . The underlying - versioning filesystem can then decipher that v3 version of the - filesystem is being requested and return the corresponding - inode. + A user can request v3 version of the file /usr/fs/namespace.c + by accessing /view/v3/usr/fs/namespace.c . The underlying + versioning filesystem can then decipher that v3 version of the + filesystem is being requested and return the corresponding + inode. 5) Detailed semantics --------------------- - The section below explains the detailed semantics of - bind, rbind, move, mount, umount and clone-namespace operations. +The section below explains the detailed semantics of +bind, rbind, move, mount, umount and clone-namespace operations. - Note: the word 'vfsmount' and the noun 'mount' have been used - to mean the same thing, throughout this document. +Note: the word 'vfsmount' and the noun 'mount' have been used +to mean the same thing, throughout this document. a) Mount states - A **propagation event** is defined as event generated on a vfsmount - that leads to mount or unmount actions in other vfsmounts. + A **propagation event** is defined as event generated on a vfsmount + that leads to mount or unmount actions in other vfsmounts. - A **peer group** is defined as a group of vfsmounts that propagate - events to each other. + A **peer group** is defined as a group of vfsmounts that propagate + events to each other. - A given mount can be in one of the following states: + A given mount can be in one of the following states: - (1) Shared mounts + (1) Shared mounts - A **shared mount** is defined as a vfsmount that belongs to a - peer group. + A **shared mount** is defined as a vfsmount that belongs to a + peer group. - For example:: + For example:: - mount --make-shared /mnt - mount --bind /mnt /tmp + mount --make-shared /mnt + mount --bind /mnt /tmp - The mount at /mnt and that at /tmp are both shared and belong - to the same peer group. Anything mounted or unmounted under - /mnt or /tmp reflect in all the other mounts of its peer - group. + The mount at /mnt and that at /tmp are both shared and belong + to the same peer group. Anything mounted or unmounted under + /mnt or /tmp reflect in all the other mounts of its peer + group. - (2) Slave mounts + (2) Slave mounts - A **slave mount** is defined as a vfsmount that receives - propagation events and does not forward propagation events. + A **slave mount** is defined as a vfsmount that receives + propagation events and does not forward propagation events. - A slave mount as the name implies has a master mount from which - mount/unmount events are received. Events do not propagate from - the slave mount to the master. Only a shared mount can be made - a slave by executing the following command:: + A slave mount as the name implies has a master mount from which + mount/unmount events are received. Events do not propagate from + the slave mount to the master. Only a shared mount can be made + a slave by executing the following command:: - mount --make-slave mount + mount --make-slave mount - A shared mount that is made as a slave is no more shared unless - modified to become shared. + A shared mount that is made as a slave is no more shared unless + modified to become shared. - (3) Shared and Slave + (3) Shared and Slave - A vfsmount can be both **shared** as well as **slave**. This state - indicates that the mount is a slave of some vfsmount, and - has its own peer group too. This vfsmount receives propagation - events from its master vfsmount, and also forwards propagation - events to its 'peer group' and to its slave vfsmounts. + A vfsmount can be both **shared** as well as **slave**. This state + indicates that the mount is a slave of some vfsmount, and + has its own peer group too. This vfsmount receives propagation + events from its master vfsmount, and also forwards propagation + events to its 'peer group' and to its slave vfsmounts. - Strictly speaking, the vfsmount is shared having its own - peer group, and this peer-group is a slave of some other - peer group. + Strictly speaking, the vfsmount is shared having its own + peer group, and this peer-group is a slave of some other + peer group. - Only a slave vfsmount can be made as 'shared and slave' by - either executing the following command:: + Only a slave vfsmount can be made as 'shared and slave' by + either executing the following command:: - mount --make-shared mount + mount --make-shared mount - or by moving the slave vfsmount under a shared vfsmount. + or by moving the slave vfsmount under a shared vfsmount. - (4) Private mount + (4) Private mount - A **private mount** is defined as vfsmount that does not - receive or forward any propagation events. + A **private mount** is defined as vfsmount that does not + receive or forward any propagation events. - (5) Unbindable mount + (5) Unbindable mount - A **unbindable mount** is defined as vfsmount that does not - receive or forward any propagation events and cannot - be bind mounted. + A **unbindable mount** is defined as vfsmount that does not + receive or forward any propagation events and cannot + be bind mounted. - State diagram: + State diagram: - The state diagram below explains the state transition of a mount, - in response to various commands:: + The state diagram below explains the state transition of a mount, + in response to various commands:: - ----------------------------------------------------------------------- - | |make-shared | make-slave | make-private |make-unbindab| - --------------|------------|--------------|--------------|-------------| - |shared |shared |*slave/private| private | unbindable | - | | | | | | - |-------------|------------|--------------|--------------|-------------| - |slave |shared | **slave | private | unbindable | - | |and slave | | | | - |-------------|------------|--------------|--------------|-------------| - |shared |shared | slave | private | unbindable | - |and slave |and slave | | | | - |-------------|------------|--------------|--------------|-------------| - |private |shared | **private | private | unbindable | - |-------------|------------|--------------|--------------|-------------| - |unbindable |shared |**unbindable | private | unbindable | - ------------------------------------------------------------------------ + ----------------------------------------------------------------------- + | |make-shared | make-slave | make-private |make-unbindab| + --------------|------------|--------------|--------------|-------------| + |shared |shared |*slave/private| private | unbindable | + | | | | | | + |-------------|------------|--------------|--------------|-------------| + |slave |shared | **slave | private | unbindable | + | |and slave | | | | + |-------------|------------|--------------|--------------|-------------| + |shared |shared | slave | private | unbindable | + |and slave |and slave | | | | + |-------------|------------|--------------|--------------|-------------| + |private |shared | **private | private | unbindable | + |-------------|------------|--------------|--------------|-------------| + |unbindable |shared |**unbindable | private | unbindable | + ------------------------------------------------------------------------ - * if the shared mount is the only mount in its peer group, making it - slave, makes it private automatically. Note that there is no master to - which it can be slaved to. + * if the shared mount is the only mount in its peer group, making it + slave, makes it private automatically. Note that there is no master to + which it can be slaved to. - ** slaving a non-shared mount has no effect on the mount. + ** slaving a non-shared mount has no effect on the mount. - Apart from the commands listed below, the 'move' operation also changes - the state of a mount depending on type of the destination mount. Its - explained in section 5d. + Apart from the commands listed below, the 'move' operation also changes + the state of a mount depending on type of the destination mount. Its + explained in section 5d. b) Bind semantics - Consider the following command:: + Consider the following command:: - mount --bind A/a B/b + mount --bind A/a B/b - where 'A' is the source mount, 'a' is the dentry in the mount 'A', 'B' - is the destination mount and 'b' is the dentry in the destination mount. + where 'A' is the source mount, 'a' is the dentry in the mount 'A', 'B' + is the destination mount and 'b' is the dentry in the destination mount. - The outcome depends on the type of mount of 'A' and 'B'. The table - below contains quick reference:: + The outcome depends on the type of mount of 'A' and 'B'. The table + below contains quick reference:: - -------------------------------------------------------------------------- - | BIND MOUNT OPERATION | - |************************************************************************| - |source(A)->| shared | private | slave | unbindable | - | dest(B) | | | | | - | | | | | | | - | v | | | | | - |************************************************************************| - | shared | shared | shared | shared & slave | invalid | - | | | | | | - |non-shared| shared | private | slave | invalid | - ************************************************************************** + -------------------------------------------------------------------------- + | BIND MOUNT OPERATION | + |************************************************************************| + |source(A)->| shared | private | slave | unbindable | + | dest(B) | | | | | + | | | | | | | + | v | | | | | + |************************************************************************| + | shared | shared | shared | shared & slave | invalid | + | | | | | | + |non-shared| shared | private | slave | invalid | + ************************************************************************** - Details: + Details: - 1. 'A' is a shared mount and 'B' is a shared mount. A new mount 'C' - which is clone of 'A', is created. Its root dentry is 'a' . 'C' is - mounted on mount 'B' at dentry 'b'. Also new mount 'C1', 'C2', 'C3' ... - are created and mounted at the dentry 'b' on all mounts where 'B' - propagates to. A new propagation tree containing 'C1',..,'Cn' is - created. This propagation tree is identical to the propagation tree of - 'B'. And finally the peer-group of 'C' is merged with the peer group - of 'A'. + 1. 'A' is a shared mount and 'B' is a shared mount. A new mount 'C' + which is clone of 'A', is created. Its root dentry is 'a' . 'C' is + mounted on mount 'B' at dentry 'b'. Also new mount 'C1', 'C2', 'C3' ... + are created and mounted at the dentry 'b' on all mounts where 'B' + propagates to. A new propagation tree containing 'C1',..,'Cn' is + created. This propagation tree is identical to the propagation tree of + 'B'. And finally the peer-group of 'C' is merged with the peer group + of 'A'. - 2. 'A' is a private mount and 'B' is a shared mount. A new mount 'C' - which is clone of 'A', is created. Its root dentry is 'a'. 'C' is - mounted on mount 'B' at dentry 'b'. Also new mount 'C1', 'C2', 'C3' ... - are created and mounted at the dentry 'b' on all mounts where 'B' - propagates to. A new propagation tree is set containing all new mounts - 'C', 'C1', .., 'Cn' with exactly the same configuration as the - propagation tree for 'B'. + 2. 'A' is a private mount and 'B' is a shared mount. A new mount 'C' + which is clone of 'A', is created. Its root dentry is 'a'. 'C' is + mounted on mount 'B' at dentry 'b'. Also new mount 'C1', 'C2', 'C3' ... + are created and mounted at the dentry 'b' on all mounts where 'B' + propagates to. A new propagation tree is set containing all new mounts + 'C', 'C1', .., 'Cn' with exactly the same configuration as the + propagation tree for 'B'. - 3. 'A' is a slave mount of mount 'Z' and 'B' is a shared mount. A new - mount 'C' which is clone of 'A', is created. Its root dentry is 'a' . - 'C' is mounted on mount 'B' at dentry 'b'. Also new mounts 'C1', 'C2', - 'C3' ... are created and mounted at the dentry 'b' on all mounts where - 'B' propagates to. A new propagation tree containing the new mounts - 'C','C1',.. 'Cn' is created. This propagation tree is identical to the - propagation tree for 'B'. And finally the mount 'C' and its peer group - is made the slave of mount 'Z'. In other words, mount 'C' is in the - state 'slave and shared'. + 3. 'A' is a slave mount of mount 'Z' and 'B' is a shared mount. A new + mount 'C' which is clone of 'A', is created. Its root dentry is 'a' . + 'C' is mounted on mount 'B' at dentry 'b'. Also new mounts 'C1', 'C2', + 'C3' ... are created and mounted at the dentry 'b' on all mounts where + 'B' propagates to. A new propagation tree containing the new mounts + 'C','C1',.. 'Cn' is created. This propagation tree is identical to the + propagation tree for 'B'. And finally the mount 'C' and its peer group + is made the slave of mount 'Z'. In other words, mount 'C' is in the + state 'slave and shared'. - 4. 'A' is a unbindable mount and 'B' is a shared mount. This is a - invalid operation. + 4. 'A' is a unbindable mount and 'B' is a shared mount. This is a + invalid operation. - 5. 'A' is a private mount and 'B' is a non-shared(private or slave or - unbindable) mount. A new mount 'C' which is clone of 'A', is created. - Its root dentry is 'a'. 'C' is mounted on mount 'B' at dentry 'b'. + 5. 'A' is a private mount and 'B' is a non-shared(private or slave or + unbindable) mount. A new mount 'C' which is clone of 'A', is created. + Its root dentry is 'a'. 'C' is mounted on mount 'B' at dentry 'b'. - 6. 'A' is a shared mount and 'B' is a non-shared mount. A new mount 'C' - which is a clone of 'A' is created. Its root dentry is 'a'. 'C' is - mounted on mount 'B' at dentry 'b'. 'C' is made a member of the - peer-group of 'A'. + 6. 'A' is a shared mount and 'B' is a non-shared mount. A new mount 'C' + which is a clone of 'A' is created. Its root dentry is 'a'. 'C' is + mounted on mount 'B' at dentry 'b'. 'C' is made a member of the + peer-group of 'A'. - 7. 'A' is a slave mount of mount 'Z' and 'B' is a non-shared mount. A - new mount 'C' which is a clone of 'A' is created. Its root dentry is - 'a'. 'C' is mounted on mount 'B' at dentry 'b'. Also 'C' is set as a - slave mount of 'Z'. In other words 'A' and 'C' are both slave mounts of - 'Z'. All mount/unmount events on 'Z' propagates to 'A' and 'C'. But - mount/unmount on 'A' do not propagate anywhere else. Similarly - mount/unmount on 'C' do not propagate anywhere else. + 7. 'A' is a slave mount of mount 'Z' and 'B' is a non-shared mount. A + new mount 'C' which is a clone of 'A' is created. Its root dentry is + 'a'. 'C' is mounted on mount 'B' at dentry 'b'. Also 'C' is set as a + slave mount of 'Z'. In other words 'A' and 'C' are both slave mounts of + 'Z'. All mount/unmount events on 'Z' propagates to 'A' and 'C'. But + mount/unmount on 'A' do not propagate anywhere else. Similarly + mount/unmount on 'C' do not propagate anywhere else. - 8. 'A' is a unbindable mount and 'B' is a non-shared mount. This is a - invalid operation. A unbindable mount cannot be bind mounted. + 8. 'A' is a unbindable mount and 'B' is a non-shared mount. This is a + invalid operation. A unbindable mount cannot be bind mounted. c) Rbind semantics - rbind is same as bind. Bind replicates the specified mount. Rbind - replicates all the mounts in the tree belonging to the specified mount. - Rbind mount is bind mount applied to all the mounts in the tree. + rbind is same as bind. Bind replicates the specified mount. Rbind + replicates all the mounts in the tree belonging to the specified mount. + Rbind mount is bind mount applied to all the mounts in the tree. - If the source tree that is rbind has some unbindable mounts, - then the subtree under the unbindable mount is pruned in the new - location. + If the source tree that is rbind has some unbindable mounts, + then the subtree under the unbindable mount is pruned in the new + location. - eg: + eg: - let's say we have the following mount tree:: + let's say we have the following mount tree:: - A - / \ - B C - / \ / \ - D E F G + A + / \ + B C + / \ / \ + D E F G - Let's say all the mount except the mount C in the tree are - of a type other than unbindable. + Let's say all the mount except the mount C in the tree are + of a type other than unbindable. - If this tree is rbound to say Z + If this tree is rbound to say Z - We will have the following tree at the new location:: + We will have the following tree at the new location:: - Z - | - A' - / - B' Note how the tree under C is pruned - / \ in the new location. - D' E' + Z + | + A' + / + B' Note how the tree under C is pruned + / \ in the new location. + D' E' d) Move semantics - Consider the following command:: + Consider the following command:: - mount --move A B/b + mount --move A B/b - where 'A' is the source mount, 'B' is the destination mount and 'b' is - the dentry in the destination mount. + where 'A' is the source mount, 'B' is the destination mount and 'b' is + the dentry in the destination mount. - The outcome depends on the type of the mount of 'A' and 'B'. The table - below is a quick reference:: + The outcome depends on the type of the mount of 'A' and 'B'. The table + below is a quick reference:: - --------------------------------------------------------------------------- - | MOVE MOUNT OPERATION | - |************************************************************************** - | source(A)->| shared | private | slave | unbindable | - | dest(B) | | | | | - | | | | | | | - | v | | | | | - |************************************************************************** - | shared | shared | shared |shared and slave| invalid | - | | | | | | - |non-shared| shared | private | slave | unbindable | - *************************************************************************** + --------------------------------------------------------------------------- + | MOVE MOUNT OPERATION | + |************************************************************************** + | source(A)->| shared | private | slave | unbindable | + | dest(B) | | | | | + | | | | | | | + | v | | | | | + |************************************************************************** + | shared | shared | shared |shared and slave| invalid | + | | | | | | + |non-shared| shared | private | slave | unbindable | + *************************************************************************** - .. Note:: moving a mount residing under a shared mount is invalid. + .. Note:: moving a mount residing under a shared mount is invalid. - Details follow: + Details follow: - 1. 'A' is a shared mount and 'B' is a shared mount. The mount 'A' is - mounted on mount 'B' at dentry 'b'. Also new mounts 'A1', 'A2'...'An' - are created and mounted at dentry 'b' on all mounts that receive - propagation from mount 'B'. A new propagation tree is created in the - exact same configuration as that of 'B'. This new propagation tree - contains all the new mounts 'A1', 'A2'... 'An'. And this new - propagation tree is appended to the already existing propagation tree - of 'A'. + 1. 'A' is a shared mount and 'B' is a shared mount. The mount 'A' is + mounted on mount 'B' at dentry 'b'. Also new mounts 'A1', 'A2'...'An' + are created and mounted at dentry 'b' on all mounts that receive + propagation from mount 'B'. A new propagation tree is created in the + exact same configuration as that of 'B'. This new propagation tree + contains all the new mounts 'A1', 'A2'... 'An'. And this new + propagation tree is appended to the already existing propagation tree + of 'A'. - 2. 'A' is a private mount and 'B' is a shared mount. The mount 'A' is - mounted on mount 'B' at dentry 'b'. Also new mount 'A1', 'A2'... 'An' - are created and mounted at dentry 'b' on all mounts that receive - propagation from mount 'B'. The mount 'A' becomes a shared mount and a - propagation tree is created which is identical to that of - 'B'. This new propagation tree contains all the new mounts 'A1', - 'A2'... 'An'. + 2. 'A' is a private mount and 'B' is a shared mount. The mount 'A' is + mounted on mount 'B' at dentry 'b'. Also new mount 'A1', 'A2'... 'An' + are created and mounted at dentry 'b' on all mounts that receive + propagation from mount 'B'. The mount 'A' becomes a shared mount and a + propagation tree is created which is identical to that of + 'B'. This new propagation tree contains all the new mounts 'A1', + 'A2'... 'An'. - 3. 'A' is a slave mount of mount 'Z' and 'B' is a shared mount. The - mount 'A' is mounted on mount 'B' at dentry 'b'. Also new mounts 'A1', - 'A2'... 'An' are created and mounted at dentry 'b' on all mounts that - receive propagation from mount 'B'. A new propagation tree is created - in the exact same configuration as that of 'B'. This new propagation - tree contains all the new mounts 'A1', 'A2'... 'An'. And this new - propagation tree is appended to the already existing propagation tree of - 'A'. Mount 'A' continues to be the slave mount of 'Z' but it also - becomes 'shared'. + 3. 'A' is a slave mount of mount 'Z' and 'B' is a shared mount. The + mount 'A' is mounted on mount 'B' at dentry 'b'. Also new mounts 'A1', + 'A2'... 'An' are created and mounted at dentry 'b' on all mounts that + receive propagation from mount 'B'. A new propagation tree is created + in the exact same configuration as that of 'B'. This new propagation + tree contains all the new mounts 'A1', 'A2'... 'An'. And this new + propagation tree is appended to the already existing propagation tree of + 'A'. Mount 'A' continues to be the slave mount of 'Z' but it also + becomes 'shared'. - 4. 'A' is a unbindable mount and 'B' is a shared mount. The operation - is invalid. Because mounting anything on the shared mount 'B' can - create new mounts that get mounted on the mounts that receive - propagation from 'B'. And since the mount 'A' is unbindable, cloning - it to mount at other mountpoints is not possible. + 4. 'A' is a unbindable mount and 'B' is a shared mount. The operation + is invalid. Because mounting anything on the shared mount 'B' can + create new mounts that get mounted on the mounts that receive + propagation from 'B'. And since the mount 'A' is unbindable, cloning + it to mount at other mountpoints is not possible. - 5. 'A' is a private mount and 'B' is a non-shared(private or slave or - unbindable) mount. The mount 'A' is mounted on mount 'B' at dentry 'b'. + 5. 'A' is a private mount and 'B' is a non-shared(private or slave or + unbindable) mount. The mount 'A' is mounted on mount 'B' at dentry 'b'. - 6. 'A' is a shared mount and 'B' is a non-shared mount. The mount 'A' - is mounted on mount 'B' at dentry 'b'. Mount 'A' continues to be a - shared mount. + 6. 'A' is a shared mount and 'B' is a non-shared mount. The mount 'A' + is mounted on mount 'B' at dentry 'b'. Mount 'A' continues to be a + shared mount. - 7. 'A' is a slave mount of mount 'Z' and 'B' is a non-shared mount. - The mount 'A' is mounted on mount 'B' at dentry 'b'. Mount 'A' - continues to be a slave mount of mount 'Z'. + 7. 'A' is a slave mount of mount 'Z' and 'B' is a non-shared mount. + The mount 'A' is mounted on mount 'B' at dentry 'b'. Mount 'A' + continues to be a slave mount of mount 'Z'. - 8. 'A' is a unbindable mount and 'B' is a non-shared mount. The mount - 'A' is mounted on mount 'B' at dentry 'b'. Mount 'A' continues to be a - unbindable mount. + 8. 'A' is a unbindable mount and 'B' is a non-shared mount. The mount + 'A' is mounted on mount 'B' at dentry 'b'. Mount 'A' continues to be a + unbindable mount. e) Mount semantics - Consider the following command:: + Consider the following command:: - mount device B/b + mount device B/b - 'B' is the destination mount and 'b' is the dentry in the destination - mount. + 'B' is the destination mount and 'b' is the dentry in the destination + mount. - The above operation is the same as bind operation with the exception - that the source mount is always a private mount. + The above operation is the same as bind operation with the exception + that the source mount is always a private mount. f) Unmount semantics - Consider the following command:: + Consider the following command:: - umount A + umount A - where 'A' is a mount mounted on mount 'B' at dentry 'b'. + where 'A' is a mount mounted on mount 'B' at dentry 'b'. - If mount 'B' is shared, then all most-recently-mounted mounts at dentry - 'b' on mounts that receive propagation from mount 'B' and does not have - sub-mounts within them are unmounted. + If mount 'B' is shared, then all most-recently-mounted mounts at dentry + 'b' on mounts that receive propagation from mount 'B' and does not have + sub-mounts within them are unmounted. - Example: Let's say 'B1', 'B2', 'B3' are shared mounts that propagate to - each other. + Example: Let's say 'B1', 'B2', 'B3' are shared mounts that propagate to + each other. - let's say 'A1', 'A2', 'A3' are first mounted at dentry 'b' on mount - 'B1', 'B2' and 'B3' respectively. + let's say 'A1', 'A2', 'A3' are first mounted at dentry 'b' on mount + 'B1', 'B2' and 'B3' respectively. - let's say 'C1', 'C2', 'C3' are next mounted at the same dentry 'b' on - mount 'B1', 'B2' and 'B3' respectively. + let's say 'C1', 'C2', 'C3' are next mounted at the same dentry 'b' on + mount 'B1', 'B2' and 'B3' respectively. - if 'C1' is unmounted, all the mounts that are most-recently-mounted on - 'B1' and on the mounts that 'B1' propagates-to are unmounted. + if 'C1' is unmounted, all the mounts that are most-recently-mounted on + 'B1' and on the mounts that 'B1' propagates-to are unmounted. - 'B1' propagates to 'B2' and 'B3'. And the most recently mounted mount - on 'B2' at dentry 'b' is 'C2', and that of mount 'B3' is 'C3'. + 'B1' propagates to 'B2' and 'B3'. And the most recently mounted mount + on 'B2' at dentry 'b' is 'C2', and that of mount 'B3' is 'C3'. - So all 'C1', 'C2' and 'C3' should be unmounted. + So all 'C1', 'C2' and 'C3' should be unmounted. - If any of 'C2' or 'C3' has some child mounts, then that mount is not - unmounted, but all other mounts are unmounted. However if 'C1' is told - to be unmounted and 'C1' has some sub-mounts, the umount operation is - failed entirely. + If any of 'C2' or 'C3' has some child mounts, then that mount is not + unmounted, but all other mounts are unmounted. However if 'C1' is told + to be unmounted and 'C1' has some sub-mounts, the umount operation is + failed entirely. g) Clone Namespace - A cloned namespace contains all the mounts as that of the parent - namespace. + A cloned namespace contains all the mounts as that of the parent + namespace. - Let's say 'A' and 'B' are the corresponding mounts in the parent and the - child namespace. + Let's say 'A' and 'B' are the corresponding mounts in the parent and the + child namespace. - If 'A' is shared, then 'B' is also shared and 'A' and 'B' propagate to - each other. + If 'A' is shared, then 'B' is also shared and 'A' and 'B' propagate to + each other. - If 'A' is a slave mount of 'Z', then 'B' is also the slave mount of - 'Z'. + If 'A' is a slave mount of 'Z', then 'B' is also the slave mount of + 'Z'. - If 'A' is a private mount, then 'B' is a private mount too. + If 'A' is a private mount, then 'B' is a private mount too. - If 'A' is unbindable mount, then 'B' is a unbindable mount too. + If 'A' is unbindable mount, then 'B' is a unbindable mount too. 6) Quiz ------- - A. What is the result of the following command sequence? +A. What is the result of the following command sequence? - :: + :: - mount --bind /mnt /mnt - mount --make-shared /mnt - mount --bind /mnt /tmp - mount --move /tmp /mnt/1 + mount --bind /mnt /mnt + mount --make-shared /mnt + mount --bind /mnt /tmp + mount --move /tmp /mnt/1 - what should be the contents of /mnt /mnt/1 /mnt/1/1 should be? - Should they all be identical? or should /mnt and /mnt/1 be - identical only? + what should be the contents of /mnt /mnt/1 /mnt/1/1 should be? + Should they all be identical? or should /mnt and /mnt/1 be + identical only? - B. What is the result of the following command sequence? +B. What is the result of the following command sequence? - :: + :: - mount --make-rshared / - mkdir -p /v/1 - mount --rbind / /v/1 + mount --make-rshared / + mkdir -p /v/1 + mount --rbind / /v/1 - what should be the content of /v/1/v/1 be? + what should be the content of /v/1/v/1 be? - C. What is the result of the following command sequence? +C. What is the result of the following command sequence? - :: + :: - mount --bind /mnt /mnt - mount --make-shared /mnt - mkdir -p /mnt/1/2/3 /mnt/1/test - mount --bind /mnt/1 /tmp - mount --make-slave /mnt - mount --make-shared /mnt - mount --bind /mnt/1/2 /tmp1 - mount --make-slave /mnt + mount --bind /mnt /mnt + mount --make-shared /mnt + mkdir -p /mnt/1/2/3 /mnt/1/test + mount --bind /mnt/1 /tmp + mount --make-slave /mnt + mount --make-shared /mnt + mount --bind /mnt/1/2 /tmp1 + mount --make-slave /mnt - At this point we have the first mount at /tmp and - its root dentry is 1. Let's call this mount 'A' - And then we have a second mount at /tmp1 with root - dentry 2. Let's call this mount 'B' - Next we have a third mount at /mnt with root dentry - mnt. Let's call this mount 'C' + At this point we have the first mount at /tmp and + its root dentry is 1. Let's call this mount 'A' + And then we have a second mount at /tmp1 with root + dentry 2. Let's call this mount 'B' + Next we have a third mount at /mnt with root dentry + mnt. Let's call this mount 'C' - 'B' is the slave of 'A' and 'C' is a slave of 'B' - A -> B -> C + 'B' is the slave of 'A' and 'C' is a slave of 'B' + A -> B -> C - at this point if we execute the following command:: + at this point if we execute the following command:: - mount --bind /bin /tmp/test + mount --bind /bin /tmp/test - The mount is attempted on 'A' + The mount is attempted on 'A' - will the mount propagate to 'B' and 'C' ? + will the mount propagate to 'B' and 'C' ? - what would be the contents of - /mnt/1/test be? + what would be the contents of + /mnt/1/test be? 7) FAQ ------ - 1. Why is bind mount needed? How is it different from symbolic links? - symbolic links can get stale if the destination mount gets - unmounted or moved. Bind mounts continue to exist even if the - other mount is unmounted or moved. +1. Why is bind mount needed? How is it different from symbolic links? - 2. Why can't the shared subtree be implemented using exportfs? + symbolic links can get stale if the destination mount gets + unmounted or moved. Bind mounts continue to exist even if the + other mount is unmounted or moved. - exportfs is a heavyweight way of accomplishing part of what - shared subtree can do. I cannot imagine a way to implement the - semantics of slave mount using exportfs? +2. Why can't the shared subtree be implemented using exportfs? - 3. Why is unbindable mount needed? + exportfs is a heavyweight way of accomplishing part of what + shared subtree can do. I cannot imagine a way to implement the + semantics of slave mount using exportfs? - Let's say we want to replicate the mount tree at multiple - locations within the same subtree. +3. Why is unbindable mount needed? - if one rbind mounts a tree within the same subtree 'n' times - the number of mounts created is an exponential function of 'n'. - Having unbindable mount can help prune the unneeded bind - mounts. Here is an example. + Let's say we want to replicate the mount tree at multiple + locations within the same subtree. - step 1: - let's say the root tree has just two directories with - one vfsmount:: + if one rbind mounts a tree within the same subtree 'n' times + the number of mounts created is an exponential function of 'n'. + Having unbindable mount can help prune the unneeded bind + mounts. Here is an example. - root - / \ - tmp usr + step 1: + let's say the root tree has just two directories with + one vfsmount:: - And we want to replicate the tree at multiple - mountpoints under /root/tmp + root + / \ + tmp usr - step 2: - :: + And we want to replicate the tree at multiple + mountpoints under /root/tmp + + step 2: + :: - mount --make-shared /root + mount --make-shared /root - mkdir -p /tmp/m1 + mkdir -p /tmp/m1 - mount --rbind /root /tmp/m1 + mount --rbind /root /tmp/m1 - the new tree now looks like this:: + the new tree now looks like this:: - root - / \ - tmp usr - / - m1 - / \ - tmp usr - / - m1 + root + / \ + tmp usr + / + m1 + / \ + tmp usr + / + m1 - it has two vfsmounts + it has two vfsmounts - step 3: - :: + step 3: + :: - mkdir -p /tmp/m2 - mount --rbind /root /tmp/m2 + mkdir -p /tmp/m2 + mount --rbind /root /tmp/m2 - the new tree now looks like this:: + the new tree now looks like this:: - root - / \ - tmp usr - / \ - m1 m2 - / \ / \ - tmp usr tmp usr - / \ / - m1 m2 m1 - / \ / \ - tmp usr tmp usr - / / \ - m1 m1 m2 - / \ - tmp usr - / \ - m1 m2 + root + / \ + tmp usr + / \ + m1 m2 + / \ / \ + tmp usr tmp usr + / \ / + m1 m2 m1 + / \ / \ + tmp usr tmp usr + / / \ + m1 m1 m2 + / \ + tmp usr + / \ + m1 m2 - it has 6 vfsmounts + it has 6 vfsmounts - step 4: - :: + step 4: + :: - mkdir -p /tmp/m3 - mount --rbind /root /tmp/m3 + mkdir -p /tmp/m3 + mount --rbind /root /tmp/m3 - I won't draw the tree..but it has 24 vfsmounts + I won't draw the tree..but it has 24 vfsmounts - at step i the number of vfsmounts is V[i] = i*V[i-1]. - This is an exponential function. And this tree has way more - mounts than what we really needed in the first place. + at step i the number of vfsmounts is V[i] = i*V[i-1]. + This is an exponential function. And this tree has way more + mounts than what we really needed in the first place. - One could use a series of umount at each step to prune - out the unneeded mounts. But there is a better solution. - Unclonable mounts come in handy here. + One could use a series of umount at each step to prune + out the unneeded mounts. But there is a better solution. + Unclonable mounts come in handy here. - step 1: - let's say the root tree has just two directories with - one vfsmount:: + step 1: + let's say the root tree has just two directories with + one vfsmount:: - root - / \ - tmp usr + root + / \ + tmp usr - How do we set up the same tree at multiple locations under - /root/tmp + How do we set up the same tree at multiple locations under + /root/tmp - step 2: - :: + step 2: + :: - mount --bind /root/tmp /root/tmp + mount --bind /root/tmp /root/tmp - mount --make-rshared /root - mount --make-unbindable /root/tmp + mount --make-rshared /root + mount --make-unbindable /root/tmp - mkdir -p /tmp/m1 + mkdir -p /tmp/m1 - mount --rbind /root /tmp/m1 + mount --rbind /root /tmp/m1 - the new tree now looks like this:: + the new tree now looks like this:: - root - / \ - tmp usr - / - m1 - / \ - tmp usr + root + / \ + tmp usr + / + m1 + / \ + tmp usr - step 3: - :: + step 3: + :: - mkdir -p /tmp/m2 - mount --rbind /root /tmp/m2 + mkdir -p /tmp/m2 + mount --rbind /root /tmp/m2 - the new tree now looks like this:: + the new tree now looks like this:: - root - / \ - tmp usr - / \ - m1 m2 - / \ / \ - tmp usr tmp usr + root + / \ + tmp usr + / \ + m1 m2 + / \ / \ + tmp usr tmp usr - step 4: - :: + step 4: + :: - mkdir -p /tmp/m3 - mount --rbind /root /tmp/m3 + mkdir -p /tmp/m3 + mount --rbind /root /tmp/m3 - the new tree now looks like this:: + the new tree now looks like this:: - root - / \ - tmp usr - / \ \ - m1 m2 m3 - / \ / \ / \ - tmp usr tmp usr tmp usr + root + / \ + tmp usr + / \ \ + m1 m2 m3 + / \ / \ / \ + tmp usr tmp usr tmp usr 8) Implementation ----------------- A) Datastructure - Several new fields are introduced to struct vfsmount: + Several new fields are introduced to struct vfsmount: - ->mnt_share - Links together all the mount to/from which this vfsmount - send/receives propagation events. + ->mnt_share + Links together all the mount to/from which this vfsmount + send/receives propagation events. - ->mnt_slave_list - Links all the mounts to which this vfsmount propagates - to. + ->mnt_slave_list + Links all the mounts to which this vfsmount propagates + to. - ->mnt_slave - Links together all the slaves that its master vfsmount - propagates to. + ->mnt_slave + Links together all the slaves that its master vfsmount + propagates to. - ->mnt_master - Points to the master vfsmount from which this vfsmount - receives propagation. + ->mnt_master + Points to the master vfsmount from which this vfsmount + receives propagation. - ->mnt_flags - Takes two more flags to indicate the propagation status of - the vfsmount. MNT_SHARE indicates that the vfsmount is a shared - vfsmount. MNT_UNCLONABLE indicates that the vfsmount cannot be - replicated. + ->mnt_flags + Takes two more flags to indicate the propagation status of + the vfsmount. MNT_SHARE indicates that the vfsmount is a shared + vfsmount. MNT_UNCLONABLE indicates that the vfsmount cannot be + replicated. - All the shared vfsmounts in a peer group form a cyclic list through - ->mnt_share. + All the shared vfsmounts in a peer group form a cyclic list through + ->mnt_share. - All vfsmounts with the same ->mnt_master form on a cyclic list anchored - in ->mnt_master->mnt_slave_list and going through ->mnt_slave. + All vfsmounts with the same ->mnt_master form on a cyclic list anchored + in ->mnt_master->mnt_slave_list and going through ->mnt_slave. - ->mnt_master can point to arbitrary (and possibly different) members - of master peer group. To find all immediate slaves of a peer group - you need to go through _all_ ->mnt_slave_list of its members. - Conceptually it's just a single set - distribution among the - individual lists does not affect propagation or the way propagation - tree is modified by operations. + ->mnt_master can point to arbitrary (and possibly different) members + of master peer group. To find all immediate slaves of a peer group + you need to go through _all_ ->mnt_slave_list of its members. + Conceptually it's just a single set - distribution among the + individual lists does not affect propagation or the way propagation + tree is modified by operations. - All vfsmounts in a peer group have the same ->mnt_master. If it is - non-NULL, they form a contiguous (ordered) segment of slave list. + All vfsmounts in a peer group have the same ->mnt_master. If it is + non-NULL, they form a contiguous (ordered) segment of slave list. - A example propagation tree looks as shown in the figure below. - [ NOTE: Though it looks like a forest, if we consider all the shared - mounts as a conceptual entity called 'pnode', it becomes a tree]:: + A example propagation tree looks as shown in the figure below. + [ NOTE: Though it looks like a forest, if we consider all the shared + mounts as a conceptual entity called 'pnode', it becomes a tree]:: - A <--> B <--> C <---> D - /|\ /| |\ - / F G J K H I - / - E<-->K - /|\ - M L N + A <--> B <--> C <---> D + /|\ /| |\ + / F G J K H I + / + E<-->K + /|\ + M L N - In the above figure A,B,C and D all are shared and propagate to each - other. 'A' has got 3 slave mounts 'E' 'F' and 'G' 'C' has got 2 slave - mounts 'J' and 'K' and 'D' has got two slave mounts 'H' and 'I'. - 'E' is also shared with 'K' and they propagate to each other. And - 'K' has 3 slaves 'M', 'L' and 'N' + In the above figure A,B,C and D all are shared and propagate to each + other. 'A' has got 3 slave mounts 'E' 'F' and 'G' 'C' has got 2 slave + mounts 'J' and 'K' and 'D' has got two slave mounts 'H' and 'I'. + 'E' is also shared with 'K' and they propagate to each other. And + 'K' has 3 slaves 'M', 'L' and 'N' - A's ->mnt_share links with the ->mnt_share of 'B' 'C' and 'D' + A's ->mnt_share links with the ->mnt_share of 'B' 'C' and 'D' - A's ->mnt_slave_list links with ->mnt_slave of 'E', 'K', 'F' and 'G' + A's ->mnt_slave_list links with ->mnt_slave of 'E', 'K', 'F' and 'G' - E's ->mnt_share links with ->mnt_share of K + E's ->mnt_share links with ->mnt_share of K - 'E', 'K', 'F', 'G' have their ->mnt_master point to struct vfsmount of 'A' + 'E', 'K', 'F', 'G' have their ->mnt_master point to struct vfsmount of 'A' - 'M', 'L', 'N' have their ->mnt_master point to struct vfsmount of 'K' + 'M', 'L', 'N' have their ->mnt_master point to struct vfsmount of 'K' - K's ->mnt_slave_list links with ->mnt_slave of 'M', 'L' and 'N' + K's ->mnt_slave_list links with ->mnt_slave of 'M', 'L' and 'N' - C's ->mnt_slave_list links with ->mnt_slave of 'J' and 'K' + C's ->mnt_slave_list links with ->mnt_slave of 'J' and 'K' - J and K's ->mnt_master points to struct vfsmount of C + J and K's ->mnt_master points to struct vfsmount of C - and finally D's ->mnt_slave_list links with ->mnt_slave of 'H' and 'I' + and finally D's ->mnt_slave_list links with ->mnt_slave of 'H' and 'I' - 'H' and 'I' have their ->mnt_master pointing to struct vfsmount of 'D'. + 'H' and 'I' have their ->mnt_master pointing to struct vfsmount of 'D'. - NOTE: The propagation tree is orthogonal to the mount tree. + NOTE: The propagation tree is orthogonal to the mount tree. B) Locking: - ->mnt_share, ->mnt_slave, ->mnt_slave_list, ->mnt_master are protected - by namespace_sem (exclusive for modifications, shared for reading). + ->mnt_share, ->mnt_slave, ->mnt_slave_list, ->mnt_master are protected + by namespace_sem (exclusive for modifications, shared for reading). - Normally we have ->mnt_flags modifications serialized by vfsmount_lock. - There are two exceptions: do_add_mount() and clone_mnt(). - The former modifies a vfsmount that has not been visible in any shared - data structures yet. - The latter holds namespace_sem and the only references to vfsmount - are in lists that can't be traversed without namespace_sem. + Normally we have ->mnt_flags modifications serialized by vfsmount_lock. + There are two exceptions: do_add_mount() and clone_mnt(). + The former modifies a vfsmount that has not been visible in any shared + data structures yet. + The latter holds namespace_sem and the only references to vfsmount + are in lists that can't be traversed without namespace_sem. C) Algorithm: - The crux of the implementation resides in rbind/move operation. + The crux of the implementation resides in rbind/move operation. - The overall algorithm breaks the operation into 3 phases: (look at - attach_recursive_mnt() and propagate_mnt()) + The overall algorithm breaks the operation into 3 phases: (look at + attach_recursive_mnt() and propagate_mnt()) - 1. Prepare phase. + 1. Prepare phase. - For each mount in the source tree: + For each mount in the source tree: - a) Create the necessary number of mount trees to - be attached to each of the mounts that receive - propagation from the destination mount. - b) Do not attach any of the trees to its destination. - However note down its ->mnt_parent and ->mnt_mountpoint - c) Link all the new mounts to form a propagation tree that - is identical to the propagation tree of the destination - mount. + a) Create the necessary number of mount trees to + be attached to each of the mounts that receive + propagation from the destination mount. + b) Do not attach any of the trees to its destination. + However note down its ->mnt_parent and ->mnt_mountpoint + c) Link all the new mounts to form a propagation tree that + is identical to the propagation tree of the destination + mount. - If this phase is successful, there should be 'n' new - propagation trees; where 'n' is the number of mounts in the - source tree. Go to the commit phase + If this phase is successful, there should be 'n' new + propagation trees; where 'n' is the number of mounts in the + source tree. Go to the commit phase - Also there should be 'm' new mount trees, where 'm' is - the number of mounts to which the destination mount - propagates to. + Also there should be 'm' new mount trees, where 'm' is + the number of mounts to which the destination mount + propagates to. - If any memory allocations fail, go to the abort phase. + If any memory allocations fail, go to the abort phase. - 2. Commit phase. + 2. Commit phase. - Attach each of the mount trees to their corresponding - destination mounts. + Attach each of the mount trees to their corresponding + destination mounts. - 3. Abort phase. - Delete all the newly created trees. + 3. Abort phase. - .. Note:: - all the propagation related functionality resides in the file pnode.c + Delete all the newly created trees. + + .. Note:: + all the propagation related functionality resides in the file pnode.c ------------------------------------------------------------------------ From ec1a37468f15b5fa69ecd01f49a0d818ed559943 Mon Sep 17 00:00:00 2001 From: Bagas Sanjaya Date: Tue, 19 Aug 2025 13:12:53 +0700 Subject: [PATCH 142/193] Documentation: sharedsubtree: Convert notes to note directive While a few of the notes are already in reST syntax, others are left intact (inconsistent). Convert them to reST syntax too. Signed-off-by: Bagas Sanjaya Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250819061254.31220-6-bagasdotme@gmail.com --- Documentation/filesystems/sharedsubtree.rst | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/Documentation/filesystems/sharedsubtree.rst b/Documentation/filesystems/sharedsubtree.rst index b09650e28534..8b7dc9159083 100644 --- a/Documentation/filesystems/sharedsubtree.rst +++ b/Documentation/filesystems/sharedsubtree.rst @@ -43,9 +43,10 @@ a) A **shared mount** can be replicated to as many mountpoints and all the # mount --make-shared /mnt - Note: mount(8) command now supports the --make-shared flag, - so the sample 'smount' program is no longer needed and has been - removed. + .. note:: + mount(8) command now supports the --make-shared flag, + so the sample 'smount' program is no longer needed and has been + removed. :: @@ -242,8 +243,9 @@ D) Versioned files The section below explains the detailed semantics of bind, rbind, move, mount, umount and clone-namespace operations. -Note: the word 'vfsmount' and the noun 'mount' have been used -to mean the same thing, throughout this document. +.. Note:: + the word 'vfsmount' and the noun 'mount' have been used + to mean the same thing, throughout this document. a) Mount states @@ -885,8 +887,12 @@ A) Datastructure non-NULL, they form a contiguous (ordered) segment of slave list. A example propagation tree looks as shown in the figure below. - [ NOTE: Though it looks like a forest, if we consider all the shared - mounts as a conceptual entity called 'pnode', it becomes a tree]:: + + .. note:: + Though it looks like a forest, if we consider all the shared + mounts as a conceptual entity called 'pnode', it becomes a tree. + + :: A <--> B <--> C <---> D From d90e7b56406032a6175e79de3d7e884185f6be71 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 25 Aug 2025 14:04:55 +0200 Subject: [PATCH 143/193] docs: conf.py: drop xindy rule The rule as-is is wrong, as it was inverted. Besides that, after retest building all repos with suggested LaTeX packages given by sphinx-pre-install, I was unable to reproduce the issues I saw with xindy in the past. So, let's just drop. If anyone reports issues with xindy, we may need to readd, but at the right way, e.g. {options}{pkgname}. Reported-by: Akira Yokosawa Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/83068bc31839e7095f1f408e49658362d467797e.1756123459.git.mchehab+huawei@kernel.org --- Documentation/conf.py | 2 -- 1 file changed, 2 deletions(-) diff --git a/Documentation/conf.py b/Documentation/conf.py index 8fcecdb927b1..574896cca198 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -458,8 +458,6 @@ latex_elements = { "papersize": "a4paper", "passoptionstopackages": dedent(r""" \PassOptionsToPackage{svgnames}{xcolor} - % Avoid encoding troubles when creating indexes - \PassOptionsToPackage{xindy}{language=english,codepage=utf8,noautomatic} """), # The font size ('10pt', '11pt' or '12pt'). "pointsize": "11pt", From 8dbb1779ae22e5cd84d807b7023d29791f892a02 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 1 Sep 2025 15:21:21 +0200 Subject: [PATCH 144/193] docs: kernel_include.py: fix an issue when O= is used As reported by Stephen, building docs with O= is now broken. Fix it by ensuring that it will seek files under Kernel source tree. The original logic was defined to accept including files under Documentation/output. The new logic doesn't need it anymore for media, but it might still be useful to preserve the previous behavior. So, I ended preserving it. Reported-by: Stephen Rothwell Closes: https://lore.kernel.org/all/20250901142639.4de35a11@canb.auug.org.au/ Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/da91980ce42f31730dc982920167b2757b9d2769.1756732363.git.mchehab+huawei@kernel.org --- Documentation/sphinx/kernel_include.py | 44 +++++++++++++++++++++++--- 1 file changed, 39 insertions(+), 5 deletions(-) diff --git a/Documentation/sphinx/kernel_include.py b/Documentation/sphinx/kernel_include.py index 23566ab74866..661ed978bed8 100755 --- a/Documentation/sphinx/kernel_include.py +++ b/Documentation/sphinx/kernel_include.py @@ -314,15 +314,49 @@ class KernelInclude(Directive): def run(self): """Include a file as part of the content of this reST file.""" env = self.state.document.settings.env - path = os.path.realpath(os.path.expandvars(self.arguments[0])) - # to get a bit security back, prohibit /etc: - if path.startswith(os.sep + "etc"): - raise self.severe('Problems with "%s" directive, prohibited path: %s' % - (self.name, path)) + # + # The include logic accepts only patches relative to: + # - Kernel source tree + # - Documentation output directory + # + # The logic does check it to prevent directory traverse + # + + srctree = os.path.abspath(os.environ["srctree"]) + + path = os.path.expandvars(self.arguments[0]) + src_path = os.path.join(srctree, path) + + if os.path.isfile(src_path): + base = srctree + path = src_path + elif os.path.exists(arg): + # Allow patches from output dir + base = os.getcwd() + path = os.path.abspath(path) + else: + raise self.warning(f'File "%s" doesn\'t exist', path) + + abs_base = os.path.abspath(base) + abs_full_path = os.path.abspath(os.path.join(base, path)) + + try: + if os.path.commonpath([abs_full_path, abs_base]) != abs_base: + raise self.severe('Problems with "%s" directive, prohibited path: %s' % + (self.name, path)) + except ValueError: + # Paths don't have the same drive (Windows) or other incompatibility + raise self.severe('Problems with "%s" directive, invalid path: %s' % + (self.name, path)) self.arguments[0] = path + # + # Add path location to Sphinx dependencies to ensure proper cache + # invalidation check. + # + env.note_dependency(os.path.abspath(path)) # HINT: I had to copy&paste the whole Include.run method. I'am not happy From 118e54633ca894748f300c0f582f4ae1b6254f8d Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 1 Sep 2025 15:21:22 +0200 Subject: [PATCH 145/193] docs: kernel_include.py: drop some old behavior The old behavior is not using anymore, so let's drop it. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/00cdf3cbe2481aac875c543ded14b5eacfe071ec.1756732363.git.mchehab+huawei@kernel.org --- Documentation/sphinx/kernel_include.py | 17 +++-------------- 1 file changed, 3 insertions(+), 14 deletions(-) diff --git a/Documentation/sphinx/kernel_include.py b/Documentation/sphinx/kernel_include.py index 661ed978bed8..2c4bb8215b4c 100755 --- a/Documentation/sphinx/kernel_include.py +++ b/Documentation/sphinx/kernel_include.py @@ -316,11 +316,9 @@ class KernelInclude(Directive): env = self.state.document.settings.env # - # The include logic accepts only patches relative to: - # - Kernel source tree - # - Documentation output directory - # - # The logic does check it to prevent directory traverse + # The include logic accepts only patches relative to the + # Kernel source tree. The logic does check it to prevent + # directory traverse issues. # srctree = os.path.abspath(os.environ["srctree"]) @@ -331,10 +329,6 @@ class KernelInclude(Directive): if os.path.isfile(src_path): base = srctree path = src_path - elif os.path.exists(arg): - # Allow patches from output dir - base = os.getcwd() - path = os.path.abspath(path) else: raise self.warning(f'File "%s" doesn\'t exist', path) @@ -359,11 +353,6 @@ class KernelInclude(Directive): env.note_dependency(os.path.abspath(path)) - # HINT: I had to copy&paste the whole Include.run method. I'am not happy - # with this, but due to security reasons, the Include.run method does - # not allow absolute or relative pathnames pointing to locations *above* - # the filesystem tree where the reST document is placed. - if not self.state.document.settings.file_insertion_enabled: raise self.warning('"%s" directive disabled.' % self.name) source = self.state_machine.input_lines.source(self.lineno - From d5958c8a09d583273d6713cd9f6da4412a2f45e6 Mon Sep 17 00:00:00 2001 From: Ryan Chung Date: Sun, 31 Aug 2025 19:17:28 +0900 Subject: [PATCH 146/193] tracing: rephrase for clearer documentation Signed-off-by: Ryan Chung Acked-by: Steven Rostedt (Google) Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250831101736.11519-2-seokwoo.chung130@gmail.com --- Documentation/trace/boottime-trace.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/trace/boottime-trace.rst b/Documentation/trace/boottime-trace.rst index 3efac10adb36..651f3a2c01de 100644 --- a/Documentation/trace/boottime-trace.rst +++ b/Documentation/trace/boottime-trace.rst @@ -19,7 +19,7 @@ this uses bootconfig file to describe tracing feature programming. Options in the Boot Config ========================== -Here is the list of available options list for boot time tracing in +Here is the list of available options for boot time tracing in boot config file [1]_. All options are under "ftrace." or "kernel." prefix. See kernel parameters for the options which starts with "kernel." prefix [2]_. From b65988af71af62b81bbc6af0cbe05b18eaef4da5 Mon Sep 17 00:00:00 2001 From: Ryan Chung Date: Sun, 31 Aug 2025 19:17:29 +0900 Subject: [PATCH 147/193] tracing: fix grammar error in debugging.rst Signed-off-by: Ryan Chung Acked-by: Steven Rostedt (Google) Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250831101736.11519-3-seokwoo.chung130@gmail.com --- Documentation/trace/debugging.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/trace/debugging.rst b/Documentation/trace/debugging.rst index d54bc500af80..4d88c346fc38 100644 --- a/Documentation/trace/debugging.rst +++ b/Documentation/trace/debugging.rst @@ -59,7 +59,7 @@ There is various methods of acquiring the state of the system when a kernel crash occurs. This could be from the oops message in printk, or one could use kexec/kdump. But these just show what happened at the time of the crash. It can be very useful in knowing what happened up to the point of the crash. -The tracing ring buffer, by default, is a circular buffer than will +The tracing ring buffer, by default, is a circular buffer that will overwrite older events with newer ones. When a crash happens, the content of the ring buffer will be all the events that lead up to the crash. From a4c2ff6e507ebb47761865289772494e717d035a Mon Sep 17 00:00:00 2001 From: Ranganath V N Date: Wed, 3 Sep 2025 01:08:22 +0530 Subject: [PATCH 148/193] Documentation: Fix spelling mistakes Corrected a few spelling mistakes to improve the readability. Signed-off-by: Ranganath V N Acked-by: Rob Herring (Arm) Reviewed-by: Randy Dunlap Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250902193822.6349-1-vnranganath.20@gmail.com --- Documentation/devicetree/bindings/submitting-patches.rst | 2 +- Documentation/filesystems/iomap/operations.rst | 2 +- Documentation/virt/kvm/review-checklist.rst | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/Documentation/devicetree/bindings/submitting-patches.rst b/Documentation/devicetree/bindings/submitting-patches.rst index 46d0b036c97e..191085b0d5e8 100644 --- a/Documentation/devicetree/bindings/submitting-patches.rst +++ b/Documentation/devicetree/bindings/submitting-patches.rst @@ -66,7 +66,7 @@ I. For patch submitters any DTS patches, regardless whether using existing or new bindings, should be placed at the end of patchset to indicate no dependency of drivers on the DTS. DTS will be anyway applied through separate tree or branch, so - different order would indicate the serie is non-bisectable. + different order would indicate the series is non-bisectable. If a driver subsystem maintainer prefers to apply entire set, instead of their relevant portion of patchset, please split the DTS patches into diff --git a/Documentation/filesystems/iomap/operations.rst b/Documentation/filesystems/iomap/operations.rst index 067ed8e14ef3..387fd9cc72ca 100644 --- a/Documentation/filesystems/iomap/operations.rst +++ b/Documentation/filesystems/iomap/operations.rst @@ -321,7 +321,7 @@ The fields are as follows: - ``writeback_submit``: Submit the previous built writeback context. Block based file systems should use the iomap_ioend_writeback_submit helper, other file system can implement their own. - File systems can optionall to hook into writeback bio submission. + File systems can optionally hook into writeback bio submission. This might include pre-write space accounting updates, or installing a custom ``->bi_end_io`` function for internal purposes, such as deferring the ioend completion to a workqueue to run metadata update diff --git a/Documentation/virt/kvm/review-checklist.rst b/Documentation/virt/kvm/review-checklist.rst index debac54e14e7..053f00c50d66 100644 --- a/Documentation/virt/kvm/review-checklist.rst +++ b/Documentation/virt/kvm/review-checklist.rst @@ -98,7 +98,7 @@ New APIs It is important to demonstrate your use case. This can be as simple as explaining that the feature is already in use on bare metal, or it can be a proof-of-concept implementation in userspace. The latter need not be - open source, though that is of course preferrable for easier testing. + open source, though that is of course preferable for easier testing. Selftests should test corner cases of the APIs, and should also cover basic host and guest operation if no open source VMM uses the feature. From 3f65aa8ede2377c47c11f1c38b44226b8ca60477 Mon Sep 17 00:00:00 2001 From: Harshit Mogalapalli Date: Sun, 31 Aug 2025 08:11:18 -0700 Subject: [PATCH 149/193] Documentation: dev-tools: Fix a typo in autofdo documentation Use "cat /proc/cpuinfo" instead of "cat proc/cpuinfo". Signed-off-by: Harshit Mogalapalli Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250831151118.1274826-1-harshit.m.mogalapalli@oracle.com --- Documentation/dev-tools/autofdo.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/dev-tools/autofdo.rst b/Documentation/dev-tools/autofdo.rst index 1f0a451e9ccd..bcf06e7d6ffa 100644 --- a/Documentation/dev-tools/autofdo.rst +++ b/Documentation/dev-tools/autofdo.rst @@ -131,11 +131,11 @@ Here is an example workflow for AutoFDO kernel: For Zen3:: - $ cat proc/cpuinfo | grep " brs" + $ cat /proc/cpuinfo | grep " brs" For Zen4:: - $ cat proc/cpuinfo | grep amd_lbr_v2 + $ cat /proc/cpuinfo | grep amd_lbr_v2 The following command generated the perf data file:: From 0df41b1b9488f1e85ceb2307639e29ebb1d7ba64 Mon Sep 17 00:00:00 2001 From: Vegard Nossum Date: Sat, 30 Aug 2025 19:08:08 +0200 Subject: [PATCH 150/193] docs: sphinx: remove SPDX/copyright comments from HTML output Use Jinja2 comments instead of HTML comments for the SPDX and copyright lines. This prevents them from appearing in the HTML output, which was never the intention; the HTML output has its own copyright line at the bottom of the document. Signed-off-by: Vegard Nossum Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250830170808.3911151-1-vegard.nossum@oracle.com --- Documentation/sphinx/templates/kernel-toc.html | 3 ++- Documentation/sphinx/templates/translations.html | 4 ++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/Documentation/sphinx/templates/kernel-toc.html b/Documentation/sphinx/templates/kernel-toc.html index 41f1efbe64bb..b84969bd31c4 100644 --- a/Documentation/sphinx/templates/kernel-toc.html +++ b/Documentation/sphinx/templates/kernel-toc.html @@ -1,4 +1,5 @@ - +{# SPDX-License-Identifier: GPL-2.0 #} + {# Create a local TOC the kernel way #}

Contents

diff --git a/Documentation/sphinx/templates/translations.html b/Documentation/sphinx/templates/translations.html index 8df5d42d8dcd..351586f41938 100644 --- a/Documentation/sphinx/templates/translations.html +++ b/Documentation/sphinx/templates/translations.html @@ -1,5 +1,5 @@ - - +{# SPDX-License-Identifier: GPL-2.0 #} +{# Copyright © 2023, Oracle and/or its affiliates. #} {# Create a language menu for translations #} {% if languages|length > 0: %} From 0059f3b82fe713481a1ccfe28ebe6a2489e77df3 Mon Sep 17 00:00:00 2001 From: Zenghui Yu Date: Wed, 27 Aug 2025 22:47:38 +0800 Subject: [PATCH 151/193] docs: admin-guide: Fix typo in nfsroot.rst There is an obvious mistake in nfsroot.rst where pxelinux was wrongly written as pxeliunx. Fix it. Signed-off-by: Zenghui Yu Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250827144738.43361-1-zenghui.yu@linux.dev --- Documentation/admin-guide/nfs/nfsroot.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/admin-guide/nfs/nfsroot.rst b/Documentation/admin-guide/nfs/nfsroot.rst index 135218f33394..06990309c6ff 100644 --- a/Documentation/admin-guide/nfs/nfsroot.rst +++ b/Documentation/admin-guide/nfs/nfsroot.rst @@ -342,7 +342,7 @@ They depend on various facilities being available: When using pxelinux, the kernel image is specified using "kernel ". The nfsroot parameters are passed to the kernel by adding them to the "append" line. - It is common to use serial console in conjunction with pxeliunx, + It is common to use serial console in conjunction with pxelinux, see Documentation/admin-guide/serial-console.rst for more information. For more information on isolinux, including how to create bootdisks From 7e5a0fe4e8ae2eb341f8ebbee2b24231a58fc28b Mon Sep 17 00:00:00 2001 From: Baruch Siach Date: Wed, 27 Aug 2025 14:37:27 +0300 Subject: [PATCH 152/193] doc: filesystems: proc: remove stale information from intro Most of the information in the first paragraph of the Introduction/Credits section is outdated. Documentation update suggestions should go to documentation maintainers listed in MAINTAINERS. Remove misleading contact information. Signed-off-by: Baruch Siach Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/cb4987a16ed96ee86841aec921d914bd44249d0b.1756294647.git.baruch@tkos.co.il --- Documentation/filesystems/proc.rst | 21 --------------------- 1 file changed, 21 deletions(-) diff --git a/Documentation/filesystems/proc.rst b/Documentation/filesystems/proc.rst index 2971551b7235..ede654478dff 100644 --- a/Documentation/filesystems/proc.rst +++ b/Documentation/filesystems/proc.rst @@ -61,19 +61,6 @@ Preface 0.1 Introduction/Credits ------------------------ -This documentation is part of a soon (or so we hope) to be released book on -the SuSE Linux distribution. As there is no complete documentation for the -/proc file system and we've used many freely available sources to write these -chapters, it seems only fair to give the work back to the Linux community. -This work is based on the 2.2.* kernel version and the upcoming 2.4.*. I'm -afraid it's still far from complete, but we hope it will be useful. As far as -we know, it is the first 'all-in-one' document about the /proc file system. It -is focused on the Intel x86 hardware, so if you are looking for PPC, ARM, -SPARC, AXP, etc., features, you probably won't find what you are looking for. -It also only covers IPv4 networking, not IPv6 nor other protocols - sorry. But -additions and patches are welcome and will be added to this document if you -mail them to Bodo. - We'd like to thank Alan Cox, Rik van Riel, and Alexey Kuznetsov and a lot of other people for help compiling this documentation. We'd also like to extend a special thank you to Andi Kleen for documentation, which we relied on heavily @@ -81,17 +68,9 @@ to create this document, as well as the additional information he provided. Thanks to everybody else who contributed source or docs to the Linux kernel and helped create a great piece of software... :) -If you have any comments, corrections or additions, please don't hesitate to -contact Bodo Bauer at bb@ricochet.net. We'll be happy to add them to this -document. - The latest version of this document is available online at https://www.kernel.org/doc/html/latest/filesystems/proc.html -If the above direction does not works for you, you could try the kernel -mailing list at linux-kernel@vger.kernel.org and/or try to reach me at -comandante@zaralinux.com. - 0.2 Legal Stuff --------------- From f874abea20bc381ecf3cab6dad56c5ff66d1a5cc Mon Sep 17 00:00:00 2001 From: Bagas Sanjaya Date: Tue, 9 Sep 2025 09:21:42 +0700 Subject: [PATCH 153/193] Documentation: w1: Fix SPDX comment syntax on masters and slaves toctree index Commit e9bb627561535d ("docs: w1: convert to ReST and add to the kAPI group of docs") converts 1-Wire docs to reST alongside with SPDX comment, yet the comment is written in one dot as opposed to two in order to be recognized as comment directive, which spills it into htmldocs output. This issue is partially fixed in d8fb03e1ea64e7 ("docs: w1: Fix SPDX-License-Identifier syntax") as it only touches top-level w1 toctree. Do the same fix on masters and slaves toctrees. Fixes: e9bb62756153 ("docs: w1: convert to ReST and add to the kAPI group of docs") Signed-off-by: Bagas Sanjaya Reviewed-by: Krzysztof Kozlowski Signed-off-by: Jonathan Corbet Message-ID: <20250909022142.18007-1-bagasdotme@gmail.com> --- Documentation/w1/masters/index.rst | 2 +- Documentation/w1/slaves/index.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/w1/masters/index.rst b/Documentation/w1/masters/index.rst index cc40189909fd..871442c7f195 100644 --- a/Documentation/w1/masters/index.rst +++ b/Documentation/w1/masters/index.rst @@ -1,4 +1,4 @@ -. SPDX-License-Identifier: GPL-2.0 +.. SPDX-License-Identifier: GPL-2.0 ===================== 1-wire Master Drivers diff --git a/Documentation/w1/slaves/index.rst b/Documentation/w1/slaves/index.rst index d0697b202f09..a210f38c889c 100644 --- a/Documentation/w1/slaves/index.rst +++ b/Documentation/w1/slaves/index.rst @@ -1,4 +1,4 @@ -. SPDX-License-Identifier: GPL-2.0 +.. SPDX-License-Identifier: GPL-2.0 ==================== 1-wire Slave Drivers From 2f1c96018b10e6d42280db3a6faa47d80c961b6b Mon Sep 17 00:00:00 2001 From: Vegard Nossum Date: Fri, 5 Sep 2025 16:46:06 +0200 Subject: [PATCH 154/193] docs: add tools/docs/gen-renames.py Add a new script that wraps git to trawl the repository history for renames of .rst files in the Documentation/ directory. Example usage: tools/docs/gen-renames.py --rev v6.17-rc3 > Documentation/.renames.txt The output format is simply: SPACE NEWLINE where neither nor contain the Documentation/ prefix or the .rst suffix. The file is sorted alphabetically. We can suggest rerunning the script for future renames (and squash the resulting change) or rerun it periodically to keep the file up to date. Signed-off-by: Vegard Nossum Signed-off-by: Jonathan Corbet Message-ID: <20250905144608.577449-2-vegard.nossum@oracle.com> --- tools/docs/gen-renames.py | 130 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 130 insertions(+) create mode 100755 tools/docs/gen-renames.py diff --git a/tools/docs/gen-renames.py b/tools/docs/gen-renames.py new file mode 100755 index 000000000000..8cb3b2157d83 --- /dev/null +++ b/tools/docs/gen-renames.py @@ -0,0 +1,130 @@ +#! /usr/bin/env python3 +# SPDX-License-Identifier: GPL-2.0 +# +# Copyright © 2025, Oracle and/or its affiliates. +# Author: Vegard Nossum + +"""Trawl repository history for renames of Documentation/**.rst files. + +Example: + + tools/docs/gen-renames.py --rev HEAD > Documentation/.renames.txt +""" + +import argparse +import itertools +import os +import subprocess +import sys + +parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) +parser.add_argument('--rev', default='HEAD', help='generate renames up to this revision') + +args = parser.parse_args() + +def normalize(path): + prefix = 'Documentation/' + suffix = '.rst' + + assert path.startswith(prefix) + assert path.endswith(suffix) + + return path[len(prefix):-len(suffix)] + +class Name(object): + def __init__(self, name): + self.names = [name] + + def rename(self, new_name): + self.names.append(new_name) + +names = { +} + +for line in subprocess.check_output([ + 'git', 'log', + '--reverse', + '--oneline', + '--find-renames', + '--diff-filter=RD', + '--name-status', + '--format=commit %H', + # ~v4.8-ish is when Sphinx/.rst was added in the first place + f'v4.8..{args.rev}', + '--', + 'Documentation/' +], text=True).splitlines(): + # rename + if line.startswith('R'): + _, old, new = line[1:].split('\t', 2) + + if old.endswith('.rst') and new.endswith('.rst'): + old = normalize(old) + new = normalize(new) + + name = names.get(old) + if name is None: + name = Name(old) + else: + del names[old] + + name.rename(new) + names[new] = name + + continue + + # delete + if line.startswith('D'): + _, old = line.split('\t', 1) + + if old.endswith('.rst'): + old = normalize(old) + + # TODO: we could save added/modified files as well and propose + # them as alternatives + name = names.get(old) + if name is None: + pass + else: + del names[old] + + continue + +# +# Get the set of current files so we can sanity check that we aren't +# redirecting any of those +# + +current_files = set() +for line in subprocess.check_output([ + 'git', 'ls-tree', + '-r', + '--name-only', + args.rev, + 'Documentation/', +], text=True).splitlines(): + if line.endswith('.rst'): + current_files.add(normalize(line)) + +# +# Format/group/output result +# + +result = [] +for _, v in names.items(): + old_names = v.names[:-1] + new_name = v.names[-1] + + for old_name in old_names: + if old_name == new_name: + # A file was renamed to its new name twice; don't redirect that + continue + + if old_name in current_files: + # A file was recreated with a former name; don't redirect those + continue + + result.append((old_name, new_name)) + +for old_name, new_name in sorted(result): + print(f"{old_name} {new_name}") From 4b6fba464322f5850dbcce32f3a25eeebf64e770 Mon Sep 17 00:00:00 2001 From: Vegard Nossum Date: Fri, 5 Sep 2025 16:46:07 +0200 Subject: [PATCH 155/193] docs: add Documentation/.renames.txt This is the result of running: scripts/documentation-gen-renames.py --rev v6.17-rc3 > Documentation/.renames.txt This file records renames in the Documentation/ directory so that we can use it to quickly generate HTML redirects from removed paths. Suggested-by: Jonathan Corbet Signed-off-by: Vegard Nossum Signed-off-by: Jonathan Corbet Message-ID: <20250905144608.577449-3-vegard.nossum@oracle.com> --- Documentation/.renames.txt | 1191 ++++++++++++++++++++++++++++++++++++ 1 file changed, 1191 insertions(+) create mode 100644 Documentation/.renames.txt diff --git a/Documentation/.renames.txt b/Documentation/.renames.txt new file mode 100644 index 000000000000..c0bd5d3dc8b9 --- /dev/null +++ b/Documentation/.renames.txt @@ -0,0 +1,1191 @@ +80211/cfg80211 driver-api/80211/cfg80211 +80211/index driver-api/80211/index +80211/introduction driver-api/80211/introduction +80211/mac80211 driver-api/80211/mac80211 +80211/mac80211-advanced driver-api/80211/mac80211-advanced +EDID/howto admin-guide/edid +PCI/picebus-howto PCI/pciebus-howto +RAS/address-translation admin-guide/RAS/address-translation +RAS/error-decoding admin-guide/RAS/error-decoding +RAS/ras admin-guide/RAS/error-decoding +accelerators/ocxl userspace-api/accelerators/ocxl +admin-guide/gpio/sysfs userspace-api/gpio/sysfs +admin-guide/l1tf admin-guide/hw-vuln/l1tf +admin-guide/media/v4l-with-ir admin-guide/media/remote-controller +admin-guide/ras admin-guide/RAS/main +admin-guide/security-bugs process/security-bugs +aoe/aoe admin-guide/aoe/aoe +aoe/examples admin-guide/aoe/examples +aoe/index admin-guide/aoe/index +aoe/todo admin-guide/aoe/todo +arc/arc arch/arc/arc +arc/features arch/arc/features +arc/index arch/arc/index +arch/x86/resctrl filesystems/resctrl +arm/arm arch/arm/arm +arm/booting arch/arm/booting +arm/cluster-pm-race-avoidance arch/arm/cluster-pm-race-avoidance +arm/features arch/arm/features +arm/firmware arch/arm/firmware +arm/google/chromebook-boot-flow arch/arm/google/chromebook-boot-flow +arm/index arch/arm/index +arm/interrupts arch/arm/interrupts +arm/ixp4xx arch/arm/ixp4xx +arm/kernel_mode_neon arch/arm/kernel_mode_neon +arm/kernel_user_helpers arch/arm/kernel_user_helpers +arm/keystone/knav-qmss arch/arm/keystone/knav-qmss +arm/keystone/overview arch/arm/keystone/overview +arm/marvel arch/arm/marvell +arm/marvell arch/arm/marvell +arm/mem_alignment arch/arm/mem_alignment +arm/memory arch/arm/memory +arm/microchip arch/arm/microchip +arm/netwinder arch/arm/netwinder +arm/nwfpe/index arch/arm/nwfpe/index +arm/nwfpe/netwinder-fpe arch/arm/nwfpe/netwinder-fpe +arm/nwfpe/notes arch/arm/nwfpe/notes +arm/nwfpe/nwfpe arch/arm/nwfpe/nwfpe +arm/nwfpe/todo arch/arm/nwfpe/todo +arm/omap/dss arch/arm/omap/dss +arm/omap/index arch/arm/omap/index +arm/omap/omap arch/arm/omap/omap +arm/omap/omap_pm arch/arm/omap/omap_pm +arm/porting arch/arm/porting +arm/pxa/mfp arch/arm/pxa/mfp +arm/sa1100/assabet arch/arm/sa1100/assabet +arm/sa1100/cerf arch/arm/sa1100/cerf +arm/sa1100/index arch/arm/sa1100/index +arm/sa1100/lart arch/arm/sa1100/lart +arm/sa1100/serial_uart arch/arm/sa1100/serial_uart +arm/samsung/bootloader-interface arch/arm/samsung/bootloader-interface +arm/samsung/gpio arch/arm/samsung/gpio +arm/samsung/index arch/arm/samsung/index +arm/samsung/overview arch/arm/samsung/overview +arm/setup arch/arm/setup +arm/spear/overview arch/arm/spear/overview +arm/sti/overview arch/arm/sti/overview +arm/sti/stih407-overview arch/arm/sti/stih407-overview +arm/sti/stih418-overview arch/arm/sti/stih418-overview +arm/stm32/overview arch/arm/stm32/overview +arm/stm32/stm32-dma-mdma-chaining arch/arm/stm32/stm32-dma-mdma-chaining +arm/stm32/stm32f429-overview arch/arm/stm32/stm32f429-overview +arm/stm32/stm32f746-overview arch/arm/stm32/stm32f746-overview +arm/stm32/stm32f769-overview arch/arm/stm32/stm32f769-overview +arm/stm32/stm32h743-overview arch/arm/stm32/stm32h743-overview +arm/stm32/stm32h750-overview arch/arm/stm32/stm32h750-overview +arm/stm32/stm32mp13-overview arch/arm/stm32/stm32mp13-overview +arm/stm32/stm32mp151-overview arch/arm/stm32/stm32mp151-overview +arm/stm32/stm32mp157-overview arch/arm/stm32/stm32mp157-overview +arm/sunxi arch/arm/sunxi +arm/sunxi/clocks arch/arm/sunxi/clocks +arm/swp_emulation arch/arm/swp_emulation +arm/tcm arch/arm/tcm +arm/uefi arch/arm/uefi +arm/vfp/release-notes arch/arm/vfp/release-notes +arm/vlocks arch/arm/vlocks +arm64/acpi_object_usage arch/arm64/acpi_object_usage +arm64/amu arch/arm64/amu +arm64/arm-acpi arch/arm64/arm-acpi +arm64/asymmetric-32bit arch/arm64/asymmetric-32bit +arm64/booting arch/arm64/booting +arm64/cpu-feature-registers arch/arm64/cpu-feature-registers +arm64/elf_hwcaps arch/arm64/elf_hwcaps +arm64/features arch/arm64/features +arm64/hugetlbpage arch/arm64/hugetlbpage +arm64/index arch/arm64/index +arm64/legacy_instructions arch/arm64/legacy_instructions +arm64/memory arch/arm64/memory +arm64/memory-tagging-extension arch/arm64/memory-tagging-extension +arm64/perf arch/arm64/perf +arm64/pointer-authentication arch/arm64/pointer-authentication +arm64/silicon-errata arch/arm64/silicon-errata +arm64/sme arch/arm64/sme +arm64/sve arch/arm64/sve +arm64/tagged-address-abi arch/arm64/tagged-address-abi +arm64/tagged-pointers arch/arm64/tagged-pointers +asm-annotations core-api/asm-annotations +auxdisplay/lcd-panel-cgram admin-guide/lcd-panel-cgram +backlight/lp855x-driver driver-api/backlight/lp855x-driver +blockdev/drbd/data-structure-v9 admin-guide/blockdev/drbd/data-structure-v9 +blockdev/drbd/figures admin-guide/blockdev/drbd/figures +blockdev/drbd/index admin-guide/blockdev/drbd/index +blockdev/floppy admin-guide/blockdev/floppy +blockdev/index admin-guide/blockdev/index +blockdev/nbd admin-guide/blockdev/nbd +blockdev/paride admin-guide/blockdev/paride +blockdev/ramdisk admin-guide/blockdev/ramdisk +blockdev/zram admin-guide/blockdev/zram +bpf/README bpf/index +bpf/bpf_lsm bpf/prog_lsm +bpf/instruction-set bpf/standardization/instruction-set +bpf/libbpf/libbpf bpf/libbpf/index +bpf/standardization/linux-notes bpf/linux-notes +bus-devices/ti-gpmc driver-api/memory-devices/ti-gpmc +cgroup-v1/blkio-controller admin-guide/cgroup-v1/blkio-controller +cgroup-v1/cgroups admin-guide/cgroup-v1/cgroups +cgroup-v1/cpuacct admin-guide/cgroup-v1/cpuacct +cgroup-v1/cpusets admin-guide/cgroup-v1/cpusets +cgroup-v1/devices admin-guide/cgroup-v1/devices +cgroup-v1/freezer-subsystem admin-guide/cgroup-v1/freezer-subsystem +cgroup-v1/hugetlb admin-guide/cgroup-v1/hugetlb +cgroup-v1/index admin-guide/cgroup-v1/index +cgroup-v1/memcg_test admin-guide/cgroup-v1/memcg_test +cgroup-v1/memory admin-guide/cgroup-v1/memory +cgroup-v1/net_cls admin-guide/cgroup-v1/net_cls +cgroup-v1/net_prio admin-guide/cgroup-v1/net_prio +cgroup-v1/pids admin-guide/cgroup-v1/pids +cgroup-v1/rdma admin-guide/cgroup-v1/rdma +cma/debugfs admin-guide/mm/cma_debugfs +connector/connector driver-api/connector +console/console driver-api/console +core-api/gcc-plugins kbuild/gcc-plugins +core-api/ioctl driver-api/ioctl +core-api/memory-hotplug-notifier core-api/memory-hotplug +dev-tools/gdb-kernel-debugging process/debugging/gdb-kernel-debugging +dev-tools/kgdb process/debugging/kgdb +dev-tools/tools dev-tools/index +development-process/1.Intro process/1.Intro +development-process/2.Process process/2.Process +development-process/3.Early-stage process/3.Early-stage +development-process/4.Coding process/4.Coding +development-process/5.Posting process/5.Posting +development-process/6.Followthrough process/6.Followthrough +development-process/7.AdvancedTopics process/7.AdvancedTopics +development-process/8.Conclusion process/8.Conclusion +development-process/development-process process/development-process +development-process/index process/index +device-mapper/cache admin-guide/device-mapper/cache +device-mapper/cache-policies admin-guide/device-mapper/cache-policies +device-mapper/delay admin-guide/device-mapper/delay +device-mapper/dm-crypt admin-guide/device-mapper/dm-crypt +device-mapper/dm-flakey admin-guide/device-mapper/dm-flakey +device-mapper/dm-init admin-guide/device-mapper/dm-init +device-mapper/dm-integrity admin-guide/device-mapper/dm-integrity +device-mapper/dm-io admin-guide/device-mapper/dm-io +device-mapper/dm-log admin-guide/device-mapper/dm-log +device-mapper/dm-queue-length admin-guide/device-mapper/dm-queue-length +device-mapper/dm-raid admin-guide/device-mapper/dm-raid +device-mapper/dm-service-time admin-guide/device-mapper/dm-service-time +device-mapper/dm-uevent admin-guide/device-mapper/dm-uevent +device-mapper/dm-zoned admin-guide/device-mapper/dm-zoned +device-mapper/era admin-guide/device-mapper/era +device-mapper/index admin-guide/device-mapper/index +device-mapper/kcopyd admin-guide/device-mapper/kcopyd +device-mapper/linear admin-guide/device-mapper/linear +device-mapper/log-writes admin-guide/device-mapper/log-writes +device-mapper/persistent-data admin-guide/device-mapper/persistent-data +device-mapper/snapshot admin-guide/device-mapper/snapshot +device-mapper/statistics admin-guide/device-mapper/statistics +device-mapper/striped admin-guide/device-mapper/striped +device-mapper/switch admin-guide/device-mapper/switch +device-mapper/thin-provisioning admin-guide/device-mapper/thin-provisioning +device-mapper/unstriped admin-guide/device-mapper/unstriped +device-mapper/verity admin-guide/device-mapper/verity +device-mapper/writecache admin-guide/device-mapper/writecache +device-mapper/zero admin-guide/device-mapper/zero +devicetree/writing-schema devicetree/bindings/writing-schema +driver-api/bt8xxgpio driver-api/gpio/bt8xxgpio +driver-api/cxl/access-coordinates driver-api/cxl/linux/access-coordinates +driver-api/cxl/memory-devices driver-api/cxl/theory-of-operation +driver-api/dcdbas userspace-api/dcdbas +driver-api/dell_rbu admin-guide/dell_rbu +driver-api/edid admin-guide/edid +driver-api/gpio driver-api/gpio/index +driver-api/hte/tegra194-hte driver-api/hte/tegra-hte +driver-api/isapnp userspace-api/isapnp +driver-api/media/drivers/v4l-drivers/zoran driver-api/media/drivers/zoran +driver-api/mtd/intel-spi driver-api/mtd/spi-intel +driver-api/pci driver-api/pci/pci +driver-api/pinctl driver-api/pin-control +driver-api/rapidio admin-guide/rapidio +driver-api/serial/moxa-smartio driver-api/tty/moxa-smartio +driver-api/serial/n_gsm driver-api/tty/n_gsm +driver-api/serial/tty driver-api/tty/tty_ldisc +driver-api/thermal/intel_powerclamp admin-guide/thermal/intel_powerclamp +driver-api/usb driver-api/usb/usb +driver-model/binding driver-api/driver-model/binding +driver-model/bus driver-api/driver-model/bus +driver-model/design-patterns driver-api/driver-model/design-patterns +driver-model/device driver-api/driver-model/device +driver-model/devres driver-api/driver-model/devres +driver-model/driver driver-api/driver-model/driver +driver-model/index driver-api/driver-model/index +driver-model/overview driver-api/driver-model/overview +driver-model/platform driver-api/driver-model/platform +driver-model/porting driver-api/driver-model/porting +early-userspace/buffer-format driver-api/early-userspace/buffer-format +early-userspace/early_userspace_support driver-api/early-userspace/early_userspace_support +early-userspace/index driver-api/early-userspace/index +errseq core-api/errseq +filesystems/binderfs admin-guide/binderfs +filesystems/cifs/cifsd filesystems/smb/ksmbd +filesystems/cifs/cifsroot filesystems/smb/cifsroot +filesystems/cifs/index filesystems/smb/index +filesystems/cifs/ksmbd filesystems/smb/ksmbd +filesystems/ext4/ext4 admin-guide/ext4 +filesystems/ext4/ondisk/about filesystems/ext4/about +filesystems/ext4/ondisk/allocators filesystems/ext4/allocators +filesystems/ext4/ondisk/attributes filesystems/ext4/attributes +filesystems/ext4/ondisk/bigalloc filesystems/ext4/bigalloc +filesystems/ext4/ondisk/bitmaps filesystems/ext4/bitmaps +filesystems/ext4/ondisk/blockgroup filesystems/ext4/blockgroup +filesystems/ext4/ondisk/blockmap filesystems/ext4/blockmap +filesystems/ext4/ondisk/blocks filesystems/ext4/blocks +filesystems/ext4/ondisk/checksums filesystems/ext4/checksums +filesystems/ext4/ondisk/directory filesystems/ext4/directory +filesystems/ext4/ondisk/dynamic filesystems/ext4/dynamic +filesystems/ext4/ondisk/eainode filesystems/ext4/eainode +filesystems/ext4/ondisk/globals filesystems/ext4/globals +filesystems/ext4/ondisk/group_descr filesystems/ext4/group_descr +filesystems/ext4/ondisk/ifork filesystems/ext4/ifork +filesystems/ext4/ondisk/inlinedata filesystems/ext4/inlinedata +filesystems/ext4/ondisk/inodes filesystems/ext4/inodes +filesystems/ext4/ondisk/journal filesystems/ext4/journal +filesystems/ext4/ondisk/mmp filesystems/ext4/mmp +filesystems/ext4/ondisk/overview filesystems/ext4/overview +filesystems/ext4/ondisk/special_inodes filesystems/ext4/special_inodes +filesystems/ext4/ondisk/super filesystems/ext4/super +filesystems/sysfs-pci PCI/sysfs-pci +filesystems/sysfs-tagging networking/sysfs-tagging +filesystems/xfs-delayed-logging-design filesystems/xfs/xfs-delayed-logging-design +filesystems/xfs-maintainer-entry-profile filesystems/xfs/xfs-maintainer-entry-profile +filesystems/xfs-online-fsck-design filesystems/xfs/xfs-online-fsck-design +filesystems/xfs-self-describing-metadata filesystems/xfs/xfs-self-describing-metadata +gpio/index admin-guide/gpio/index +gpio/sysfs userspace-api/gpio/sysfs +gpu/amdgpu gpu/amdgpu/index +hte/hte driver-api/hte/hte +hte/index driver-api/hte/index +hte/tegra194-hte driver-api/hte/tegra-hte +input/alps input/devices/alps +input/amijoy input/devices/amijoy +input/appletouch input/devices/appletouch +input/atarikbd input/devices/atarikbd +input/bcm5974 input/devices/bcm5974 +input/cma3000_d0x input/devices/cma3000_d0x +input/cs461x input/devices/cs461x +input/edt-ft5x06 input/devices/edt-ft5x06 +input/elantech input/devices/elantech +input/iforce-protocol input/devices/iforce-protocol +input/joystick input/joydev/joystick +input/joystick-api input/joydev/joystick-api +input/joystick-parport input/devices/joystick-parport +input/ntrig input/devices/ntrig +input/rotary-encoder input/devices/rotary-encoder +input/sentelic input/devices/sentelic +input/walkera0701 input/devices/walkera0701 +input/xpad input/devices/xpad +input/yealink input/devices/yealink +interconnect/interconnect driver-api/interconnect +ioctl/botching-up-ioctls process/botching-up-ioctls +ioctl/cdrom userspace-api/ioctl/cdrom +ioctl/hdio userspace-api/ioctl/hdio +ioctl/index userspace-api/ioctl/index +ioctl/ioctl-decoding userspace-api/ioctl/ioctl-decoding +ioctl/ioctl-number userspace-api/ioctl/ioctl-number +kbuild/namespaces core-api/symbol-namespaces +kdump/index admin-guide/kdump/index +kdump/kdump admin-guide/kdump/kdump +kdump/vmcoreinfo admin-guide/kdump/vmcoreinfo +kernel-documentation doc-guide/kernel-doc +laptops/asus-laptop admin-guide/laptops/asus-laptop +laptops/disk-shock-protection admin-guide/laptops/disk-shock-protection +laptops/index admin-guide/laptops/index +laptops/laptop-mode admin-guide/laptops/laptop-mode +laptops/lg-laptop admin-guide/laptops/lg-laptop +laptops/sony-laptop admin-guide/laptops/sony-laptop +laptops/sonypi admin-guide/laptops/sonypi +laptops/thinkpad-acpi admin-guide/laptops/thinkpad-acpi +laptops/toshiba_haps admin-guide/laptops/toshiba_haps +loongarch/booting arch/loongarch/booting +loongarch/features arch/loongarch/features +loongarch/index arch/loongarch/index +loongarch/introduction arch/loongarch/introduction +loongarch/irq-chip-model arch/loongarch/irq-chip-model +m68k/buddha-driver arch/m68k/buddha-driver +m68k/features arch/m68k/features +m68k/index arch/m68k/index +m68k/kernel-options arch/m68k/kernel-options +md/index driver-api/md/index +md/md-cluster driver-api/md/md-cluster +md/raid5-cache driver-api/md/raid5-cache +md/raid5-ppl driver-api/md/raid5-ppl +media/dvb-drivers/avermedia admin-guide/media/avermedia +media/dvb-drivers/bt8xx admin-guide/media/bt8xx +media/dvb-drivers/ci admin-guide/media/ci +media/dvb-drivers/contributors driver-api/media/drivers/contributors +media/dvb-drivers/dvb-usb driver-api/media/drivers/dvb-usb +media/dvb-drivers/faq admin-guide/media/faq +media/dvb-drivers/frontends driver-api/media/drivers/frontends +media/dvb-drivers/index driver-api/media/drivers/index +media/dvb-drivers/lmedm04 admin-guide/media/lmedm04 +media/dvb-drivers/opera-firmware admin-guide/media/opera-firmware +media/dvb-drivers/technisat admin-guide/media/technisat +media/dvb-drivers/ttusb-dec admin-guide/media/ttusb-dec +media/intro userspace-api/media/intro +media/kapi/cec-core driver-api/media/cec-core +media/kapi/dtv-ca driver-api/media/dtv-ca +media/kapi/dtv-common driver-api/media/dtv-common +media/kapi/dtv-core driver-api/media/dtv-core +media/kapi/dtv-demux driver-api/media/dtv-demux +media/kapi/dtv-frontend driver-api/media/dtv-frontend +media/kapi/dtv-net driver-api/media/dtv-net +media/kapi/mc-core driver-api/media/mc-core +media/kapi/rc-core driver-api/media/rc-core +media/kapi/v4l2-async driver-api/media/v4l2-async +media/kapi/v4l2-common driver-api/media/v4l2-common +media/kapi/v4l2-controls driver-api/media/v4l2-controls +media/kapi/v4l2-core driver-api/media/v4l2-core +media/kapi/v4l2-dev driver-api/media/v4l2-dev +media/kapi/v4l2-device driver-api/media/v4l2-device +media/kapi/v4l2-dv-timings driver-api/media/v4l2-dv-timings +media/kapi/v4l2-event driver-api/media/v4l2-event +media/kapi/v4l2-fh driver-api/media/v4l2-fh +media/kapi/v4l2-flash-led-class driver-api/media/v4l2-flash-led-class +media/kapi/v4l2-fwnode driver-api/media/v4l2-fwnode +media/kapi/v4l2-intro driver-api/media/v4l2-intro +media/kapi/v4l2-mc driver-api/media/v4l2-mc +media/kapi/v4l2-mediabus driver-api/media/v4l2-mediabus +media/kapi/v4l2-mem2mem driver-api/media/v4l2-mem2mem +media/kapi/v4l2-rect driver-api/media/v4l2-rect +media/kapi/v4l2-subdev driver-api/media/v4l2-subdev +media/kapi/v4l2-tuner driver-api/media/v4l2-tuner +media/kapi/v4l2-tveeprom driver-api/media/v4l2-tveeprom +media/kapi/v4l2-videobuf2 driver-api/media/v4l2-videobuf2 +media/media_kapi driver-api/media/index +media/media_uapi userspace-api/media/index +media/uapi/cec/cec-api userspace-api/media/cec/cec-api +media/uapi/cec/cec-func-close userspace-api/media/cec/cec-func-close +media/uapi/cec/cec-func-ioctl userspace-api/media/cec/cec-func-ioctl +media/uapi/cec/cec-func-open userspace-api/media/cec/cec-func-open +media/uapi/cec/cec-func-poll userspace-api/media/cec/cec-func-poll +media/uapi/cec/cec-funcs userspace-api/media/cec/cec-funcs +media/uapi/cec/cec-header userspace-api/media/cec/cec-header +media/uapi/cec/cec-intro userspace-api/media/cec/cec-intro +media/uapi/cec/cec-ioc-adap-g-caps userspace-api/media/cec/cec-ioc-adap-g-caps +media/uapi/cec/cec-ioc-adap-g-conn-info userspace-api/media/cec/cec-ioc-adap-g-conn-info +media/uapi/cec/cec-ioc-adap-g-log-addrs userspace-api/media/cec/cec-ioc-adap-g-log-addrs +media/uapi/cec/cec-ioc-adap-g-phys-addr userspace-api/media/cec/cec-ioc-adap-g-phys-addr +media/uapi/cec/cec-ioc-dqevent userspace-api/media/cec/cec-ioc-dqevent +media/uapi/cec/cec-ioc-g-mode userspace-api/media/cec/cec-ioc-g-mode +media/uapi/cec/cec-ioc-receive userspace-api/media/cec/cec-ioc-receive +media/uapi/cec/cec-pin-error-inj userspace-api/media/cec/cec-pin-error-inj +media/uapi/dvb/ca userspace-api/media/dvb/ca +media/uapi/dvb/ca-fclose userspace-api/media/dvb/ca-fclose +media/uapi/dvb/ca-fopen userspace-api/media/dvb/ca-fopen +media/uapi/dvb/ca-get-cap userspace-api/media/dvb/ca-get-cap +media/uapi/dvb/ca-get-descr-info userspace-api/media/dvb/ca-get-descr-info +media/uapi/dvb/ca-get-msg userspace-api/media/dvb/ca-get-msg +media/uapi/dvb/ca-get-slot-info userspace-api/media/dvb/ca-get-slot-info +media/uapi/dvb/ca-reset userspace-api/media/dvb/ca-reset +media/uapi/dvb/ca-send-msg userspace-api/media/dvb/ca-send-msg +media/uapi/dvb/ca-set-descr userspace-api/media/dvb/ca-set-descr +media/uapi/dvb/ca_data_types userspace-api/media/dvb/ca_data_types +media/uapi/dvb/ca_function_calls userspace-api/media/dvb/ca_function_calls +media/uapi/dvb/ca_high_level userspace-api/media/dvb/ca_high_level +media/uapi/dvb/demux userspace-api/media/dvb/demux +media/uapi/dvb/dmx-add-pid userspace-api/media/dvb/dmx-add-pid +media/uapi/dvb/dmx-expbuf userspace-api/media/dvb/dmx-expbuf +media/uapi/dvb/dmx-fclose userspace-api/media/dvb/dmx-fclose +media/uapi/dvb/dmx-fopen userspace-api/media/dvb/dmx-fopen +media/uapi/dvb/dmx-fread userspace-api/media/dvb/dmx-fread +media/uapi/dvb/dmx-fwrite userspace-api/media/dvb/dmx-fwrite +media/uapi/dvb/dmx-get-pes-pids userspace-api/media/dvb/dmx-get-pes-pids +media/uapi/dvb/dmx-get-stc userspace-api/media/dvb/dmx-get-stc +media/uapi/dvb/dmx-mmap userspace-api/media/dvb/dmx-mmap +media/uapi/dvb/dmx-munmap userspace-api/media/dvb/dmx-munmap +media/uapi/dvb/dmx-qbuf userspace-api/media/dvb/dmx-qbuf +media/uapi/dvb/dmx-querybuf userspace-api/media/dvb/dmx-querybuf +media/uapi/dvb/dmx-remove-pid userspace-api/media/dvb/dmx-remove-pid +media/uapi/dvb/dmx-reqbufs userspace-api/media/dvb/dmx-reqbufs +media/uapi/dvb/dmx-set-buffer-size userspace-api/media/dvb/dmx-set-buffer-size +media/uapi/dvb/dmx-set-filter userspace-api/media/dvb/dmx-set-filter +media/uapi/dvb/dmx-set-pes-filter userspace-api/media/dvb/dmx-set-pes-filter +media/uapi/dvb/dmx-start userspace-api/media/dvb/dmx-start +media/uapi/dvb/dmx-stop userspace-api/media/dvb/dmx-stop +media/uapi/dvb/dmx_fcalls userspace-api/media/dvb/dmx_fcalls +media/uapi/dvb/dmx_types userspace-api/media/dvb/dmx_types +media/uapi/dvb/dvb-fe-read-status userspace-api/media/dvb/dvb-fe-read-status +media/uapi/dvb/dvb-frontend-event userspace-api/media/dvb/dvb-frontend-event +media/uapi/dvb/dvb-frontend-parameters userspace-api/media/dvb/dvb-frontend-parameters +media/uapi/dvb/dvbapi userspace-api/media/dvb/dvbapi +media/uapi/dvb/dvbproperty userspace-api/media/dvb/dvbproperty +media/uapi/dvb/examples userspace-api/media/dvb/examples +media/uapi/dvb/fe-bandwidth-t userspace-api/media/dvb/fe-bandwidth-t +media/uapi/dvb/fe-diseqc-recv-slave-reply userspace-api/media/dvb/fe-diseqc-recv-slave-reply +media/uapi/dvb/fe-diseqc-reset-overload userspace-api/media/dvb/fe-diseqc-reset-overload +media/uapi/dvb/fe-diseqc-send-burst userspace-api/media/dvb/fe-diseqc-send-burst +media/uapi/dvb/fe-diseqc-send-master-cmd userspace-api/media/dvb/fe-diseqc-send-master-cmd +media/uapi/dvb/fe-dishnetwork-send-legacy-cmd userspace-api/media/dvb/fe-dishnetwork-send-legacy-cmd +media/uapi/dvb/fe-enable-high-lnb-voltage userspace-api/media/dvb/fe-enable-high-lnb-voltage +media/uapi/dvb/fe-get-event userspace-api/media/dvb/fe-get-event +media/uapi/dvb/fe-get-frontend userspace-api/media/dvb/fe-get-frontend +media/uapi/dvb/fe-get-info userspace-api/media/dvb/fe-get-info +media/uapi/dvb/fe-get-property userspace-api/media/dvb/fe-get-property +media/uapi/dvb/fe-read-ber userspace-api/media/dvb/fe-read-ber +media/uapi/dvb/fe-read-signal-strength userspace-api/media/dvb/fe-read-signal-strength +media/uapi/dvb/fe-read-snr userspace-api/media/dvb/fe-read-snr +media/uapi/dvb/fe-read-status userspace-api/media/dvb/fe-read-status +media/uapi/dvb/fe-read-uncorrected-blocks userspace-api/media/dvb/fe-read-uncorrected-blocks +media/uapi/dvb/fe-set-frontend userspace-api/media/dvb/fe-set-frontend +media/uapi/dvb/fe-set-frontend-tune-mode userspace-api/media/dvb/fe-set-frontend-tune-mode +media/uapi/dvb/fe-set-tone userspace-api/media/dvb/fe-set-tone +media/uapi/dvb/fe-set-voltage userspace-api/media/dvb/fe-set-voltage +media/uapi/dvb/fe-type-t userspace-api/media/dvb/fe-type-t +media/uapi/dvb/fe_property_parameters userspace-api/media/dvb/fe_property_parameters +media/uapi/dvb/frontend userspace-api/media/dvb/frontend +media/uapi/dvb/frontend-header userspace-api/media/dvb/frontend-header +media/uapi/dvb/frontend-property-cable-systems userspace-api/media/dvb/frontend-property-cable-systems +media/uapi/dvb/frontend-property-satellite-systems userspace-api/media/dvb/frontend-property-satellite-systems +media/uapi/dvb/frontend-property-terrestrial-systems userspace-api/media/dvb/frontend-property-terrestrial-systems +media/uapi/dvb/frontend-stat-properties userspace-api/media/dvb/frontend-stat-properties +media/uapi/dvb/frontend_f_close userspace-api/media/dvb/frontend_f_close +media/uapi/dvb/frontend_f_open userspace-api/media/dvb/frontend_f_open +media/uapi/dvb/frontend_fcalls userspace-api/media/dvb/frontend_fcalls +media/uapi/dvb/frontend_legacy_api userspace-api/media/dvb/frontend_legacy_api +media/uapi/dvb/frontend_legacy_dvbv3_api userspace-api/media/dvb/frontend_legacy_dvbv3_api +media/uapi/dvb/headers userspace-api/media/dvb/headers +media/uapi/dvb/intro userspace-api/media/dvb/intro +media/uapi/dvb/legacy_dvb_apis userspace-api/media/dvb/legacy_dvb_apis +media/uapi/dvb/net userspace-api/media/dvb/net +media/uapi/dvb/net-add-if userspace-api/media/dvb/net-add-if +media/uapi/dvb/net-get-if userspace-api/media/dvb/net-get-if +media/uapi/dvb/net-remove-if userspace-api/media/dvb/net-remove-if +media/uapi/dvb/net-types userspace-api/media/dvb/net-types +media/uapi/dvb/query-dvb-frontend-info userspace-api/media/dvb/query-dvb-frontend-info +media/uapi/fdl-appendix userspace-api/media/fdl-appendix +media/uapi/gen-errors userspace-api/media/gen-errors +media/uapi/mediactl/media-controller userspace-api/media/mediactl/media-controller +media/uapi/mediactl/media-controller-intro userspace-api/media/mediactl/media-controller-intro +media/uapi/mediactl/media-controller-model userspace-api/media/mediactl/media-controller-model +media/uapi/mediactl/media-func-close userspace-api/media/mediactl/media-func-close +media/uapi/mediactl/media-func-ioctl userspace-api/media/mediactl/media-func-ioctl +media/uapi/mediactl/media-func-open userspace-api/media/mediactl/media-func-open +media/uapi/mediactl/media-funcs userspace-api/media/mediactl/media-funcs +media/uapi/mediactl/media-header userspace-api/media/mediactl/media-header +media/uapi/mediactl/media-ioc-device-info userspace-api/media/mediactl/media-ioc-device-info +media/uapi/mediactl/media-ioc-enum-entities userspace-api/media/mediactl/media-ioc-enum-entities +media/uapi/mediactl/media-ioc-enum-links userspace-api/media/mediactl/media-ioc-enum-links +media/uapi/mediactl/media-ioc-g-topology userspace-api/media/mediactl/media-ioc-g-topology +media/uapi/mediactl/media-ioc-request-alloc userspace-api/media/mediactl/media-ioc-request-alloc +media/uapi/mediactl/media-ioc-setup-link userspace-api/media/mediactl/media-ioc-setup-link +media/uapi/mediactl/media-request-ioc-queue userspace-api/media/mediactl/media-request-ioc-queue +media/uapi/mediactl/media-request-ioc-reinit userspace-api/media/mediactl/media-request-ioc-reinit +media/uapi/mediactl/media-types userspace-api/media/mediactl/media-types +media/uapi/mediactl/request-api userspace-api/media/mediactl/request-api +media/uapi/mediactl/request-func-close userspace-api/media/mediactl/request-func-close +media/uapi/mediactl/request-func-ioctl userspace-api/media/mediactl/request-func-ioctl +media/uapi/mediactl/request-func-poll userspace-api/media/mediactl/request-func-poll +media/uapi/rc/keytable.c userspace-api/media/rc/keytable.c +media/uapi/rc/lirc-dev userspace-api/media/rc/lirc-dev +media/uapi/rc/lirc-dev-intro userspace-api/media/rc/lirc-dev-intro +media/uapi/rc/lirc-func userspace-api/media/rc/lirc-func +media/uapi/rc/lirc-get-features userspace-api/media/rc/lirc-get-features +media/uapi/rc/lirc-get-rec-mode userspace-api/media/rc/lirc-get-rec-mode +media/uapi/rc/lirc-get-rec-resolution userspace-api/media/rc/lirc-get-rec-resolution +media/uapi/rc/lirc-get-send-mode userspace-api/media/rc/lirc-get-send-mode +media/uapi/rc/lirc-get-timeout userspace-api/media/rc/lirc-get-timeout +media/uapi/rc/lirc-header userspace-api/media/rc/lirc-header +media/uapi/rc/lirc-read userspace-api/media/rc/lirc-read +media/uapi/rc/lirc-set-measure-carrier-mode userspace-api/media/rc/lirc-set-measure-carrier-mode +media/uapi/rc/lirc-set-rec-carrier userspace-api/media/rc/lirc-set-rec-carrier +media/uapi/rc/lirc-set-rec-carrier-range userspace-api/media/rc/lirc-set-rec-carrier-range +media/uapi/rc/lirc-set-rec-timeout userspace-api/media/rc/lirc-set-rec-timeout +media/uapi/rc/lirc-set-send-carrier userspace-api/media/rc/lirc-set-send-carrier +media/uapi/rc/lirc-set-send-duty-cycle userspace-api/media/rc/lirc-set-send-duty-cycle +media/uapi/rc/lirc-set-transmitter-mask userspace-api/media/rc/lirc-set-transmitter-mask +media/uapi/rc/lirc-set-wideband-receiver userspace-api/media/rc/lirc-set-wideband-receiver +media/uapi/rc/lirc-write userspace-api/media/rc/lirc-write +media/uapi/rc/rc-intro userspace-api/media/rc/rc-intro +media/uapi/rc/rc-protos userspace-api/media/rc/rc-protos +media/uapi/rc/rc-sysfs-nodes userspace-api/media/rc/rc-sysfs-nodes +media/uapi/rc/rc-table-change userspace-api/media/rc/rc-table-change +media/uapi/rc/rc-tables userspace-api/media/rc/rc-tables +media/uapi/rc/remote_controllers userspace-api/media/rc/remote_controllers +media/uapi/v4l/app-pri userspace-api/media/v4l/app-pri +media/uapi/v4l/audio userspace-api/media/v4l/audio +media/uapi/v4l/biblio userspace-api/media/v4l/biblio +media/uapi/v4l/buffer userspace-api/media/v4l/buffer +media/uapi/v4l/capture-example userspace-api/media/v4l/capture-example +media/uapi/v4l/capture.c userspace-api/media/v4l/capture.c +media/uapi/v4l/colorspaces userspace-api/media/v4l/colorspaces +media/uapi/v4l/colorspaces-defs userspace-api/media/v4l/colorspaces-defs +media/uapi/v4l/colorspaces-details userspace-api/media/v4l/colorspaces-details +media/uapi/v4l/common userspace-api/media/v4l/common +media/uapi/v4l/common-defs userspace-api/media/v4l/common-defs +media/uapi/v4l/compat userspace-api/media/v4l/compat +media/uapi/v4l/control userspace-api/media/v4l/control +media/uapi/v4l/crop userspace-api/media/v4l/crop +media/uapi/v4l/depth-formats userspace-api/media/v4l/depth-formats +media/uapi/v4l/dev-capture userspace-api/media/v4l/dev-capture +media/uapi/v4l/dev-codec userspace-api/media/v4l/dev-mem2mem +media/uapi/v4l/dev-decoder userspace-api/media/v4l/dev-decoder +media/uapi/v4l/dev-event userspace-api/media/v4l/dev-event +media/uapi/v4l/dev-mem2mem userspace-api/media/v4l/dev-mem2mem +media/uapi/v4l/dev-meta userspace-api/media/v4l/dev-meta +media/uapi/v4l/dev-osd userspace-api/media/v4l/dev-osd +media/uapi/v4l/dev-output userspace-api/media/v4l/dev-output +media/uapi/v4l/dev-overlay userspace-api/media/v4l/dev-overlay +media/uapi/v4l/dev-radio userspace-api/media/v4l/dev-radio +media/uapi/v4l/dev-raw-vbi userspace-api/media/v4l/dev-raw-vbi +media/uapi/v4l/dev-rds userspace-api/media/v4l/dev-rds +media/uapi/v4l/dev-sdr userspace-api/media/v4l/dev-sdr +media/uapi/v4l/dev-sliced-vbi userspace-api/media/v4l/dev-sliced-vbi +media/uapi/v4l/dev-stateless-decoder userspace-api/media/v4l/dev-stateless-decoder +media/uapi/v4l/dev-subdev userspace-api/media/v4l/dev-subdev +media/uapi/v4l/dev-touch userspace-api/media/v4l/dev-touch +media/uapi/v4l/devices userspace-api/media/v4l/devices +media/uapi/v4l/diff-v4l userspace-api/media/v4l/diff-v4l +media/uapi/v4l/dmabuf userspace-api/media/v4l/dmabuf +media/uapi/v4l/dv-timings userspace-api/media/v4l/dv-timings +media/uapi/v4l/ext-ctrls-camera userspace-api/media/v4l/ext-ctrls-camera +media/uapi/v4l/ext-ctrls-codec userspace-api/media/v4l/ext-ctrls-codec +media/uapi/v4l/ext-ctrls-detect userspace-api/media/v4l/ext-ctrls-detect +media/uapi/v4l/ext-ctrls-dv userspace-api/media/v4l/ext-ctrls-dv +media/uapi/v4l/ext-ctrls-flash userspace-api/media/v4l/ext-ctrls-flash +media/uapi/v4l/ext-ctrls-fm-rx userspace-api/media/v4l/ext-ctrls-fm-rx +media/uapi/v4l/ext-ctrls-fm-tx userspace-api/media/v4l/ext-ctrls-fm-tx +media/uapi/v4l/ext-ctrls-image-process userspace-api/media/v4l/ext-ctrls-image-process +media/uapi/v4l/ext-ctrls-image-source userspace-api/media/v4l/ext-ctrls-image-source +media/uapi/v4l/ext-ctrls-jpeg userspace-api/media/v4l/ext-ctrls-jpeg +media/uapi/v4l/ext-ctrls-rf-tuner userspace-api/media/v4l/ext-ctrls-rf-tuner +media/uapi/v4l/extended-controls userspace-api/media/v4l/extended-controls +media/uapi/v4l/field-order userspace-api/media/v4l/field-order +media/uapi/v4l/format userspace-api/media/v4l/format +media/uapi/v4l/func-close userspace-api/media/v4l/func-close +media/uapi/v4l/func-ioctl userspace-api/media/v4l/func-ioctl +media/uapi/v4l/func-mmap userspace-api/media/v4l/func-mmap +media/uapi/v4l/func-munmap userspace-api/media/v4l/func-munmap +media/uapi/v4l/func-open userspace-api/media/v4l/func-open +media/uapi/v4l/func-poll userspace-api/media/v4l/func-poll +media/uapi/v4l/func-read userspace-api/media/v4l/func-read +media/uapi/v4l/func-select userspace-api/media/v4l/func-select +media/uapi/v4l/func-write userspace-api/media/v4l/func-write +media/uapi/v4l/hist-v4l2 userspace-api/media/v4l/hist-v4l2 +media/uapi/v4l/hsv-formats userspace-api/media/v4l/hsv-formats +media/uapi/v4l/io userspace-api/media/v4l/io +media/uapi/v4l/libv4l userspace-api/media/v4l/libv4l +media/uapi/v4l/libv4l-introduction userspace-api/media/v4l/libv4l-introduction +media/uapi/v4l/meta-formats userspace-api/media/v4l/meta-formats +media/uapi/v4l/mmap userspace-api/media/v4l/mmap +media/uapi/v4l/open userspace-api/media/v4l/open +media/uapi/v4l/pixfmt userspace-api/media/v4l/pixfmt +media/uapi/v4l/pixfmt-002 userspace-api/media/v4l/pixfmt-v4l2 +media/uapi/v4l/pixfmt-003 userspace-api/media/v4l/pixfmt-v4l2-mplane +media/uapi/v4l/pixfmt-004 userspace-api/media/v4l/pixfmt-intro +media/uapi/v4l/pixfmt-006 userspace-api/media/v4l/colorspaces-defs +media/uapi/v4l/pixfmt-007 userspace-api/media/v4l/colorspaces-details +media/uapi/v4l/pixfmt-013 userspace-api/media/v4l/pixfmt-compressed +media/uapi/v4l/pixfmt-bayer userspace-api/media/v4l/pixfmt-bayer +media/uapi/v4l/pixfmt-cnf4 userspace-api/media/v4l/pixfmt-cnf4 +media/uapi/v4l/pixfmt-compressed userspace-api/media/v4l/pixfmt-compressed +media/uapi/v4l/pixfmt-indexed userspace-api/media/v4l/pixfmt-indexed +media/uapi/v4l/pixfmt-intro userspace-api/media/v4l/pixfmt-intro +media/uapi/v4l/pixfmt-inzi userspace-api/media/v4l/pixfmt-inzi +media/uapi/v4l/pixfmt-m420 userspace-api/media/v4l/pixfmt-m420 +media/uapi/v4l/pixfmt-meta-d4xx userspace-api/media/v4l/metafmt-d4xx +media/uapi/v4l/pixfmt-meta-intel-ipu3 userspace-api/media/v4l/metafmt-intel-ipu3 +media/uapi/v4l/pixfmt-meta-uvc userspace-api/media/v4l/metafmt-uvc +media/uapi/v4l/pixfmt-meta-vivid userspace-api/media/v4l/metafmt-vivid +media/uapi/v4l/pixfmt-meta-vsp1-hgo userspace-api/media/v4l/metafmt-vsp1-hgo +media/uapi/v4l/pixfmt-meta-vsp1-hgt userspace-api/media/v4l/metafmt-vsp1-hgt +media/uapi/v4l/pixfmt-packed-hsv userspace-api/media/v4l/pixfmt-packed-hsv +media/uapi/v4l/pixfmt-packed-yuv userspace-api/media/v4l/pixfmt-packed-yuv +media/uapi/v4l/pixfmt-reserved userspace-api/media/v4l/pixfmt-reserved +media/uapi/v4l/pixfmt-rgb userspace-api/media/v4l/pixfmt-rgb +media/uapi/v4l/pixfmt-sbggr16 userspace-api/media/v4l/pixfmt-srggb16 +media/uapi/v4l/pixfmt-sdr-cs08 userspace-api/media/v4l/pixfmt-sdr-cs08 +media/uapi/v4l/pixfmt-sdr-cs14le userspace-api/media/v4l/pixfmt-sdr-cs14le +media/uapi/v4l/pixfmt-sdr-cu08 userspace-api/media/v4l/pixfmt-sdr-cu08 +media/uapi/v4l/pixfmt-sdr-cu16le userspace-api/media/v4l/pixfmt-sdr-cu16le +media/uapi/v4l/pixfmt-sdr-pcu16be userspace-api/media/v4l/pixfmt-sdr-pcu16be +media/uapi/v4l/pixfmt-sdr-pcu18be userspace-api/media/v4l/pixfmt-sdr-pcu18be +media/uapi/v4l/pixfmt-sdr-pcu20be userspace-api/media/v4l/pixfmt-sdr-pcu20be +media/uapi/v4l/pixfmt-sdr-ru12le userspace-api/media/v4l/pixfmt-sdr-ru12le +media/uapi/v4l/pixfmt-srggb10 userspace-api/media/v4l/pixfmt-srggb10 +media/uapi/v4l/pixfmt-srggb10-ipu3 userspace-api/media/v4l/pixfmt-srggb10-ipu3 +media/uapi/v4l/pixfmt-srggb10alaw8 userspace-api/media/v4l/pixfmt-srggb10alaw8 +media/uapi/v4l/pixfmt-srggb10dpcm8 userspace-api/media/v4l/pixfmt-srggb10dpcm8 +media/uapi/v4l/pixfmt-srggb10p userspace-api/media/v4l/pixfmt-srggb10p +media/uapi/v4l/pixfmt-srggb12 userspace-api/media/v4l/pixfmt-srggb12 +media/uapi/v4l/pixfmt-srggb12p userspace-api/media/v4l/pixfmt-srggb12p +media/uapi/v4l/pixfmt-srggb14 userspace-api/media/v4l/pixfmt-srggb14 +media/uapi/v4l/pixfmt-srggb14p userspace-api/media/v4l/pixfmt-srggb14p +media/uapi/v4l/pixfmt-srggb16 userspace-api/media/v4l/pixfmt-srggb16 +media/uapi/v4l/pixfmt-srggb8 userspace-api/media/v4l/pixfmt-srggb8 +media/uapi/v4l/pixfmt-tch-td08 userspace-api/media/v4l/pixfmt-tch-td08 +media/uapi/v4l/pixfmt-tch-td16 userspace-api/media/v4l/pixfmt-tch-td16 +media/uapi/v4l/pixfmt-tch-tu08 userspace-api/media/v4l/pixfmt-tch-tu08 +media/uapi/v4l/pixfmt-tch-tu16 userspace-api/media/v4l/pixfmt-tch-tu16 +media/uapi/v4l/pixfmt-uv8 userspace-api/media/v4l/pixfmt-uv8 +media/uapi/v4l/pixfmt-v4l2 userspace-api/media/v4l/pixfmt-v4l2 +media/uapi/v4l/pixfmt-v4l2-mplane userspace-api/media/v4l/pixfmt-v4l2-mplane +media/uapi/v4l/pixfmt-y12i userspace-api/media/v4l/pixfmt-y12i +media/uapi/v4l/pixfmt-y8i userspace-api/media/v4l/pixfmt-y8i +media/uapi/v4l/pixfmt-z16 userspace-api/media/v4l/pixfmt-z16 +media/uapi/v4l/planar-apis userspace-api/media/v4l/planar-apis +media/uapi/v4l/querycap userspace-api/media/v4l/querycap +media/uapi/v4l/rw userspace-api/media/v4l/rw +media/uapi/v4l/sdr-formats userspace-api/media/v4l/sdr-formats +media/uapi/v4l/selection-api userspace-api/media/v4l/selection-api +media/uapi/v4l/selection-api-002 userspace-api/media/v4l/selection-api-intro +media/uapi/v4l/selection-api-003 userspace-api/media/v4l/selection-api-targets +media/uapi/v4l/selection-api-004 userspace-api/media/v4l/selection-api-configuration +media/uapi/v4l/selection-api-005 userspace-api/media/v4l/selection-api-vs-crop-api +media/uapi/v4l/selection-api-006 userspace-api/media/v4l/selection-api-examples +media/uapi/v4l/selection-api-configuration userspace-api/media/v4l/selection-api-configuration +media/uapi/v4l/selection-api-examples userspace-api/media/v4l/selection-api-examples +media/uapi/v4l/selection-api-intro userspace-api/media/v4l/selection-api-intro +media/uapi/v4l/selection-api-targets userspace-api/media/v4l/selection-api-targets +media/uapi/v4l/selection-api-vs-crop-api userspace-api/media/v4l/selection-api-vs-crop-api +media/uapi/v4l/selections-common userspace-api/media/v4l/selections-common +media/uapi/v4l/standard userspace-api/media/v4l/standard +media/uapi/v4l/streaming-par userspace-api/media/v4l/streaming-par +media/uapi/v4l/subdev-formats userspace-api/media/v4l/subdev-formats +media/uapi/v4l/tch-formats userspace-api/media/v4l/tch-formats +media/uapi/v4l/tuner userspace-api/media/v4l/tuner +media/uapi/v4l/user-func userspace-api/media/v4l/user-func +media/uapi/v4l/userp userspace-api/media/v4l/userp +media/uapi/v4l/v4l2 userspace-api/media/v4l/v4l2 +media/uapi/v4l/v4l2-selection-flags userspace-api/media/v4l/v4l2-selection-flags +media/uapi/v4l/v4l2-selection-targets userspace-api/media/v4l/v4l2-selection-targets +media/uapi/v4l/v4l2grab-example userspace-api/media/v4l/v4l2grab-example +media/uapi/v4l/v4l2grab.c userspace-api/media/v4l/v4l2grab.c +media/uapi/v4l/video userspace-api/media/v4l/video +media/uapi/v4l/videodev userspace-api/media/v4l/videodev +media/uapi/v4l/vidioc-create-bufs userspace-api/media/v4l/vidioc-create-bufs +media/uapi/v4l/vidioc-cropcap userspace-api/media/v4l/vidioc-cropcap +media/uapi/v4l/vidioc-dbg-g-chip-info userspace-api/media/v4l/vidioc-dbg-g-chip-info +media/uapi/v4l/vidioc-dbg-g-register userspace-api/media/v4l/vidioc-dbg-g-register +media/uapi/v4l/vidioc-decoder-cmd userspace-api/media/v4l/vidioc-decoder-cmd +media/uapi/v4l/vidioc-dqevent userspace-api/media/v4l/vidioc-dqevent +media/uapi/v4l/vidioc-dv-timings-cap userspace-api/media/v4l/vidioc-dv-timings-cap +media/uapi/v4l/vidioc-encoder-cmd userspace-api/media/v4l/vidioc-encoder-cmd +media/uapi/v4l/vidioc-enum-dv-timings userspace-api/media/v4l/vidioc-enum-dv-timings +media/uapi/v4l/vidioc-enum-fmt userspace-api/media/v4l/vidioc-enum-fmt +media/uapi/v4l/vidioc-enum-frameintervals userspace-api/media/v4l/vidioc-enum-frameintervals +media/uapi/v4l/vidioc-enum-framesizes userspace-api/media/v4l/vidioc-enum-framesizes +media/uapi/v4l/vidioc-enum-freq-bands userspace-api/media/v4l/vidioc-enum-freq-bands +media/uapi/v4l/vidioc-enumaudio userspace-api/media/v4l/vidioc-enumaudio +media/uapi/v4l/vidioc-enumaudioout userspace-api/media/v4l/vidioc-enumaudioout +media/uapi/v4l/vidioc-enuminput userspace-api/media/v4l/vidioc-enuminput +media/uapi/v4l/vidioc-enumoutput userspace-api/media/v4l/vidioc-enumoutput +media/uapi/v4l/vidioc-enumstd userspace-api/media/v4l/vidioc-enumstd +media/uapi/v4l/vidioc-expbuf userspace-api/media/v4l/vidioc-expbuf +media/uapi/v4l/vidioc-g-audio userspace-api/media/v4l/vidioc-g-audio +media/uapi/v4l/vidioc-g-audioout userspace-api/media/v4l/vidioc-g-audioout +media/uapi/v4l/vidioc-g-crop userspace-api/media/v4l/vidioc-g-crop +media/uapi/v4l/vidioc-g-ctrl userspace-api/media/v4l/vidioc-g-ctrl +media/uapi/v4l/vidioc-g-dv-timings userspace-api/media/v4l/vidioc-g-dv-timings +media/uapi/v4l/vidioc-g-edid userspace-api/media/v4l/vidioc-g-edid +media/uapi/v4l/vidioc-g-enc-index userspace-api/media/v4l/vidioc-g-enc-index +media/uapi/v4l/vidioc-g-ext-ctrls userspace-api/media/v4l/vidioc-g-ext-ctrls +media/uapi/v4l/vidioc-g-fbuf userspace-api/media/v4l/vidioc-g-fbuf +media/uapi/v4l/vidioc-g-fmt userspace-api/media/v4l/vidioc-g-fmt +media/uapi/v4l/vidioc-g-frequency userspace-api/media/v4l/vidioc-g-frequency +media/uapi/v4l/vidioc-g-input userspace-api/media/v4l/vidioc-g-input +media/uapi/v4l/vidioc-g-jpegcomp userspace-api/media/v4l/vidioc-g-jpegcomp +media/uapi/v4l/vidioc-g-modulator userspace-api/media/v4l/vidioc-g-modulator +media/uapi/v4l/vidioc-g-output userspace-api/media/v4l/vidioc-g-output +media/uapi/v4l/vidioc-g-parm userspace-api/media/v4l/vidioc-g-parm +media/uapi/v4l/vidioc-g-priority userspace-api/media/v4l/vidioc-g-priority +media/uapi/v4l/vidioc-g-selection userspace-api/media/v4l/vidioc-g-selection +media/uapi/v4l/vidioc-g-sliced-vbi-cap userspace-api/media/v4l/vidioc-g-sliced-vbi-cap +media/uapi/v4l/vidioc-g-std userspace-api/media/v4l/vidioc-g-std +media/uapi/v4l/vidioc-g-tuner userspace-api/media/v4l/vidioc-g-tuner +media/uapi/v4l/vidioc-log-status userspace-api/media/v4l/vidioc-log-status +media/uapi/v4l/vidioc-overlay userspace-api/media/v4l/vidioc-overlay +media/uapi/v4l/vidioc-prepare-buf userspace-api/media/v4l/vidioc-prepare-buf +media/uapi/v4l/vidioc-qbuf userspace-api/media/v4l/vidioc-qbuf +media/uapi/v4l/vidioc-query-dv-timings userspace-api/media/v4l/vidioc-query-dv-timings +media/uapi/v4l/vidioc-querybuf userspace-api/media/v4l/vidioc-querybuf +media/uapi/v4l/vidioc-querycap userspace-api/media/v4l/vidioc-querycap +media/uapi/v4l/vidioc-queryctrl userspace-api/media/v4l/vidioc-queryctrl +media/uapi/v4l/vidioc-querystd userspace-api/media/v4l/vidioc-querystd +media/uapi/v4l/vidioc-reqbufs userspace-api/media/v4l/vidioc-reqbufs +media/uapi/v4l/vidioc-s-hw-freq-seek userspace-api/media/v4l/vidioc-s-hw-freq-seek +media/uapi/v4l/vidioc-streamon userspace-api/media/v4l/vidioc-streamon +media/uapi/v4l/vidioc-subdev-enum-frame-interval userspace-api/media/v4l/vidioc-subdev-enum-frame-interval +media/uapi/v4l/vidioc-subdev-enum-frame-size userspace-api/media/v4l/vidioc-subdev-enum-frame-size +media/uapi/v4l/vidioc-subdev-enum-mbus-code userspace-api/media/v4l/vidioc-subdev-enum-mbus-code +media/uapi/v4l/vidioc-subdev-g-crop userspace-api/media/v4l/vidioc-subdev-g-crop +media/uapi/v4l/vidioc-subdev-g-fmt userspace-api/media/v4l/vidioc-subdev-g-fmt +media/uapi/v4l/vidioc-subdev-g-frame-interval userspace-api/media/v4l/vidioc-subdev-g-frame-interval +media/uapi/v4l/vidioc-subdev-g-selection userspace-api/media/v4l/vidioc-subdev-g-selection +media/uapi/v4l/vidioc-subscribe-event userspace-api/media/v4l/vidioc-subscribe-event +media/uapi/v4l/yuv-formats userspace-api/media/v4l/yuv-formats +media/v4l-drivers/au0828-cardlist admin-guide/media/au0828-cardlist +media/v4l-drivers/bttv admin-guide/media/bttv +media/v4l-drivers/bttv-cardlist admin-guide/media/bttv-cardlist +media/v4l-drivers/bttv-devel driver-api/media/drivers/bttv-devel +media/v4l-drivers/cafe_ccic admin-guide/media/cafe_ccic +media/v4l-drivers/cardlist admin-guide/media/cardlist +media/v4l-drivers/cx2341x driver-api/media/drivers/cx2341x-devel +media/v4l-drivers/cx2341x-devel driver-api/media/drivers/cx2341x-devel +media/v4l-drivers/cx2341x-uapi userspace-api/media/drivers/cx2341x-uapi +media/v4l-drivers/cx23885-cardlist admin-guide/media/cx23885-cardlist +media/v4l-drivers/cx88 admin-guide/media/cx88 +media/v4l-drivers/cx88-cardlist admin-guide/media/cx88-cardlist +media/v4l-drivers/cx88-devel driver-api/media/drivers/cx88-devel +media/v4l-drivers/em28xx-cardlist admin-guide/media/em28xx-cardlist +media/v4l-drivers/fimc admin-guide/media/fimc +media/v4l-drivers/fimc-devel driver-api/media/drivers/fimc-devel +media/v4l-drivers/fourcc userspace-api/media/v4l/fourcc +media/v4l-drivers/gspca-cardlist admin-guide/media/gspca-cardlist +media/v4l-drivers/imx admin-guide/media/imx +media/v4l-drivers/imx-uapi userspace-api/media/drivers/imx-uapi +media/v4l-drivers/imx7 admin-guide/media/imx7 +media/v4l-drivers/index userspace-api/media/drivers/index +media/v4l-drivers/ipu3 admin-guide/media/ipu3 +media/v4l-drivers/ivtv admin-guide/media/ivtv +media/v4l-drivers/ivtv-cardlist admin-guide/media/ivtv-cardlist +media/v4l-drivers/max2175 userspace-api/media/drivers/max2175 +media/v4l-drivers/omap3isp admin-guide/media/omap3isp +media/v4l-drivers/omap3isp-uapi userspace-api/media/drivers/omap3isp-uapi +media/v4l-drivers/philips admin-guide/media/philips +media/v4l-drivers/pvrusb2 driver-api/media/drivers/pvrusb2 +media/v4l-drivers/pxa_camera driver-api/media/drivers/pxa_camera +media/v4l-drivers/qcom_camss admin-guide/media/qcom_camss +media/v4l-drivers/radiotrack driver-api/media/drivers/radiotrack +media/v4l-drivers/rcar-fdp1 admin-guide/media/rcar-fdp1 +media/v4l-drivers/saa7134 admin-guide/media/saa7134 +media/v4l-drivers/saa7134-cardlist admin-guide/media/saa7134-cardlist +media/v4l-drivers/saa7134-devel driver-api/media/drivers/saa7134-devel +media/v4l-drivers/saa7164-cardlist admin-guide/media/saa7164-cardlist +media/v4l-drivers/sh_mobile_ceu_camera driver-api/media/drivers/sh_mobile_ceu_camera +media/v4l-drivers/si470x admin-guide/media/si470x +media/v4l-drivers/si4713 admin-guide/media/si4713 +media/v4l-drivers/si476x admin-guide/media/si476x +media/v4l-drivers/tuner-cardlist admin-guide/media/tuner-cardlist +media/v4l-drivers/tuners driver-api/media/drivers/tuners +media/v4l-drivers/uvcvideo userspace-api/media/drivers/uvcvideo +media/v4l-drivers/v4l-with-ir admin-guide/media/remote-controller +media/v4l-drivers/vimc admin-guide/media/vimc +media/v4l-drivers/vimc-devel driver-api/media/drivers/vimc-devel +media/v4l-drivers/vivid admin-guide/media/vivid +media/v4l-drivers/zoran driver-api/media/drivers/zoran +memory-devices/ti-emif driver-api/memory-devices/ti-emif +mips/booting arch/mips/booting +mips/features arch/mips/features +mips/index arch/mips/index +mips/ingenic-tcu arch/mips/ingenic-tcu +mm/slub admin-guide/mm/slab +mmc/index driver-api/mmc/index +mmc/mmc-async-req driver-api/mmc/mmc-async-req +mmc/mmc-dev-attrs driver-api/mmc/mmc-dev-attrs +mmc/mmc-dev-parts driver-api/mmc/mmc-dev-parts +mmc/mmc-tools driver-api/mmc/mmc-tools +mtd/index driver-api/mtd/index +mtd/intel-spi driver-api/mtd/spi-intel +mtd/nand_ecc driver-api/mtd/nand_ecc +mtd/spi-nor driver-api/mtd/spi-nor +namespaces/compatibility-list admin-guide/namespaces/compatibility-list +namespaces/index admin-guide/namespaces/index +namespaces/resource-control admin-guide/namespaces/resource-control +networking/altera_tse networking/device_drivers/ethernet/altera/altera_tse +networking/baycom networking/device_drivers/hamradio/baycom +networking/bpf_flow_dissector bpf/prog_flow_dissector +networking/cxacru networking/device_drivers/atm/cxacru +networking/defza networking/device_drivers/fddi/defza +networking/device_drivers/3com/3c509 networking/device_drivers/ethernet/3com/3c509 +networking/device_drivers/3com/vortex networking/device_drivers/ethernet/3com/vortex +networking/device_drivers/amazon/ena networking/device_drivers/ethernet/amazon/ena +networking/device_drivers/aquantia/atlantic networking/device_drivers/ethernet/aquantia/atlantic +networking/device_drivers/chelsio/cxgb networking/device_drivers/ethernet/chelsio/cxgb +networking/device_drivers/cirrus/cs89x0 networking/device_drivers/ethernet/cirrus/cs89x0 +networking/device_drivers/davicom/dm9000 networking/device_drivers/ethernet/davicom/dm9000 +networking/device_drivers/dec/dmfe networking/device_drivers/ethernet/dec/dmfe +networking/device_drivers/dlink/dl2k networking/device_drivers/ethernet/dlink/dl2k +networking/device_drivers/freescale/dpaa networking/device_drivers/ethernet/freescale/dpaa +networking/device_drivers/freescale/dpaa2/dpio-driver networking/device_drivers/ethernet/freescale/dpaa2/dpio-driver +networking/device_drivers/freescale/dpaa2/ethernet-driver networking/device_drivers/ethernet/freescale/dpaa2/ethernet-driver +networking/device_drivers/freescale/dpaa2/index networking/device_drivers/ethernet/freescale/dpaa2/index +networking/device_drivers/freescale/dpaa2/mac-phy-support networking/device_drivers/ethernet/freescale/dpaa2/mac-phy-support +networking/device_drivers/freescale/dpaa2/overview networking/device_drivers/ethernet/freescale/dpaa2/overview +networking/device_drivers/freescale/gianfar networking/device_drivers/ethernet/freescale/gianfar +networking/device_drivers/google/gve networking/device_drivers/ethernet/google/gve +networking/device_drivers/intel/e100 networking/device_drivers/ethernet/intel/e100 +networking/device_drivers/intel/e1000 networking/device_drivers/ethernet/intel/e1000 +networking/device_drivers/intel/e1000e networking/device_drivers/ethernet/intel/e1000e +networking/device_drivers/intel/fm10k networking/device_drivers/ethernet/intel/fm10k +networking/device_drivers/intel/i40e networking/device_drivers/ethernet/intel/i40e +networking/device_drivers/intel/iavf networking/device_drivers/ethernet/intel/iavf +networking/device_drivers/intel/ice networking/device_drivers/ethernet/intel/ice +networking/device_drivers/intel/igb networking/device_drivers/ethernet/intel/igb +networking/device_drivers/intel/igbvf networking/device_drivers/ethernet/intel/igbvf +networking/device_drivers/intel/ipw2100 networking/device_drivers/wifi/intel/ipw2100 +networking/device_drivers/intel/ipw2200 networking/device_drivers/wifi/intel/ipw2200 +networking/device_drivers/intel/ixgbe networking/device_drivers/ethernet/intel/ixgbe +networking/device_drivers/intel/ixgbevf networking/device_drivers/ethernet/intel/ixgbevf +networking/device_drivers/marvell/octeontx2 networking/device_drivers/ethernet/marvell/octeontx2 +networking/device_drivers/microsoft/netvsc networking/device_drivers/ethernet/microsoft/netvsc +networking/device_drivers/neterion/s2io networking/device_drivers/ethernet/neterion/s2io +networking/device_drivers/netronome/nfp networking/device_drivers/ethernet/netronome/nfp +networking/device_drivers/pensando/ionic networking/device_drivers/ethernet/pensando/ionic +networking/device_drivers/qualcomm/rmnet networking/device_drivers/cellular/qualcomm/rmnet +networking/device_drivers/smsc/smc9 networking/device_drivers/ethernet/smsc/smc9 +networking/device_drivers/stmicro/stmmac networking/device_drivers/ethernet/stmicro/stmmac +networking/device_drivers/ti/cpsw networking/device_drivers/ethernet/ti/cpsw +networking/device_drivers/ti/cpsw_switchdev networking/device_drivers/ethernet/ti/cpsw_switchdev +networking/device_drivers/ti/tlan networking/device_drivers/ethernet/ti/tlan +networking/devlink-trap networking/devlink/devlink-trap +networking/dpaa2/dpio-driver networking/device_drivers/ethernet/freescale/dpaa2/dpio-driver +networking/dpaa2/ethernet-driver networking/device_drivers/ethernet/freescale/dpaa2/ethernet-driver +networking/dpaa2/index networking/device_drivers/ethernet/freescale/dpaa2/index +networking/dpaa2/overview networking/device_drivers/ethernet/freescale/dpaa2/overview +networking/e100 networking/device_drivers/ethernet/intel/e100 +networking/e1000 networking/device_drivers/ethernet/intel/e1000 +networking/e1000e networking/device_drivers/ethernet/intel/e1000e +networking/fm10k networking/device_drivers/ethernet/intel/fm10k +networking/fore200e networking/device_drivers/atm/fore200e +networking/hinic networking/device_drivers/ethernet/huawei/hinic +networking/i40e networking/device_drivers/ethernet/intel/i40e +networking/iavf networking/device_drivers/ethernet/intel/iavf +networking/ice networking/device_drivers/ethernet/intel/ice +networking/igb networking/device_drivers/ethernet/intel/igb +networking/igbvf networking/device_drivers/ethernet/intel/igbvf +networking/iphase networking/device_drivers/atm/iphase +networking/ixgbe networking/device_drivers/ethernet/intel/ixgbe +networking/ixgbevf networking/device_drivers/ethernet/intel/ixgbevf +networking/netdev-FAQ process/maintainer-netdev +networking/skfp networking/device_drivers/fddi/skfp +networking/z8530drv networking/device_drivers/hamradio/z8530drv +nfc/index driver-api/nfc/index +nfc/nfc-hci driver-api/nfc/nfc-hci +nfc/nfc-pn544 driver-api/nfc/nfc-pn544 +nios2/features arch/nios2/features +nios2/index arch/nios2/index +nios2/nios2 arch/nios2/nios2 +nvdimm/btt driver-api/nvdimm/btt +nvdimm/index driver-api/nvdimm/index +nvdimm/nvdimm driver-api/nvdimm/nvdimm +nvdimm/security driver-api/nvdimm/security +nvmem/nvmem driver-api/nvmem +openrisc/features arch/openrisc/features +openrisc/index arch/openrisc/index +openrisc/openrisc_port arch/openrisc/openrisc_port +openrisc/todo arch/openrisc/todo +parisc/debugging arch/parisc/debugging +parisc/features arch/parisc/features +parisc/index arch/parisc/index +parisc/registers arch/parisc/registers +perf/arm-ccn admin-guide/perf/arm-ccn +perf/arm_dsu_pmu admin-guide/perf/arm_dsu_pmu +perf/hisi-pmu admin-guide/perf/hisi-pmu +perf/index admin-guide/perf/index +perf/qcom_l2_pmu admin-guide/perf/qcom_l2_pmu +perf/qcom_l3_pmu admin-guide/perf/qcom_l3_pmu +perf/thunderx2-pmu admin-guide/perf/thunderx2-pmu +perf/xgene-pmu admin-guide/perf/xgene-pmu +phy/samsung-usb2 driver-api/phy/samsung-usb2 +powerpc/associativity arch/powerpc/associativity +powerpc/booting arch/powerpc/booting +powerpc/bootwrapper arch/powerpc/bootwrapper +powerpc/cpu_families arch/powerpc/cpu_families +powerpc/cpu_features arch/powerpc/cpu_features +powerpc/dawr-power9 arch/powerpc/dawr-power9 +powerpc/dexcr arch/powerpc/dexcr +powerpc/dscr arch/powerpc/dscr +powerpc/eeh-pci-error-recovery arch/powerpc/eeh-pci-error-recovery +powerpc/elf_hwcaps arch/powerpc/elf_hwcaps +powerpc/elfnote arch/powerpc/elfnote +powerpc/features arch/powerpc/features +powerpc/firmware-assisted-dump arch/powerpc/firmware-assisted-dump +powerpc/hvcs arch/powerpc/hvcs +powerpc/imc arch/powerpc/imc +powerpc/index arch/powerpc/index +powerpc/isa-versions arch/powerpc/isa-versions +powerpc/kaslr-booke32 arch/powerpc/kaslr-booke32 +powerpc/mpc52xx arch/powerpc/mpc52xx +powerpc/papr_hcalls arch/powerpc/papr_hcalls +powerpc/pci_iov_resource_on_powernv arch/powerpc/pci_iov_resource_on_powernv +powerpc/pmu-ebb arch/powerpc/pmu-ebb +powerpc/ptrace arch/powerpc/ptrace +powerpc/qe_firmware arch/powerpc/qe_firmware +powerpc/syscall64-abi arch/powerpc/syscall64-abi +powerpc/transactional_memory arch/powerpc/transactional_memory +powerpc/ultravisor arch/powerpc/ultravisor +powerpc/vas-api arch/powerpc/vas-api +powerpc/vcpudispatch_stats arch/powerpc/vcpudispatch_stats +powerpc/vmemmap_dedup arch/powerpc/vmemmap_dedup +process/clang-format dev-tools/clang-format +process/magic-number staging/magic-number +process/unaligned-memory-access core-api/unaligned-memory-access +rapidio/index driver-api/rapidio/index +rapidio/mport_cdev driver-api/rapidio/mport_cdev +rapidio/rapidio driver-api/rapidio/rapidio +rapidio/rio_cm driver-api/rapidio/rio_cm +rapidio/sysfs driver-api/rapidio/sysfs +rapidio/tsi721 driver-api/rapidio/tsi721 +riscv/acpi arch/riscv/acpi +riscv/boot arch/riscv/boot +riscv/boot-image-header arch/riscv/boot-image-header +riscv/features arch/riscv/features +riscv/hwprobe arch/riscv/hwprobe +riscv/index arch/riscv/index +riscv/patch-acceptance arch/riscv/patch-acceptance +riscv/uabi arch/riscv/uabi +riscv/vector arch/riscv/vector +riscv/vm-layout arch/riscv/vm-layout +s390/3270 arch/s390/3270 +s390/cds arch/s390/cds +s390/common_io arch/s390/common_io +s390/driver-model arch/s390/driver-model +s390/features arch/s390/features +s390/index arch/s390/index +s390/monreader arch/s390/monreader +s390/pci arch/s390/pci +s390/qeth arch/s390/qeth +s390/s390dbf arch/s390/s390dbf +s390/text_files arch/s390/text_files +s390/vfio-ap arch/s390/vfio-ap +s390/vfio-ap-locking arch/s390/vfio-ap-locking +s390/vfio-ccw arch/s390/vfio-ccw +s390/zfcpdump arch/s390/zfcpdump +security/LSM security/lsm-development +security/LSM-sctp security/SCTP +serial/driver driver-api/serial/driver +serial/index driver-api/serial/index +serial/moxa-smartio driver-api/tty/moxa-smartio +serial/n_gsm driver-api/tty/n_gsm +serial/serial-iso7816 driver-api/serial/serial-iso7816 +serial/serial-rs485 driver-api/serial/serial-rs485 +serial/tty driver-api/tty/tty_ldisc +sh/booting arch/sh/booting +sh/features arch/sh/features +sh/index arch/sh/index +sh/new-machine arch/sh/new-machine +sh/register-banks arch/sh/register-banks +sparc/adi arch/sparc/adi +sparc/console arch/sparc/console +sparc/features arch/sparc/features +sparc/index arch/sparc/index +sparc/oradax/oracle-dax arch/sparc/oradax/oracle-dax +staging/kprobes trace/kprobes +sysctl/abi admin-guide/sysctl/abi +sysctl/fs admin-guide/sysctl/fs +sysctl/index admin-guide/sysctl/index +sysctl/kernel admin-guide/sysctl/kernel +sysctl/net admin-guide/sysctl/net +sysctl/sunrpc admin-guide/sysctl/sunrpc +sysctl/user admin-guide/sysctl/user +sysctl/vm admin-guide/sysctl/vm +thermal/cpu-cooling-api driver-api/thermal/cpu-cooling-api +thermal/exynos_thermal driver-api/thermal/exynos_thermal +thermal/exynos_thermal_emulation driver-api/thermal/exynos_thermal_emulation +thermal/index driver-api/thermal/index +thermal/intel_powerclamp admin-guide/thermal/intel_powerclamp +thermal/nouveau_thermal driver-api/thermal/nouveau_thermal +thermal/power_allocator driver-api/thermal/power_allocator +thermal/sysfs-api driver-api/thermal/sysfs-api +thermal/x86_pkg_temperature_thermal driver-api/thermal/x86_pkg_temperature_thermal +tpm/index security/tpm/index +tpm/tpm_vtpm_proxy security/tpm/tpm_vtpm_proxy +trace/coresight trace/coresight/coresight +trace/coresight-cpu-debug trace/coresight/coresight-cpu-debug +trace/rv/da_monitor_synthesis trace/rv/monitor_synthesis +translations/it_IT/admin-guide/security-bugs translations/it_IT/process/security-bugs +translations/it_IT/process/clang-format translations/it_IT/dev-tools/clang-format +translations/it_IT/process/magic-number translations/it_IT/staging/magic-number +translations/it_IT/riscv/patch-acceptance translations/it_IT/arch/riscv/patch-acceptance +translations/ja_JP/howto translations/ja_JP/process/howto +translations/ko_KR/howto translations/ko_KR/process/howto +translations/sp_SP/howto translations/sp_SP/process/howto +translations/sp_SP/submitting-patches translations/sp_SP/process/submitting-patches +translations/zh_CN/admin-guide/security-bugs translations/zh_CN/process/security-bugs +translations/zh_CN/arch translations/zh_CN/arch/index +translations/zh_CN/arm64/amu translations/zh_CN/arch/arm64/amu +translations/zh_CN/arm64/elf_hwcaps translations/zh_CN/arch/arm64/elf_hwcaps +translations/zh_CN/arm64/hugetlbpage translations/zh_CN/arch/arm64/hugetlbpage +translations/zh_CN/arm64/index translations/zh_CN/arch/arm64/index +translations/zh_CN/arm64/perf translations/zh_CN/arch/arm64/perf +translations/zh_CN/coding-style translations/zh_CN/process/coding-style +translations/zh_CN/loongarch/booting translations/zh_CN/arch/loongarch/booting +translations/zh_CN/loongarch/features translations/zh_CN/arch/loongarch/features +translations/zh_CN/loongarch/index translations/zh_CN/arch/loongarch/index +translations/zh_CN/loongarch/introduction translations/zh_CN/arch/loongarch/introduction +translations/zh_CN/loongarch/irq-chip-model translations/zh_CN/arch/loongarch/irq-chip-model +translations/zh_CN/mips/booting translations/zh_CN/arch/mips/booting +translations/zh_CN/mips/features translations/zh_CN/arch/mips/features +translations/zh_CN/mips/index translations/zh_CN/arch/mips/index +translations/zh_CN/mips/ingenic-tcu translations/zh_CN/arch/mips/ingenic-tcu +translations/zh_CN/openrisc/index translations/zh_CN/arch/openrisc/index +translations/zh_CN/openrisc/openrisc_port translations/zh_CN/arch/openrisc/openrisc_port +translations/zh_CN/openrisc/todo translations/zh_CN/arch/openrisc/todo +translations/zh_CN/parisc/debugging translations/zh_CN/arch/parisc/debugging +translations/zh_CN/parisc/index translations/zh_CN/arch/parisc/index +translations/zh_CN/parisc/registers translations/zh_CN/arch/parisc/registers +translations/zh_CN/riscv/boot-image-header translations/zh_CN/arch/riscv/boot-image-header +translations/zh_CN/riscv/index translations/zh_CN/arch/riscv/index +translations/zh_CN/riscv/patch-acceptance translations/zh_CN/arch/riscv/patch-acceptance +translations/zh_CN/riscv/vm-layout translations/zh_CN/arch/riscv/vm-layout +translations/zh_CN/vm/active_mm translations/zh_CN/mm/active_mm +translations/zh_CN/vm/balance translations/zh_CN/mm/balance +translations/zh_CN/vm/damon/api translations/zh_CN/mm/damon/api +translations/zh_CN/vm/damon/design translations/zh_CN/mm/damon/design +translations/zh_CN/vm/damon/faq translations/zh_CN/mm/damon/faq +translations/zh_CN/vm/damon/index translations/zh_CN/mm/damon/index +translations/zh_CN/vm/free_page_reporting translations/zh_CN/mm/free_page_reporting +translations/zh_CN/vm/highmem translations/zh_CN/mm/highmem +translations/zh_CN/vm/hmm translations/zh_CN/mm/hmm +translations/zh_CN/vm/hugetlbfs_reserv translations/zh_CN/mm/hugetlbfs_reserv +translations/zh_CN/vm/hwpoison translations/zh_CN/mm/hwpoison +translations/zh_CN/vm/index translations/zh_CN/mm/index +translations/zh_CN/vm/ksm translations/zh_CN/mm/ksm +translations/zh_CN/vm/memory-model translations/zh_CN/mm/memory-model +translations/zh_CN/vm/mmu_notifier translations/zh_CN/mm/mmu_notifier +translations/zh_CN/vm/numa translations/zh_CN/mm/numa +translations/zh_CN/vm/overcommit-accounting translations/zh_CN/mm/overcommit-accounting +translations/zh_CN/vm/page_frags translations/zh_CN/mm/page_frags +translations/zh_CN/vm/page_owner translations/zh_CN/mm/page_owner +translations/zh_CN/vm/page_table_check translations/zh_CN/mm/page_table_check +translations/zh_CN/vm/remap_file_pages translations/zh_CN/mm/remap_file_pages +translations/zh_CN/vm/split_page_table_lock translations/zh_CN/mm/split_page_table_lock +translations/zh_CN/vm/zsmalloc translations/zh_CN/mm/zsmalloc +translations/zh_TW/arm64/amu translations/zh_TW/arch/arm64/amu +translations/zh_TW/arm64/elf_hwcaps translations/zh_TW/arch/arm64/elf_hwcaps +translations/zh_TW/arm64/hugetlbpage translations/zh_TW/arch/arm64/hugetlbpage +translations/zh_TW/arm64/index translations/zh_TW/arch/arm64/index +translations/zh_TW/arm64/perf translations/zh_TW/arch/arm64/perf +tty/device_drivers/oxsemi-tornado misc-devices/oxsemi-tornado +tty/index driver-api/tty/index +tty/n_tty driver-api/tty/n_tty +tty/tty_buffer driver-api/tty/tty_buffer +tty/tty_driver driver-api/tty/tty_driver +tty/tty_internals driver-api/tty/tty_internals +tty/tty_ldisc driver-api/tty/tty_ldisc +tty/tty_port driver-api/tty/tty_port +tty/tty_struct driver-api/tty/tty_struct +usb/typec driver-api/usb/typec +usb/usb3-debug-port driver-api/usb/usb3-debug-port +userspace-api/media/drivers/st-vgxy61 userspace-api/media/drivers/vgxy61 +userspace-api/media/v4l/pixfmt-meta-d4xx userspace-api/media/v4l/metafmt-d4xx +userspace-api/media/v4l/pixfmt-meta-intel-ipu3 userspace-api/media/v4l/metafmt-intel-ipu3 +userspace-api/media/v4l/pixfmt-meta-rkisp1 userspace-api/media/v4l/metafmt-rkisp1 +userspace-api/media/v4l/pixfmt-meta-uvc userspace-api/media/v4l/metafmt-uvc +userspace-api/media/v4l/pixfmt-meta-vivid userspace-api/media/v4l/metafmt-vivid +userspace-api/media/v4l/pixfmt-meta-vsp1-hgo userspace-api/media/v4l/metafmt-vsp1-hgo +userspace-api/media/v4l/pixfmt-meta-vsp1-hgt userspace-api/media/v4l/metafmt-vsp1-hgt +virt/coco/sevguest virt/coco/sev-guest +virt/kvm/amd-memory-encryption virt/kvm/x86/amd-memory-encryption +virt/kvm/arm/psci virt/kvm/arm/fw-pseudo-registers +virt/kvm/cpuid virt/kvm/x86/cpuid +virt/kvm/hypercalls virt/kvm/x86/hypercalls +virt/kvm/mmu virt/kvm/x86/mmu +virt/kvm/msr virt/kvm/x86/msr +virt/kvm/nested-vmx virt/kvm/x86/nested-vmx +virt/kvm/running-nested-guests virt/kvm/x86/running-nested-guests +virt/kvm/s390-diag virt/kvm/s390/s390-diag +virt/kvm/s390-pv virt/kvm/s390/s390-pv +virt/kvm/s390-pv-boot virt/kvm/s390/s390-pv-boot +virt/kvm/timekeeping virt/kvm/x86/timekeeping +virt/kvm/x86/halt-polling virt/kvm/halt-polling +virtual/index virt/index +virtual/kvm/amd-memory-encryption virt/kvm/x86/amd-memory-encryption +virtual/kvm/cpuid virt/kvm/x86/cpuid +virtual/kvm/index virt/kvm/index +virtual/kvm/vcpu-requests virt/kvm/vcpu-requests +virtual/paravirt_ops virt/paravirt_ops +vm/active_mm mm/active_mm +vm/arch_pgtable_helpers mm/arch_pgtable_helpers +vm/balance mm/balance +vm/bootmem mm/bootmem +vm/damon/api mm/damon/api +vm/damon/design mm/damon/design +vm/damon/faq mm/damon/faq +vm/damon/index mm/damon/index +vm/free_page_reporting mm/free_page_reporting +vm/highmem mm/highmem +vm/hmm mm/hmm +vm/hugetlbfs_reserv mm/hugetlbfs_reserv +vm/hugetlbpage admin-guide/mm/hugetlbpage +vm/hwpoison mm/hwpoison +vm/idle_page_tracking admin-guide/mm/idle_page_tracking +vm/index mm/index +vm/ksm mm/ksm +vm/memory-model mm/memory-model +vm/mmu_notifier mm/mmu_notifier +vm/numa mm/numa +vm/numa_memory_policy admin-guide/mm/numa_memory_policy +vm/oom mm/oom +vm/overcommit-accounting mm/overcommit-accounting +vm/page_allocation mm/page_allocation +vm/page_cache mm/page_cache +vm/page_frags mm/page_frags +vm/page_migration mm/page_migration +vm/page_owner mm/page_owner +vm/page_reclaim mm/page_reclaim +vm/page_table_check mm/page_table_check +vm/page_tables mm/page_tables +vm/pagemap admin-guide/mm/pagemap +vm/physical_memory mm/physical_memory +vm/process_addrs mm/process_addrs +vm/remap_file_pages mm/remap_file_pages +vm/shmfs mm/shmfs +vm/slab mm/slab +vm/slub admin-guide/mm/slab +vm/soft-dirty admin-guide/mm/soft-dirty +vm/split_page_table_lock mm/split_page_table_lock +vm/swap mm/swap +vm/swap_numa admin-guide/mm/swap_numa +vm/transhuge mm/transhuge +vm/unevictable-lru mm/unevictable-lru +vm/userfaultfd admin-guide/mm/userfaultfd +vm/vmalloc mm/vmalloc +vm/vmalloced-kernel-stacks mm/vmalloced-kernel-stacks +vm/vmemmap_dedup mm/vmemmap_dedup +vm/zsmalloc mm/zsmalloc +vm/zswap admin-guide/mm/zswap +watch_queue core-api/watch_queue +x86/amd-memory-encryption arch/x86/amd-memory-encryption +x86/amd_hsmp arch/x86/amd_hsmp +x86/boot arch/x86/boot +x86/booting-dt arch/x86/booting-dt +x86/buslock arch/x86/buslock +x86/cpuinfo arch/x86/cpuinfo +x86/earlyprintk arch/x86/earlyprintk +x86/elf_auxvec arch/x86/elf_auxvec +x86/entry_64 arch/x86/entry_64 +x86/exception-tables arch/x86/exception-tables +x86/features arch/x86/features +x86/i386/IO-APIC arch/x86/i386/IO-APIC +x86/i386/index arch/x86/i386/index +x86/ifs arch/x86/ifs +x86/index arch/x86/index +x86/intel-hfi arch/x86/intel-hfi +x86/intel_txt arch/x86/intel_txt +x86/iommu arch/x86/iommu +x86/kernel-stacks arch/x86/kernel-stacks +x86/mds arch/x86/mds +x86/microcode arch/x86/microcode +x86/mtrr arch/x86/mtrr +x86/orc-unwinder arch/x86/orc-unwinder +x86/pat arch/x86/pat +x86/protection-keys core-api/protection-keys +x86/pti arch/x86/pti +x86/resctrl filesystems/resctrl +x86/resctrl_ui filesystems/resctrl +x86/sgx arch/x86/sgx +x86/sva arch/x86/sva +x86/tdx arch/x86/tdx +x86/tlb arch/x86/tlb +x86/topology arch/x86/topology +x86/tsx_async_abort arch/x86/tsx_async_abort +x86/usb-legacy-support arch/x86/usb-legacy-support +x86/x86_64/5level-paging arch/x86/x86_64/5level-paging +x86/x86_64/cpu-hotplug-spec arch/x86/x86_64/cpu-hotplug-spec +x86/x86_64/fake-numa-for-cpusets arch/x86/x86_64/fake-numa-for-cpusets +x86/x86_64/fsgs arch/x86/x86_64/fsgs +x86/x86_64/index arch/x86/x86_64/index +x86/x86_64/machinecheck arch/x86/x86_64/machinecheck +x86/x86_64/mm arch/x86/x86_64/mm +x86/x86_64/uefi arch/x86/x86_64/uefi +x86/xstate arch/x86/xstate +x86/zero-page arch/x86/zero-page +xilinx/eemi driver-api/xilinx/eemi +xilinx/index driver-api/xilinx/index +xtensa/atomctl arch/xtensa/atomctl +xtensa/booting arch/xtensa/booting +xtensa/features arch/xtensa/features +xtensa/index arch/xtensa/index +xtensa/mmu arch/xtensa/mmu From f2c2f6490085e29521f87d5464b2cdceff0f0c7a Mon Sep 17 00:00:00 2001 From: Vegard Nossum Date: Fri, 5 Sep 2025 16:46:08 +0200 Subject: [PATCH 156/193] docs: add tools/docs/gen-redirects.py Add a new script and a new documentation 'make' target, htmldocs-redirects. This will generate HTML stub files in the HTML documentation output directory that redirect the browser to the new path. Suggested-by: Konstantin Ryabitsev Suggested-by: Jonathan Corbet Signed-off-by: Vegard Nossum Signed-off-by: Jonathan Corbet Message-ID: <20250905144608.577449-4-vegard.nossum@oracle.com> --- Documentation/Makefile | 4 +++ Makefile | 5 ++-- tools/docs/gen-redirects.py | 54 +++++++++++++++++++++++++++++++++++++ 3 files changed, 61 insertions(+), 2 deletions(-) create mode 100755 tools/docs/gen-redirects.py diff --git a/Documentation/Makefile b/Documentation/Makefile index 5c20c68be89a..3609cb86137b 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -108,6 +108,9 @@ htmldocs: @$(srctree)/scripts/sphinx-pre-install --version-check @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var))) +htmldocs-redirects: $(srctree)/Documentation/.renames.txt + @tools/docs/gen-redirects.py --output $(BUILDDIR) < $< + # If Rust support is available and .config exists, add rustdoc generated contents. # If there are any, the errors from this make rustdoc will be displayed but # won't stop the execution of htmldocs @@ -175,6 +178,7 @@ cleandocs: dochelp: @echo ' Linux kernel internal documentation in different formats from ReST:' @echo ' htmldocs - HTML' + @echo ' htmldocs-redirects - generate HTML redirects for moved pages' @echo ' texinfodocs - Texinfo' @echo ' infodocs - Info' @echo ' latexdocs - LaTeX' diff --git a/Makefile b/Makefile index 6bfe776bf3c5..d764afe3a30a 100644 --- a/Makefile +++ b/Makefile @@ -1799,8 +1799,9 @@ $(help-board-dirs): help-%: # Documentation targets # --------------------------------------------------------------------------- -DOC_TARGETS := xmldocs latexdocs pdfdocs htmldocs epubdocs cleandocs \ - linkcheckdocs dochelp refcheckdocs texinfodocs infodocs +DOC_TARGETS := xmldocs latexdocs pdfdocs htmldocs htmldocs-redirects \ + epubdocs cleandocs linkcheckdocs dochelp refcheckdocs \ + texinfodocs infodocs PHONY += $(DOC_TARGETS) $(DOC_TARGETS): $(Q)$(MAKE) $(build)=Documentation $@ diff --git a/tools/docs/gen-redirects.py b/tools/docs/gen-redirects.py new file mode 100755 index 000000000000..6a6ebf6f42dc --- /dev/null +++ b/tools/docs/gen-redirects.py @@ -0,0 +1,54 @@ +#! /usr/bin/env python3 +# SPDX-License-Identifier: GPL-2.0 +# +# Copyright © 2025, Oracle and/or its affiliates. +# Author: Vegard Nossum + +"""Generate HTML redirects for renamed Documentation/**.rst files using +the output of tools/docs/gen-renames.py. + +Example: + + tools/docs/gen-redirects.py --output Documentation/output/ < Documentation/.renames.txt +""" + +import argparse +import os +import sys + +parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) +parser.add_argument('-o', '--output', help='output directory') + +args = parser.parse_args() + +for line in sys.stdin: + line = line.rstrip('\n') + + old_name, new_name = line.split(' ', 2) + + old_html_path = os.path.join(args.output, old_name + '.html') + new_html_path = os.path.join(args.output, new_name + '.html') + + if not os.path.exists(new_html_path): + print(f"warning: target does not exist: {new_html_path} (redirect from {old_html_path})") + continue + + old_html_dir = os.path.dirname(old_html_path) + if not os.path.exists(old_html_dir): + os.makedirs(old_html_dir) + + relpath = os.path.relpath(new_name, os.path.dirname(old_name)) + '.html' + + with open(old_html_path, 'w') as f: + print(f"""\ + + + + + This page has moved + + + +

This page has moved to {new_name}.

+ +""", file=f) From dc896f853e1ae4523a6a45947c8ee89f46b8c93b Mon Sep 17 00:00:00 2001 From: Jakub Kicinski Date: Thu, 4 Sep 2025 07:45:33 -0700 Subject: [PATCH 157/193] docs: submitting-patches: adjust Fixes definition slightly Every now and then people send stylistic patches and use Fixes purely to refer to a commit which added the ugly or unnecessary code. Reword the docs about Fixes. It should hopefully be enough to lead with the word "bug" rather than "issue". We can add more verbiage later, tho, let's try the word swap first. I always feel like the more words the smaller the chance someone will actually read the docs. Signed-off-by: Jakub Kicinski Signed-off-by: Jonathan Corbet Message-ID: <20250904144533.2146576-1-kuba@kernel.org> --- Documentation/process/submitting-patches.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index cede4e7b29af..5778cb9701e1 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -602,8 +602,8 @@ future. Note, this is one of only three tags you might be able to use without explicit permission of the person named (see 'Tagging people requires permission' below for details). -A Fixes: tag indicates that the patch fixes an issue in a previous commit. It -is used to make it easy to determine where a bug originated, which can help +A Fixes: tag indicates that the patch fixes a bug in a previous commit. It +is used to make it easy to determine where an issue originated, which can help review a bug fix. This tag also assists the stable kernel team in determining which stable kernel versions should receive your fix. This is the preferred method for indicating a bug fixed by the patch. See :ref:`describe_changes` From f44a29784f685804d9970cfb0d3439c9e30981d7 Mon Sep 17 00:00:00 2001 From: Konstantin Ryabitsev Date: Tue, 2 Sep 2025 11:44:19 -0400 Subject: [PATCH 158/193] Documentation: update maintainer-pgp-guide for latest best practices Freshen up the maintainer PGP guide: - Bump minimum GnuPG version requirement from 2.2 to 2.4, since 2.2 is no longer maintained - All major hardware tokens now support Curve25519, so remove outdated ECC support callouts - Update hardware device recommendations (Nitrokey Pro 2 -> Nitrokey 3) - Broaden backup media terminology (USB thumb drive -> external media) - Update wording to follow vale's linter recommendations - Various minor wording improvements for clarity Signed-off-by: Konstantin Ryabitsev Reviewed-by: Paul Barker Signed-off-by: Jonathan Corbet Message-ID: <20250902-pgp-guide-updates-v1-1-62ac7312d3f9@linuxfoundation.org> --- .../process/maintainer-pgp-guide.rst | 158 +++++++++--------- 1 file changed, 75 insertions(+), 83 deletions(-) diff --git a/Documentation/process/maintainer-pgp-guide.rst b/Documentation/process/maintainer-pgp-guide.rst index f5277993b195..b6919bf606c3 100644 --- a/Documentation/process/maintainer-pgp-guide.rst +++ b/Documentation/process/maintainer-pgp-guide.rst @@ -49,7 +49,7 @@ hosting infrastructure, regardless of how good the security practices for the latter may be. The above guiding principle is the reason why this guide is needed. We -want to make sure that by placing trust into developers we do not simply +want to make sure that by placing trust into developers we do not merely shift the blame for potential future security incidents to someone else. The goal is to provide a set of guidelines developers can use to create a secure working environment and safeguard the PGP keys used to @@ -60,7 +60,7 @@ establish the integrity of the Linux kernel itself. PGP tools ========= -Use GnuPG 2.2 or later +Use GnuPG 2.4 or later ---------------------- Your distro should already have GnuPG installed by default, you just @@ -69,9 +69,9 @@ To check, run:: $ gpg --version | head -n1 -If you have version 2.2 or above, then you are good to go. If you have a -version that is prior than 2.2, then some commands from this guide may -not work. +If you have version 2.4 or above, then you are good to go. If you have +an earlier version, then you are using a release of GnuPG that is no +longer maintained and some commands from this guide may not work. Configure gpg-agent options ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -199,13 +199,6 @@ separate signing subkey:: $ gpg --quick-addkey [fpr] ed25519 sign -.. note:: ECC support in GnuPG - - Note, that if you intend to use a hardware token that does not - support ED25519 ECC keys, you should choose "nistp256" instead or - "ed25519." See the section below on recommended hardware devices. - - Back up your Certify key for disaster recovery ---------------------------------------------- @@ -213,7 +206,7 @@ The more signatures you have on your PGP key from other developers, the more reasons you have to create a backup version that lives on something other than digital media, for disaster recovery reasons. -The best way to create a printable hardcopy of your private key is by +A good way to create a printable hardcopy of your private key is by using the ``paperkey`` software written for this very purpose. See ``man paperkey`` for more details on the output format and its benefits over other solutions. Paperkey should already be packaged for most @@ -224,11 +217,11 @@ key:: $ gpg --export-secret-key [fpr] | paperkey -o /tmp/key-backup.txt -Print out that file (or pipe the output straight to lpr), then take a -pen and write your passphrase on the margin of the paper. **This is -strongly recommended** because the key printout is still encrypted with -that passphrase, and if you ever change it you will not remember what it -used to be when you had created the backup -- *guaranteed*. +Print out that file, then take a pen and write your passphrase on the +margin of the paper. **This is strongly recommended** because the key +printout is still encrypted with that passphrase, and if you ever change +it you will not remember what it used to be when you had created the +backup -- *guaranteed*. Put the resulting printout and the hand-written passphrase into an envelope and store in a secure and well-protected place, preferably away from your @@ -236,10 +229,9 @@ home, such as your bank vault. .. note:: - Your printer is probably no longer a simple dumb device connected to - your parallel port, but since the output is still encrypted with - your passphrase, printing out even to "cloud-integrated" modern - printers should remain a relatively safe operation. + The key is still encrypted with your passphrase, so printing out + even to "cloud-integrated" modern printers should remain a + relatively safe operation. Back up your whole GnuPG directory ---------------------------------- @@ -255,16 +247,17 @@ on these external copies whenever you need to use your Certify key -- such as when making changes to your own key or signing other people's keys after conferences and summits. -Start by getting a small USB "thumb" drive (preferably two!) that you -will use for backup purposes. You will need to encrypt them using LUKS --- refer to your distro's documentation on how to accomplish this. +Start by getting an external media card (preferably two!) that you will +use for backup purposes. You will need to create an encrypted partition +on this device using LUKS -- refer to your distro's documentation on how +to accomplish this. For the encryption passphrase, you can use the same one as on your PGP key. -Once the encryption process is over, re-insert the USB drive and make -sure it gets properly mounted. Copy your entire ``.gnupg`` directory -over to the encrypted storage:: +Once the encryption process is over, re-insert your device and make sure +it gets properly mounted. Copy your entire ``.gnupg`` directory over to +the encrypted storage:: $ cp -a ~/.gnupg /media/disk/foo/gnupg-backup @@ -273,11 +266,10 @@ You should now test to make sure everything still works:: $ gpg --homedir=/media/disk/foo/gnupg-backup --list-key [fpr] If you don't get any errors, then you should be good to go. Unmount the -USB drive, distinctly label it so you don't blow it away next time you -need to use a random USB drive, and put in a safe place -- but not too -far away, because you'll need to use it every now and again for things -like editing identities, adding or revoking subkeys, or signing other -people's keys. +device, distinctly label it so you don't overwrite it by accident, and +put in a safe place -- but not too far away, because you'll need to use +it every now and again for things like editing identities, adding or +revoking subkeys, or signing other people's keys. Remove the Certify key from your homedir ---------------------------------------- @@ -303,7 +295,7 @@ and store it on offline storage. your GnuPG directory in its entirety. What we are about to do will render your key useless if you do not have a usable backup! -First, identify the keygrip of your Certify key:: +First, identify the "keygrip" of your Certify key:: $ gpg --with-keygrip --list-key [fpr] @@ -328,8 +320,8 @@ Certify key fingerprint). This will correspond directly to a file in your 2222000000000000000000000000000000000000.key 3333000000000000000000000000000000000000.key -All you have to do is simply remove the .key file that corresponds to -the Certify key keygrip:: +It is sufficient to remove the .key file that corresponds to the Certify +key keygrip:: $ cd ~/.gnupg/private-keys-v1.d $ rm 1111000000000000000000000000000000000000.key @@ -372,7 +364,7 @@ GnuPG operation is performed, the keys are loaded into system memory and can be stolen from there by sufficiently advanced malware (think Meltdown and Spectre). -The best way to completely protect your keys is to move them to a +A good way to completely protect your keys is to move them to a specialized hardware device that is capable of smartcard operations. The benefits of smartcards @@ -383,11 +375,11 @@ private keys and performing crypto operations directly on the card itself. Because the key contents never leave the smartcard, the operating system of the computer into which you plug in the hardware device is not able to retrieve the private keys themselves. This is very -different from the encrypted USB storage device we used earlier for -backup purposes -- while that USB device is plugged in and mounted, the +different from the encrypted media storage device we used earlier for +backup purposes -- while that device is plugged in and mounted, the operating system is able to access the private key contents. -Using external encrypted USB media is not a substitute to having a +Using external encrypted media is not a substitute to having a smartcard-capable device. Available smartcard devices @@ -398,17 +390,15 @@ easiest is to get a specialized USB device that implements smartcard functionality. There are several options available: - `Nitrokey Start`_: Open hardware and Free Software, based on FSI - Japan's `Gnuk`_. One of the few available commercial devices that - support ED25519 ECC keys, but offer fewest security features (such as - resistance to tampering or some side-channel attacks). -- `Nitrokey Pro 2`_: Similar to the Nitrokey Start, but more - tamper-resistant and offers more security features. Pro 2 supports ECC - cryptography (NISTP). + Japan's `Gnuk`_. One of the cheapest options, but offers fewest + security features (such as resistance to tampering or some + side-channel attacks). +- `Nitrokey 3`_: Similar to the Nitrokey Start, but more + tamper-resistant and offers more security features and USB + form-factors. Supports ECC cryptography (ED25519 and NISTP). - `Yubikey 5`_: proprietary hardware and software, but cheaper than - Nitrokey Pro and comes available in the USB-C form that is more useful - with newer laptops. Offers additional security features such as FIDO - U2F, among others, and now finally supports NISTP and ED25519 ECC - keys. + Nitrokey with a similar set of features. Supports ECC cryptography + (ED25519 and NISTP). Your choice will depend on cost, shipping availability in your geographical region, and open/proprietary hardware considerations. @@ -419,8 +409,8 @@ geographical region, and open/proprietary hardware considerations. you `qualify for a free Nitrokey Start`_ courtesy of The Linux Foundation. -.. _`Nitrokey Start`: https://shop.nitrokey.com/shop/product/nitrokey-start-6 -.. _`Nitrokey Pro 2`: https://shop.nitrokey.com/shop/product/nkpr2-nitrokey-pro-2-3 +.. _`Nitrokey Start`: https://www.nitrokey.com/products/nitrokeys +.. _`Nitrokey 3`: https://www.nitrokey.com/products/nitrokeys .. _`Yubikey 5`: https://www.yubico.com/products/yubikey-5-overview/ .. _Gnuk: https://www.fsij.org/doc-gnuk/ .. _`qualify for a free Nitrokey Start`: https://www.kernel.org/nitrokey-digital-tokens-for-kernel-developers.html @@ -455,7 +445,7 @@ the smartcard). You so rarely need to use the Admin PIN, that you will inevitably forget what it is if you do not record it. Getting back to the main card menu, you can also set other values (such -as name, sex, login data, etc), but it's not necessary and will +as name, gender, login data, etc), but it's not necessary and will additionally leak information about your smartcard should you lose it. .. note:: @@ -615,7 +605,7 @@ run:: You can also use a specific date if that is easier to remember (e.g. your birthday, January 1st, or Canada Day):: - $ gpg --quick-set-expire [fpr] 2025-07-01 + $ gpg --quick-set-expire [fpr] 2038-07-01 Remember to send the updated key back to keyservers:: @@ -656,9 +646,9 @@ hundreds of cloned repositories floating around, how does anyone verify that their copy of linux.git has not been tampered with by a malicious third party? -Or what happens if a backdoor is discovered in the code and the "Author" -line in the commit says it was done by you, while you're pretty sure you -had `nothing to do with it`_? +Or what happens if malicious code is discovered in the kernel and the +"Author" line in the commit says it was done by you, while you're pretty +sure you had `nothing to do with it`_? To address both of these issues, Git introduced PGP integration. Signed tags prove the repository integrity by assuring that its contents are @@ -681,8 +671,7 @@ should be used (``[fpr]`` is the fingerprint of your key):: How to work with signed tags ---------------------------- -To create a signed tag, simply pass the ``-s`` switch to the tag -command:: +To create a signed tag, pass the ``-s`` switch to the tag command:: $ git tag -s [tagname] @@ -693,7 +682,7 @@ not been maliciously altered. How to verify signed tags ~~~~~~~~~~~~~~~~~~~~~~~~~ -To verify a signed tag, simply use the ``verify-tag`` command:: +To verify a signed tag, use the ``verify-tag`` command:: $ git verify-tag [tagname] @@ -712,9 +701,9 @@ The merge message will contain something like this:: # gpg: Signature made [...] # gpg: Good signature from [...] -If you are verifying someone else's git tag, then you will need to -import their PGP key. Please refer to the -":ref:`verify_identities`" section below. +If you are verifying someone else's git tag, you will first need to +import their PGP key. Please refer to the ":ref:`verify_identities`" +section below. Configure git to always sign annotated tags ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -728,16 +717,16 @@ configuration option:: How to work with signed commits ------------------------------- -It is easy to create signed commits, but it is much more difficult to -use them in Linux kernel development, since it relies on patches sent to -the mailing list, and this workflow does not preserve PGP commit -signatures. Furthermore, when rebasing your repository to match -upstream, even your own PGP commit signatures will end up discarded. For -this reason, most kernel developers don't bother signing their commits -and will ignore signed commits in any external repositories that they -rely upon in their work. +It is also possible to create signed commits, but they have limited +usefulness in Linux kernel development. The kernel contribution workflow +relies on sending in patches, and converting commits to patches does not +preserve git commit signatures. Furthermore, when rebasing your own +repository on a newer upstream, PGP commit signatures will end up +discarded. For this reason, most kernel developers don't bother signing +their commits and will ignore signed commits in any external +repositories that they rely upon in their work. -However, if you have your working git tree publicly available at some +That said, if you have your working git tree publicly available at some git hosting service (kernel.org, infradead.org, ozlabs.org, or others), then the recommendation is that you sign all your git commits even if upstream developers do not directly benefit from this practice. @@ -748,7 +737,7 @@ We recommend this for the following reasons: provenance, even externally maintained trees carrying PGP commit signatures will be valuable for such purposes. 2. If you ever need to re-clone your local repository (for example, - after a disk failure), this lets you easily verify the repository + after reinstalling your system), this lets you verify the repository integrity before resuming your work. 3. If someone needs to cherry-pick your commits, this allows them to quickly verify their integrity before applying them. @@ -756,9 +745,8 @@ We recommend this for the following reasons: Creating signed commits ~~~~~~~~~~~~~~~~~~~~~~~ -To create a signed commit, you just need to pass the ``-S`` flag to the -``git commit`` command (it's capital ``-S`` due to collision with -another flag):: +To create a signed commit, pass the ``-S`` flag to the ``git commit`` +command (it's capital ``-S`` due to collision with another flag):: $ git commit -S @@ -775,7 +763,6 @@ You can tell git to always sign commits:: .. _verify_identities: - How to work with signed patches ------------------------------- @@ -793,6 +780,11 @@ headers (a-la DKIM): Installing and configuring patatt ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. note:: + + If you use B4 to send in your patches, patatt is already installed + and integrated into your workflow. + Patatt is packaged for many distributions already, so please check there first. You can also install it from pypi using "``pip install patatt``". @@ -835,9 +827,9 @@ encounters, for example:: How to verify kernel developer identities ========================================= -Signing tags and commits is easy, but how does one go about verifying -that the key used to sign something belongs to the actual kernel -developer and not to a malicious imposter? +Signing tags and commits is straightforward, but how does one go about +verifying that the key used to sign something belongs to the actual +kernel developer and not to a malicious imposter? Configure auto-key-retrieval using WKD and DANE ----------------------------------------------- @@ -884,7 +876,7 @@ various software makers dictating who should be your trusted certifying entity, PGP leaves this responsibility to each user. Unfortunately, very few people understand how the Web of Trust works. -While it remains an important aspect of the OpenPGP specification, +While it is still an important part of the OpenPGP specification, recent versions of GnuPG (2.2 and above) have implemented an alternative mechanism called "Trust on First Use" (TOFU). You can think of TOFU as "the SSH-like approach to trust." With SSH, the first time you connect @@ -894,8 +886,8 @@ to connect, forcing you to make a decision on whether you choose to trust the changed key or not. Similarly, the first time you import someone's PGP key, it is assumed to be valid. If at any point in the future GnuPG comes across another key with the same identity, both the -previously imported key and the new key will be marked as invalid and -you will need to manually figure out which one to keep. +previously imported key and the new key will be marked for verification +and you will need to manually figure out which one to keep. We recommend that you use the combined TOFU+PGP trust model (which is the new default in GnuPG v2). To set it, add (or modify) the From 944df7a31452f75bbc15b1e7215e1aacee8cd1b4 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Mon, 8 Sep 2025 13:32:10 -0600 Subject: [PATCH 159/193] docs: update the guidance for Link: tags As stated definitively by Linus, the use of Link: tags should be limited to situations where there is additional useful information to be found at the far end of the link. Update our documentation to reflect that policy, and to remove the suggestion for a Git hook to add those tags automatically. Link: https://lore.kernel.org/all/CAHk-=wh5AyuvEhNY9a57v-vwyr7EkPVRUKMPwj92yF_K0dJHVg@mail.gmail.com/ Cc: Linus Walleij Reviewed-by: Randy Dunlap Reviewed-by: Linus Walleij Signed-off-by: Jonathan Corbet Message-ID: <87segwyc3p.fsf@trenco.lwn.net> --- Documentation/maintainer/configure-git.rst | 28 ---------------------- Documentation/process/5.Posting.rst | 7 +++--- 2 files changed, 3 insertions(+), 32 deletions(-) diff --git a/Documentation/maintainer/configure-git.rst b/Documentation/maintainer/configure-git.rst index 0a36831814ea..0c21f203cf7a 100644 --- a/Documentation/maintainer/configure-git.rst +++ b/Documentation/maintainer/configure-git.rst @@ -28,31 +28,3 @@ You may also like to tell ``gpg`` which ``tty`` to use (add to your shell rc file):: export GPG_TTY=$(tty) - - -Creating commit links to lore.kernel.org ----------------------------------------- - -The web site https://lore.kernel.org is meant as a grand archive of all mail -list traffic concerning or influencing the kernel development. Storing archives -of patches here is a recommended practice, and when a maintainer applies a -patch to a subsystem tree, it is a good idea to provide a Link: tag with a -reference back to the lore archive so that people that browse the commit -history can find related discussions and rationale behind a certain change. -The link tag will look like this:: - - Link: https://lore.kernel.org/r/ - -This can be configured to happen automatically any time you issue ``git am`` -by adding the following hook into your git:: - - $ git config am.messageid true - $ cat >.git/hooks/applypatch-msg <<'EOF' - #!/bin/sh - . git-sh-setup - perl -pi -e 's|^Message-I[dD]:\s*]+)>?$|Link: https://lore.kernel.org/r/$1|g;' "$1" - test -x "$GIT_DIR/hooks/commit-msg" && - exec "$GIT_DIR/hooks/commit-msg" ${1+"$@"} - : - EOF - $ chmod a+x .git/hooks/applypatch-msg diff --git a/Documentation/process/5.Posting.rst b/Documentation/process/5.Posting.rst index 22fa925353cf..9999bcbdccc9 100644 --- a/Documentation/process/5.Posting.rst +++ b/Documentation/process/5.Posting.rst @@ -207,10 +207,9 @@ document with a specification implemented by the patch:: Link: https://example.com/somewhere.html optional-other-stuff -Many maintainers when applying a patch also add this tag to link to the -latest public review posting of the patch; often this is automatically done -by tools like b4 or a git hook like the one described in -'Documentation/maintainer/configure-git.rst'. +As per guidance from the Chief Penguin, a Link: tag should only be added to +a commit if it leads to useful information that is not found in the commit +itself. If the URL points to a public bug report being fixed by the patch, use the "Closes:" tag instead:: From 00d95fcc4dee66dfb6980de6f2973b32f973a1eb Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Tue, 9 Sep 2025 13:35:37 -0600 Subject: [PATCH 160/193] docs: kdoc: handle the obsolescensce of docutils.ErrorString() The ErrorString() and SafeString() docutils functions were helpers meant to ease the handling of encodings during the Python 3 transition. There is no real need for them after Python 3.6, and docutils 0.22 removes them, breaking the docs build Handle this by just injecting our own one-liner version of ErrorString(), and removing the sole SafeString() call entirely. Reported-by: Zhixu Liu Signed-off-by: Jonathan Corbet Message-ID: <87ldmnv2pi.fsf@trenco.lwn.net> --- Documentation/sphinx/kernel_feat.py | 4 +++- Documentation/sphinx/kernel_include.py | 6 ++++-- Documentation/sphinx/maintainers_include.py | 4 +++- 3 files changed, 10 insertions(+), 4 deletions(-) diff --git a/Documentation/sphinx/kernel_feat.py b/Documentation/sphinx/kernel_feat.py index e3a51867f27b..aaac76892ceb 100644 --- a/Documentation/sphinx/kernel_feat.py +++ b/Documentation/sphinx/kernel_feat.py @@ -40,9 +40,11 @@ import sys from docutils import nodes, statemachine from docutils.statemachine import ViewList from docutils.parsers.rst import directives, Directive -from docutils.utils.error_reporting import ErrorString from sphinx.util.docutils import switch_source_input +def ErrorString(exc): # Shamelessly stolen from docutils + return f'{exc.__class__.__name}: {exc}' + __version__ = '1.0' def setup(app): diff --git a/Documentation/sphinx/kernel_include.py b/Documentation/sphinx/kernel_include.py index 2c4bb8215b4c..f94412cd17c9 100755 --- a/Documentation/sphinx/kernel_include.py +++ b/Documentation/sphinx/kernel_include.py @@ -89,7 +89,6 @@ import sys from docutils import io, nodes, statemachine from docutils.statemachine import ViewList -from docutils.utils.error_reporting import SafeString, ErrorString from docutils.parsers.rst import Directive, directives from docutils.parsers.rst.directives.body import CodeBlock, NumberLines @@ -106,6 +105,9 @@ logger = logging.getLogger(__name__) RE_DOMAIN_REF = re.compile(r'\\ :(ref|c:type|c:func):`([^<`]+)(?:<([^>]+)>)?`\\') RE_SIMPLE_REF = re.compile(r'`([^`]+)`') +def ErrorString(exc): # Shamelessly stolen from docutils + return f'{exc.__class__.__name}: {exc}' + # ============================================================================== class KernelInclude(Directive): @@ -156,7 +158,7 @@ class KernelInclude(Directive): except UnicodeEncodeError: raise self.severe('Problems with directive path:\n' 'Cannot encode input file path "%s" ' - '(wrong locale?).' % SafeString(path)) + '(wrong locale?).' % path) except IOError as error: raise self.severe('Problems with directive path:\n%s.' % ErrorString(error)) diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py index d31cff867436..519ad18685b2 100755 --- a/Documentation/sphinx/maintainers_include.py +++ b/Documentation/sphinx/maintainers_include.py @@ -22,10 +22,12 @@ import re import os.path from docutils import statemachine -from docutils.utils.error_reporting import ErrorString from docutils.parsers.rst import Directive from docutils.parsers.rst.directives.misc import Include +def ErrorString(exc): # Shamelessly stolen from docutils + return f'{exc.__class__.__name}: {exc}' + __version__ = '1.0' def setup(app): From 5089ec0bb1bc80a87cfbc2a90e047161adfcb630 Mon Sep 17 00:00:00 2001 From: Taimoor Zaeem Date: Sun, 14 Sep 2025 16:31:56 +0500 Subject: [PATCH 161/193] Documentation: staging: fix spelling error in remoteproc.rst Fix typo 'implementors' to 'implementers' in remote processor framework documentation. Signed-off-by: Taimoor Zaeem Signed-off-by: Jonathan Corbet Message-ID: --- Documentation/staging/remoteproc.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/staging/remoteproc.rst b/Documentation/staging/remoteproc.rst index 348ee7e508ac..5c226fa076d6 100644 --- a/Documentation/staging/remoteproc.rst +++ b/Documentation/staging/remoteproc.rst @@ -104,7 +104,7 @@ Typical usage rproc_shutdown(my_rproc); } -API for implementors +API for implementers ==================== :: From 9946f344528afabb8620a5c3b788cfa505211517 Mon Sep 17 00:00:00 2001 From: Akiyoshi Kurita Date: Sun, 14 Sep 2025 02:34:13 +0900 Subject: [PATCH 162/193] docs: w1: ds2482: fix typo in buses Correct a spelling mistake in ds2482.rst ("busses" -> "buses"). No functional change. Signed-off-by: Akiyoshi Kurita Signed-off-by: Jonathan Corbet Message-ID: <20250913173413.951378-1-weibu@redadmin.org> --- Documentation/w1/masters/ds2482.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/w1/masters/ds2482.rst b/Documentation/w1/masters/ds2482.rst index 17ebe8f660cd..5862024e4b15 100644 --- a/Documentation/w1/masters/ds2482.rst +++ b/Documentation/w1/masters/ds2482.rst @@ -22,7 +22,7 @@ Description ----------- The Maxim/Dallas Semiconductor DS2482 is a I2C device that provides -one (DS2482-100) or eight (DS2482-800) 1-wire busses. +one (DS2482-100) or eight (DS2482-800) 1-wire buses. General Remarks From 1e9ddbb2cd346e42256c5ede2cc40439f2f99bb7 Mon Sep 17 00:00:00 2001 From: Akira Yokosawa Date: Thu, 11 Sep 2025 17:29:31 +0900 Subject: [PATCH 163/193] docs: Pull LKMM documentation into dev-tools book Currently, LKMM docs are not included in any of kernel documentation books. Commit e40573a43d16 ("docs: put atomic*.txt and memory-barriers.txt into the core-api book") covered plain-text docs under Documentation/ by using the "include::" directive along with the ":literal:" option. As LKMM docs are not under Documentation/, the same approach would not work due to the directive's restriction. As a matter of fact, kernel documentation has an extended directive by the name of "kernel-include::", which loosens such restriction and accepts any files under the kernel source tree. Rather than moving LKMM docs around, use the latter and pull them into the dev-tools book next to KCSAN. Signed-off-by: Akira Yokosawa Cc: Paul E. McKenney Acked-by: Paul E. McKenney Signed-off-by: Jonathan Corbet Message-ID: <7ce84a93-5cbc-420e-894a-06a0372c52ab@gmail.com> --- Documentation/dev-tools/index.rst | 1 + .../dev-tools/lkmm/docs/access-marking.rst | 11 ++++++++++ .../dev-tools/lkmm/docs/cheatsheet.rst | 11 ++++++++++ .../lkmm/docs/control-dependencies.rst | 11 ++++++++++ .../dev-tools/lkmm/docs/explanation.rst | 11 ++++++++++ .../dev-tools/lkmm/docs/glossary.rst | 11 ++++++++++ .../lkmm/docs/herd-representation.rst | 11 ++++++++++ Documentation/dev-tools/lkmm/docs/index.rst | 21 +++++++++++++++++++ .../dev-tools/lkmm/docs/litmus-tests.rst | 11 ++++++++++ Documentation/dev-tools/lkmm/docs/locking.rst | 11 ++++++++++ .../dev-tools/lkmm/docs/ordering.rst | 11 ++++++++++ Documentation/dev-tools/lkmm/docs/readme.rst | 11 ++++++++++ Documentation/dev-tools/lkmm/docs/recipes.rst | 11 ++++++++++ .../dev-tools/lkmm/docs/references.rst | 11 ++++++++++ Documentation/dev-tools/lkmm/docs/simple.rst | 11 ++++++++++ Documentation/dev-tools/lkmm/index.rst | 15 +++++++++++++ Documentation/dev-tools/lkmm/readme.rst | 11 ++++++++++ MAINTAINERS | 1 + 18 files changed, 192 insertions(+) create mode 100644 Documentation/dev-tools/lkmm/docs/access-marking.rst create mode 100644 Documentation/dev-tools/lkmm/docs/cheatsheet.rst create mode 100644 Documentation/dev-tools/lkmm/docs/control-dependencies.rst create mode 100644 Documentation/dev-tools/lkmm/docs/explanation.rst create mode 100644 Documentation/dev-tools/lkmm/docs/glossary.rst create mode 100644 Documentation/dev-tools/lkmm/docs/herd-representation.rst create mode 100644 Documentation/dev-tools/lkmm/docs/index.rst create mode 100644 Documentation/dev-tools/lkmm/docs/litmus-tests.rst create mode 100644 Documentation/dev-tools/lkmm/docs/locking.rst create mode 100644 Documentation/dev-tools/lkmm/docs/ordering.rst create mode 100644 Documentation/dev-tools/lkmm/docs/readme.rst create mode 100644 Documentation/dev-tools/lkmm/docs/recipes.rst create mode 100644 Documentation/dev-tools/lkmm/docs/references.rst create mode 100644 Documentation/dev-tools/lkmm/docs/simple.rst create mode 100644 Documentation/dev-tools/lkmm/index.rst create mode 100644 Documentation/dev-tools/lkmm/readme.rst diff --git a/Documentation/dev-tools/index.rst b/Documentation/dev-tools/index.rst index 65c54b27a60b..4b8425e348ab 100644 --- a/Documentation/dev-tools/index.rst +++ b/Documentation/dev-tools/index.rst @@ -29,6 +29,7 @@ Documentation/process/debugging/index.rst ubsan kmemleak kcsan + lkmm/index kfence kselftest kunit/index diff --git a/Documentation/dev-tools/lkmm/docs/access-marking.rst b/Documentation/dev-tools/lkmm/docs/access-marking.rst new file mode 100644 index 000000000000..80058a4da980 --- /dev/null +++ b/Documentation/dev-tools/lkmm/docs/access-marking.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Access Marking +-------------- + +Literal include of ``tools/memory-model/Documentation/access-marking.txt``. + +------------------------------------------------------------------ + +.. kernel-include:: tools/memory-model/Documentation/access-marking.txt + :literal: diff --git a/Documentation/dev-tools/lkmm/docs/cheatsheet.rst b/Documentation/dev-tools/lkmm/docs/cheatsheet.rst new file mode 100644 index 000000000000..37681f6a6a8c --- /dev/null +++ b/Documentation/dev-tools/lkmm/docs/cheatsheet.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Cheatsheet +---------- + +Literal include of ``tools/memory-model/Documentation/cheatsheet.txt``. + +------------------------------------------------------------------ + +.. kernel-include:: tools/memory-model/Documentation/cheatsheet.txt + :literal: diff --git a/Documentation/dev-tools/lkmm/docs/control-dependencies.rst b/Documentation/dev-tools/lkmm/docs/control-dependencies.rst new file mode 100644 index 000000000000..5ae97e8861eb --- /dev/null +++ b/Documentation/dev-tools/lkmm/docs/control-dependencies.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Control Dependencies +-------------------- + +Literal include of ``tools/memory-model/Documentation/control-dependencies.txt``. + +------------------------------------------------------------------ + +.. kernel-include:: tools/memory-model/Documentation/control-dependencies.txt + :literal: diff --git a/Documentation/dev-tools/lkmm/docs/explanation.rst b/Documentation/dev-tools/lkmm/docs/explanation.rst new file mode 100644 index 000000000000..0bcba9a5ddf7 --- /dev/null +++ b/Documentation/dev-tools/lkmm/docs/explanation.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Explanation +----------- + +Literal include of ``tools/memory-model/Documentation/explanation.txt``. + +------------------------------------------------------------------ + +.. kernel-include:: tools/memory-model/Documentation/explanation.txt + :literal: diff --git a/Documentation/dev-tools/lkmm/docs/glossary.rst b/Documentation/dev-tools/lkmm/docs/glossary.rst new file mode 100644 index 000000000000..849aefdf3d6e --- /dev/null +++ b/Documentation/dev-tools/lkmm/docs/glossary.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Glossary +-------- + +Literal include of ``tools/memory-model/Documentation/glossary.txt``. + +------------------------------------------------------------------ + +.. kernel-include:: tools/memory-model/Documentation/glossary.txt + :literal: diff --git a/Documentation/dev-tools/lkmm/docs/herd-representation.rst b/Documentation/dev-tools/lkmm/docs/herd-representation.rst new file mode 100644 index 000000000000..ebf4a2181cd7 --- /dev/null +++ b/Documentation/dev-tools/lkmm/docs/herd-representation.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +herd-representation +------------------- + +Literal include of ``tools/memory-model/Documentation/herd-representation``. + +------------------------------------------------------------------ + +.. kernel-include:: tools/memory-model/Documentation/herd-representation.txt + :literal: diff --git a/Documentation/dev-tools/lkmm/docs/index.rst b/Documentation/dev-tools/lkmm/docs/index.rst new file mode 100644 index 000000000000..abbddcc009de --- /dev/null +++ b/Documentation/dev-tools/lkmm/docs/index.rst @@ -0,0 +1,21 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Documentation +============= + +.. toctree:: + :maxdepth: 1 + + readme + simple + ordering + litmus-tests + locking + recipes + control-dependencies + access-marking + cheatsheet + explanation + herd-representation + glossary + references diff --git a/Documentation/dev-tools/lkmm/docs/litmus-tests.rst b/Documentation/dev-tools/lkmm/docs/litmus-tests.rst new file mode 100644 index 000000000000..3293f4540156 --- /dev/null +++ b/Documentation/dev-tools/lkmm/docs/litmus-tests.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Litmus Tests +------------ + +Literal include of ``tools/memory-model/Documentation/litmus-tests.txt``. + +------------------------------------------------------------------ + +.. kernel-include:: tools/memory-model/Documentation/litmus-tests.txt + :literal: diff --git a/Documentation/dev-tools/lkmm/docs/locking.rst b/Documentation/dev-tools/lkmm/docs/locking.rst new file mode 100644 index 000000000000..b5eae4c0acb7 --- /dev/null +++ b/Documentation/dev-tools/lkmm/docs/locking.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Locking +------- + +Literal include of ``tools/memory-model/Documentation/locking.txt``. + +------------------------------------------------------------------ + +.. kernel-include:: tools/memory-model/Documentation/locking.txt + :literal: diff --git a/Documentation/dev-tools/lkmm/docs/ordering.rst b/Documentation/dev-tools/lkmm/docs/ordering.rst new file mode 100644 index 000000000000..a2343c12462d --- /dev/null +++ b/Documentation/dev-tools/lkmm/docs/ordering.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Ordering +-------- + +Literal include of ``tools/memory-model/Documentation/ordering.txt``. + +------------------------------------------------------------------ + +.. kernel-include:: tools/memory-model/Documentation/ordering.txt + :literal: diff --git a/Documentation/dev-tools/lkmm/docs/readme.rst b/Documentation/dev-tools/lkmm/docs/readme.rst new file mode 100644 index 000000000000..51e7a64e4435 --- /dev/null +++ b/Documentation/dev-tools/lkmm/docs/readme.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +README (for LKMM Documentation) +------------------------------- + +Literal include of ``tools/memory-model/Documentation/README``. + +------------------------------------------------------------------ + +.. kernel-include:: tools/memory-model/Documentation/README + :literal: diff --git a/Documentation/dev-tools/lkmm/docs/recipes.rst b/Documentation/dev-tools/lkmm/docs/recipes.rst new file mode 100644 index 000000000000..e55952640047 --- /dev/null +++ b/Documentation/dev-tools/lkmm/docs/recipes.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Recipes +------- + +Literal include of ``tools/memory-model/Documentation/recipes.txt``. + +------------------------------------------------------------------ + +.. kernel-include:: tools/memory-model/Documentation/recipes.txt + :literal: diff --git a/Documentation/dev-tools/lkmm/docs/references.rst b/Documentation/dev-tools/lkmm/docs/references.rst new file mode 100644 index 000000000000..c6831b3c9c02 --- /dev/null +++ b/Documentation/dev-tools/lkmm/docs/references.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +References +---------- + +Literal include of ``tools/memory-model/Documentation/references.txt``. + +------------------------------------------------------------------ + +.. kernel-include:: tools/memory-model/Documentation/references.txt + :literal: diff --git a/Documentation/dev-tools/lkmm/docs/simple.rst b/Documentation/dev-tools/lkmm/docs/simple.rst new file mode 100644 index 000000000000..5c1094c95f45 --- /dev/null +++ b/Documentation/dev-tools/lkmm/docs/simple.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Simple +------ + +Literal include of ``tools/memory-model/Documentation/simple.txt``. + +------------------------------------------------------------------ + +.. kernel-include:: tools/memory-model/Documentation/simple.txt + :literal: diff --git a/Documentation/dev-tools/lkmm/index.rst b/Documentation/dev-tools/lkmm/index.rst new file mode 100644 index 000000000000..e52782449ca3 --- /dev/null +++ b/Documentation/dev-tools/lkmm/index.rst @@ -0,0 +1,15 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================================ +Linux Kernel Memory Consistency Model (LKMM) +============================================ + +This section literally renders documents under ``tools/memory-model/`` +and ``tools/memory-model/Documentation/``, which are maintained in +the *pure* plain text form. + +.. toctree:: + :maxdepth: 2 + + readme + docs/index diff --git a/Documentation/dev-tools/lkmm/readme.rst b/Documentation/dev-tools/lkmm/readme.rst new file mode 100644 index 000000000000..a7f847109584 --- /dev/null +++ b/Documentation/dev-tools/lkmm/readme.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +README (for LKMM) +================= + +Literal include of ``tools/memory-model/README``. + +------------------------------------------------------------ + +.. kernel-include:: tools/memory-model/README + :literal: diff --git a/MAINTAINERS b/MAINTAINERS index ef87548b8f88..ac47a5d0d8e8 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -14151,6 +14151,7 @@ T: git git://git.kernel.org/pub/scm/linux/kernel/git/rcu/linux.git rcu/dev F: Documentation/atomic_bitops.txt F: Documentation/atomic_t.txt F: Documentation/core-api/refcount-vs-atomic.rst +F: Documentation/dev-tools/lkmm/ F: Documentation/litmus-tests/ F: Documentation/memory-barriers.txt F: tools/memory-model/ From 8b00d6fe96960aaba1b923d4a8c1ddb173c9c1ff Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Thu, 4 Sep 2025 13:33:56 -0600 Subject: [PATCH 164/193] docs: kdoc: trim __cacheline_group_* with the other annotations The special case for __cacheline_group_begin/end() can be handled by just adding another pattern to the struct_prefixes, eliminating the need for a special case in push_parameter(). One change is that these annotations no longer appear in the rendered output, just like all the other annotations that we clean out. Signed-off-by: Jonathan Corbet --- scripts/lib/kdoc/kdoc_parser.py | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py index a560546c1867..a90f77d6b669 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -90,6 +90,7 @@ struct_prefixes = [ (KernRe(r'\s*CRYPTO_MINALIGN_ATTR', re.S), ' '), (KernRe(r'\s*____cacheline_aligned_in_smp', re.S), ' '), (KernRe(r'\s*____cacheline_aligned', re.S), ' '), + (KernRe(r'\s*__cacheline_group_(begin|end)\([^\)]+\);'), ''), # # Unwrap struct_group macros based on this definition: # __struct_group(TAG, NAME, ATTRS, MEMBERS...) @@ -447,12 +448,6 @@ class KernelDoc: self.entry.parameterdescs[param] = "anonymous\n" self.entry.anon_struct_union = True - # Handle cache group enforcing variables: they do not need - # to be described in header files - elif "__cacheline_group" in param: - # Ignore __cacheline_group_begin and __cacheline_group_end - return - # Warn if parameter has no description # (but ignore ones starting with # as these are not parameters # but inline preprocessor statements) From e214cca38f1f35d42e63e990c610c96f993343c4 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Thu, 4 Sep 2025 14:01:20 -0600 Subject: [PATCH 165/193] docs: kdoc: tighten up the push_parameter() no-type case The handling of untyped parameters involved a number of redundant tests; restructure the code to remove them and be more compact. No output changes. Signed-off-by: Jonathan Corbet --- scripts/lib/kdoc/kdoc_parser.py | 40 +++++++++++++++------------------ 1 file changed, 18 insertions(+), 22 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py index a90f77d6b669..2118c20b3056 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -423,30 +423,26 @@ class KernelDoc: param = KernRe(r'[\[\)].*').sub('', param, count=1) - if dtype == "" and param.endswith("..."): - if KernRe(r'\w\.\.\.$').search(param): - # For named variable parameters of the form `x...`, - # remove the dots - param = param[:-3] - else: - # Handles unnamed variable parameters - param = "..." + # + # Look at various "anonymous type" cases. + # + if dtype == '': + if param.endswith("..."): + if len(param) > 3: # there is a name provided, use that + param = param[:-3] + if not self.entry.parameterdescs.get(param): + self.entry.parameterdescs[param] = "variable arguments" - if param not in self.entry.parameterdescs or \ - not self.entry.parameterdescs[param]: + elif (not param) or param == "void": + param = "void" + self.entry.parameterdescs[param] = "no arguments" - self.entry.parameterdescs[param] = "variable arguments" - - elif dtype == "" and (not param or param == "void"): - param = "void" - self.entry.parameterdescs[param] = "no arguments" - - elif dtype == "" and param in ["struct", "union"]: - # Handle unnamed (anonymous) union or struct - dtype = param - param = "{unnamed_" + param + "}" - self.entry.parameterdescs[param] = "anonymous\n" - self.entry.anon_struct_union = True + elif param in ["struct", "union"]: + # Handle unnamed (anonymous) union or struct + dtype = param + param = "{unnamed_" + param + "}" + self.entry.parameterdescs[param] = "anonymous\n" + self.entry.anon_struct_union = True # Warn if parameter has no description # (but ignore ones starting with # as these are not parameters From f853e83006ab39c3dafe085a488c14bb46906601 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Thu, 4 Sep 2025 14:27:00 -0600 Subject: [PATCH 166/193] docs: kdoc: remove a single-use variable struct_attribute is only used once, so just put its value there directly and drop the name. Signed-off-by: Jonathan Corbet --- scripts/lib/kdoc/kdoc_parser.py | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py index 2118c20b3056..b25c8d80b965 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -76,13 +76,11 @@ doc_begin_func = KernRe(str(doc_com) + # initial " * ' # Here begins a long set of transformations to turn structure member prefixes # and macro invocations into something we can parse and generate kdoc for. # -struct_attribute = KernRe(r"__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)", - flags=re.I | re.S, cache=False) struct_args_pattern = r'([^,)]+)' struct_prefixes = [ # Strip attributes - (struct_attribute, ' '), + (KernRe(r"__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)", flags=re.I | re.S, cache=False), ' '), (KernRe(r'\s*__aligned\s*\([^;]*\)', re.S), ' '), (KernRe(r'\s*__counted_by\s*\([^;]*\)', re.S), ' '), (KernRe(r'\s*__counted_by_(le|be)\s*\([^;]*\)', re.S), ' '), From 4c232a81b0831e7bfa7518968e431d5db29b2cac Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Thu, 4 Sep 2025 16:40:49 -0600 Subject: [PATCH 167/193] docs: kdoc: move the function transform patterns out of dump_function() Move these definitions to file level, where they are executed once, and don't clutter the function itself. Signed-off-by: Jonathan Corbet --- scripts/lib/kdoc/kdoc_parser.py | 78 +++++++++++++++------------------ 1 file changed, 35 insertions(+), 43 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py index b25c8d80b965..37811cddd55c 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -161,6 +161,37 @@ struct_nested_prefixes = [ (re.compile(r'\bSTRUCT_GROUP\('), r'\1'), ] +# +# Transforms for function prototypes +# +function_xforms = [ + (r"^static +", "", 0), + (r"^extern +", "", 0), + (r"^asmlinkage +", "", 0), + (r"^inline +", "", 0), + (r"^__inline__ +", "", 0), + (r"^__inline +", "", 0), + (r"^__always_inline +", "", 0), + (r"^noinline +", "", 0), + (r"^__FORTIFY_INLINE +", "", 0), + (r"__init +", "", 0), + (r"__init_or_module +", "", 0), + (r"__deprecated +", "", 0), + (r"__flatten +", "", 0), + (r"__meminit +", "", 0), + (r"__must_check +", "", 0), + (r"__weak +", "", 0), + (r"__sched +", "", 0), + (r"_noprof", "", 0), + (r"__printf\s*\(\s*\d*\s*,\s*\d*\s*\) +", "", 0), + (r"__(?:re)?alloc_size\s*\(\s*\d+\s*(?:,\s*\d+\s*)?\) +", "", 0), + (r"__diagnose_as\s*\(\s*\S+\s*(?:,\s*\d+\s*)*\) +", "", 0), + (r"DECL_BUCKET_PARAMS\s*\(\s*(\S+)\s*,\s*(\S+)\s*\)", r"\1, \2", 0), + (r"__attribute_const__ +", "", 0), + (r"__attribute__\s*\(\((?:[\w\s]+(?:\([^)]*\))?\s*,?)+\)\)\s+", "", 0), +] + + # # A little helper to get rid of excess white space @@ -894,49 +925,10 @@ class KernelDoc: return_type = '' decl_type = 'function' - # Prefixes that would be removed - sub_prefixes = [ - (r"^static +", "", 0), - (r"^extern +", "", 0), - (r"^asmlinkage +", "", 0), - (r"^inline +", "", 0), - (r"^__inline__ +", "", 0), - (r"^__inline +", "", 0), - (r"^__always_inline +", "", 0), - (r"^noinline +", "", 0), - (r"^__FORTIFY_INLINE +", "", 0), - (r"__init +", "", 0), - (r"__init_or_module +", "", 0), - (r"__deprecated +", "", 0), - (r"__flatten +", "", 0), - (r"__meminit +", "", 0), - (r"__must_check +", "", 0), - (r"__weak +", "", 0), - (r"__sched +", "", 0), - (r"_noprof", "", 0), - (r"__printf\s*\(\s*\d*\s*,\s*\d*\s*\) +", "", 0), - (r"__(?:re)?alloc_size\s*\(\s*\d+\s*(?:,\s*\d+\s*)?\) +", "", 0), - (r"__diagnose_as\s*\(\s*\S+\s*(?:,\s*\d+\s*)*\) +", "", 0), - (r"DECL_BUCKET_PARAMS\s*\(\s*(\S+)\s*,\s*(\S+)\s*\)", r"\1, \2", 0), - (r"__attribute_const__ +", "", 0), - - # It seems that Python support for re.X is broken: - # At least for me (Python 3.13), this didn't work -# (r""" -# __attribute__\s*\(\( -# (?: -# [\w\s]+ # attribute name -# (?:\([^)]*\))? # attribute arguments -# \s*,? # optional comma at the end -# )+ -# \)\)\s+ -# """, "", re.X), - - # So, remove whitespaces and comments from it - (r"__attribute__\s*\(\((?:[\w\s]+(?:\([^)]*\))?\s*,?)+\)\)\s+", "", 0), - ] - - for search, sub, flags in sub_prefixes: + # + # Apply the initial transformations. + # + for search, sub, flags in function_xforms: prototype = KernRe(search, flags).sub(sub, prototype) # Macros are a special case, as they change the prototype format From a2752f8c631201e189f501fc4d320354efa3e72e Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Thu, 4 Sep 2025 16:49:52 -0600 Subject: [PATCH 168/193] doc: kdoc: unify transform handling Both functions and structs are passed through a set of regex-based transforms, but the two were structured differently, despite being the same thing. Create a utility function to apply transformations and use it in both cases. Signed-off-by: Jonathan Corbet --- scripts/lib/kdoc/kdoc_parser.py | 65 +++++++++++++++++---------------- 1 file changed, 34 insertions(+), 31 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py index 37811cddd55c..1a1558211acd 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -78,7 +78,7 @@ doc_begin_func = KernRe(str(doc_com) + # initial " * ' # struct_args_pattern = r'([^,)]+)' -struct_prefixes = [ +struct_xforms = [ # Strip attributes (KernRe(r"__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)", flags=re.I | re.S, cache=False), ' '), (KernRe(r'\s*__aligned\s*\([^;]*\)', re.S), ' '), @@ -165,33 +165,39 @@ struct_nested_prefixes = [ # Transforms for function prototypes # function_xforms = [ - (r"^static +", "", 0), - (r"^extern +", "", 0), - (r"^asmlinkage +", "", 0), - (r"^inline +", "", 0), - (r"^__inline__ +", "", 0), - (r"^__inline +", "", 0), - (r"^__always_inline +", "", 0), - (r"^noinline +", "", 0), - (r"^__FORTIFY_INLINE +", "", 0), - (r"__init +", "", 0), - (r"__init_or_module +", "", 0), - (r"__deprecated +", "", 0), - (r"__flatten +", "", 0), - (r"__meminit +", "", 0), - (r"__must_check +", "", 0), - (r"__weak +", "", 0), - (r"__sched +", "", 0), - (r"_noprof", "", 0), - (r"__printf\s*\(\s*\d*\s*,\s*\d*\s*\) +", "", 0), - (r"__(?:re)?alloc_size\s*\(\s*\d+\s*(?:,\s*\d+\s*)?\) +", "", 0), - (r"__diagnose_as\s*\(\s*\S+\s*(?:,\s*\d+\s*)*\) +", "", 0), - (r"DECL_BUCKET_PARAMS\s*\(\s*(\S+)\s*,\s*(\S+)\s*\)", r"\1, \2", 0), - (r"__attribute_const__ +", "", 0), - (r"__attribute__\s*\(\((?:[\w\s]+(?:\([^)]*\))?\s*,?)+\)\)\s+", "", 0), + (KernRe(r"^static +"), ""), + (KernRe(r"^extern +"), ""), + (KernRe(r"^asmlinkage +"), ""), + (KernRe(r"^inline +"), ""), + (KernRe(r"^__inline__ +"), ""), + (KernRe(r"^__inline +"), ""), + (KernRe(r"^__always_inline +"), ""), + (KernRe(r"^noinline +"), ""), + (KernRe(r"^__FORTIFY_INLINE +"), ""), + (KernRe(r"__init +"), ""), + (KernRe(r"__init_or_module +"), ""), + (KernRe(r"__deprecated +"), ""), + (KernRe(r"__flatten +"), ""), + (KernRe(r"__meminit +"), ""), + (KernRe(r"__must_check +"), ""), + (KernRe(r"__weak +"), ""), + (KernRe(r"__sched +"), ""), + (KernRe(r"_noprof"), ""), + (KernRe(r"__printf\s*\(\s*\d*\s*,\s*\d*\s*\) +"), ""), + (KernRe(r"__(?:re)?alloc_size\s*\(\s*\d+\s*(?:,\s*\d+\s*)?\) +"), ""), + (KernRe(r"__diagnose_as\s*\(\s*\S+\s*(?:,\s*\d+\s*)*\) +"), ""), + (KernRe(r"DECL_BUCKET_PARAMS\s*\(\s*(\S+)\s*,\s*(\S+)\s*\)"), r"\1, \2"), + (KernRe(r"__attribute_const__ +"), ""), + (KernRe(r"__attribute__\s*\(\((?:[\w\s]+(?:\([^)]*\))?\s*,?)+\)\)\s+"), ""), ] - +# +# Apply a set of transforms to a block of text. +# +def apply_transforms(xforms, text): + for search, subst in xforms: + text = search.sub(subst, text) + return text # # A little helper to get rid of excess white space @@ -807,8 +813,7 @@ class KernelDoc: # Go through the list of members applying all of our transformations. # members = trim_private_members(members) - for search, sub in struct_prefixes: - members = search.sub(sub, members) + members = apply_transforms(struct_xforms, members) nested = NestedMatch() for search, sub in struct_nested_prefixes: @@ -924,12 +929,10 @@ class KernelDoc: func_macro = False return_type = '' decl_type = 'function' - # # Apply the initial transformations. # - for search, sub, flags in function_xforms: - prototype = KernRe(search, flags).sub(sub, prototype) + prototype = apply_transforms(function_xforms, prototype) # Macros are a special case, as they change the prototype format new_proto = KernRe(r"^#\s*define\s+").sub("", prototype) From fee63c8f10c2fe77f618f9955c2f5521ff9cc622 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Fri, 5 Sep 2025 15:53:05 -0600 Subject: [PATCH 169/193] docs: kdoc: remove a couple of spurious regex characters The "name" regex in dump_function() includes both the tilde and colon characters, but neither has any place in function prototypes. Remove the characters, after which the regex simplifies to "\w+" No output changes. Signed-off-by: Jonathan Corbet --- scripts/lib/kdoc/kdoc_parser.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py index 1a1558211acd..decd127df82e 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -958,7 +958,7 @@ class KernelDoc: # - atomic_set (macro) # - pci_match_device, __copy_to_user (long return type) - name = r'[a-zA-Z0-9_~:]+' + name = r'\w+' prototype_end1 = r'[^\(]*' prototype_end2 = r'[^\{]*' prototype_end = fr'\(({prototype_end1}|{prototype_end2})\)' From 08b5228cf455d46a23bfb341766563d1a48e3c8f Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Fri, 5 Sep 2025 16:30:48 -0600 Subject: [PATCH 170/193] docs: kdoc: remove a useless empty capture group The is_define_proto case in dump_function() uses a regex with an empty capture group - () - that has no use; just take it out. Signed-off-by: Jonathan Corbet --- scripts/lib/kdoc/kdoc_parser.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py index decd127df82e..f9be5414244d 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -972,11 +972,11 @@ class KernelDoc: found = False if is_define_proto: - r = KernRe(r'^()(' + name + r')\s+') + r = KernRe(r'^(' + name + r')\s+') if r.search(prototype): return_type = '' - declaration_name = r.group(2) + declaration_name = r.group(1) func_macro = True found = True From ff1f2af341b72bd5b6b5d432da55faf2f6d24cfe Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Mon, 8 Sep 2025 13:22:42 -0600 Subject: [PATCH 171/193] docs: kdoc: Simplify the dump_function() prototype regexes The regexes for the parsing of function prototypes were more complicated than they needed to be and difficult to understand -- at least, I spent a fair amount of time bashing my head against them. Simplify them, and add some documentation comments as well. Signed-off-by: Jonathan Corbet --- scripts/lib/kdoc/kdoc_parser.py | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py index f9be5414244d..ec2e6e83df05 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -959,15 +959,15 @@ class KernelDoc: # - pci_match_device, __copy_to_user (long return type) name = r'\w+' - prototype_end1 = r'[^\(]*' - prototype_end2 = r'[^\{]*' - prototype_end = fr'\(({prototype_end1}|{prototype_end2})\)' - - # Besides compiling, Perl qr{[\w\s]+} works as a non-capturing group. - # So, this needs to be mapped in Python with (?:...)? or (?:...)+ - type1 = r'(?:[\w\s]+)?' type2 = r'(?:[\w\s]+\*+)+' + # + # Attempt to match first on (args) with no internal parentheses; this + # lets us easily filter out __acquires() and other post-args stuff. If + # that fails, just grab the rest of the line to the last closing + # parenthesis. + # + proto_args = r'\(([^\(]*|.*)\)' found = False @@ -983,9 +983,9 @@ class KernelDoc: if not found: patterns = [ - rf'^()({name})\s*{prototype_end}', - rf'^({type1})\s+({name})\s*{prototype_end}', - rf'^({type2})\s*({name})\s*{prototype_end}', + rf'^()({name})\s*{proto_args}', + rf'^({type1})\s+({name})\s*{proto_args}', + rf'^({type2})\s*({name})\s*{proto_args}', ] for p in patterns: From 370f430527ecd35938ad94167e45fc784f6e4d95 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Mon, 8 Sep 2025 16:01:15 -0600 Subject: [PATCH 172/193] docs: kdoc: consolidate some of the macro-processing logic The logic to handle macros is split in dump_function(); bring it all together into a single place and add a comment saying what's going on. Remove the unneeded is_define_proto variable, and tighten up the code a bit. Signed-off-by: Jonathan Corbet --- scripts/lib/kdoc/kdoc_parser.py | 43 +++++++++++++++------------------ 1 file changed, 20 insertions(+), 23 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py index ec2e6e83df05..27329ce9b5e9 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -926,21 +926,31 @@ class KernelDoc: Stores a function of function macro inside self.entries array. """ - func_macro = False + found = func_macro = False return_type = '' decl_type = 'function' # # Apply the initial transformations. # prototype = apply_transforms(function_xforms, prototype) - - # Macros are a special case, as they change the prototype format + # + # If we have a macro, remove the "#define" at the front. + # new_proto = KernRe(r"^#\s*define\s+").sub("", prototype) if new_proto != prototype: - is_define_proto = True prototype = new_proto - else: - is_define_proto = False + # + # Dispense with the simple "#define A B" case here; the key + # is the space after the name of the symbol being defined. + # NOTE that the seemingly misnamed "func_macro" indicates a + # macro *without* arguments. + # + r = KernRe(r'^(\w+)\s+') + if r.search(prototype): + return_type = '' + declaration_name = r.group(1) + func_macro = True + found = True # Yes, this truly is vile. We are looking for: # 1. Return type (may be nothing if we're looking at a macro) @@ -968,19 +978,10 @@ class KernelDoc: # parenthesis. # proto_args = r'\(([^\(]*|.*)\)' - - found = False - - if is_define_proto: - r = KernRe(r'^(' + name + r')\s+') - - if r.search(prototype): - return_type = '' - declaration_name = r.group(1) - func_macro = True - - found = True - + # + # (Except for the simple macro case) attempt to split up the prototype + # in the various ways we understand. + # if not found: patterns = [ rf'^()({name})\s*{proto_args}', @@ -990,16 +991,12 @@ class KernelDoc: for p in patterns: r = KernRe(p) - if r.match(prototype): - return_type = r.group(1) declaration_name = r.group(2) args = r.group(3) - self.create_parameter_list(ln, decl_type, args, ',', declaration_name) - found = True break if not found: From 3dff54410e56ddee2dad8824ea77e60cd5b16d5b Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Mon, 8 Sep 2025 16:21:28 -0600 Subject: [PATCH 173/193] docs: kdoc: final dump_function() cleanups Add some more comments to dump_function(), add some comments, and trim out an unneeded duplicate output_declaration() call. Signed-off-by: Jonathan Corbet --- scripts/lib/kdoc/kdoc_parser.py | 30 +++++++++++++----------------- 1 file changed, 13 insertions(+), 17 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py index 27329ce9b5e9..5e41acfef7b8 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -999,32 +999,28 @@ class KernelDoc: declaration_name) found = True break + # + # Parsing done; make sure that things are as we expect. + # if not found: self.emit_msg(ln, f"cannot understand function prototype: '{prototype}'") return - if self.entry.identifier != declaration_name: - self.emit_msg(ln, - f"expecting prototype for {self.entry.identifier}(). Prototype was for {declaration_name}() instead") + self.emit_msg(ln, f"expecting prototype for {self.entry.identifier}(). " + f"Prototype was for {declaration_name}() instead") return - self.check_sections(ln, declaration_name, "function") - self.check_return_section(ln, declaration_name, return_type) + # + # Store the result. + # + self.output_declaration(decl_type, declaration_name, + typedef=('typedef' in return_type), + functiontype=return_type, + purpose=self.entry.declaration_purpose, + func_macro=func_macro) - if 'typedef' in return_type: - self.output_declaration(decl_type, declaration_name, - typedef=True, - functiontype=return_type, - purpose=self.entry.declaration_purpose, - func_macro=func_macro) - else: - self.output_declaration(decl_type, declaration_name, - typedef=False, - functiontype=return_type, - purpose=self.entry.declaration_purpose, - func_macro=func_macro) def dump_typedef(self, ln, proto): """ From 999a642d7e7d4241cc7dba942a13c67d0685284b Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Mon, 8 Sep 2025 16:32:10 -0600 Subject: [PATCH 174/193] docs: kdoc: remove some dead code in dump_typedef() The regex in this block of code makes no sense, and a quick test shows that it never matches anything; simply delete the code. No output changes. Signed-off-by: Jonathan Corbet --- scripts/lib/kdoc/kdoc_parser.py | 5 ----- 1 file changed, 5 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py index 5e41acfef7b8..7c739b495d58 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -1060,11 +1060,6 @@ class KernelDoc: purpose=self.entry.declaration_purpose) return - # Handle nested parentheses or brackets - r = KernRe(r'(\(*.\)\s*|\[*.\]\s*);$') - while r.search(proto): - proto = r.sub('', proto) - # Parse simple typedefs r = KernRe(r'typedef.*\s+(\w+)\s*;') if r.match(proto): From 00fa9bc4e93cb336575a5f2c1da90d2443ff14c8 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Mon, 8 Sep 2025 16:49:58 -0600 Subject: [PATCH 175/193] docs: kdoc: remove redundant comment stripping in dump_typedef() By the time we get here, comments have long since been stripped out; there is no need to do it again. Signed-off-by: Jonathan Corbet --- scripts/lib/kdoc/kdoc_parser.py | 3 --- 1 file changed, 3 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py index 7c739b495d58..ad9df0536bbf 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -1034,9 +1034,6 @@ class KernelDoc: typedef1 = KernRe(r'typedef' + typedef_type + r'\(' + typedef_ident + r'\)' + typedef_args) typedef2 = KernRe(r'typedef' + typedef_type + typedef_ident + typedef_args) - # Strip comments - proto = KernRe(r'/\*.*?\*/', flags=re.S).sub('', proto) - # Parse function typedef prototypes for r in [typedef1, typedef2]: if not r.match(proto): From c01878437739f86851da76235f394346c6bd8ce3 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Mon, 8 Sep 2025 17:12:14 -0600 Subject: [PATCH 176/193] docs: kdoc: a few more dump_typedef() tweaks Merge "typedef" into the typedef_type pattern rather than repeating it later, and add some comments. Signed-off-by: Jonathan Corbet --- scripts/lib/kdoc/kdoc_parser.py | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py index ad9df0536bbf..2376f180b1fa 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -1026,13 +1026,15 @@ class KernelDoc: """ Stores a typedef inside self.entries array. """ - - typedef_type = r'((?:\s+[\w*]+\b){0,7}\s+(?:\w+\b|\*+))\s*' + # + # We start by looking for function typedefs. + # + typedef_type = r'typedef((?:\s+[\w*]+\b){0,7}\s+(?:\w+\b|\*+))\s*' typedef_ident = r'\*?\s*(\w\S+)\s*' typedef_args = r'\s*\((.*)\);' - typedef1 = KernRe(r'typedef' + typedef_type + r'\(' + typedef_ident + r'\)' + typedef_args) - typedef2 = KernRe(r'typedef' + typedef_type + typedef_ident + typedef_args) + typedef1 = KernRe(typedef_type + r'\(' + typedef_ident + r'\)' + typedef_args) + typedef2 = KernRe(typedef_type + typedef_ident + typedef_args) # Parse function typedef prototypes for r in [typedef1, typedef2]: @@ -1048,16 +1050,16 @@ class KernelDoc: f"expecting prototype for typedef {self.entry.identifier}. Prototype was for typedef {declaration_name} instead\n") return - decl_type = 'function' - self.create_parameter_list(ln, decl_type, args, ',', declaration_name) + self.create_parameter_list(ln, 'function', args, ',', declaration_name) - self.output_declaration(decl_type, declaration_name, + self.output_declaration('function', declaration_name, typedef=True, functiontype=return_type, purpose=self.entry.declaration_purpose) return - - # Parse simple typedefs + # + # Not a function, try to parse a simple typedef. + # r = KernRe(r'typedef.*\s+(\w+)\s*;') if r.match(proto): declaration_name = r.group(1) From d725668ed28b2434b548190472ac9bdc64a08e80 Mon Sep 17 00:00:00 2001 From: Thorsten Blum Date: Wed, 17 Sep 2025 00:29:44 +0200 Subject: [PATCH 177/193] docs: maintainer: Fix ambiguous subheading formatting Add a newline after both subheadings to avoid any ambiguous formatting, especially in htmldocs. Without the newline, subheadings are rendered as part of the following paragraphs, which can be confusing to read. Suggested-by: Randy Dunlap Signed-off-by: Thorsten Blum Reviewed-by: Bagas Sanjaya Reviewed-by: Randy Dunlap Tested-by: Randy Dunlap Signed-off-by: Jonathan Corbet Message-ID: <20250916222944.2547948-2-thorsten.blum@linux.dev> --- Documentation/maintainer/maintainer-entry-profile.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Documentation/maintainer/maintainer-entry-profile.rst b/Documentation/maintainer/maintainer-entry-profile.rst index cda5d691e967..d36dd892a78a 100644 --- a/Documentation/maintainer/maintainer-entry-profile.rst +++ b/Documentation/maintainer/maintainer-entry-profile.rst @@ -59,6 +59,7 @@ week) that patches might be considered for merging and when patches need to wait for the next -rc. At a minimum: - Last -rc for new feature submissions: + New feature submissions targeting the next merge window should have their first posting for consideration before this point. Patches that are submitted after this point should be clear that they are targeting @@ -68,6 +69,7 @@ wait for the next -rc. At a minimum: submissions should appear before -rc5. - Last -rc to merge features: Deadline for merge decisions + Indicate to contributors the point at which an as yet un-applied patch set will need to wait for the NEXT+1 merge window. Of course there is no obligation to ever accept any given patchset, but if the review has not From a1d4416f8682d3c6d0545ad8a887d2a77f170808 Mon Sep 17 00:00:00 2001 From: Alex Tran Date: Mon, 1 Sep 2025 19:30:39 -0700 Subject: [PATCH 178/193] docs: filesystems: sysfs: remove top level sysfs net directory The net/ directory is not present as a top level sysfs directory in standard Linux systems. Network interfaces can be accessible via /sys/class/net instead. Signed-off-by: Alex Tran Signed-off-by: Jonathan Corbet Message-ID: <20250902023039.1351270-3-alex.t.tran@gmail.com> --- Documentation/filesystems/sysfs.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/Documentation/filesystems/sysfs.rst b/Documentation/filesystems/sysfs.rst index 624e4f51212e..db153cda0786 100644 --- a/Documentation/filesystems/sysfs.rst +++ b/Documentation/filesystems/sysfs.rst @@ -299,7 +299,6 @@ The top level sysfs directory looks like:: hypervisor/ kernel/ module/ - net/ power/ devices/ contains a filesystem representation of the device tree. It maps From 63e6e9dde28a8e8967308a9dfb807edea3810aab Mon Sep 17 00:00:00 2001 From: Alex Tran Date: Mon, 1 Sep 2025 19:30:38 -0700 Subject: [PATCH 179/193] docs: filesystems: sysfs: clarify symlink destinations in dev and bus/devices descriptions Change sysfs bus/devices and dev directory descriptions to provide more verbose information about the specific symlink destination the devices point to. Signed-off-by: Alex Tran Signed-off-by: Jonathan Corbet Message-ID: <20250902023039.1351270-2-alex.t.tran@gmail.com> --- Documentation/filesystems/sysfs.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/filesystems/sysfs.rst b/Documentation/filesystems/sysfs.rst index db153cda0786..f1a776a7ac66 100644 --- a/Documentation/filesystems/sysfs.rst +++ b/Documentation/filesystems/sysfs.rst @@ -312,7 +312,7 @@ kernel. Each bus's directory contains two subdirectories:: drivers/ devices/ contains symlinks for each device discovered in the system -that point to the device's directory under root/. +that point to the device's directory under /sys/devices. drivers/ contains a directory for each device driver that is loaded for devices on that particular bus (this assumes that drivers do not @@ -327,7 +327,7 @@ loaded system modules, for both builtin and loadable modules. dev/ contains two directories: char/ and block/. Inside these two directories there are symlinks named :. These symlinks -point to the sysfs directory for the given device. /sys/dev provides a +point to the directories under /sys/devices for each device. /sys/dev provides a quick way to lookup the sysfs interface for a device from the result of a stat(2) operation. From a3d13ec44aea30794c4764b3516b4b0396ce4814 Mon Sep 17 00:00:00 2001 From: Alex Tran Date: Mon, 1 Sep 2025 19:30:37 -0700 Subject: [PATCH 180/193] docs: filesystems: sysfs: add remaining top level sysfs directory descriptions Finish top level sysfs directory descriptions for block, class, firmware, hypervisor, kernel, and power. Did not write one for net directory. See commit bc3a88431672 ("docs: filesystems: sysfs: remove top level sysfs net directory") Signed-off-by: Alex Tran Signed-off-by: Jonathan Corbet Message-ID: <20250902023039.1351270-1-alex.t.tran@gmail.com> --- Documentation/filesystems/sysfs.rst | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/Documentation/filesystems/sysfs.rst b/Documentation/filesystems/sysfs.rst index f1a776a7ac66..354c5fb310b4 100644 --- a/Documentation/filesystems/sysfs.rst +++ b/Documentation/filesystems/sysfs.rst @@ -334,8 +334,22 @@ a stat(2) operation. More information on driver-model specific features can be found in Documentation/driver-api/driver-model/. +block/ contains symlinks to all the block devices discovered on the system. +These symlinks point to directories under /sys/devices. -TODO: Finish this section. +class/ contains a directory for each device class, grouped by functional type. +Each directory in class/ contains symlinks to devices in the /sys/devices directory. + +firmware/ contains system firmware data and configuration such as firmware tables, +ACPI information, and device tree data. + +hypervisor/ contains virtualization platform information and provides an interface to +the underlying hypervisor. It is only present when running on a virtual machine. + +kernel/ contains runtime kernel parameters, configuration settings, and status. + +power/ contains power management subsystem information including +sleep states, suspend/resume capabilities, and policies. Current Interfaces From 78494f9e3b52d339463962b462bda1604990e4fb Mon Sep 17 00:00:00 2001 From: Bagas Sanjaya Date: Tue, 9 Sep 2025 13:37:41 +0700 Subject: [PATCH 181/193] Documentation: fbcon: Add boot options and attach/detach/unload section headings These last two enumerated sections headings are in normal paragraphs, making both sections merged into "Loading" section instead. Add the headings. Signed-off-by: Bagas Sanjaya Reviewed-by: Randy Dunlap Tested-by: Randy Dunlap Signed-off-by: Jonathan Corbet Message-ID: <20250909063744.30053-2-bagasdotme@gmail.com> --- Documentation/fb/fbcon.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Documentation/fb/fbcon.rst b/Documentation/fb/fbcon.rst index 212f7003cfba..b9ddc145aa9f 100644 --- a/Documentation/fb/fbcon.rst +++ b/Documentation/fb/fbcon.rst @@ -74,6 +74,7 @@ Possible scenarios: over the console. C. Boot options +=============== The framebuffer console has several, largely unknown, boot options that can change its behavior. @@ -172,7 +173,8 @@ C. Boot options The value 'n' overrides the number of bootup logos. 0 disables the logo, and -1 gives the default which is the number of online CPUs. -C. Attaching, Detaching and Unloading +D. Attaching, Detaching and Unloading +===================================== Before going on to how to attach, detach and unload the framebuffer console, an illustration of the dependencies may help. From cfa51cfdb5100cecc3feb9ccdc08b17eeb711fe8 Mon Sep 17 00:00:00 2001 From: Bagas Sanjaya Date: Tue, 9 Sep 2025 13:37:42 +0700 Subject: [PATCH 182/193] Documentation: fbcon: Reindent 8th step of attach/detach/unload Properly indent 8th step text (as enumerated list item) to be inline with other steps. Signed-off-by: Bagas Sanjaya Reviewed-by: Randy Dunlap Tested-by: Randy Dunlap Signed-off-by: Jonathan Corbet Message-ID: <20250909063744.30053-3-bagasdotme@gmail.com> --- Documentation/fb/fbcon.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Documentation/fb/fbcon.rst b/Documentation/fb/fbcon.rst index b9ddc145aa9f..3ed98b3ce647 100644 --- a/Documentation/fb/fbcon.rst +++ b/Documentation/fb/fbcon.rst @@ -251,11 +251,11 @@ restored properly. The following is one of the several methods that you can do: echo 1 > /sys/class/vtconsole/vtcon1/bind 8. Once fbcon is unbound, all drivers registered to the system will also -become unbound. This means that fbcon and individual framebuffer drivers -can be unloaded or reloaded at will. Reloading the drivers or fbcon will -automatically bind the console, fbcon and the drivers together. Unloading -all the drivers without unloading fbcon will make it impossible for the -console to bind fbcon. + become unbound. This means that fbcon and individual framebuffer drivers + can be unloaded or reloaded at will. Reloading the drivers or fbcon will + automatically bind the console, fbcon and the drivers together. Unloading + all the drivers without unloading fbcon will make it impossible for the + console to bind fbcon. Notes for vesafb users: ======================= From 4eb018bd15881504351c44f0d3d7287c88ef161f Mon Sep 17 00:00:00 2001 From: Bagas Sanjaya Date: Tue, 9 Sep 2025 13:37:43 +0700 Subject: [PATCH 183/193] Documentation: fbcon: Use admonition directives Use reST syntax for admonitions (notes and custom admonition for gotcha). Signed-off-by: Bagas Sanjaya Reviewed-by: Randy Dunlap Tested-by: Randy Dunlap Signed-off-by: Jonathan Corbet Message-ID: <20250909063744.30053-4-bagasdotme@gmail.com> --- Documentation/fb/fbcon.rst | 28 ++++++++++++++++------------ 1 file changed, 16 insertions(+), 12 deletions(-) diff --git a/Documentation/fb/fbcon.rst b/Documentation/fb/fbcon.rst index 3ed98b3ce647..a98a5cb0b0d8 100644 --- a/Documentation/fb/fbcon.rst +++ b/Documentation/fb/fbcon.rst @@ -39,11 +39,13 @@ Also, you will need to select at least one compiled-in font, but if you don't do anything, the kernel configuration tool will select one for you, usually an 8x16 font. -GOTCHA: A common bug report is enabling the framebuffer without enabling the -framebuffer console. Depending on the driver, you may get a blanked or -garbled display, but the system still boots to completion. If you are -fortunate to have a driver that does not alter the graphics chip, then you -will still get a VGA console. +.. admonition:: GOTCHA + + A common bug report is enabling the framebuffer without enabling the + framebuffer console. Depending on the driver, you may get a blanked or + garbled display, but the system still boots to completion. If you are + fortunate to have a driver that does not alter the graphics chip, then you + will still get a VGA console. B. Loading ========== @@ -117,9 +119,10 @@ C. Boot options outside the given range will still be controlled by the standard console driver. - NOTE: For x86 machines, the standard console is the VGA console which - is typically located on the same video card. Thus, the consoles that - are controlled by the VGA console will be garbled. + .. note:: + For x86 machines, the standard console is the VGA console which + is typically located on the same video card. Thus, the consoles that + are controlled by the VGA console will be garbled. 4. fbcon=rotate: @@ -141,10 +144,11 @@ C. Boot options Console rotation will only become available if Framebuffer Console Rotation support is compiled in your kernel. - NOTE: This is purely console rotation. Any other applications that - use the framebuffer will remain at their 'normal' orientation. - Actually, the underlying fb driver is totally ignorant of console - rotation. + .. note:: + This is purely console rotation. Any other applications that + use the framebuffer will remain at their 'normal' orientation. + Actually, the underlying fb driver is totally ignorant of console + rotation. 5. fbcon=margin: From 395107a7c91aafef8eb8ffee574b43cc7cce34be Mon Sep 17 00:00:00 2001 From: Marneni PoornaChandu Date: Thu, 18 Sep 2025 06:04:30 +0800 Subject: [PATCH 184/193] docs: driver-api: fix spelling of "buses". Replace incorrect plural form "busses" with "buses" in multiple documentation files under "Documentation/driver-api". Signed-off-by: Marneni PoornaChandu Signed-off-by: Jonathan Corbet Message-ID: <20250917220430.5815-1-Poornachandumarneni@gmail.com> --- Documentation/driver-api/device-io.rst | 4 ++-- Documentation/driver-api/driver-model/overview.rst | 2 +- Documentation/driver-api/driver-model/platform.rst | 2 +- Documentation/driver-api/eisa.rst | 6 +++--- Documentation/driver-api/i3c/protocol.rst | 4 ++-- Documentation/driver-api/ipmi.rst | 4 ++-- Documentation/driver-api/media/tx-rx.rst | 4 ++-- Documentation/driver-api/nvdimm/nvdimm.rst | 2 +- Documentation/driver-api/pm/devices.rst | 4 ++-- Documentation/driver-api/scsi.rst | 4 ++-- Documentation/driver-api/spi.rst | 2 +- Documentation/driver-api/usb/hotplug.rst | 2 +- Documentation/driver-api/usb/usb.rst | 4 ++-- 13 files changed, 22 insertions(+), 22 deletions(-) diff --git a/Documentation/driver-api/device-io.rst b/Documentation/driver-api/device-io.rst index 5c7e8194bef9..d1aaa961cac4 100644 --- a/Documentation/driver-api/device-io.rst +++ b/Documentation/driver-api/device-io.rst @@ -16,7 +16,7 @@ Bus-Independent Device Accesses Introduction ============ -Linux provides an API which abstracts performing IO across all busses +Linux provides an API which abstracts performing IO across all buses and devices, allowing device drivers to be written independently of bus type. @@ -71,7 +71,7 @@ can be compiler optimised, you can use __readb() and friends to indicate the relaxed ordering. Use this with care. While the basic functions are defined to be synchronous with respect to -each other and ordered with respect to each other the busses the devices +each other and ordered with respect to each other the buses the devices sit on may themselves have asynchronicity. In particular many authors are burned by the fact that PCI bus writes are posted asynchronously. A driver author must issue a read from the same device to ensure that diff --git a/Documentation/driver-api/driver-model/overview.rst b/Documentation/driver-api/driver-model/overview.rst index e98d0ab4a9b6..b3f447bf9f07 100644 --- a/Documentation/driver-api/driver-model/overview.rst +++ b/Documentation/driver-api/driver-model/overview.rst @@ -22,7 +22,7 @@ uniformity across the different bus types. The current driver model provides a common, uniform data model for describing a bus and the devices that can appear under the bus. The unified bus -model includes a set of common attributes which all busses carry, and a set +model includes a set of common attributes which all buses carry, and a set of common callbacks, such as device discovery during bus probing, bus shutdown, bus power management, etc. diff --git a/Documentation/driver-api/driver-model/platform.rst b/Documentation/driver-api/driver-model/platform.rst index 7beb8a9648c5..cf5ff48d3115 100644 --- a/Documentation/driver-api/driver-model/platform.rst +++ b/Documentation/driver-api/driver-model/platform.rst @@ -4,7 +4,7 @@ Platform Devices and Drivers See for the driver model interface to the platform bus: platform_device, and platform_driver. This pseudo-bus -is used to connect devices on busses with minimal infrastructure, +is used to connect devices on buses with minimal infrastructure, like those used to integrate peripherals on many system-on-chip processors, or some "legacy" PC interconnects; as opposed to large formally specified ones like PCI or USB. diff --git a/Documentation/driver-api/eisa.rst b/Documentation/driver-api/eisa.rst index b33ebe1ec9ed..3563e5f7e98d 100644 --- a/Documentation/driver-api/eisa.rst +++ b/Documentation/driver-api/eisa.rst @@ -8,9 +8,9 @@ This document groups random notes about porting EISA drivers to the new EISA/sysfs API. Starting from version 2.5.59, the EISA bus is almost given the same -status as other much more mainstream busses such as PCI or USB. This +status as other much more mainstream buses such as PCI or USB. This has been possible through sysfs, which defines a nice enough set of -abstractions to manage busses, devices and drivers. +abstractions to manage buses, devices and drivers. Although the new API is quite simple to use, converting existing drivers to the new infrastructure is not an easy task (mostly because @@ -205,7 +205,7 @@ Random notes Converting an EISA driver to the new API mostly involves *deleting* code (since probing is now in the core EISA code). Unfortunately, most drivers share their probing routine between ISA, and EISA. Special -care must be taken when ripping out the EISA code, so other busses +care must be taken when ripping out the EISA code, so other buses won't suffer from these surgical strikes... You *must not* expect any EISA device to be detected when returning diff --git a/Documentation/driver-api/i3c/protocol.rst b/Documentation/driver-api/i3c/protocol.rst index 23a0b93c62b1..fe338f8085db 100644 --- a/Documentation/driver-api/i3c/protocol.rst +++ b/Documentation/driver-api/i3c/protocol.rst @@ -165,8 +165,8 @@ The first thing attached to an HDR command is the HDR mode. There are currently for more details): * HDR-DDR: Double Data Rate mode -* HDR-TSP: Ternary Symbol Pure. Only usable on busses with no I2C devices -* HDR-TSL: Ternary Symbol Legacy. Usable on busses with I2C devices +* HDR-TSP: Ternary Symbol Pure. Only usable on buses with no I2C devices +* HDR-TSL: Ternary Symbol Legacy. Usable on buses with I2C devices When sending an HDR command, the whole bus has to enter HDR mode, which is done using a broadcast CCC command. diff --git a/Documentation/driver-api/ipmi.rst b/Documentation/driver-api/ipmi.rst index 2cc6c898ab90..f52ab2df2569 100644 --- a/Documentation/driver-api/ipmi.rst +++ b/Documentation/driver-api/ipmi.rst @@ -617,12 +617,12 @@ Note that the address you give here is the I2C address, not the IPMI address. So if you want your MC address to be 0x60, you put 0x30 here. See the I2C driver info for more details. -Command bridging to other IPMB busses through this interface does not +Command bridging to other IPMB buses through this interface does not work. The receive message queue is not implemented, by design. There is only one receive message queue on a BMC, and that is meant for the host drivers, not something on the IPMB bus. -A BMC may have multiple IPMB busses, which bus your device sits on +A BMC may have multiple IPMB buses, which bus your device sits on depends on how the system is wired. You can fetch the channels with "ipmitool channel info " where is the channel, with the channels being 0-7 and try the IPMB channels. diff --git a/Documentation/driver-api/media/tx-rx.rst b/Documentation/driver-api/media/tx-rx.rst index 0b8c9cde8ee4..22e1b13ecde9 100644 --- a/Documentation/driver-api/media/tx-rx.rst +++ b/Documentation/driver-api/media/tx-rx.rst @@ -12,7 +12,7 @@ CSI-2 receiver in an SoC. Bus types --------- -The following busses are the most common. This section discusses these two only. +The following buses are the most common. This section discusses these two only. MIPI CSI-2 ^^^^^^^^^^ @@ -36,7 +36,7 @@ Transmitter drivers Transmitter drivers generally need to provide the receiver drivers with the configuration of the transmitter. What is required depends on the type of the -bus. These are common for both busses. +bus. These are common for both buses. Media bus pixel code ^^^^^^^^^^^^^^^^^^^^ diff --git a/Documentation/driver-api/nvdimm/nvdimm.rst b/Documentation/driver-api/nvdimm/nvdimm.rst index c205efa4d45b..959ba1cc0263 100644 --- a/Documentation/driver-api/nvdimm/nvdimm.rst +++ b/Documentation/driver-api/nvdimm/nvdimm.rst @@ -230,7 +230,7 @@ LIBNVDIMM/LIBNDCTL: Bus A bus has a 1:1 relationship with an NFIT. The current expectation for ACPI based systems is that there is only ever one platform-global NFIT. That said, it is trivial to register multiple NFITs, the specification -does not preclude it. The infrastructure supports multiple busses and +does not preclude it. The infrastructure supports multiple buses and we use this capability to test multiple NFIT configurations in the unit test. diff --git a/Documentation/driver-api/pm/devices.rst b/Documentation/driver-api/pm/devices.rst index 8d86d5da4023..36d5c9c9fd11 100644 --- a/Documentation/driver-api/pm/devices.rst +++ b/Documentation/driver-api/pm/devices.rst @@ -255,7 +255,7 @@ get registered: a child can never be registered, probed or resumed before its parent; and can't be removed or suspended after that parent. The policy is that the device hierarchy should match hardware bus topology. -[Or at least the control bus, for devices which use multiple busses.] +[Or at least the control bus, for devices which use multiple buses.] In particular, this means that a device registration may fail if the parent of the device is suspending (i.e. has been chosen by the PM core as the next device to suspend) or has already suspended, as well as after all of the other @@ -493,7 +493,7 @@ states, like S3). Drivers must also be prepared to notice that the device has been removed while the system was powered down, whenever that's physically possible. -PCMCIA, MMC, USB, Firewire, SCSI, and even IDE are common examples of busses +PCMCIA, MMC, USB, Firewire, SCSI, and even IDE are common examples of buses where common Linux platforms will see such removal. Details of how drivers will notice and handle such removals are currently bus-specific, and often involve a separate thread. diff --git a/Documentation/driver-api/scsi.rst b/Documentation/driver-api/scsi.rst index bf2be96cc2d6..8bbdfb018c53 100644 --- a/Documentation/driver-api/scsi.rst +++ b/Documentation/driver-api/scsi.rst @@ -18,7 +18,7 @@ optical drives, test equipment, and medical devices) to a host computer. Although the old parallel (fast/wide/ultra) SCSI bus has largely fallen out of use, the SCSI command set is more widely used than ever to -communicate with devices over a number of different busses. +communicate with devices over a number of different buses. The `SCSI protocol `__ is a big-endian peer-to-peer packet based protocol. SCSI commands are 6, 10, 12, or 16 @@ -286,7 +286,7 @@ Parallel SCSI (SPI) transport class ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The file drivers/scsi/scsi_transport_spi.c defines transport -attributes for traditional (fast/wide/ultra) SCSI busses. +attributes for traditional (fast/wide/ultra) SCSI buses. .. kernel-doc:: drivers/scsi/scsi_transport_spi.c :export: diff --git a/Documentation/driver-api/spi.rst b/Documentation/driver-api/spi.rst index f28887045049..74eca6735042 100644 --- a/Documentation/driver-api/spi.rst +++ b/Documentation/driver-api/spi.rst @@ -13,7 +13,7 @@ additional chipselect line is usually active-low (nCS); four signals are normally used for each peripheral, plus sometimes an interrupt. The SPI bus facilities listed here provide a generalized interface to -declare SPI busses and devices, manage them according to the standard +declare SPI buses and devices, manage them according to the standard Linux driver model, and perform input/output operations. At this time, only "master" side interfaces are supported, where Linux talks to SPI peripherals and does not implement such a peripheral itself. (Interfaces diff --git a/Documentation/driver-api/usb/hotplug.rst b/Documentation/driver-api/usb/hotplug.rst index c1e13107c50e..12260f704a01 100644 --- a/Documentation/driver-api/usb/hotplug.rst +++ b/Documentation/driver-api/usb/hotplug.rst @@ -5,7 +5,7 @@ Linux Hotplugging ================= -In hotpluggable busses like USB (and Cardbus PCI), end-users plug devices +In hotpluggable buses like USB (and Cardbus PCI), end-users plug devices into the bus with power on. In most cases, users expect the devices to become immediately usable. That means the system must do many things, including: diff --git a/Documentation/driver-api/usb/usb.rst b/Documentation/driver-api/usb/usb.rst index 976fb4221062..7f2f41e80c1c 100644 --- a/Documentation/driver-api/usb/usb.rst +++ b/Documentation/driver-api/usb/usb.rst @@ -13,7 +13,7 @@ structure, with the host as the root (the system's master), hubs as interior nodes, and peripherals as leaves (and slaves). Modern PCs support several such trees of USB devices, usually a few USB 3.0 (5 GBit/s) or USB 3.1 (10 GBit/s) and some legacy -USB 2.0 (480 MBit/s) busses just in case. +USB 2.0 (480 MBit/s) buses just in case. That master/slave asymmetry was designed-in for a number of reasons, one being ease of use. It is not physically possible to mistake upstream and @@ -42,7 +42,7 @@ two. One is intended for *general-purpose* drivers (exposed through driver frameworks), and the other is for drivers that are *part of the core*. Such core drivers include the *hub* driver (which manages trees of USB devices) and several different kinds of *host controller -drivers*, which control individual busses. +drivers*, which control individual buses. The device model seen by USB drivers is relatively complex. From 348b7ca8d3f7fdc7bc28ef219253cb31c218fdb0 Mon Sep 17 00:00:00 2001 From: Bagas Sanjaya Date: Tue, 16 Sep 2025 12:41:59 +0700 Subject: [PATCH 185/193] Documentation: trace: histogram: Fix histogram trigger subsection number order Section numbering in subsections of "Histogram Trigger Command" sections is inconsistent in order. In particular, "'hist' trigger examples" is erroneously numbered as 6.2, which is a leftover from b8df4a3634e08a ("tracing: Move hist trigger Documentation to histogram.txt"). Fix the order. Reviewed-by: Tom Zanussi Reviewed-by: Masami Hiramatsu (Google) Signed-off-by: Bagas Sanjaya Acked-by: Steven Rostedt (Google) Signed-off-by: Jonathan Corbet Message-ID: <20250916054202.582074-3-bagasdotme@gmail.com> --- Documentation/trace/histogram.rst | 34 +++++++++++++++---------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/Documentation/trace/histogram.rst b/Documentation/trace/histogram.rst index af6d2e15568e..d158dadaa424 100644 --- a/Documentation/trace/histogram.rst +++ b/Documentation/trace/histogram.rst @@ -186,8 +186,8 @@ Documentation written by Tom Zanussi The examples below provide a more concrete illustration of the concepts and typical usage patterns discussed above. -'special' event fields ------------------------- +2.1. 'special' event fields +--------------------------- There are a number of 'special event fields' available for use as keys or values in a hist trigger. These look like and behave as if @@ -204,16 +204,16 @@ Documentation written by Tom Zanussi common_cpu int the cpu on which the event occurred. ====================== ==== ======================================= -Extended error information --------------------------- +2.2. Extended error information +------------------------------- For some error conditions encountered when invoking a hist trigger command, extended error information is available via the tracing/error_log file. See Error Conditions in :file:`Documentation/trace/ftrace.rst` for details. -6.2 'hist' trigger examples ---------------------------- +2.3. 'hist' trigger examples +---------------------------- The first set of examples creates aggregations using the kmalloc event. The fields that can be used for the hist trigger are listed @@ -1608,8 +1608,8 @@ Extended error information Entries: 7 Dropped: 0 -2.2 Inter-event hist triggers ------------------------------ +2.4. Inter-event hist triggers +------------------------------ Inter-event hist triggers are hist triggers that combine values from one or more other events and create a histogram using that data. Data @@ -1685,8 +1685,8 @@ pseudo-file. These features are described in more detail in the following sections. -2.2.1 Histogram Variables -------------------------- +2.5. Histogram Variables +------------------------ Variables are simply named locations used for saving and retrieving values between matching events. A 'matching' event is defined as an @@ -1789,8 +1789,8 @@ or assigned to a variable and referenced in a subsequent expression:: Variables can even hold stacktraces, which are useful with synthetic events. -2.2.2 Synthetic Events ----------------------- +2.6. Synthetic Events +--------------------- Synthetic events are user-defined events generated from hist trigger variables or fields associated with one or more other events. Their @@ -1846,7 +1846,7 @@ the command that defined it with a '!':: At this point, there isn't yet an actual 'wakeup_latency' event instantiated in the event subsystem - for this to happen, a 'hist trigger action' needs to be instantiated and bound to actual fields -and variables defined on other events (see Section 2.2.3 below on +and variables defined on other events (see Section 2.7. below on how that is done using hist trigger 'onmatch' action). Once that is done, the 'wakeup_latency' synthetic event instance is created. @@ -2094,8 +2094,8 @@ histogram:: Entries: 7 Dropped: 0 -2.2.3 Hist trigger 'handlers' and 'actions' -------------------------------------------- +2.7. Hist trigger 'handlers' and 'actions' +------------------------------------------ A hist trigger 'action' is a function that's executed (in most cases conditionally) whenever a histogram entry is added or updated. @@ -2526,8 +2526,8 @@ The following commonly-used handler.action pairs are available: kworker/3:2-135 [003] d..3 49.823123: sched_switch: prev_comm=kworker/3:2 prev_pid=135 prev_prio=120 prev_state=T ==> next_comm=swapper/3 next_pid=0 next_prio=120 -0 [004] ..s7 49.823798: tcp_probe: src=10.0.0.10:54326 dest=23.215.104.193:80 mark=0x0 length=32 snd_nxt=0xe3ae2ff5 snd_una=0xe3ae2ecd snd_cwnd=10 ssthresh=2147483647 snd_wnd=28960 srtt=19604 rcv_wnd=29312 -3. User space creating a trigger --------------------------------- +2.8. User space creating a trigger +---------------------------------- Writing into /sys/kernel/tracing/trace_marker writes into the ftrace ring buffer. This can also act like an event, by writing into the trigger From f867a298ac71c097a22ea77c06f5814095c0d288 Mon Sep 17 00:00:00 2001 From: Bagas Sanjaya Date: Tue, 16 Sep 2025 12:42:00 +0700 Subject: [PATCH 186/193] Documentation: trace: histogram-design: Trim trailing vertices in diagram explanation text Diagram explanation text is supposed to be interleaved commentary between diagram parts that are spread out, but it outputs ugly in htmldocs due to trailing vertices as if both the explanation and the diagram are in the same literal code block. Trim trailing vertices. Reviewed-by: Tom Zanussi Reviewed-by: Masami Hiramatsu (Google) Signed-off-by: Bagas Sanjaya Acked-by: Steven Rostedt (Google) Signed-off-by: Jonathan Corbet Message-ID: <20250916054202.582074-4-bagasdotme@gmail.com> --- Documentation/trace/histogram-design.rst | 138 +++++++++++------------ 1 file changed, 69 insertions(+), 69 deletions(-) diff --git a/Documentation/trace/histogram-design.rst b/Documentation/trace/histogram-design.rst index 5765eb3e9efa..231a12bd7d46 100644 --- a/Documentation/trace/histogram-design.rst +++ b/Documentation/trace/histogram-design.rst @@ -142,30 +142,30 @@ elements for a couple hypothetical keys and values.:: +--------------+ | | n_keys = n_fields - n_vals | | -The hist_data n_vals and n_fields delineate the extent of the fields[] | | -array and separate keys from values for the rest of the code. | | +The hist_data n_vals and n_fields delineate the extent of the fields[] +array and separate keys from values for the rest of the code. -Below is a run-time representation of the tracing_map part of the | | -histogram, with pointers from various parts of the fields[] array | | -to corresponding parts of the tracing_map. | | +Below is a run-time representation of the tracing_map part of the +histogram, with pointers from various parts of the fields[] array +to corresponding parts of the tracing_map. -The tracing_map consists of an array of tracing_map_entrys and a set | | -of preallocated tracing_map_elts (abbreviated below as map_entry and | | -map_elt). The total number of map_entrys in the hist_data.map array = | | -map->max_elts (actually map->map_size but only max_elts of those are | | -used. This is a property required by the map_insert() algorithm). | | +The tracing_map consists of an array of tracing_map_entrys and a set +of preallocated tracing_map_elts (abbreviated below as map_entry and +map_elt). The total number of map_entrys in the hist_data.map array = +map->max_elts (actually map->map_size but only max_elts of those are +used. This is a property required by the map_insert() algorithm). -If a map_entry is unused, meaning no key has yet hashed into it, its | | -.key value is 0 and its .val pointer is NULL. Once a map_entry has | | -been claimed, the .key value contains the key's hash value and the | | -.val member points to a map_elt containing the full key and an entry | | -for each key or value in the map_elt.fields[] array. There is an | | -entry in the map_elt.fields[] array corresponding to each hist_field | | -in the histogram, and this is where the continually aggregated sums | | -corresponding to each histogram value are kept. | | +If a map_entry is unused, meaning no key has yet hashed into it, its +.key value is 0 and its .val pointer is NULL. Once a map_entry has +been claimed, the .key value contains the key's hash value and the +.val member points to a map_elt containing the full key and an entry +for each key or value in the map_elt.fields[] array. There is an +entry in the map_elt.fields[] array corresponding to each hist_field +in the histogram, and this is where the continually aggregated sums +corresponding to each histogram value are kept. -The diagram attempts to show the relationship between the | | -hist_data.fields[] and the map_elt.fields[] with the links drawn | | +The diagram attempts to show the relationship between the +hist_data.fields[] and the map_elt.fields[] with the links drawn between diagrams:: +-----------+ | | @@ -440,31 +440,31 @@ sched_waking histogram n_keys = n_fields - n_vals | | | | | | -This is very similar to the basic case. In the above diagram, we can | | | -see a new .flags member has been added to the struct hist_field | | | -struct, and a new entry added to hist_data.fields representing the ts0 | | | -variable. For a normal val hist_field, .flags is just 0 (modulo | | | -modifier flags), but if the value is defined as a variable, the .flags | | | -contains a set FL_VAR bit. | | | +This is very similar to the basic case. In the above diagram, we can +see a new .flags member has been added to the struct hist_field +struct, and a new entry added to hist_data.fields representing the ts0 +variable. For a normal val hist_field, .flags is just 0 (modulo +modifier flags), but if the value is defined as a variable, the .flags +contains a set FL_VAR bit. -As you can see, the ts0 entry's .var.idx member contains the index | | | -into the tracing_map_elts' .vars[] array containing variable values. | | | -This idx is used whenever the value of the variable is set or read. | | | -The map_elt.vars idx assigned to the given variable is assigned and | | | -saved in .var.idx by create_tracing_map_fields() after it calls | | | -tracing_map_add_var(). | | | +As you can see, the ts0 entry's .var.idx member contains the index +into the tracing_map_elts' .vars[] array containing variable values. +This idx is used whenever the value of the variable is set or read. +The map_elt.vars idx assigned to the given variable is assigned and +saved in .var.idx by create_tracing_map_fields() after it calls +tracing_map_add_var(). -Below is a representation of the histogram at run-time, which | | | -populates the map, along with correspondence to the above hist_data and | | | -hist_field data structures. | | | +Below is a representation of the histogram at run-time, which +populates the map, along with correspondence to the above hist_data and +hist_field data structures. -The diagram attempts to show the relationship between the | | | -hist_data.fields[] and the map_elt.fields[] and map_elt.vars[] with | | | -the links drawn between diagrams. For each of the map_elts, you can | | | -see that the .fields[] members point to the .sum or .offset of a key | | | -or val and the .vars[] members point to the value of a variable. The | | | -arrows between the two diagrams show the linkages between those | | | -tracing_map members and the field definitions in the corresponding | | | +The diagram attempts to show the relationship between the +hist_data.fields[] and the map_elt.fields[] and map_elt.vars[] with +the links drawn between diagrams. For each of the map_elts, you can +see that the .fields[] members point to the .sum or .offset of a key +or val and the .vars[] members point to the value of a variable. The +arrows between the two diagrams show the linkages between those +tracing_map members and the field definitions in the corresponding hist_data fields[] members.:: +-----------+ | | | @@ -565,40 +565,40 @@ hist_data fields[] members.:: | | | | +---------------+ | | -For each used map entry, there's a map_elt pointing to an array of | | -.vars containing the current value of the variables associated with | | -that histogram entry. So in the above, the timestamp associated with | | -pid 999 is 113345679876, and the timestamp variable in the same | | -.var.idx for pid 4444 is 213499240729. | | +For each used map entry, there's a map_elt pointing to an array of +.vars containing the current value of the variables associated with +that histogram entry. So in the above, the timestamp associated with +pid 999 is 113345679876, and the timestamp variable in the same +.var.idx for pid 4444 is 213499240729. -sched_switch histogram | | ----------------------- | | +sched_switch histogram +---------------------- -The sched_switch histogram paired with the above sched_waking | | -histogram is shown below. The most important aspect of the | | -sched_switch histogram is that it references a variable on the | | -sched_waking histogram above. | | +The sched_switch histogram paired with the above sched_waking +histogram is shown below. The most important aspect of the +sched_switch histogram is that it references a variable on the +sched_waking histogram above. -The histogram diagram is very similar to the others so far displayed, | | -but it adds variable references. You can see the normal hitcount and | | -key fields along with a new wakeup_lat variable implemented in the | | -same way as the sched_waking ts0 variable, but in addition there's an | | -entry with the new FL_VAR_REF (short for HIST_FIELD_FL_VAR_REF) flag. | | +The histogram diagram is very similar to the others so far displayed, +but it adds variable references. You can see the normal hitcount and +key fields along with a new wakeup_lat variable implemented in the +same way as the sched_waking ts0 variable, but in addition there's an +entry with the new FL_VAR_REF (short for HIST_FIELD_FL_VAR_REF) flag. -Associated with the new var ref field are a couple of new hist_field | | -members, var.hist_data and var_ref_idx. For a variable reference, the | | -var.hist_data goes with the var.idx, which together uniquely identify | | -a particular variable on a particular histogram. The var_ref_idx is | | -just the index into the var_ref_vals[] array that caches the values of | | -each variable whenever a hist trigger is updated. Those resulting | | -values are then finally accessed by other code such as trace action | | -code that uses the var_ref_idx values to assign param values. | | +Associated with the new var ref field are a couple of new hist_field +members, var.hist_data and var_ref_idx. For a variable reference, the +var.hist_data goes with the var.idx, which together uniquely identify +a particular variable on a particular histogram. The var_ref_idx is +just the index into the var_ref_vals[] array that caches the values of +each variable whenever a hist trigger is updated. Those resulting +values are then finally accessed by other code such as trace action +code that uses the var_ref_idx values to assign param values. -The diagram below describes the situation for the sched_switch | | +The diagram below describes the situation for the sched_switch histogram referred to before:: - # echo 'hist:keys=next_pid:wakeup_lat=common_timestamp.usecs-$ts0' >> | | - events/sched/sched_switch/trigger | | + # echo 'hist:keys=next_pid:wakeup_lat=common_timestamp.usecs-$ts0' >> + events/sched/sched_switch/trigger | | +------------------+ | | | hist_data | | | From 8c716e87ea33519920811338100d6d8a7fb32456 Mon Sep 17 00:00:00 2001 From: Bagas Sanjaya Date: Tue, 16 Sep 2025 12:42:01 +0700 Subject: [PATCH 187/193] Documentation: trace: historgram-design: Separate sched_waking histogram section heading and the following diagram Section heading for sched_waking histogram is shown as normal paragraph instead due to codeblock marker for the following diagram being in the same line as the section underline. Separate them. Fixes: daceabf1b494 ("tracing/doc: Fix ascii-art in histogram-design.rst") Reviewed-by: Tom Zanussi Reviewed-by: Masami Hiramatsu (Google) Signed-off-by: Bagas Sanjaya Acked-by: Steven Rostedt (Google) Signed-off-by: Jonathan Corbet Message-ID: <20250916054202.582074-5-bagasdotme@gmail.com> --- Documentation/trace/histogram-design.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Documentation/trace/histogram-design.rst b/Documentation/trace/histogram-design.rst index 231a12bd7d46..4faff1669b77 100644 --- a/Documentation/trace/histogram-design.rst +++ b/Documentation/trace/histogram-design.rst @@ -380,7 +380,9 @@ entry, ts0, corresponding to the ts0 variable in the sched_waking trigger above. sched_waking histogram -----------------------:: +---------------------- + +.. code-block:: +------------------+ | hist_data |<-------------------------------------------------------+ From fa06220f3467bc7264809be58a8cbb0329ce6fcb Mon Sep 17 00:00:00 2001 From: Bagas Sanjaya Date: Tue, 16 Sep 2025 12:42:02 +0700 Subject: [PATCH 188/193] Documentation: trace: histogram-design: Wrap introductory note in note:: directive Use Sphinx note:: directive for the introductory note at the beginning of docs, instead of aligned-text paragraph that renders as definition list. Reviewed-by: Tom Zanussi Reviewed-by: Masami Hiramatsu (Google) Signed-off-by: Bagas Sanjaya Acked-by: Steven Rostedt (Google) Signed-off-by: Jonathan Corbet Message-ID: <20250916054202.582074-6-bagasdotme@gmail.com> --- Documentation/trace/histogram-design.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/Documentation/trace/histogram-design.rst b/Documentation/trace/histogram-design.rst index 4faff1669b77..ae71b5bf97c6 100644 --- a/Documentation/trace/histogram-design.rst +++ b/Documentation/trace/histogram-design.rst @@ -11,13 +11,14 @@ histograms work and how the individual pieces map to the data structures used to implement them in trace_events_hist.c and tracing_map.c. -Note: All the ftrace histogram command examples assume the working - directory is the ftrace /tracing directory. For example:: +.. note:: + All the ftrace histogram command examples assume the working + directory is the ftrace /tracing directory. For example:: # cd /sys/kernel/tracing -Also, the histogram output displayed for those commands will be -generally be truncated - only enough to make the point is displayed. + Also, the histogram output displayed for those commands will be + generally be truncated - only enough to make the point is displayed. 'hist_debug' trace event files ============================== From b8874ea3d0fdb2c48b2261bb3b46c84908fa67bb Mon Sep 17 00:00:00 2001 From: Bagas Sanjaya Date: Tue, 16 Sep 2025 12:42:03 +0700 Subject: [PATCH 189/193] Documentation: trace: histogram: Convert ftrace docs cross-reference In brief "Extended error information" section, details on error condition is referred to ftrace docs, which is written in :file: directive instead of a proper cross-reference. Convert it. Reviewed-by: Tom Zanussi Signed-off-by: Bagas Sanjaya Acked-by: Steven Rostedt (Google) Signed-off-by: Jonathan Corbet Message-ID: <20250916054202.582074-7-bagasdotme@gmail.com> --- Documentation/trace/histogram.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/trace/histogram.rst b/Documentation/trace/histogram.rst index d158dadaa424..340bcb5099e7 100644 --- a/Documentation/trace/histogram.rst +++ b/Documentation/trace/histogram.rst @@ -209,8 +209,8 @@ Documentation written by Tom Zanussi For some error conditions encountered when invoking a hist trigger command, extended error information is available via the - tracing/error_log file. See Error Conditions in - :file:`Documentation/trace/ftrace.rst` for details. + tracing/error_log file. See "Error conditions" section in + Documentation/trace/ftrace.rst for details. 2.3. 'hist' trigger examples ---------------------------- From ab588b78cdb8d677f70278587041a7366b0cff71 Mon Sep 17 00:00:00 2001 From: Akira Yokosawa Date: Sun, 21 Sep 2025 16:26:04 +0900 Subject: [PATCH 190/193] docs: dev-tools/lkmm: Fix typo of missing file extension Commit 1e9ddbb2cd34 ("docs: Pull LKMM documentation into dev-tools book") failed to add a file extension in lkmm/docs/herd-representation.rst for referencing its plane-text counterpart. Fix it. Fixes: 1e9ddbb2cd34 ("docs: Pull LKMM documentation into dev-tools book") Reported-by: kernel test robot Closes: https://lore.kernel.org/oe-kbuild-all/202509192138.fx3H6NzG-lkp@intel.com/ Signed-off-by: Akira Yokosawa Signed-off-by: Jonathan Corbet Message-ID: --- Documentation/dev-tools/lkmm/docs/herd-representation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/dev-tools/lkmm/docs/herd-representation.rst b/Documentation/dev-tools/lkmm/docs/herd-representation.rst index ebf4a2181cd7..f7b41f286eb9 100644 --- a/Documentation/dev-tools/lkmm/docs/herd-representation.rst +++ b/Documentation/dev-tools/lkmm/docs/herd-representation.rst @@ -3,7 +3,7 @@ herd-representation ------------------- -Literal include of ``tools/memory-model/Documentation/herd-representation``. +Literal include of ``tools/memory-model/Documentation/herd-representation.txt``. ------------------------------------------------------------------ From 22014a23009326ae63efb08575aada1de2c95bda Mon Sep 17 00:00:00 2001 From: Yash Suthar Date: Sun, 21 Sep 2025 00:38:56 +0530 Subject: [PATCH 191/193] Documentation/process: submitting-patches: fix typo in "were do" Fixes a typo in submitting-patches.rst: "were do" -> "where do" Signed-off-by: Yash Suthar Acked-by: Randy Dunlap Signed-off-by: Jonathan Corbet Message-ID: <20250920190856.7394-1-yashsuthar983@gmail.com> --- Documentation/process/submitting-patches.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index 5778cb9701e1..910e8fc9e3c8 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -343,7 +343,7 @@ https://en.wikipedia.org/wiki/Posting_style#Interleaved_style As is frequently quoted on the mailing list:: A: http://en.wikipedia.org/wiki/Top_post - Q: Were do I find info about this thing called top-posting? + Q: Where do I find info about this thing called top-posting? A: Because it messes up the order in which people normally read text. Q: Why is top-posting such a bad thing? A: Top-posting. From 2af8a8a47df36a202c65ce4af93fb8bc7b607210 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sat, 20 Sep 2025 17:22:09 +0200 Subject: [PATCH 192/193] docs: remove cdomain.py This is not used anymore, as it was a logic we had to support pre Sphinx 3.x, as shown at: afde706afde2 ("Make the docs build "work" with Sphinx 3.x") Remove it. Fixes: b26717852db7 ("docs: conf.py: drop backward support for old Sphinx versions") Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Message-ID: <3b86d236c64af17924e4cfedbbfb8bc60059802f.1758381727.git.mchehab+huawei@kernel.org> --- Documentation/sphinx/cdomain.py | 247 -------------------------------- 1 file changed, 247 deletions(-) delete mode 100644 Documentation/sphinx/cdomain.py diff --git a/Documentation/sphinx/cdomain.py b/Documentation/sphinx/cdomain.py deleted file mode 100644 index 3dc285dc70f5..000000000000 --- a/Documentation/sphinx/cdomain.py +++ /dev/null @@ -1,247 +0,0 @@ -# -*- coding: utf-8; mode: python -*- -# SPDX-License-Identifier: GPL-2.0 -# pylint: disable=W0141,C0113,C0103,C0325 -""" - cdomain - ~~~~~~~ - - Replacement for the sphinx c-domain. - - :copyright: Copyright (C) 2016 Markus Heiser - :license: GPL Version 2, June 1991 see Linux/COPYING for details. - - List of customizations: - - * Moved the *duplicate C object description* warnings for function - declarations in the nitpicky mode. See Sphinx documentation for - the config values for ``nitpick`` and ``nitpick_ignore``. - - * Add option 'name' to the "c:function:" directive. With option 'name' the - ref-name of a function can be modified. E.g.:: - - .. c:function:: int ioctl( int fd, int request ) - :name: VIDIOC_LOG_STATUS - - The func-name (e.g. ioctl) remains in the output but the ref-name changed - from 'ioctl' to 'VIDIOC_LOG_STATUS'. The function is referenced by:: - - * :c:func:`VIDIOC_LOG_STATUS` or - * :any:`VIDIOC_LOG_STATUS` (``:any:`` needs sphinx 1.3) - - * Handle signatures of function-like macros well. Don't try to deduce - arguments types of function-like macros. - -""" - -from docutils import nodes -from docutils.parsers.rst import directives - -import sphinx -from sphinx import addnodes -from sphinx.domains.c import c_funcptr_sig_re, c_sig_re -from sphinx.domains.c import CObject as Base_CObject -from sphinx.domains.c import CDomain as Base_CDomain -from itertools import chain -import re - -__version__ = '1.1' - -# Namespace to be prepended to the full name -namespace = None - -# -# Handle trivial newer c domain tags that are part of Sphinx 3.1 c domain tags -# - Store the namespace if ".. c:namespace::" tag is found -# -RE_namespace = re.compile(r'^\s*..\s*c:namespace::\s*(\S+)\s*$') - -def markup_namespace(match): - global namespace - - namespace = match.group(1) - - return "" - -# -# Handle c:macro for function-style declaration -# -RE_macro = re.compile(r'^\s*..\s*c:macro::\s*(\S+)\s+(\S.*)\s*$') -def markup_macro(match): - return ".. c:function:: " + match.group(1) + ' ' + match.group(2) - -# -# Handle newer c domain tags that are evaluated as .. c:type: for -# backward-compatibility with Sphinx < 3.0 -# -RE_ctype = re.compile(r'^\s*..\s*c:(struct|union|enum|enumerator|alias)::\s*(.*)$') - -def markup_ctype(match): - return ".. c:type:: " + match.group(2) - -# -# Handle newer c domain tags that are evaluated as :c:type: for -# backward-compatibility with Sphinx < 3.0 -# -RE_ctype_refs = re.compile(r':c:(var|struct|union|enum|enumerator)::`([^\`]+)`') -def markup_ctype_refs(match): - return ":c:type:`" + match.group(2) + '`' - -# -# Simply convert :c:expr: and :c:texpr: into a literal block. -# -RE_expr = re.compile(r':c:(expr|texpr):`([^\`]+)`') -def markup_c_expr(match): - return '\\ ``' + match.group(2) + '``\\ ' - -# -# Parse Sphinx 3.x C markups, replacing them by backward-compatible ones -# -def c_markups(app, docname, source): - result = "" - markup_func = { - RE_namespace: markup_namespace, - RE_expr: markup_c_expr, - RE_macro: markup_macro, - RE_ctype: markup_ctype, - RE_ctype_refs: markup_ctype_refs, - } - - lines = iter(source[0].splitlines(True)) - for n in lines: - match_iterators = [regex.finditer(n) for regex in markup_func] - matches = sorted(chain(*match_iterators), key=lambda m: m.start()) - for m in matches: - n = n[:m.start()] + markup_func[m.re](m) + n[m.end():] - - result = result + n - - source[0] = result - -# -# Now implements support for the cdomain namespacing logic -# - -def setup(app): - - # Handle easy Sphinx 3.1+ simple new tags: :c:expr and .. c:namespace:: - app.connect('source-read', c_markups) - app.add_domain(CDomain, override=True) - - return dict( - version = __version__, - parallel_read_safe = True, - parallel_write_safe = True - ) - -class CObject(Base_CObject): - - """ - Description of a C language object. - """ - option_spec = { - "name" : directives.unchanged - } - - def handle_func_like_macro(self, sig, signode): - """Handles signatures of function-like macros. - - If the objtype is 'function' and the signature ``sig`` is a - function-like macro, the name of the macro is returned. Otherwise - ``False`` is returned. """ - - global namespace - - if not self.objtype == 'function': - return False - - m = c_funcptr_sig_re.match(sig) - if m is None: - m = c_sig_re.match(sig) - if m is None: - raise ValueError('no match') - - rettype, fullname, arglist, _const = m.groups() - arglist = arglist.strip() - if rettype or not arglist: - return False - - arglist = arglist.replace('`', '').replace('\\ ', '') # remove markup - arglist = [a.strip() for a in arglist.split(",")] - - # has the first argument a type? - if len(arglist[0].split(" ")) > 1: - return False - - # This is a function-like macro, its arguments are typeless! - signode += addnodes.desc_name(fullname, fullname) - paramlist = addnodes.desc_parameterlist() - signode += paramlist - - for argname in arglist: - param = addnodes.desc_parameter('', '', noemph=True) - # separate by non-breaking space in the output - param += nodes.emphasis(argname, argname) - paramlist += param - - if namespace: - fullname = namespace + "." + fullname - - return fullname - - def handle_signature(self, sig, signode): - """Transform a C signature into RST nodes.""" - - global namespace - - fullname = self.handle_func_like_macro(sig, signode) - if not fullname: - fullname = super(CObject, self).handle_signature(sig, signode) - - if "name" in self.options: - if self.objtype == 'function': - fullname = self.options["name"] - else: - # FIXME: handle :name: value of other declaration types? - pass - else: - if namespace: - fullname = namespace + "." + fullname - - return fullname - - def add_target_and_index(self, name, sig, signode): - # for C API items we add a prefix since names are usually not qualified - # by a module name and so easily clash with e.g. section titles - targetname = 'c.' + name - if targetname not in self.state.document.ids: - signode['names'].append(targetname) - signode['ids'].append(targetname) - signode['first'] = (not self.names) - self.state.document.note_explicit_target(signode) - inv = self.env.domaindata['c']['objects'] - if (name in inv and self.env.config.nitpicky): - if self.objtype == 'function': - if ('c:func', name) not in self.env.config.nitpick_ignore: - self.state_machine.reporter.warning( - 'duplicate C object description of %s, ' % name + - 'other instance in ' + self.env.doc2path(inv[name][0]), - line=self.lineno) - inv[name] = (self.env.docname, self.objtype) - - indextext = self.get_index_text(name) - if indextext: - self.indexnode['entries'].append( - ('single', indextext, targetname, '', None)) - -class CDomain(Base_CDomain): - - """C language domain.""" - name = 'c' - label = 'C' - directives = { - 'function': CObject, - 'member': CObject, - 'macro': CObject, - 'type': CObject, - 'var': CObject, - } From 99510c324e531addd9f7b80a72dab7435ca66215 Mon Sep 17 00:00:00 2001 From: Lukas Bulwahn Date: Thu, 25 Sep 2025 09:36:34 +0200 Subject: [PATCH 193/193] Documentation/features: Update feature lists for 6.17-rc7 It seems that ./Documentation/features/scripts/features-refresh.sh was most recently used in December 2022, with the latest kernel release v6.1-rc7 at that time (see commit 7f2e60ff51ca ("Documentation/features: Update feature lists for 6.1") to update the feature lists in this subdirectory. All further changes to Documentation/features/ since then have probably been done manually, without checking for changes in other architectures and features, that missed to update this part of the documentation. Running ./Documentation/features/scripts/features-refresh.sh now showed seven changes of supported features in various architectures (one in arc, two in parisc, one in riscv, one in openrisc, and two in um), which were not reflected yet in the current documentation. To confirm the sanity of this script's suggested changes, I checked if the commit messages confirm that the features have in fact been added in the following commits: - commit f122668ddcce ("ARC: Add eBPF JIT support") - commit 4800a6215e33 ("parisc: Wire up eBPF JIT compiler") - commit a869b8c29f86 ("riscv: enable mseal sysmap for RV64") - commit 2f681ba4b352 ("um: move thread info into task") - commit 3f17fed21491 ("um: switch to regset API and depend on XSTATE") - commit 7ce8716e2769 ("openrisc: Add HAVE_REGS_AND_STACK_ACCESS_API support") - commit b5ff52be8913 ("parisc: Convert to generic clockevents") So, update all documents to the current state with features-refresh.sh. Signed-off-by: Lukas Bulwahn Signed-off-by: Jonathan Corbet Message-ID: <20250925073634.112142-1-lukas.bulwahn@redhat.com> --- Documentation/features/core/eBPF-JIT/arch-support.txt | 4 ++-- .../features/core/mseal_sys_mappings/arch-support.txt | 2 +- .../features/core/thread-info-in-task/arch-support.txt | 2 +- Documentation/features/core/tracehook/arch-support.txt | 2 +- Documentation/features/perf/kprobes-event/arch-support.txt | 2 +- Documentation/features/time/clockevents/arch-support.txt | 2 +- 6 files changed, 7 insertions(+), 7 deletions(-) diff --git a/Documentation/features/core/eBPF-JIT/arch-support.txt b/Documentation/features/core/eBPF-JIT/arch-support.txt index 7434b43c2ff8..83f77f55fc87 100644 --- a/Documentation/features/core/eBPF-JIT/arch-support.txt +++ b/Documentation/features/core/eBPF-JIT/arch-support.txt @@ -7,7 +7,7 @@ | arch |status| ----------------------- | alpha: | TODO | - | arc: | TODO | + | arc: | ok | | arm: | ok | | arm64: | ok | | csky: | TODO | @@ -18,7 +18,7 @@ | mips: | ok | | nios2: | TODO | | openrisc: | TODO | - | parisc: | TODO | + | parisc: | ok | | powerpc: | ok | | riscv: | ok | | s390: | ok | diff --git a/Documentation/features/core/mseal_sys_mappings/arch-support.txt b/Documentation/features/core/mseal_sys_mappings/arch-support.txt index a3c24233eb9b..fa85381acc43 100644 --- a/Documentation/features/core/mseal_sys_mappings/arch-support.txt +++ b/Documentation/features/core/mseal_sys_mappings/arch-support.txt @@ -20,7 +20,7 @@ | openrisc: | N/A | | parisc: | TODO | | powerpc: | TODO | - | riscv: | TODO | + | riscv: | ok | | s390: | ok | | sh: | N/A | | sparc: | TODO | diff --git a/Documentation/features/core/thread-info-in-task/arch-support.txt b/Documentation/features/core/thread-info-in-task/arch-support.txt index 2afeb6bf6e64..f3d744c76061 100644 --- a/Documentation/features/core/thread-info-in-task/arch-support.txt +++ b/Documentation/features/core/thread-info-in-task/arch-support.txt @@ -24,7 +24,7 @@ | s390: | ok | | sh: | TODO | | sparc: | TODO | - | um: | TODO | + | um: | ok | | x86: | ok | | xtensa: | TODO | ----------------------- diff --git a/Documentation/features/core/tracehook/arch-support.txt b/Documentation/features/core/tracehook/arch-support.txt index a72330e25542..4f36fcbfb6d5 100644 --- a/Documentation/features/core/tracehook/arch-support.txt +++ b/Documentation/features/core/tracehook/arch-support.txt @@ -24,7 +24,7 @@ | s390: | ok | | sh: | ok | | sparc: | ok | - | um: | TODO | + | um: | ok | | x86: | ok | | xtensa: | ok | ----------------------- diff --git a/Documentation/features/perf/kprobes-event/arch-support.txt b/Documentation/features/perf/kprobes-event/arch-support.txt index 713a69fcd697..75c05d348c01 100644 --- a/Documentation/features/perf/kprobes-event/arch-support.txt +++ b/Documentation/features/perf/kprobes-event/arch-support.txt @@ -17,7 +17,7 @@ | microblaze: | TODO | | mips: | ok | | nios2: | TODO | - | openrisc: | TODO | + | openrisc: | ok | | parisc: | ok | | powerpc: | ok | | riscv: | ok | diff --git a/Documentation/features/time/clockevents/arch-support.txt b/Documentation/features/time/clockevents/arch-support.txt index 4d4bfac52970..d6100b226de5 100644 --- a/Documentation/features/time/clockevents/arch-support.txt +++ b/Documentation/features/time/clockevents/arch-support.txt @@ -18,7 +18,7 @@ | mips: | ok | | nios2: | ok | | openrisc: | ok | - | parisc: | TODO | + | parisc: | ok | | powerpc: | ok | | riscv: | ok | | s390: | ok |