[Deepin-Kernel-SIG] [linux 6.6.y] [Upstream] Upstream backport: checkpatch enhancements, README restructuring, and AI coding assistant docs

[Avenger-285714]

This PR backports upstream improvements to the kernel's patch checking infrastructure,
documentation, and contributor guidelines. All commits are signed-off and rebased.

checkpatch.pl improvements (16 commits)

Enhance the kernel patch style checker with new validations and bug fixes:

• New checks:

  • Detect unhandled placeholders in cover letters
  • Warn about context_unsafe() without explanatory comment
  • Flag uninitialized pointers with __free attribute
  • Check for missing sentinels in ID device arrays (of_device_id, pci_device_id, etc.)
  • Require comments for RGMII PHY modes in Device Trees
  • Add invalid patch separator test (3 dashes with trailing content)
  • Suggest kmalloc_obj family for sizeof() allocations
  • Add IDR APIs to the deprecated list

• False positive fixes:

  • Suppress strscpy warnings for userspace tools (tools/, scripts/)
  • Allow HTTP links of any length in commit logs
  • Special-case cacheline group macros to avoid spurious warnings
  • Fix false DT_SPLIT_BINDING_PATCH warnings on deleted files
  • Don't complain on _Generic() use (improve CamelCase detection)
  • Use UTF-8 matching for spell checking (fixes false misspelling on non-ASCII names)

• Robustness & clarity:

  • Align git commit ID abbreviation guidelines: accept 12+ characters consistently
  • Check return of git_commit_info to avoid undefined variable concatenation
  • Describe --min-conf-desc-length unit explicitly as "lines" with default 4

Documentation (2 commits)

• Add new Documentation/process/coding-assistants.rst with guidance for AI-assisted
  kernel contributions (licensing, Signed-off-by, attribution format)
• Restructure README with role-based documentation paths for developers, researchers,
  security experts, and maintainers; add quick-start section

README fixes (1 commit)

• Fix "ReStructured Text" spelling/capitalization to "reStructuredText"

---

Files changed: 7
Insertions: 396, Deletions: 38

Summary by Sourcery

Document guidelines for using AI coding assistants in kernel development and surface this guidance from existing documentation entry points.

Enhancements:

• Backport upstream README updates to resolve conflicts while aligning with the latest documentation structure.

Documentation:

• Add a new coding-assistants.rst document detailing expectations and requirements for AI-assisted kernel contributions, including licensing, attribution, and Signed-off-by usage.
• Link the new AI assistant guidelines into the process documentation index for discoverability.
• Adjust the top-level README to direct AI tools and users to the new coding assistant documentation.

Summary by Sourcery

Backport upstream improvements to the kernel checkpatch script and documentation, including new validations, clearer diagnostics, and guidance for AI-assisted contributions, while updating the top-level README structure.

New Features:

• Extend checkpatch to detect placeholder text in commit messages, invalid patch separators, missing sentinels in device ID tables, uninitialized __free pointers, uncommented context_unsafe usage, and RGMII PHY modes without explanatory comments.
• Add new recommendations in checkpatch for preferred allocation helpers and deprecate legacy IDR APIs.
• Introduce Documentation/process/coding-assistants.rst describing expectations and requirements for AI-assisted kernel contributions and how to attribute such tools.

Bug Fixes:

• Relax Fixes: tag validation to accept 12+ character commit IDs and avoid using undefined commit metadata when git lookup fails.
• Prevent false-positive checkpatch warnings for strcpy/strlcpy/strncpy in userspace code, cacheline grouping macros, _Generic uses, long HTTP links, DT binding patches on deleted files, and non-ASCII spellings by improving context detection and UTF-8 handling.
• Clarify the meaning of the --min-conf-desc-length option and the associated warning message for configuration symbol descriptions.

Enhancements:

• Refine checkpatch style guidance for config help text and allocation patterns to better reflect current kernel practices.
• Improve spell-check robustness in checkpatch by operating on UTF-8 decoded lines and preserving pointer diagnostics.
• Tighten device-tree specific checks to require comments for certain RGMII PHY modes when delays are handled on the PCB.

Documentation:

