K3 review

.github/doc-review-agent/config.yml

@@ -38,6 +38,8 @@ checks:
     enabled: true
     # Flag if the paired file in the other language is missing
     flag_missing_pair: true
+    # Remind author to update the counterpart when only one language file is modified
+    flag_sync_reminder: true
     # Flag if heading count differs by more than this threshold
     heading_count_tolerance: 2
 
@@ -52,12 +54,56 @@ checks:
     # Enforce Chinese punctuation in zh/ files
     chinese_punctuation_in_zh: true
 
+  # ─── Professional technical-writer checks ──────────────────────────────
+  technical_writing:
+
+    # Flag runs of more than 2 consecutive blank lines
+    consecutive_blank_lines:
+      enabled: true
+
+    # Flag lines with single trailing whitespace
+    trailing_whitespace:
+      enabled: true
+
+    # Validate Markdown table structure (separator row + consistent columns)
+    table_structure:
+      enabled: true
+
+    # Enforce correct product name casing: K1, K3, P1, P1S
+    product_name_casing:
+      enabled: true
+
+    # Flag bare numeric values in unit-bearing contexts (voltage, frequency, etc.)
+    missing_units:
+      enabled: true
+
+    # Flag first-person pronouns (I, me, my, we, us) in formal en/ docs — Warning level
+    first_person:
+      enabled: true
+
+    # Passive voice is natural in academic technical EN — disabled
+    passive_voice:
+      enabled: false
+
+    # Flag non-standard admonition keywords (only NOTE/WARNING/CAUTION/TIP/IMPORTANT)
+    admonition_keywords:
+      enabled: true
+
 # ─── Severity overrides ───────────────────────────────────────────────────────
 # Default severities are defined in the agent. Override here if needed.
 severity_overrides:
   missing_pair_file: "warning"      # missing bilingual pair → warning, not error
   tbd_in_content: "warning"
   missing_code_block_lang: "suggestion"
+  consecutive_blank_lines: "suggestion"
+  trailing_whitespace: "suggestion"
+  table_structure_missing_separator: "error"
+  table_structure_inconsistent_columns: "warning"
+  product_name_casing: "warning"
+  missing_units: "suggestion"
+  first_person: "warning"
+  passive_voice: "suggestion"   # disabled above; severity kept for reference
+  admonition_keywords: "suggestion"
 
 # ─── Output ───────────────────────────────────────────────────────────────────
 output:

.github/doc-review-agent/system_prompt.md

@@ -101,18 +101,31 @@ You are a professional technical documentation reviewer for a semiconductor comp
 
 ### 3. Bilingual Consistency (cross-file check)
 - The corresponding file in the other language (`en/` ↔ `zh/`) exists.
+- If a file is modified in this PR but its language counterpart is **not** in the PR, post a `[Warning]` reminding the author to update the paired file so both versions stay in sync.
 - Section count (number of `##` headings) matches between language versions.
 - Product names and model numbers are consistent: K1, K3, P1, P1S (not k1, K-1, etc.).
 
 ### 4. Technical Content
