20 Patches Hacking and the Community

Linux Kernel Community and Development Workflow

The Linux Kernel Community

• The Linux Kernel Mailing List (lkml) serves as the central hub for feature announcements, architectural discussions, and code review.
• Subscription requires sending a plain text email to majordomo@vger.kernel.org containing subscribe linux-kernel <email>.
• Daily traffic typically exceeds 300 messages, requiring developers to aggressively filter and monitor specific threads.
• Supplemental resources include kernelnewbies.org for onboarding, lwn.net for kernel news, and kerneltrap.org for technical commentary.

Active participation in the kernel community requires strict adherence to standardized formatting to ensure global readability and efficient peer review.

Kernel Coding Style

• Indentation
  • Use 8-character tabs exclusively, never spaces.
  • Limit architectural complexity to avoid exceeding three levels of indentation.
• Switch Statements
  • Align subordinate case labels at the identical indentation level as the parent switch statement.
• Spacing
  • Insert spaces around binary and tertiary operators (=, +, %, ?).
  • Insert spaces after control-flow keywords (if, while, for, switch).
  • Omit spaces between functions, function-like macros (sizeof, typeof), and their opening parentheses.
  • Omit spaces around unary operators (++, --, ~, !).
  • Attach pointer dereference asterisks directly to the variable name (e.g., char *dest), not the data type.
• Braces
  • Place the opening brace on the first line at the end of the statement, and the closing brace on a new line.
  • Place both the opening and closing braces on their own independent lines for function definitions.
  • Omit braces entirely for single-line conditional statements.
• Line Length
  • Enforce a strict 80-character maximum line length.
  • Manually break and align overflowing lines, typically aligning wrapped parameters with the opening parenthesis of the function call.
• Naming Conventions
  • Use descriptive lowercase variable and function names separated by underscores.
  • Discard CamelCase, StudlyCaps, and Hungarian notation completely.
• Functions
  • Restrict function length to 1-2 screens of text and utilize fewer than 10 local variables.
  • Utilize the inline keyword for small, overhead-sensitive routines.
• Comments
  • Document the what and why of an algorithm, never the how.
  • Utilize standard C-style /* ... */ comment blocks.
  • Prefix critical development notes with XXX: and known bugs with FIXME:.
  • Format API documentation using the Kernel-doc standard (/** ... */) to enable self-generating HTML/Postscript manuals via make htmldocs.
• Typedefs
  • Avoid typedef usage to prevent hiding underlying data sizes and enabling pass-by-value stack errors.
  • Restrict typedef usage strictly to architecture-specific abstractions or required forward compatibility.
• Code Design
  • Call built-in kernel functions for string manipulation and linked lists rather than reinventing algorithms or writing generic wrapper macros.
  • Avoid inline #ifdef preprocessor directives within function bodies.
  • Abstract hardware or configuration checks by defining static inline stubs outside the function scope when the target configuration is disabled.
  • Initialize structures using C99 labeled identifiers (e.g., .field = value), allowing unassigned fields to default to zero.
• Automated Formatting
  • Retrofit non-conforming source files using the GNU indent utility with parameters: indent -kr -i8 -ts8 -sob -l80 -ss -bs -psl <file>.
  • Execute the scripts/Lindent script to automatically apply the required indent parameters.

Adhering to these rigid coding standards ensures code is properly formatted for review by the kernel hierarchy when developers report system issues or submit modifications.

Chain of Command and Bug Reporting

• Hierarchy
  • Kernel hackers with significant contributions are documented in the root CREDITS file.
  • Subsystem and driver maintainers are listed in the root MAINTAINERS file, holding responsibility for reviewing changes to specific code paths.
  • The Kernel Maintainer manages the primary kernel tree, splitting duties between the perpetual development branch and strict bug-fix stable branches.
• Bug Reporting Protocol
  • Document the problem comprehensively, including system output, hardware specifications, and exact steps to reliably reproduce the fault.
  • Supply a fully decoded oops trace utilizing kallsyms for any memory access violations or fatal errors.
  • Route the bug report directly to the specific subsystem maintainer identified in MAINTAINERS and carbon-copy the LKML.
  • Consult REPORTING-BUGS and Documentation/oops-tracing.txt for subsystem-specific reporting requirements.

Identifying kernel faults and locating the correct subsystem maintainer sets the stage for developing, testing, and distributing the actual code fixes through patches.

Patch Generation and Submission

• Standard Patch Generation
  • Maintain a pristine source tree (e.g., linux-x.y.z/) alongside a modified tree (e.g., linux/).
  • Generate a unified diff from the parent directory containing both trees: diff -urN linux-x.y.z/ linux/ > my-patch.
  • Test patch applicability on a clean tree using patch -p1 < ../my-patch.
  • Generate a line-modification histogram for peer review using diffstat -p1 my-patch.
• Git Patch Generation
  • Commit source modifications to the local Git repository using git commit -a or git add followed by git commit.
  • Provide a verbose and complete commit changelog describing the technical modifications.
  • Generate formatted patch files against the origin tree using git format-patch origin.
  • Isolate patches for only the last sequence of commits using git format-patch -N (e.g., -1 for the most recent commit).
• Submission Protocol
  • Email the patch to the designated maintainer and CC the LKML.
  • Format the email subject line as [PATCH] brief description.
  • Detail the technical rationale and specify the exact kernel base version within the email body.
  • Insert the patch directly inline at the end of the email message to facilitate inline peer review, ensuring the email client does not apply line-wrapping.
  • Deconstruct large modifications into sequential, independent patch chunks (e.g., split API generation from downstream driver implementation), noting dependencies between chunks.