• Add a new coding-assistants process document and link it from the process index and maintainer tips to guide AI-assisted development practices.
• Restructure and expand the top-level README to provide role-based navigation, a quick-start section, and explicit pointers to coding assistant documentation.
• Correct the spelling and capitalization of “reStructuredText” in the README.

[sourcery-ai]

Reviewer's Guide

Backports a series of upstream improvements to scripts/checkpatch.pl (new style checks, false-positive reductions, and robustness fixes) and updates documentation by restructuring the top-level README and adding AI coding assistant contribution guidelines wired into the process docs.

Sequence diagram for Fixes tag validation with git_commit_info

sequenceDiagram
  participant Dev as Developer
  participant Checkpatch as checkpatch_pl
  participant Git as git_commit_info

  Dev->>Checkpatch: Run checkpatch on patch
  Checkpatch->>Checkpatch: Detect Fixes line in commit log
  Checkpatch->>Git: git_commit_info(orig_commit, id, title)
  Git-->>Checkpatch: cid, ctitle
  Checkpatch->>Checkpatch: Validate commit id length (12-40), case, spacing, quotes
  alt Bad Fixes tag and cid defined
    Checkpatch->>Checkpatch: Build corrected Fixes line
    Checkpatch-->>Dev: WARN BAD_FIXES_TAG with suggested Fixes: cid ("ctitle")
    opt --fix option enabled
      Checkpatch->>Checkpatch: Replace line with corrected Fixes tag
    end
  else cid not defined
    Checkpatch->>Checkpatch: Skip BAD_FIXES_TAG warning
  end
  Checkpatch-->>Dev: Continue reporting other issues and summary

Loading

Class diagram for logical components in checkpatch.pl

classDiagram
  class CheckpatchProcess {
    +process(filename)
    +exclude_global_initialisers(realfile)
    +is_userspace(realfile)
  }

  class CommitLogChecks {
    +check_placeholder_text(line, in_commit_log, in_header_lines)
    +check_bad_commit_separator(line, in_commit_log, fix)
    +check_fixes_tag(line, herecurr, fix)
    +check_commit_log_long_line(line, herecurr)
    +spell_check_line(rawline, misspellings, hereptr)
  }

  class ConfigHelpChecks {
    +check_config_description(linenr, help_length, min_conf_desc_length)
  }

  class DeviceTreeChecks {
    +check_uncommented_rgmii_mode(realfile, line, first_line, linenr, herecurr)
  }

  class ContextChecks {
    +ctx_has_comment(first_line, linenr)
    +check_context_unsafe(line, first_line, linenr, herecurr)
  }

  class StringUsageChecks {
    +check_strcpy_usage(line, realfile, herecurr)
    +check_strlcpy_usage(line, realfile, herecurr)
    +check_strncpy_usage(line, realfile, herecurr)
  }

  class AllocationChecks {
    +check_alloc_with_sizeof(stat, linenr, here, fix)
    +check_alloc_with_multiply(stat, linenr, here, fix)
  }

  class DeviceIdChecks {
    +dev_id_types
    +check_device_id_sentinel(stat, line, here)
  }

  class PointerChecks {
    +check_uninitialized_free_pointer(line, herecurr)
  }

  class GitIntegration {
    +git_commit_info(orig_commit, id, title)
  }

  class SpellingSupport {
    +decode_utf8(rawline)
    +copy_spacing(rawline_utf8)
  }

  CheckpatchProcess --> CommitLogChecks : uses
  CheckpatchProcess --> ConfigHelpChecks : uses
  CheckpatchProcess --> DeviceTreeChecks : uses
  CheckpatchProcess --> ContextChecks : uses
  CheckpatchProcess --> StringUsageChecks : uses
  CheckpatchProcess --> AllocationChecks : uses
  CheckpatchProcess --> DeviceIdChecks : uses
  CheckpatchProcess --> PointerChecks : uses
  CommitLogChecks --> GitIntegration : uses
  CommitLogChecks --> SpellingSupport : uses
  ContextChecks <.. DeviceTreeChecks : uses
  StringUsageChecks <.. CheckpatchProcess : calls is_userspace
  DeviceIdChecks <.. CheckpatchProcess : uses dev_id_types

Loading

File-Level Changes