-- Numerical values include units (V, mA, MHz, °C, etc.).
-- Tables have headers and consistent column counts.
-- Code blocks specify a language identifier (e.g., ` ```bash `, ` ```c `).
+- Numerical values include units (V, mA, MHz, °C, etc.). Flag bare numbers in sentences that mention voltage, current, frequency, temperature, power, or timing.
+- Tables have a separator row (`| --- |`) and consistent column counts across all rows.
+- Code blocks specify a language identifier (e.g., ` ```bash `, ` ```c `, ` ```python `).
+- Product names use correct casing: **K1**, **K3**, **P1**, **P1S** — never `k1`, `K-1`, `p1s`, etc.
 
 ### 5. Style
-- No "TBD", "TODO", or "FIXME" in content intended for publication.
-- No consecutive blank lines (more than 2).
-- Chinese punctuation used in `zh/` files (，。；：""instead of , . ; : "").
+- No “TBD”, “TODO”, or “FIXME” in content intended for publication.
+- No more than 1 consecutive blank line between paragraphs.
+- Chinese punctuation used in `zh/` files (，。；：“” instead of , . ; : "").
+- No trailing whitespace on any line.
+- No first-person pronouns (`I`, `me`, `my`, `we`, `us`) in formal technical documentation. Use imperative mood ("Configure the…") or a subject-neutral third-person construction ("The user should…"). This is a **Warning**-level issue.
+- Passive voice is acceptable and encouraged where it improves clarity or objectivity (e.g., "The register is reset to 0x00 on power-up"). Do **not** flag passive constructions.
+- Admonition blocks must use standard keywords only:
+  - English: `NOTE`, `WARNING`, `CAUTION`, `TIP`, `IMPORTANT`
+  - Chinese: `注意`、`警告`、`提示`、`重要`、`危险`
+
+### 6. Chinese-specific Rules
+- Keep English technical terms untranslated and in their canonical form: SoC, PCIe, DDR4, LPDDR4X, GPIO, UART, I²C, SPI, EVB, BOM, SDK, API.
+- Units always use the international symbol in both languages: V, mA, MHz, GHz, °C — never “伏特”, “毫安”, etc.
+- Numbers in body text follow the pattern: Arabic numerals + unit (e.g., `1.8 V`, `400 MHz`) — no mixing of Chinese numerals (一二三) with units.
 
 ---
 

.github/workflows/doc-review.yml

@@ -8,7 +8,7 @@ on:
       - "zh/**/*.md"
 
 permissions:
-  pull-requests: write   # post review comments
+  pull-requests: write   # post review comments and update PR description
   contents: read
 
 jobs:

en/key_stone/k1/k1_docs/k1_usermanual/15.High-Speed_Interface_System.md

@@ -273,7 +273,7 @@ The architecture of the USB port set is depicted below, where
 | --- | --- | --- | --- | --- |
 | 31:0 | pumon_monitor_ro[63:32] | RO | 0x0 | Debug signal from PUPHY |
 
-#### 17.1.4.15 P_ADDR_RO4 REGISTER
+#### 15.1.4.15 P_ADDR_RO4 REGISTER
 
 **Offset: 0x48**
 
@@ -444,15 +444,15 @@ The architecture of the USB port set is depicted below, where
 | 1 | sof_toggle_out | RO | 0x0 | sof_toggle_out signal |
 | 0 | interrupt | RO | 0x0 | interrupt signal |
 
-## 16.2 PCIe
+## 15.2 PCIe
 
-### 16.2.1 Introduction
+### 15.2.1 Introduction
 
 K1 implements three PCIe Dual-Mode ports which can be configured as either Root Complex (RC) or Endpoint (EP) device.
 
 All ports support Gen2 with a data transfer speed of 5GT/s per lane. However, one port supports one lane only and two ports support two lanes each.
 
-### 16.2.2 Features
+### 15.2.2 Features
 
 - Support for Dual-Mode, programmable as either Complex (RC) or Endpoint (EP) device
 - Support for all non-optional features of the PCI Express Base Specification - Revision 5.0 - Version 1.0 (limited to Gen2 speed scope)
@@ -473,7 +473,7 @@ All ports support Gen2 with a data transfer speed of 5GT/s per lane. However, on
 - Support for MSI Capability in EP Mode
 - Support for Integrated MSI Reception Module in RC Mode
 
-### 16.2.3 Functional Description
+### 15.2.3 Functional Description
 
 The architecture of the PCIe Dual-Mode port set is depicted below.
 
@@ -608,17 +608,17 @@ The embedded DMA controller (EDMA) offloads data transfer tasks from the CPU and
     - Fetches the channel context (transfer control information)
     - Executes transfers based on the DMA elements programmed in local memory
 
-## 16.3 EMAC
+## 15.3 EMAC
 
-### 16.3.1 Introduction
+### 15.3.1 Introduction
 
 K1 features a EMAC core which includes the essential protocol requirements for the operation of 10/100/1000 Mbps Ethernet/IEEE 802.3-2012 compliant node.
 
 On the system side, the EMAC core features a 64-bit AXI Master Interface and a 32-bit AXI Target (Slave) Interface for seamless integration with the AXI Bus.
 
 The EMAC core can operate at 10 Mbps, 100 Mbps (Fast Ethernet) or 1000 Mbps (Gigabit Ethernet). Additionally, it includes a powerful 64-bit Scatter-Gather DMA to transfer packets between HOST Memory and Internal FIFOs to achieve high performance.
 
-### 16.3.2 Features
+### 15.3.2 Features
 
 - Capability of handling transmit/receive data encapsulation functions, including Framing (frame boundary delimitation, frame synchronization) and Error Detection (physical medium transmission errors)
 - Media access management with medium allocation (collision avoidance) and contention resolution (collision handling) in Half-Duplex Mode of operation at speeds of 10/100 Mbps
@@ -629,7 +629,7 @@ The EMAC core can operate at 10 Mbps, 100 Mbps (Fast Ethernet) or 1000 Mbps (Gig
 - Bus mastering on the AXI interface to transfer packets between the HOST memory and the internal FIFOs using 64-bit transfer mode
 - Automatic transfer of packets between the HOST memory and internal FIFOs (based on descriptors) to minimize CPU overhead
 
-### 16.3.3 Block Diagram
+### 15.3.3 Block Diagram
 
 The micro-architecture of EMAC unit is depicted below.
 
@@ -649,7 +649,7 @@ A brief description of each module is provided below.
 - **AXI Master Interface**: This module provides the AXI Master functionality to generate transactions on the AXI Bus. The transactions are generated based on the requests from the Transmit/Receive DMA’s.
 - **AXI Target Interface**: This module provides the AXI Target functionality to the AXI Host (CPU). This interface is used to access all the DMA/MAC registers in the Registers Module.
 
-### 16.3.4 Programming Model
+### 15.3.4 Programming Model
 
 The EMAC Core transfers received data frames/packets from the RMII/RGMII interface to the receive buffers in the host memory. Similarly, it transmits data frames/packets from the transmit buffers in the host memory to the RMII/RGMII interface. Descriptors, which reside in the host memory, act as pointers to these buffers. The receive and transmit FIFOs inside the EMAC Core serve as temporary storage for frame transmission and reception.
 
@@ -665,7 +665,7 @@ Below is depicted the descriptor chain structure. In this configuration, each de
 
 ![](static/Programming_Model_1.png)
 
-### 16.3.5 Register Description
+### 15.3.5 Register Description
 
 The EMAC registers are used to control the operation of the EMAC core and to read status/interrupt information from it. The EMAC core decodes all 16 bits of the AHB/AXI (Slave) target address to access the registers. These registers are 32-bit word-aligned and must be accessed using 32-bit aligned addresses only. Reserved fields should be written as zero, and the EMAC core returns a value of zero in those fields. All registers are set to their default values upon reset.