mirror of
https://github.com/eunomia-bpf/bpf-developer-tutorial.git
synced 2026-11-01 05:05:38 +08:00
Add advanced eBPF tutorials 51–54 and tutorial agent skills (#220)
* Add targeted TCP connection quarantine tool * Document TCP quarantine workflow * Refresh package indexes before CI install * Document TCP quarantine namespace scope * Require BPF events for TCP iterator * Add production fsession latency tracer * Document fsession latency workflow * Reject empty fsession CLI values * Preserve successful fsession exit status * Document fsession deadline regression test * Drain fsession events before summary * Document fsession PID and shutdown semantics * Simplify fsession polling control flow * Add bounded BPF egress pacer tutorial * Test queued packet cleanup on signal * Document the BPF egress pacer * Polish and review the BPF egress pacer * Refactor egress pacer option parsing * Add executable image inspector lesson * Build the exec image inspector in CI * Document executable image inspection * Handle re-exec chains in the image inspector * Polish exec image inspector guidance * Reduce exec inspector wait complexity * Rewrite the egress pacer tutorial * Rewrite the exec image inspector tutorial * Polish the exec image inspector tutorial * Correct the egress pacer tutorial * Make the exec tutorial Chinese natural * Fix egress tutorial prose checks * Finish the exec tutorial style pass * Clarify exec tutorial runtime evidence * Polish exec tutorial scope wording * Rewrite the egress pacer tutorial for readers * Regenerate tutorial indexes * Teach the egress pacer component by component * Use standard Markdown in the egress tutorial * Strengthen the egress pacer tutorial narrative * jiji * Use positive framing in the egress tutorial * Rewrite the exec image inspector tutorial * Rewrite the TCP quarantine tutorial * Add the egress pacer lifecycle diagram * Refresh TCP tutorial indexes * Add the exec image inspection flow diagram * Use one source directory link * Rewrite the fsession latency tutorial * Add fsession feature background * Add BPF qdisc feature background * Add TCP iterator feature background * Add exec inspection feature background * Require feature background in tutorial openings * Polish fsession background prose * Simplify repository tutorial skills * Update exec inspector tooling revisions * Restructure tutorials 51-54 following advanced guideline - Update SKILL.md with strict section ordering and "why" requirements - Rewrite README.zh.md for tutorials 51-54: - Add background sections explaining why traditional approaches fail - Move compilation/execution sections after code analysis - Add high-level mechanism explanation before code - Use paragraph style instead of bullet lists * Consolidate skill guidelines and remove duplicates - Update write-bpf-production-tutorial skill to reference 47, 48, 49 - Add structure requirements section with "Why" section emphasis - Remove duplicate advanced-tutorial-guidelines.md (use scripts/guideline_advance.md instead) * Rewrite English READMEs 51-54 to match Chinese structure Restructure all four English tutorials to match their Chinese counterparts: - Add "Why this approach is needed" sections explaining traditional limitations - Add high-level mechanism sections before code - Move compilation/execution sections after code analysis - Add environment requirements tables - Use consistent section ordering across all tutorials * Regenerate TOC after tutorial title changes Run generate_toc.py to sync SUMMARY and README files with updated tutorial titles from the restructuring. * Regenerate compatibility tables after title changes --------- Co-authored-by: LinuxDev9002 <i@littlefisher.me>
This commit is contained in:
云微
@@ -1,70 +1,104 @@
|
||||
---
|
||||
name: bpf-tutorial-writing-style
|
||||
description: Repository-local prose and bilingual checklist for drafting, rewriting, or reviewing advanced bpf-developer-tutorial README.md and README.zh.md files. Use to match the readable voice of 49-hid and the useful depth of 47-cuda-events while preserving implementation facts, complete source, commands, evidence, caveats, and references.
|
||||
description: Style checklist for English and Chinese bpf-developer-tutorial README files. Use while drafting or reviewing a tutorial so it reads like the established series, preserves technical detail, and presents complete source clearly.
|
||||
---
|
||||
|
||||
# BPF Tutorial Writing Style
|
||||
|
||||
Use this Skill for writing quality only. Use `$write-bpf-production-tutorial` for build, KVM, exact-source checks, and PR steps.
|
||||
Read the complete guidelines first:
|
||||
- [Advanced tutorial guideline](https://github.com/eunomia-bpf/bpf-developer-tutorial/blob/main/scripts/guideline_advance.md) for tutorials 40+
|
||||
- [Basic tutorial guideline](https://github.com/eunomia-bpf/bpf-developer-tutorial/blob/main/scripts/guideline_basic.md) for tutorials 0-39
|
||||
|
||||
Read all three references before drafting or reviewing:
|
||||
Then read the English and Chinese versions of `47-cuda-events`, `48-energy`, and `49-hid` as style references. Learn their teaching rhythm and level of detail without copying their topic or wording.
|
||||
|
||||
1. [Advanced tutorial guidelines](https://github.com/eunomia-bpf/bpf-developer-tutorial/blob/main/.agents/skills/bpf-tutorial-writing-style/references/advanced-tutorial-guidelines.md) contains the complete project-provided requirements and must remain intact.
|
||||
2. [Repository house style](https://github.com/eunomia-bpf/bpf-developer-tutorial/blob/main/.agents/skills/bpf-tutorial-writing-style/references/repository-house-style.md) explains how to learn from existing tutorials without copying their defects.
|
||||
3. [Prose and bilingual checklist](https://github.com/eunomia-bpf/bpf-developer-tutorial/blob/main/.agents/skills/bpf-tutorial-writing-style/references/prose-and-bilingual-checklist.md) carries the relevant eunomia.dev writing discipline into this repository.
|
||||
## Document Structure (strictly follow guideline)
|
||||
|
||||
Also read the English and Chinese versions of `47-cuda-events` and `49-hid` in full. Existing lessons are examples of rhythm, depth, and teaching order, not templates. Verified code, real output, primary sources, and the user's requirements remain authoritative.
|
||||
For advanced tutorials (40+), follow this exact section order:
|
||||
|
||||
## Write for a reader
|
||||
1. **Title**: `# eBPF 教程：[Topic Description]` or `# eBPF Tutorial by Example: [Topic Description]`
|
||||
|
||||
Start with a short, truthful scene the reader can picture. Show one observable problem or useful action, then raise the technical question that the lesson will answer. Keep one example, packet, event, task, device interaction, or failure as the thread through the article, so the opening scene returns naturally when the code and output are explained.
|
||||
2. **Introduction**: Brief intro with a concrete problem scenario. Highlight significance and what readers will learn. Link to complete source once here.
|
||||
|
||||
Treat the scene as a teaching device, not a license to write fiction. Do not invent a named operator, customer, outage, deployment, benchmark, urgency, or result. If the implementation is a bounded lab tool, make the scene a bounded lab situation and let the real mechanism make it interesting.
|
||||
3. **Background / Why This Approach**:
|
||||
- Explain WHY this approach is needed
|
||||
- List traditional/alternative approaches and their limitations (e.g., killing process, firewall rules, user-space tools)
|
||||
- Explain what eBPF/the new kernel feature enables that traditional approaches cannot
|
||||
- State when the feature entered Linux (kernel version + commit if relevant)
|
||||
|
||||
Use oral English, familiar words, and connected sentences. Write natural Chinese independently from the same facts. Chinese punctuation should be restrained: prefer one or two connected sentences that carry one technical thought over a row of short, period-heavy statements. Prefer causal explanation over inventories. A paragraph should tell the reader what happens, why it happens, and what that enables.
|
||||
4. **High-Level Mechanism**:
|
||||
- Explain HOW the eBPF feature/tool works at a high level BEFORE showing code
|
||||
- Describe the overall flow: what happens in kernel, what happens in user space, how they interact
|
||||
- Use diagrams for complex flows with branches, waits, ownership transfers, or 3+ dependent states
|
||||
|
||||
Prefer positive, concrete statements throughout the tutorial. Explain what the hook, program, loader, command, or test does and which scope it covers. Rewrite `not`, `do not`, `cannot`, `will not`, `不要`, `不能`, `不会`, `并非`, and `别` whenever the same fact has an accurate positive form, and remove every double negative. Keep at most one compact boundary paragraph near the end, limited to two sentences, instead of distributing failure, limitation, and safety warnings through the article.
|
||||
5. **Code Implementation**:
|
||||
- First introduce the overall processing logic
|
||||
- Show complete source code for each component (header, BPF program, user-space loader)
|
||||
- After each complete code block, explain the key parts with paragraph style (not bullet lists)
|
||||
- Focus on logic and advanced features, not basic syntax
|
||||
|
||||
Keep the actor close to the action. Start important sentences with a concrete component, use active voice when ownership matters, connect short facts through cause and effect, and give `this`, `it`, `这` and `它` an unmistakable referent. Put the claim before detailed evidence, use verbs instead of abstract noun phrases, and end a sentence on the new fact the reader should remember.
|
||||
6. **Additional Concepts** (if needed): Deeper explanation of specific features, edge cases, or semantics
|
||||
|
||||
Do not write like a paper, specification, PR description, release note, test log, or compliance report. Build and KVM evidence belongs in compilation and execution, where it should support a claim instead of becoming the article's main plot.
|
||||
7. **Compilation and Execution** (AFTER code, not before):
|
||||
- Build commands
|
||||
- Run commands with examples
|
||||
- Expected output with explanation
|
||||
- Environment requirements table (kernel version, config, privileges, architecture)
|
||||
|
||||
## Draw the relationship when prose starts carrying a graph
|
||||
8. **Summary**: Key points, scope boundaries, future extensions
|
||||
|
||||
Use a small technical diagram when the running example crosses at least three dependent states, branches and later rejoins, waits and retries, transfers ownership, or connects one component to several consumers. The diagram should let the reader see a relationship that would otherwise require rereading a paragraph. Keep a simple linear filter, a single hook, or a two-step command in prose.
|
||||
9. **Call to Action**: Repository and website invitation (as blockquote)
|
||||
|
||||
Build diagrams from verified code and tests. Prefer code identifiers and short labels, one clear direction, restrained color, and enough whitespace to read the figure at ordinary README width. Introduce the figure with the concrete packet, event, task, or device interaction already used in the story, then explain the decisive branch or ownership change after the image. A diagram supports the narrative; it does not replace the source walkthrough.
|
||||
10. **References**: Links to kernel commits, upstream selftests, documentation
|
||||
|
||||
Keep the editable DOT, Mermaid, or SVG source beside the rendered PNG. Use descriptive alt text and a canonical absolute GitHub target for the image. A language-neutral figure can serve both README files when code identifiers carry the flow; prose-heavy labels call for matched Chinese and English assets.
|
||||
## Tell one useful story
|
||||
|
||||
## Keep the source readable
|
||||
- Open with a concrete situation that the example can reproduce and the question it answers.
|
||||
- Near the first mention of eBPF, use one natural sentence to say what eBPF is and why it fits this problem.
|
||||
- Introduce the relevant kernel subsystem and new feature when the running example needs them. State when the feature entered Linux and what it enabled.
|
||||
- Follow one packet, event, task, or device interaction through kernel space and user space. Explain what happens, why it happens, and what the next step enables.
|
||||
- Present the whole flow before detailed code. A small diagram helps when the reader must track a branch, wait, retry, ownership transfer, or at least three dependent states.
|
||||
|
||||
Include complete core source exactly as implemented. Teach one component at a time: introduce its role, present its source inline, and immediately explain the important logic before moving on. Do not hide source in `<details>` and do not separate a long source dump from all of its explanation.
|
||||
## Explain the "Why" thoroughly
|
||||
|
||||
Do not simplify code, insert ellipses, or rewrite comments. Present complete source in ordinary Markdown fenced code blocks without HTML synchronization markers, then verify it against the real file.
|
||||
This is critical. The Background section must explain:
|
||||
- What problem you're solving
|
||||
- What traditional approaches exist (killing process, firewall rules, user-space tools like `ss --kill`, sampling, etc.)
|
||||
- Why each traditional approach doesn't work well (race conditions, incomplete coverage, performance overhead, etc.)
|
||||
- What the eBPF approach enables that wasn't possible before
|
||||
|
||||
Place one complete-source callout near the opening and link only the lesson's GitHub directory. Let the directory serve as the entry point for source, build files, fixtures, and tests, while later component sections name individual files beside their complete code blocks.
|
||||
Example pattern for the "Why" section:
|
||||
> **杀掉进程**是最直接的想法，但一个进程往往维护着多条连接，杀进程会中断所有业务流量。
|
||||
> **防火墙规则**可以阻止新连接，但对已建立的连接无能为力。
|
||||
> **用户态工具**如 `ss --kill` 依赖 `/proc/net/tcp` 遍历和注入 RST 报文，但这种方式有竞态问题。
|
||||
> **内核态方案**才能真正解决这个问题。BPF 迭代器可以在持有适当锁的情况下遍历内核的套接字表...
|
||||
|
||||
Use canonical GitHub absolute URLs for every other Markdown link, even when the target belongs to the current lesson. Never use `./`, `../`, or another host. If no stable GitHub URL exists, leave the text unlinked. This rule overrides link patterns in older lessons and the website call to action in the advanced guidelines.
|
||||
## Sound like a tutorial
|
||||
|
||||
Keep local infrastructure private. Do not name workspace paths, shared lab repositories, VM instances, copy routes, caches, or agent trace locations in a tutorial or PR description. Retain only public reproducibility facts such as architecture, kernel version and commit, configuration, commands, and captured output.
|
||||
- Use familiar words, direct verbs, and connected paragraphs. Attraction comes from the problem and mechanism rather than promotional language.
|
||||
- Prefer positive descriptions of what the example does. Put remaining limits and safety boundaries in one short paragraph near the end.
|
||||
- Use prose for the main explanation and lists for genuinely parallel items.
|
||||
- Keep each paragraph focused on one job. Connect facts through cause, sequence, or contrast instead of listing them like a specification.
|
||||
- Write Chinese naturally from the same facts instead of translating English sentence by sentence. Use restrained punctuation and spaces between Chinese text and Latin letters or numbers.
|
||||
- Keep technical names, code identifiers, commands, numbers, output, versions, and references exact.
|
||||
|
||||
## Keep scope honest
|
||||
Use this Chinese paragraph only as a voice reference for connected rhythm, restrained symbols, and technical density:
|
||||
|
||||
Describe what the implementation actually provides. A bounded lab command is a bounded lab command. Do not inflate it into a daemon, controller, production scheduler, security product, or operational platform.
|
||||
> libbpf 是一个 C/C++ 的 eBPF 用户态加载和控制库，随着内核一起分发，几乎已经成为 eBPF 用户态事实上的 API 标准，libbpf 也支持 CO-RE(Compile Once – Run Everywhere) 的解决方案，即预编译的 bpf 代码可以在不同内核版本上正常工作，而无需为每个特定内核重新编译。
|
||||
|
||||
State requirements and explain cleanup through the normal lifecycle. Collect failure conditions, limitations, and safety boundaries into one compact paragraph of at most two sentences near the end. Move low-level kernel provenance into a compact requirements or reproducibility note.
|
||||
## Teach from complete source
|
||||
|
||||
## Final reader check
|
||||
- Introduce one component, show its complete source in an ordinary Markdown fence, then explain the important logic before moving to the next component.
|
||||
- Keep source byte-exact. Preserve comments and commands; use focused excerpts only after the complete block.
|
||||
- Use neither `<details>` nor HTML synchronization markers.
|
||||
- Link to the complete lesson once through its GitHub directory. Avoid an opening catalog of individual files.
|
||||
- Every Markdown link uses an absolute `https://github.com/...` target. Omit a link when no stable GitHub target exists.
|
||||
- Public prose contains no local path, shared test repository, VM name, copy route, cache, prompt, model, agent, or trace detail.
|
||||
|
||||
Read the finished lesson in order once. The reader should be able to answer:
|
||||
## Finish the lesson
|
||||
|
||||
- What concrete problem does this lesson solve?
|
||||
- How does one packet or event move through kernel and user space?
|
||||
- Which eBPF mechanism makes that possible?
|
||||
- Which code deserves close attention?
|
||||
- How do I build, run, and recognize success?
|
||||
- What does the captured output prove?
|
||||
- Where does the example stop?
|
||||
- Show copyable build and run commands, representative real output, and what that output proves.
|
||||
- State kernel, configuration, privilege, architecture, and hardware requirements that affect the example (use a table).
|
||||
- End with a compact scope boundary, summary, repository invitation, and primary references.
|
||||
- Keep the English and Chinese files aligned on structure, facts, source, commands, output, limits, and references while allowing each language to sound natural.
|
||||
|
||||
Revise if the reader instead encounters a code wall, repeated disclaimers, a validation transcript, dense spec-sheet paragraphs, literal Chinese translation, or a scenario larger than the tool. This reader check is a judgment pass, not a reason to add reviewers or models.
|
||||
The final read should answer: what problem is solved, how one event moves through the system, which eBPF mechanism makes it possible, which code matters, how to run it, what success looks like, and where the example stops.
|
||||
|
||||
@@ -1,80 +0,0 @@
|
||||
# Blog Guidelines for Advanced eBPF Tutorials
|
||||
|
||||
This document outlines the key patterns and requirements for writing advanced eBPF tutorials. Advanced tutorials focus on complex eBPF programs, tools, or features that extend beyond basic concepts. They require a deeper understanding of eBPF and kernel interactions.
|
||||
|
||||
The audience for advanced tutorials includes developers, system administrators, and security professionals with intermediate to advanced eBPF knowledge. The goal is to provide in-depth explanations of advanced eBPF topics and practical examples that readers can apply in real-world scenarios.
|
||||
|
||||
The key point in tone: Using oral English, clear and simple words and short sentence, make it attractive and easy to read, do not make it like a paper. Not too much fancy words, try to be attracive.
|
||||
|
||||
You should also include all the details and information I provide to you. do not simplify or change any of them, you just need to regorganize them in a more attractive way as a tutorial blog.
|
||||
|
||||
## starting with a clear and descriptive title
|
||||
|
||||
Begin with a clear and descriptive title:
|
||||
|
||||
```
|
||||
# eBPF Tutorial by Example: [Advanced Topic]
|
||||
```
|
||||
|
||||
Kick off with a brief intro to the advanced eBPF topic you're covering, and the example or tool you'll discuss. Highlight its significance and how it extends beyond basic concepts. Let readers know what they'll learn and why it's important.
|
||||
|
||||
## Incroduction to the concept, tool and Background
|
||||
|
||||
(Come up with a better session title)
|
||||
|
||||
Provide an overview of the specific eBPF programs, tools, or features you'll discuss. Explain their purpose, use cases, and the key eBPF features or kernel events involved. Focus on aspects that are crucial for advanced understanding.
|
||||
|
||||
## High-Level Code Analysis
|
||||
|
||||
Dive into the kernel-mode eBPF code and user-space code, focusing on high-level concepts rather than basic syntax.
|
||||
|
||||
Always include the full code as it is first. then break down the key parts.
|
||||
|
||||
Try to avoid using too much list, make it more like a story.
|
||||
|
||||
Follow the steps:
|
||||
|
||||
1. First, introduce The overall processing logic in both kernel and user space.
|
||||
2. Then break down the kernel-mode eBPF code, include
|
||||
|
||||
- How the eBPF program is structured.
|
||||
- Key eBPF functionalities utilized.
|
||||
- How the code interacts with kernel events.
|
||||
|
||||
Do not make them a list, make them some paragraphs, you can also quote some code snippets to explain the key parts of the code if needed, focus on the logic and features used in advanced eBPF development. Don't make it too long, but make sure it is informative enough and you explain everything a advanced eBPF developer wants to know.
|
||||
|
||||
3. Then briefly explain the user-space code
|
||||
|
||||
Aim to help readers grasp how the code works without getting bogged down in basic details.
|
||||
|
||||
## Any more detailed concepts or features explanation
|
||||
|
||||
If there are other information or features that are important to understand the code, you can add them here.
|
||||
|
||||
## 5. Compilation and Execution
|
||||
|
||||
Provide instructions on compiling and running the eBPF programs, noting any advanced configurations or dependencies. Include commands and what readers should expect as output. Typically, you can run `make` in the relevant directory in the tutorial repository to build the code.
|
||||
|
||||
Include links to complete source code and resources:
|
||||
|
||||
- **Repository:** <https://github.com/eunomia-bpf/bpf-developer-tutorial>
|
||||
|
||||
## 6. Summary and Call to Action
|
||||
|
||||
Wrap up by summarizing the key points. Emphasize the advanced concepts covered and encourage readers to apply this knowledge. Invite them to explore more examples and tutorials, as one paragraph:
|
||||
|
||||
> If you'd like to dive deeper into eBPF, check out our tutorial repository at <https://github.com/eunomia-bpf/bpf-developer-tutorial>.
|
||||
|
||||
## reference
|
||||
|
||||
You should include the important references and resources that used in the tutorial. If this is from other sources like kernel sample or tools, make sure to include them here and clearly mention them in the tutorial.
|
||||
|
||||
## Additional Guidelines
|
||||
|
||||
- **Clarity:** Use simple language and short sentences to explain complex ideas. But the information should be complete and detailed.
|
||||
- **Focus on Advanced Concepts:** Assume readers have basic eBPF knowledge; skip elementary explanations.
|
||||
- **Engagement:** Encourage readers to think critically and engage with the material.
|
||||
- **Consistency:** Keep a consistent style and formatting throughout.
|
||||
- **Code Formatting:** Ensure code snippets are well-formatted and highlight key parts. Do not change or simplify any of the code and commands, keep them as they are.
|
||||
- **Proofreading:** Double-check for errors and ensure technical accuracy.
|
||||
- **Accessibility:** Make the content valuable for readers with advanced expertise, avoiding unnecessary simplifications.
|
||||
@@ -1,119 +0,0 @@
|
||||
# Prose and bilingual checklist
|
||||
|
||||
This checklist carries the relevant eunomia.dev writing discipline into advanced eBPF tutorials. It is self-contained and does not depend on a global or external Skill.
|
||||
|
||||
Use it as a reader-focused editing guide, not as a reason to add review rounds. Technical fidelity is mandatory. Numeric paragraph ranges and stylistic labels are diagnostic signals that still require judgment.
|
||||
|
||||
## Fidelity is the first gate
|
||||
|
||||
- **Must fix:** Any code, command, captured output, number, version, requirement, limitation, negative result, cleanup behavior, reference, or scope-bearing qualifier from the supplied material is missing or changed.
|
||||
- Preserve technical names and project names. Do not replace them with vague pronouns across paragraphs.
|
||||
- Treat numbers as claims. State what was measured, under which conditions, and what the result does or does not prove.
|
||||
- Avoid absolute words such as “always,” “never,” “cannot,” and “impossible” unless the implementation or a primary source proves the boundary.
|
||||
- Do not invent output, benchmark numbers, PIDs, paths, errors, production uses, or performance conclusions.
|
||||
- Reorganize for teaching, but do not simplify away technical information. During a rewrite, compare the final text against the entry version from the end backwards and account for every removed paragraph.
|
||||
- Preserving a fact does not require repeating it. Put each requirement, failure behavior, cleanup rule, and limitation at the one point where it helps the reader most.
|
||||
|
||||
## Voice and argument
|
||||
|
||||
- Use oral, direct English with familiar words and short connected sentences. Write as an experienced developer explaining a working tool, not as a paper, merge report, release note, or test log.
|
||||
- Open with a short, truthful story or concrete scenario that the implementation can reproduce. Show an observable symptom, action, packet, event, task, device interaction, or failure, then raise the technical question instead of answering everything in the first paragraph.
|
||||
- Carry the same concrete thread into the mechanism, code, and output sections. The opening should pay off when the reader sees where the event goes and how the result is produced.
|
||||
- Do not fabricate a persona, customer, production incident, deployment, benchmark, urgency, or result. Avoid “In this tutorial, we will explore,” generic eBPF history, product promotion, and an abstract-style contribution list.
|
||||
- Let each section answer the question raised by the previous one. A useful progression is problem, background, whole-system flow, complete code, focused walkthrough, deeper concept, compilation and execution, limits, summary, and references.
|
||||
- Give each paragraph one primary job. If a paragraph establishes context, explains a mechanism, reports evidence, and states a limitation at once, split it.
|
||||
- Prefer active voice and concrete actors. Name the hook, BPF program, map, callback, loader, fixture, command, or kernel rather than using “it,” “this,” “the approach,” or “the result.”
|
||||
- Replace spec-sheet prose with causal explanation. If three neighboring sentences can be reordered without changing the paragraph, connect each fact to what it enables or why it matters.
|
||||
- Avoid fancy or promotional words, clickbait, exclamation marks, vague superlatives, hollow calls to action, and self-praise. Attraction should come from a concrete problem and a mechanism the reader can reuse.
|
||||
- Do not overuse lists. Use prose for the implementation story and lists only when parallel items become easier to scan.
|
||||
- Do not let provenance become the plot. Kernel commits, guest versions, CI details, and test matrices belong in a compact reproducibility note unless the lesson is specifically about them.
|
||||
- Match the scenario to the tool. A small fixture, lab command, or feature demonstration can be valuable without being described as a production service.
|
||||
|
||||
## Diagram decision and presentation
|
||||
|
||||
- Add a diagram when it makes a real relationship visible: three or more dependent state changes, a branch/retry loop, ownership transfer, or one component feeding several later actions.
|
||||
- Keep a simple linear filter, single attach point, or two-step command in prose. The figure count follows teaching value rather than article length.
|
||||
- Derive every node, edge, label, and branch from implementation or test evidence. A diagram carries technical claims and receives the same fidelity review as prose.
|
||||
- Prefer a reviewable DOT, Mermaid, or SVG source and commit it beside the rendered PNG. Use deterministic rendering so another agent can reproduce the asset after a code change.
|
||||
- Use short labels, code identifiers, one dominant reading direction, restrained color, and text that remains legible at README width.
|
||||
- Introduce the packet, event, task, or device interaction before the figure. Explain the important branch, retry, or ownership change immediately after it.
|
||||
- Use descriptive alt text and a canonical absolute GitHub image target. Keep both README files aligned on the same figure and conclusion; use paired assets when language-specific labels materially help readers.
|
||||
- Update the diagram in the same change whenever implementation or prose changes its state sequence, ownership, branch condition, or cleanup path.
|
||||
|
||||
## Positive and concrete sentences
|
||||
|
||||
- Use a positive statement of behavior or scope. Write “The loader observes one child that it creates” instead of “The loader does not monitor every exec on the system.” Write “The example implements one aggregate FIFO” instead of opening with the scheduler policies it lacks.
|
||||
- Rewrite `not`, `do not`, `does not`, `cannot`, `will not`, `不要`, `不能`, `不会`, `并非` and `别` whenever an accurate positive form exists. Remove double negatives and paragraphs built from consecutive negative sentences.
|
||||
- Keep the supported scope exact while using positive wording. “The example focuses on one child” describes the implemented behavior without implying that system-wide monitoring already exists.
|
||||
- Collect failure conditions, unsupported behavior, limitations, and safety boundaries near the end in one paragraph of at most two sentences. The main narrative should stay with the working path.
|
||||
- Start important sentences with a concrete actor such as the hook, BPF program, map, callback, loader, fixture, kernel, or command. Keep that subject close to its verb and prefer active voice when ownership or sequencing matters.
|
||||
- Connect three or more short declarative sentences through cause, contrast, or sequence. A pair of short sentences can create emphasis, while a longer note-like run should become a causal paragraph.
|
||||
- Give vague referents a name. Replace an unclear `this`, `it`, `they`, `这`, `它` or `这种方式` with the component or mechanism it denotes.
|
||||
- Put the claim or practical meaning before a block of numbers, counters, or output. The reader should know what the evidence demonstrates before reading the evidence.
|
||||
- Prefer direct verbs over nominalizations and filler. Use “the callback reads,” “the loader attaches,” and “the test verifies” instead of “performs a read,” “conducts attachment,” or “provides verification.”
|
||||
- Place known context near the sentence opening and the new result near the end. This topic-to-stress order helps adjacent sentences form one path instead of a fact catalog.
|
||||
|
||||
Treat this wording as a negative example:
|
||||
|
||||
> 这个例子故意只做聚合 FIFO，没有 class、公平调度、ECN、burst 控制。用它做实验可以，但别往物理网卡上挂，也别当生产调度器。
|
||||
|
||||
The paragraph defines the example through missing features and repeated warnings, so the useful mechanism disappears behind negation. Rewrite it around the implemented path and a concrete learning setting:
|
||||
|
||||
> 这个例子用一条聚合 FIFO 展示 skb 所有权、发送时序和 qdisc 清理，适合在 veth、TAP 或 IFB 这类受控接口上观察完整流程，更完整的调度器可以在此基础上加入 class、公平调度、ECN 和 burst 控制。
|
||||
|
||||
Apply the same repair in English. Replace a paragraph built from “no classes,” “not production,” and “do not attach” with the mechanism the reader can run, the controlled setting that fits it, and the natural extensions that follow.
|
||||
|
||||
## Paragraph and sentence checks
|
||||
|
||||
- English paragraphs usually work best at 40–90 words. Inspect every paragraph above 110 words. Three consecutive paragraphs above 90 words are **Must fix**.
|
||||
- Chinese paragraphs usually work best at 120–260 Chinese characters. Inspect every paragraph above 320 characters. Three consecutive paragraphs above 260 characters are **Must fix**.
|
||||
- The ranges are diagnostic tripwires, not quotas. Short transitions and longer indivisible mechanism explanations are allowed.
|
||||
- Keep a sentence's subject near its verb. Split long modifiers, dangling introductions, and sentences that make the reader hold several clauses before reaching the action.
|
||||
- Avoid weak openings such as “It is,” “There is,” and “This is” when a concrete subject is available.
|
||||
- Do not stack three or more short note-like sentences. Connect cause, mechanism, and consequence.
|
||||
- Avoid a pair of neighboring negative sentences when positive wording can carry the same facts. Reserve the compact final boundary paragraph for the remaining limits.
|
||||
- Cut filler such as “in order to,” “utilize,” “it is important to note that,” “due to the fact that,” “in terms of,” and “with respect to.” Prefer direct verbs.
|
||||
- Do not use spaced English em dashes (` — `) or Chinese em dashes (`——`) in prose.
|
||||
- Do not join independent clauses with semicolons. Use two sentences or a conjunction.
|
||||
- Use colons only to introduce a list, code block, or table. Rewrite claim-colon-evidence and Chinese noun-phrase-colon openings as sentences.
|
||||
|
||||
## Code and evidence presentation
|
||||
|
||||
- Present full core source exactly as it exists before excerpting it again for explanation. Use ordinary Markdown fenced code blocks with no HTML markers, then require the workflow Skill's read-only `--check` mode to pass against the complete source inventory. Never silently shorten functions, replace blocks with ellipses, translate comments, or “clean up” commands.
|
||||
- Teach one component at a time. Introduce the file's role, present its complete source inline, and immediately explain the parts that matter before starting the next component.
|
||||
- Never hide source in `<details>` and never place several complete files in one uninterrupted dump followed by a distant walkthrough. Long examples need stronger component boundaries and local explanations, not collapsed code.
|
||||
- Explain what advanced developers need to know: program type, attach point, context restrictions, helper or kfunc semantics, map ownership, state lifetime, concurrency, verifier constraints, event/control path, error handling, and cleanup.
|
||||
- Keep build and run commands copyable. Explain prerequisites before the command and interpret real output after it.
|
||||
- Label volatile fields and distinguish demonstrations, functional tests, and benchmarks.
|
||||
- Use one opening complete-source callout that links only to the lesson directory. Treat that directory as the entry point for implementation, build files, fixtures, and tests; name individual files as code labels next to their complete source blocks instead of listing file links in the opening.
|
||||
- Use canonical GitHub absolute URLs for every Markdown link, including links to the current lesson. Reject every `./`, `../`, or non-GitHub target. If no stable GitHub URL exists, do not add a link. This repository rule overrides link examples in precedents and the advanced guideline's website call to action.
|
||||
- Keep local infrastructure and agent state private. Never publish workspace paths, shared lab repository or VM names, host-to-guest copy routes, cache locations, prompt stores, or trace paths. Public reproducibility may include architecture, kernel version and commit, configuration, commands, and captured output.
|
||||
|
||||
## Natural Chinese
|
||||
|
||||
- Compose Chinese from the facts and paragraph role, not from English sentence order. The two languages may use different sentence and paragraph boundaries.
|
||||
- Keep punctuation restrained. When several clauses explain one subject, mechanism, or consequence, connect them naturally with commas instead of turning each clause into a separate short sentence. Prefer one or two complete sentences per ordinary paragraph; do not create a choppy sequence of periods.
|
||||
- Do not imitate “short English sentences” mechanically in Chinese. A cohesive Chinese sentence may carry the concept, mechanism, compatibility boundary, and motivation together when they belong to one thought.
|
||||
- Still split a sentence when its subject drifts, the causal relation becomes unclear, or the reader must hold unrelated facts at once. Fewer periods are a voice preference, not permission for an unreadable run-on sentence.
|
||||
- Translate ordinary concept nouns consistently. Keep proper nouns, product names, code, commands, file names, function names, and genuine terms of art in English.
|
||||
- Do not begin a Chinese prose sentence with an English common noun. Avoid English clause splicing and glossary-style prose where every other concept stays in English.
|
||||
- Use full-width Chinese punctuation. Put a half-width space between CJK text and Latin letters or digits, such as “64 个事件” and “eBPF 程序.”
|
||||
- Write table headings in Chinese. Translate ordinary prose inside comments only when the code block is illustrative; when the block claims to be complete source, preserve it byte-for-byte in both languages.
|
||||
- Read every Chinese paragraph aloud. Rewrite literal translations, English word order, and stiff phrases that a developer would not use in conversation.
|
||||
|
||||
Use this paragraph as a compact Chinese voice reference. Learn its connected rhythm, restrained symbols, technical density, and direct statement of motivation; do not copy its subject matter into unrelated lessons:
|
||||
|
||||
> libbpf 是一个 C/C++ 的 eBPF 用户态加载和控制库，随着内核一起分发，几乎已经成为 eBPF 用户态事实上的 API 标准，libbpf 也支持 CO-RE(Compile Once – Run Everywhere) 的解决方案，即预编译的 bpf 代码可以在不同内核版本上正常工作，而无需为每个特定内核重新编译。我们希望尽可能的保持与 libbpf 的用户态 API 以及行为一致，尽可能减少应用迁移到 Wasm （如果需要的话）的成本。
|
||||
|
||||
The sample is not a factual source. Do not copy `libbpf`, CO-RE, Wasm, API claims, compatibility claims, or any other technical content from it unless the lesson's fact pack independently requires that content. Leakage from the sample into an unrelated lesson is a **Must fix** failure.
|
||||
|
||||
## Bilingual consistency
|
||||
|
||||
- Keep the same macro structure, examples, complete code payload, commands, output, claims, numbers, caveats, limitations, summary, and references in both files.
|
||||
- Corresponding headings should promise the same content, but they do not need literal translations.
|
||||
- A near-perfect line-for-line prose translation is a review smell. Confirm that each language reads naturally even when that changes sentence or paragraph boundaries.
|
||||
- When one version changes a fact, example, figure, command, code block, output, or limitation, update the other in the same pass.
|
||||
|
||||
## Final reader check
|
||||
|
||||
After reading in order, an intermediate or advanced eBPF developer should be able to explain the real problem, the kernel/user-space flow, why the advanced capability is needed, how the core code works, how to build and run it, what the captured output proves, and where the example stops. If the reader remembers only a feature name, a code wall, repeated caveats, or a validation transcript, revise the narrative.
|
||||
@@ -1,48 +0,0 @@
|
||||
# Repository house style
|
||||
|
||||
New advanced lessons should feel at home beside `src/47-cuda-events/` and `src/49-hid/`. Read both English/Chinese README pairs in full. Use `47-cuda-events` as a depth reference for an end-to-end tool and `49-hid` as the stronger reference for voice, pacing, and teaching through a concrete device problem.
|
||||
|
||||
These lessons are precedents, not perfect templates. Do not copy their unsupported claims, stale version language, inconsistent punctuation, or unnecessary feature catalogs. Verified implementation facts and current project rules win whenever a precedent differs.
|
||||
|
||||
Read at most one additional completed bilingual lesson when it offers a closer subsystem pattern. For networking, good candidates include `20-tc`, `41-xdp-tcpdump`, `42-xdp-loadbalancer`, and `50-tcx`. Choose by teaching need, not by directory number.
|
||||
|
||||
## Build one continuous story
|
||||
|
||||
Open with a concrete situation the reader can picture. Name the small tool or example and the useful result, but do not preview every version, counter, failure case, and test in the opening.
|
||||
|
||||
Give enough background to explain why the hook or kernel subsystem matters. Then introduce the whole kernel/user-space path before individual functions. Keep returning to the same packet, event, device, or failure so adjacent sections feel causally connected.
|
||||
|
||||
Present complete core source exactly as required by the advanced tutorial guidelines, but organize it by component. Introduce one file, show it inline, explain its important behavior, and only then move to the next file. Never hide source in `<details>` and never make readers cross several complete files before reaching the explanation.
|
||||
|
||||
After the source, explain the BPF structure, attach point, state and ownership, relevant helpers or kfuncs, kernel interaction, user-space lifecycle, error handling, and cleanup. Spend words on advanced constraints and surprising behavior. Do not explain ordinary C syntax.
|
||||
|
||||
Compilation and execution should show copyable commands, representative real output, and what that output means. Put public kernel provenance, commit IDs, and compatibility data in a compact requirements or reproducibility paragraph. Do not name local workspaces, shared lab repositories, VM instances, copy routes, caches, agent traces, or the PR's validation history.
|
||||
|
||||
End with an honest boundary, a short summary, the required invitation, and primary references.
|
||||
|
||||
## Lessons from the 53-egress-pacer rewrite
|
||||
|
||||
The first `53-egress-pacer` draft was technically accurate but still failed as a tutorial. It:
|
||||
|
||||
- packed the scenario, kernel version, algorithm, counters, conflict behavior, and test result into the opening;
|
||||
- gave the reader only a few setup paragraphs before several hundred lines of source;
|
||||
- repeated the same conflict, signal, cleanup, KVM, or safety caveat in the introduction, implementation, run section, and limitations;
|
||||
- read like an artifact report because validation details received more emphasis than the mechanism;
|
||||
- called a fixed-duration lab demo a production or operational tool without matching CLI capabilities;
|
||||
- wrote Chinese by following English sentence order.
|
||||
|
||||
The rewrite kept all four complete source files, commands, output, versions, failure paths, and limits. It replaced the invented production story with an honest lab scope and followed one skb through ownership and timing. Reader review then exposed a structural problem: collecting the files before their explanations made the tutorial read like a design document. The corrected method places each complete file beside its component explanation, as tutorials 47 and 49 do.
|
||||
|
||||
Reuse the corrected method, not exact section counts. Shrink overloaded openings, give the reader one useful mental model, and alternate complete component source with nearby explanation. Keep each technical fact, but place it once where the reader is ready for it.
|
||||
|
||||
## Preserve modern correctness
|
||||
|
||||
- Use captured output and identify fields that vary across runs.
|
||||
- Source version, performance, deployment, adoption, and upstream-history claims.
|
||||
- State the minimum kernel, config, privilege, architecture, and hardware requirements.
|
||||
- Explain at least one meaningful failure or boundary path and relevant cleanup.
|
||||
- Distinguish a functional KVM run from a benchmark.
|
||||
- Avoid unsupported claims such as “production-ready,” “safe,” “negligible,” or “complete visibility.”
|
||||
- Keep Markdown consistent. Use full-width Chinese punctuation and spaces between CJK text and Latin letters or digits.
|
||||
|
||||
English and Chinese must share the same promise, section progression, source, commands, output, facts, caveats, summary, and references. Natural expression matters more than sentence-for-sentence symmetry.
|
||||
Reference in New Issue
Block a user