Change	Details	Files
Extend checkpatch.pl with new diagnostics and automatic fix suggestions for device IDs, allocation helpers, context safety, placeholders, RGMII DT modes, uninitialized __free pointers, and Fixes tags.	Document --min-conf-desc-length more clearly in help output and warning text, stating units (lines) and default value. Add dev_id_types regex and logic to detect _device_id arrays missing sentinel entries, including stripping diff/whitespace noise before checking. Add warnings for context_unsafe() used without a nearby explanatory comment and for RGMII phy-mode/phy-connection-type without a context comment in DT files. Introduce PLACEHOLDER_USE error for common auto-generated cover letter placeholders like 'SUBJECT HERE' or 'BLURB HERE' in commit logs/headers. Warn on uninitialized pointers annotated with the __free attribute when they appear in declarations. Add BAD_COMMIT_SEPARATOR error for commit log separators like '--- ...' that have trailing content instead of a clean '---' line. Enhance Fixes: tag validation to accept 12–40 character SHA-1s, guard git_commit_info() usage with defined() checks, and refactor the suggested replacement into a local variable. Relax COMMIT_LOG_LONG_LINE to allow arbitrary-length http/https links by treating them as exempted lines. Switch spelling check to operate on UTF-8 decoded lines to avoid false positives on non-ASCII words while still using the existing misspelling patterns. Add cacheline-group macros (_cacheline_group{begin,end}[_aligned], _dma_from_device_group{begin,end}) to the type pattern whitelist to avoid spurious warnings. Add is_userspace() helper and use it to suppress STRCPY/STRLCPY/STRNCPY warnings for files under tools/ and scripts/. Add IDR APIs (DEFINE_IDR, idr_init, idr_init_base) to the deprecated signature mapping, recommending XArray replacements. Introduce new kmalloc_obj/kvmalloc_obj*/kzalloc_obj*/kvzalloc_obj* suggestions when (kv	k)[mz]alloc is used with sizeof, including an auto-fix rewrite when safe. Update the multiply-allocation heuristic to suggest kmalloc_objs*/kvmalloc_objs*/kzalloc_objs*/kvzalloc_objs* instead of *array/*calloc APIs and adjust the auto-fix to convert the sizeof expression into the typed argument name. Exclude /dev/null from DT binding split checks by allowing MAINTAINERS
Improve documentation around contribution processes, especially for AI-assisted development, and integrate the new guidance into existing process indices and maintainer tips.	Add Documentation/process/coding-assistants.rst describing expectations for using AI coding assistants in kernel development, including licensing, attribution, and Signed-off-by requirements. Link the new coding-assistants.rst document from Documentation/process/index.rst so it appears in the main process documentation TOC. Update maintainer-focused docs (maintainer-tip.rst, submitting-patches.rst, and/or related process docs) to reference or align with the AI assistant guidance and checkpatch behavior where relevant.	Documentation/process/coding-assistants.rst Documentation/process/index.rst Documentation/process/maintainer-tip.rst Documentation/process/submitting-patches.rst
Restructure and polish the top-level README to clarify audience-specific entry points and fix minor terminology issues.	Rewrite/expand README sections to provide role-based pointers for developers, researchers, security experts, and maintainers, and add a quick-start section. Add explicit guidance in README directing AI tools and contributors to the new coding-assistants documentation. Fix the spelling/capitalization of 'ReStructured Text' to the correct 'reStructuredText' form.	README

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[deepin-ci-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please ask for approval from avenger-285714. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• deepin/OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[sourcery-ai]

Hey - I've reviewed your changes and they look great!

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[Copilot]

Pull request overview

Adds a new process document describing expectations for AI-assisted kernel contributions and updates entry points so humans and tools can discover it (README + process index).

Changes:

• Expand README into a role-oriented entry document and add a prominent pointer for AI coding assistants to the new guidance.
• Add Documentation/process/coding-assistants.rst covering licensing, DCO / Signed-off-by handling, and attribution expectations.
• Include the new document in Documentation/process/index.rst to surface it in the rendered “process” docs.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
README	Reworks the top-level entry points and adds an explicit pointer to the AI assistants guidance.
Documentation/process/index.rst	Adds the new AI assistants document to the process toctree.
Documentation/process/coding-assistants.rst	Introduces AI-assistant contribution guidance (licensing, sign-off responsibilities, attribution format).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The documented Assisted-by: format/example does not include a Name <email> identity. In this tree, scripts/checkpatch.pl treats any *-by: tag as a signature and will error out with “Unrecognized email address” when the text after the tag is not parseable as an email identity (see scripts/checkpatch.pl around the signature-style checks). Please adjust the documented format to include a valid email identity (or use a different tag name that doesn’t match *-by: / update checkpatch to explicitly accept the intended format).

[Copilot]

The Assisted-by: format line uses [TOOL1] [TOOL2] (square brackets), but the example omits brackets. If the brackets are meant to indicate optional items (not literal characters), consider switching to a placeholder style that can’t be mistaken for part of the actual tag value and keep the format line and example consistent for tooling that will parse it.

Suggested change

	Assisted-by: AGENT_NAME:MODEL_VERSION [TOOL1] [TOOL2]
	Where:
	* ``AGENT_NAME`` is the name of the AI tool or framework
	* ``MODEL_VERSION`` is the specific model version used
	* ``[TOOL1] [TOOL2]`` are optional specialized analysis tools used
	Assisted-by: AGENT_NAME:MODEL_VERSION <TOOL1> <TOOL2> ...
	Where:
	* ``AGENT_NAME`` is the name of the AI tool or framework
	* ``MODEL_VERSION`` is the specific model version used
	* ``<TOOL1> <TOOL2> ...`` are optional specialized analysis tools used

[sourcery-ai]

Hey - I've found 4 issues, and left some high level feedback:

• In the new ALLOC_WITH_SIZEOF and ALLOC_WITH_MULTIPLE checks, the capture groups from the regex are used incorrectly (e.g., $oldfunc = $3; my $a1 = $4; when the regex only defines $1..$3), which will result in wrong or undefined values at runtime; please realign the variable assignments with the actual capture indices (function name is $2, first argument $3, etc.).
• The $dev_id_types regex only matches IDs starting with a lowercase ASCII letter ([a-z]), which may miss valid *_device_id types that start with an uppercase letter or underscore in future or out-of-tree code; consider relaxing this to \w or similar if you want the check to be more robust.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- In the new ALLOC_WITH_SIZEOF and ALLOC_WITH_MULTIPLE checks, the capture groups from the regex are used incorrectly (e.g., `$oldfunc = $3; my $a1 = $4;` when the regex only defines `$1..$3`), which will result in wrong or undefined values at runtime; please realign the variable assignments with the actual capture indices (function name is `$2`, first argument `$3`, etc.).
- The `$dev_id_types` regex only matches IDs starting with a lowercase ASCII letter (`[a-z]`), which may miss valid `*_device_id` types that start with an uppercase letter or underscore in future or out-of-tree code; consider relaxing this to `\w` or similar if you want the check to be more robust.

## Individual Comments

### Comment 1
<location path="scripts/checkpatch.pl" line_range="3102-3104" />
<code_context>
 		}

+# Check for invalid patch separator
+		if ($in_commit_log &&
+		    $line =~ /^---.+/) {
+			if (ERROR("BAD_COMMIT_SEPARATOR",
+				  "Invalid commit separator - some tools may have problems applying this\n" . $herecurr) &&
+			    $fix) {
</code_context>
<issue_to_address>
**issue (bug_risk):** Auto-fix for BAD_COMMIT_SEPARATOR is overly aggressive

The fix uses `$fixed[$fixlinenr] =~ s/-/=/g;`, which replaces every dash on the line, not just the `---` separator. This risks altering commit message content on the same line. Please scope the substitution to the leading separator only (e.g. `s/^---/===/` or another prefix-limited pattern).
</issue_to_address>

### Comment 2
<location path="Documentation/dev-tools/checkpatch.rst" line_range="523" />
<code_context>
+    used inconsistently, often referring to the usage of delays on the PHY
+    side rather than describing the board.
+
+    PHY modes "rgmii", "rgmii-rxid" and "rgmii-txid" modes require the clock
+    signal to be delayed on the PCB; this unusual configuration should be
+    described in a comment. If they are not (meaning that the delay is realized
</code_context>
<issue_to_address>
**issue (typo):** Duplicated word "modes" in the RGMII PHY modes sentence

The phrase "PHY modes 'rgmii', 'rgmii-rxid' and 'rgmii-txid' modes" repeats "modes". Please drop the second occurrence, e.g. "PHY modes 'rgmii', 'rgmii-rxid' and 'rgmii-txid' require the clock".

```suggestion
    PHY modes "rgmii", "rgmii-rxid" and "rgmii-txid" require the clock
```
</issue_to_address>

### Comment 3
<location path="Documentation/dev-tools/checkpatch.rst" line_range="633-634" />
<code_context>

+  **BAD_COMMIT_SEPARATOR**
+    The commit separator is a single line with 3 dashes.
+    The regex match is '^---$'
+    Lines that start with 3 dashes and have more content on the same line
+    may confuse tools that apply patches.

</code_context>
<issue_to_address>
**issue (typo):** Missing punctuation between two sentences in BAD_COMMIT_SEPARATOR description

"The regex match is '^---$'" runs directly into "Lines that start with 3 dashes..." without punctuation. Please add a period after the closing quote or rephrase to "The regex matches '^---$'."

Suggested implementation:

```
    The regex matches '^---$'.

```

The snippet you provided doesn't show the "The regex match is '^---$'" line or the following "Lines that start with 3 dashes..." line, so you'll need to ensure this search string matches exactly what is in your file (indentation, spacing, and quoting). If the actual text differs (for example different quotes, extra spaces, or punctuation), adjust the SEARCH string accordingly while keeping the REPLACE text as suggested.
</issue_to_address>

### Comment 4
<location path="Documentation/dev-tools/checkpatch.rst" line_range="1023-1024" />
<code_context>
       return bar;

+  **UNINITIALIZED_PTR_WITH_FREE**
+    Pointers with __free attribute should be declared at the place of use
+    and initialized (see include/linux/cleanup.h). In this case
+    declarations at the top of the function rule can be relaxed. Not doing
</code_context>
<issue_to_address>
**issue (typo):** Missing article before "__free attribute"

For correct grammar, use: "Pointers with the __free attribute should be declared at the place of use..."

```suggestion
  **UNINITIALIZED_PTR_WITH_FREE**
    Pointers with the __free attribute should be declared at the place of use
```
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[sourcery-ai]

issue (bug_risk): Auto-fix for BAD_COMMIT_SEPARATOR is overly aggressive

The fix uses $fixed[$fixlinenr] =~ s/-/=/g;, which replaces every dash on the line, not just the --- separator. This risks altering commit message content on the same line. Please scope the substitution to the leading separator only (e.g. s/^---/===/ or another prefix-limited pattern).

[sourcery-ai]

issue (typo): Duplicated word "modes" in the RGMII PHY modes sentence

The phrase "PHY modes 'rgmii', 'rgmii-rxid' and 'rgmii-txid' modes" repeats "modes". Please drop the second occurrence, e.g. "PHY modes 'rgmii', 'rgmii-rxid' and 'rgmii-txid' require the clock".

Suggested change

	PHY modes "rgmii", "rgmii-rxid" and "rgmii-txid" modes require the clock
	PHY modes "rgmii", "rgmii-rxid" and "rgmii-txid" require the clock

[sourcery-ai]

issue (typo): Missing punctuation between two sentences in BAD_COMMIT_SEPARATOR description

"The regex match is '^---$'" runs directly into "Lines that start with 3 dashes..." without punctuation. Please add a period after the closing quote or rephrase to "The regex matches '^---$'."

Suggested implementation:

    The regex matches '^---$'.

The snippet you provided doesn't show the "The regex match is '^---$'" line or the following "Lines that start with 3 dashes..." line, so you'll need to ensure this search string matches exactly what is in your file (indentation, spacing, and quoting). If the actual text differs (for example different quotes, extra spaces, or punctuation), adjust the SEARCH string accordingly while keeping the REPLACE text as suggested.

[sourcery-ai]

issue (typo): Missing article before "__free attribute"

For correct grammar, use: "Pointers with the __free attribute should be declared at the place of use..."

Suggested change

	**UNINITIALIZED_PTR_WITH_FREE**
	Pointers with __free attribute should be declared at the place of use
	**UNINITIALIZED_PTR_WITH_FREE**
	Pointers with the __free attribute should be declared at the place of use

[opsiff]

kzalloc_objs这些不在这个分支里面吧?