docs: publish shared porting records and subsystem guides

2026-10-25 02:30:02 +08:00
1 parent 6fed2312dd
commit 6488ad6468
@@ -88,3 +88,12 @@ display, input, and GPU observations separately from host builds.

 Preserve unrelated working-tree changes. Keep documentation concise and describe
 current behavior. Use standard terms, neutral headings, and ordinary punctuation.
+
+## Porting record
+
+Read the device's `porting.toml` and the
+[record guide](https://unixnu.com/porting/records) before implementation.
+For storage, also read the [UFS guide](https://unixnu.com/porting/ufs).
+Update each affected area's findings or evidence with its code change.
+The documentation site renders this same record. Follow its schema and
+completion levels for both maintainer and agent work.
@@ -107,3 +107,11 @@ Report a security issue privately to the maintainers. Do not open a public issue
 ## License

 Contributions are licensed under BSD-2-Clause-Patent. The `LICENSE` file in each directory applies to that directory.
+
+## Official device records
+
+Update the affected areas in the device's `porting.toml` with each code change.
+Use the [record guide](https://unixnu.com/porting/records) for required hardware,
+configuration, findings, evidence and completion criteria. The site renders the
+same record for maintainers and agents. Official device branches require its CI
+check. Board driver submodules belong to device repositories.
@@ -19,8 +19,6 @@

 # UniXNU

-Adreno740 and AdrenoMetal provide GPU acceleration on the Xiaomi Pad 6S Pro (sheng). The render server composites the system UI through the Adreno 740, and listed processes get their own Metal devices. See the [Adreno 740 driver documentation](https://unixnu.com/drivers/adreno740).
-
 An independent project to run iOS and macOS on non-Apple ARM64 hardware through UEFI.

 ## Documentation
@@ -45,10 +43,23 @@ The documentation is at [unixnu.com](https://unixnu.com). Its sources, navigatio
 | [UniXNU-sheng](https://github.com/UniXNU/UniXNU-sheng) | Device repository for the Xiaomi Pad 6S Pro |
 | [uefi-sheng](https://github.com/UniXNU/uefi-sheng) | UEFI firmware port for the Xiaomi Pad 6S Pro |

-Drivers and kits are independent public repositories under the UniXNU organization, included as submodules. Clone with `--recurse-submodules`, or run `git submodule update --init --recursive`.
+The main checkout contains shared drivers and kits. Device repositories own their board driver submodules; sheng supplies ShengUfs and ShengHidInput alongside its touch and preflight components. The catalog describes available components, and the build tools assemble the selected device sources. Clone repositories with `--recurse-submodules`.

 Device repositories select pinned SoC sources, OS profiles, and components. The build tools merge the profiles, resolve dependencies, compile the board DTS, and generate the ADT. Start with [AGENTS.md](AGENTS.md), [the device template](examples/device/README.md), and [the migration guide](https://unixnu.com/porting/migration).

+## Official device development
+
+Every official device maintains `porting.toml` with hardware inputs, configuration,
+procedures, findings, evidence and completion criteria for each subsystem.
+Maintainers and agents use this record. The site renders it from the device
+revision pinned in `devices.toml`.
+
+The required CI check covers the record structure, component dependencies and
+updates to findings or evidence for changed code. Start with the
+[record guide](https://unixnu.com/porting/records),
+[UFS porting guide](https://unixnu.com/porting/ufs) and
+[device template](examples/device/README.md).
+
 ## Contributing

 Read [CONTRIBUTING.md](CONTRIBUTING.md) for the repository scope, the development workflow, the commit format and the documentation rules.
@@ -19,8 +19,6 @@

 # UniXNU

-Adreno740 和 AdrenoMetal 在小米平板 6S Pro（sheng）上提供 GPU 加速。render server 通过 Adreno 740 合成系统界面，列入白名单的进程会获得各自的 Metal 设备。详见 [Adreno 740 驱动文档](https://unixnu.com/zh/drivers/adreno740)。
-
 一个独立项目，通过 UEFI 在非 Apple ARM64 硬件上运行 iOS 与 macOS。

 ## 文档
@@ -45,10 +43,19 @@ Adreno740 和 AdrenoMetal 在小米平板 6S Pro（sheng）上提供 GPU 加速
 | [UniXNU-sheng](https://github.com/UniXNU/UniXNU-sheng) | 小米平板 6S Pro 的设备仓库 |
 | [uefi-sheng](https://github.com/UniXNU/uefi-sheng) | 小米平板 6S Pro 的 UEFI 固件移植 |

-驱动和 kit 是 UniXNU 组织下的独立公开仓库，以子模块形式引入。克隆时使用 `--recurse-submodules`，或运行 `git submodule update --init --recursive`。
+主仓库检出共享驱动和 kit。设备仓库维护板级驱动子模块，sheng 提供 ShengUfs、ShengHidInput、触控和 preflight 组件。组件目录描述可用组件，构建工具组装所选设备的源码。克隆仓库时使用 `--recurse-submodules`。

 设备仓库选择固定版本的 SoC 源码、OS 配置和组件。构建工具合并配置、解析依赖、编译板级 DTS 并生成 ADT。先读 [AGENTS.md](AGENTS.md)、[设备模板](examples/device/README.md)和[迁移指南](https://unixnu.com/zh/porting/migration)。

+## 官方设备开发
+
+每个官方设备维护 `porting.toml`，为每个子系统记录硬件输入、配置、步骤、经验、
+证据和完成条件。维护者与 agent 共用这份记录。文档站按 `devices.toml` 固定的设备版本生成页面。
+
+必需 CI 检查覆盖记录结构、组件依赖，以及代码改动对应部分的经验或证据更新。
+从[记录指南](https://unixnu.com/zh/porting/records)、[UFS 移植指南](https://unixnu.com/zh/porting/ufs)
+和[设备模板](examples/device/README.md)开始。
+
 ## 参与贡献

 阅读 [CONTRIBUTING.md](CONTRIBUTING.md)（英文），或查看[文档站的贡献页面](https://unixnu.com/zh/contributing/documentation)。
@@ -0,0 +1,6 @@
+schema_version = 1
+
+[[device]]
+name = "sheng"
+repository = "UniXNU/UniXNU-sheng"
+revision = "95295f4874cf3da2cdfffff8784e185d2eba8f62"
@@ -78,6 +78,8 @@ export default withMermaid(defineConfig({
              items: [
                { text: '移植总览', link: '/zh/porting/' },
                { text: '设备仓库', link: '/zh/porting/device-repository' },
+                { text: '适配记录', link: '/zh/porting/records' },
+                { text: 'UFS 移植', link: '/zh/porting/ufs' },
                { text: 'SM8550 支持', link: '/zh/porting/sm8550' },
                { text: '迁移指南', link: '/zh/porting/migration' },
                { text: 'UEFI 固件', link: '/zh/porting/uefi-firmware' },
@@ -317,6 +319,8 @@ export default withMermaid(defineConfig({
          items: [
            { text: 'Porting overview', link: '/porting/' },
            { text: 'Device repository', link: '/porting/device-repository' },
+            { text: 'Porting records', link: '/porting/records' },
+            { text: 'UFS porting', link: '/porting/ufs' },
            { text: 'SM8550 support', link: '/porting/sm8550' },
            { text: 'Migration', link: '/porting/migration' },
            { text: 'UEFI firmware', link: '/porting/uefi-firmware' },
@@ -85,3 +85,11 @@ VitePress fails the build on a broken internal link.

 - [Repository layout](/contributing/repository)
 - [Overview](/guide/overview)
+
+## Device records
+
+Site builds require Python 3.11 or newer. `npm run build` fetches the device
+revisions in `devices.toml`, validates their records and renders device pages.
+Edit `porting.toml` in the device repository and update its registry revision
+after publication. Both language editions include the same record. See the
+[record guide](/porting/records).
@@ -81,3 +81,11 @@ Commit messages describe changes. Documentation describes current behavior.
 - [Component catalog](/reference/components)
 - [Documentation site](/contributing/documentation)
 - [Build](/building)
+
+## Device records and source ownership
+
+Main-repository submodules provide shared components. Device repositories own
+board driver submodules. The catalog supports discovery and selection. Official
+devices maintain `porting.toml` for maintainers and agents; the site renders the
+revision pinned in `devices.toml`. Code changes update the corresponding findings
+or evidence. See the [record guide](/porting/records).
@@ -4,7 +4,7 @@ A device entry is a pair of repositories and the values that make the generic st

 | Device | SoC | Support | Device repository | Firmware |
 | --- | --- | --- | --- | --- |
-| Xiaomi Pad 6S Pro (sheng) | SM8550 | Display, Touch, UFS, GPU | [UniXNU-sheng](https://github.com/UniXNU/UniXNU-sheng) | [uefi-sheng](https://github.com/UniXNU/uefi-sheng) |
+| [Xiaomi Pad 6S Pro (sheng)](/devices/sheng) | SM8550 | [Implementation and evidence by area](/devices/sheng) | [UniXNU-sheng](https://github.com/UniXNU/UniXNU-sheng) | [uefi-sheng](https://github.com/UniXNU/uefi-sheng) |

 ## Community ports

@@ -117,3 +117,5 @@ Device pages are the place for board specific values. The general guide uses pla
 ## sheng

 The [sheng page](/devices/sheng) records the Xiaomi Pad 6S Pro port. It is one device entry. The [Novatek touch driver](/drivers/sheng-novatek-touch) uses the sheng touch driver as a worked example of a built-in XNU driver.
+
+Official device pages render each repository's `porting.toml`. See the [record workflow](/porting/records).
@@ -1,126 +1,12 @@
 # Xiaomi Pad 6S Pro (sheng)

-sheng uses the SM8550 SoC and the `ipados-17.7.11-21H461` OS profile.
+[Device repository](https://github.com/UniXNU/UniXNU-sheng),
+[SM8550 support](/porting/sm8550),
+[firmware](https://github.com/UniXNU/uefi-sheng).

-| Repository | Responsibility |
-| --- | --- |
-| [UniXNU-sm8550-common](https://github.com/UniXNU/UniXNU-sm8550-common) | SoC configuration, DTSI, GPU platform operations, shared patches |
-| [UniXNU-sheng](https://github.com/UniXNU/UniXNU-sheng) | Board DTS, peripherals, selected components, firmware policy, partitions and packaging |
-| [uefi-sheng](https://github.com/UniXNU/uefi-sheng) | UEFI platform integration |
+The device repository owns board drivers, hardware configuration and the
+porting record. Use the [record guide](/porting/records),
+[repository specification](/porting/device-repository) and
+[UFS guide](/porting/ufs) with the relevant section below.

-## Configuration
-
-```toml
-schema_version = 2
-
-[board]
-name = "sheng"
-soc = "SM8550"
-soc_source = "sm8550"
-os_profile = "ipados-17.7.11-21H461"
-kit = "sheng"
-
-[device_tree]
-source = "device:dts/sheng.dts"
-include_dirs = ["soc:dts"]
-```
-
-The device feed pins the SoC commit. ARM64, SoC, OS, and device settings merge in
-that order. The selected `sheng_defconfig` follows their configuration fragments.
-The output root is `out/sheng/ipados-17.7.11-21H461/sheng/`.
-
-The OS profile supplies XNU 10063.141.1, iPad7,1 iPadOS 17.7.11 build 21H461,
-IPSW member pins, prelink roots, Apple identity, and OS ABI requirements.
-`payload.adt` supplies the device root UUID, memory request, and platform seed policy.
-
-## Hardware description
-
-`dts/sheng.dts` includes `sm8550.dtsi`. It supplies the model, compatible values,
-DRAM range, splash reservation, CPU selection, and enabled peripherals. The
-shared ADT generator converts it with the OS profile and payload inputs.
-
-| Input | Value |
-| --- | --- |
-| DRAM range used by the handoff | Base `0x80000000`, size `0x80000000` |
-| Splash region | Base `0xb8000000`, size `0x2b00000` |
-| Contiguous memory request | `0x130000000` |
-| Root UUID | `04769D26-2CA0-4825-B443-E2E5F88300F2` |
-| Platform seed | Supplied with `--unique-chip-id` |
-
-## Components
-
-The device selects ArmDTPlatform, ArmCpu, SoftwareAES, ShengUfs, VirtioMmioBlock,
-RamBlock, Adreno740, AdrenoMetal, GopFramebuffer, ShengHidInput, ShengNovatekTouch,
-QcomGeniSpi, AppleKeyStoreState, XnuPrelink, DarwinBoot, VerifiedRoot, ShengPreflight,
-AirNir, and Ath12kWifi. The resolver adds dependencies including the shared SM8550 GPU kit.
-
-Adreno740 and AdrenoMetal implement the A740/SM8550 graphics stack. sheng supplies
-signed firmware, power policy, memory, and display inputs. The [GPU page](/drivers/adreno740)
-describes runtime submission and plugin staging. Plugin filenames and runtime
-classes retain their ABI identifiers.
-
-ShengUfs uses the SM8550 UFS resources and sheng storage policy. The userdata
-partition has `first_lba = 0x2f3840`, `last_lba = 0x3d0abfa`, and 4096-byte blocks.
-The OS and SystemOS windows come from the selected IPSW. With
-`sheng-data-persist=2`, the Data store writes through to the end of userdata,
-below the 1024 MiB log reserve.
-
-Ath12kWifi uses the board PCIe, MSI, DMA, and network interfaces. The board
-selects a 208 MiB payload, sRGB display properties, and a 120 Hz timing request.
-
-## Build
-
-```sh
-git clone --recurse-submodules https://github.com/UniXNU/UniXNU
-git clone --recurse-submodules https://github.com/UniXNU/UniXNU-sheng
-git clone https://github.com/UniXNU/uefi-sheng
-cd UniXNU
-./unixnu defconfig sheng_defconfig -D ../UniXNU-sheng
-./unixnu fetch
-./unixnu status --json
-./unixnu ipsw fetch
-./unixnu build kernel
-./unixnu build package
-./unixnu build firmware --uefi ../uefi-sheng
-./unixnu build payload --unique-chip-id <hex> --trust-cache <bundle> --data-ramdisk <seed>
-./unixnu bootimg --uefi ../uefi-sheng --dtb <firmware.dtb>
-```
-
-The platform seed, trust cache, Data seed, and vendor firmware come from the
-device input inventory. `proprietary-files.txt` records firmware sources and
-hashes. The OS profile records accepted trust-cache hashes.
-
-The kernel selects ARM64, SoC, OS, and device patch series in that order. Its archive plan interleaves component recipes
-with ABI bindings and board helper scripts. Inspect both in `status --json`.
-
-## Boot
-
-```sh
-fastboot boot out/sheng/ipados-17.7.11-21H461/sheng/boot/boot.img
-```
-
-The userdata installation uses the partition described above:
-
-```sh
-./unixnu build userdata
-fastboot flash userdata out/sheng/ipados-17.7.11-21H461/sheng/userdata/userdata-root.img
-fastboot reboot bootloader
-fastboot boot out/sheng/ipados-17.7.11-21H461/sheng/boot/boot.img
-```
-
-## Verification
-
-Run `unixnu status --json` to inspect source revisions, profiles, components,
-and patch order. Build the selected target with the
-[required inputs](/porting/migration#build-inputs). Inspect DTS/ADT output,
-kernel and prelink logs, payload contents, and firmware packaging.
-
-Record image revisions, commands, outputs, and hardware observations with the
-[migration report](/porting/migration#verification-report). The complete board
-inputs are maintained in the device repository.
-
- [SM8550 support](/porting/sm8550)
- [Adreno740](/drivers/adreno740)
- [Novatek touch](/drivers/sheng-novatek-touch)
- [Unattended checks](/devices/sheng-unattended-test)
- [Migration](/porting/migration)
+<!--@include: ../.vitepress/records/sheng.md-->
@@ -18,3 +18,9 @@ profile enables `CONFIG_XNU_NATIVE_UFS` and supplies the board inputs.
 ```sh
 ./unixnu build kernel -D ../UniXNU-sheng
 ```
+
+## Porting and records
+
+The sheng device repository supplies ShengUfs as a submodule. Follow the
+[UFS porting guide](/porting/ufs) and maintain controller, clock, PHY, SMMU,
+DMA, partition and completion details in the [storage record](/devices/sheng#storage).
@@ -5,7 +5,10 @@
  "scripts": {
    "dev": "vitepress dev",
    "build": "vitepress build",
-    "preview": "vitepress preview"
+    "preview": "vitepress preview",
+    "records": "python3 ../scripts/porting-record.py site",
+    "prebuild": "npm run records",
+    "predev": "npm run records"
  },
  "devDependencies": {
    "mermaid": "^11.17.2",
@@ -10,6 +10,8 @@ UniXNU-<device>/
  AGENTS.md
  README.md
  board.toml
+  porting.toml
+  .github/workflows/porting-record.yml
  feeds.toml
  configs/<device>_defconfig
  dts/<device>.dts
@@ -391,3 +393,14 @@ The `[match]` keys are all required. Within one key, any listed value matches. A
 - [Device tree](/porting/device-tree)
 - [Device configuration reference](/reference/configuration)
 - [Devices](/devices/)
+
+## Porting record
+
+`porting.toml` sits beside `board.toml`. Every area contains development findings,
+evidence and completion criteria. Its identity and component coverage match the
+board configuration and catalog dependencies. Device CI checks findings or
+evidence updates for changed code paths. See the [record guide](/porting/records)
+for fields, status levels and publication.
+
+Board driver submodules belong to the device repository. sheng pins ShengUfs,
+ShengHidInput, ShengNovatekTouch and ShengPreflight there.
@@ -44,3 +44,10 @@ power, memory, and display inputs. See [SM8550 support](/porting/sm8550).
 - [Component catalog](/reference/components)
 - [Migration](/porting/migration)
 - [UEFI firmware](/porting/uefi-firmware)
+
+## Porting records
+
+Official devices record hardware, configuration, findings, evidence and completion
+criteria in `porting.toml`. Maintainers and agents use the same record; device
+pages render its pinned revision. Read the [record guide](/porting/records)
+and the [UFS guide](/porting/ufs) before storage work.
@@ -225,3 +225,13 @@ Record unavailable hardware checks as pending. Keep build completion and device
 observations separate. Update English and Chinese documentation, root README,
 root `AGENTS.md`, component metadata, and firmware references with the final names
 and commands.
+
+## Structured porting record
+
+Copy `porting.toml` and `.github/workflows/porting-record.yml` from the template.
+Populate each area from the implementation with hardware, configuration,
+procedure, findings, completion criteria and evidence. Cover selected components
+and their dependencies. Put board driver submodules in the device repository.
+Run the record checker, require `Porting record` on the official device branch,
+and update the published revision in UniXNU `devices.toml`. The site renders
+this record. Read the [record guide](/porting/records) and [UFS guide](/porting/ufs).
@@ -0,0 +1,120 @@
+# Device porting records
+
+Every official device repository maintains `porting.toml`. Maintainers and
+agents use this record throughout development. The documentation site renders
+it at the device page from the revision pinned in `devices.toml`.
+
+## Required areas
+
+Each area records inputs, configuration, procedure, development findings,
+completion criteria, current limits, next action, and evidence.
+
+| Area | Required technical detail |
+| --- | --- |
+| Configuration | SoC and OS profiles, source pins, component choices, array replacements, defconfig and patch order |
+| Firmware and boot | Boot format, firmware revision, PSCI, framebuffer and memory handoff |
+| CPU and interrupts | CPU affinities, enabled cores, GIC ranges, timer rate, interrupts and IPIs |
+| Memory and DMA | DRAM, reservations, address translation, DMA widths, cache policy and SMMU ownership |
+| Storage and root | Host, PHY, clocks, resets, power, SMMU stream, DMA, LUNs, GPT, root and persistent Data |
+| Display | Controller or GOP, panel, stride, format, timing, backlight and presentation |
+| Input | Bus, sensor protocol, pins, interrupts, firmware, contact IDs and coordinate mapping |
+| GPU | GPU/GMU generation, firmware, votes, SMMU, submission, fences, frontend ABI and presentation |
+| Network | Bus, firmware, interrupts, DMA, OS interface, association and packet transfer |
+| Audio | DSP, codec, clocks, firmware services, routes and playback/capture |
+| Power | Regulators, clocks, battery units, firmware ownership and supported transitions |
+| Image assembly | XNU and IPSW versions, ABI inputs, patch order, ADT, payload and boot-image format |
+| Diagnostics | Log transport, checkpoints, recovery, commands and image/source revisions |
+
+Add areas for other peripherals. Every selected component and its catalog
+dependencies belong to an area. Use `not-applicable` with a reason in `limits`
+for a function outside the board's scope. Use `planned` for unfinished work.
+
+## Record format
+
+Copy `examples/device/porting.toml`. Its device name, SoC and OS profile must
+match `board.toml`. Each `[[area]]` contains:
+
+| Field | Content |
+| --- | --- |
+| `id` | Stable area identifier |
+| `status` | Completion level from the table below |
+| `components` | Canonical component IDs, including dependencies |
+| `paths` | Repository-relative file patterns owned by this area |
+| `inputs` | Hardware resources, external inputs and dependencies |
+| `configuration` | Actual TOML keys, DTS properties and kernel flags |
+| `procedure` | Ordered operations and commands |
+| `findings` | Observation, established cause, implementation decision and conditions for reuse |
+| `completion` | Observable result required at each milestone |
+| `limits` | Current implementation scope and unresolved inputs |
+| `next_action` | Concrete next measurement or implementation step |
+| `evidence` | Source, host or device records with references and results |
+
+Write findings as technical facts. For example: an idle UFS AHB clock branch
+can report `CLK_OFF` while hardware gating is enabled, so the probe checks
+branch enable and gating together. Link the implementation or captured register
+record. When the cause is unknown, record the symptom and the next measurement.
+
+## Completion levels
+
+| Status | Required evidence |
+| --- | --- |
+| `planned` | Required inputs and next action |
+| `implemented` | Source reference and implementation scope |
+| `host-verified` | Host command, full source commit, result and accessible log |
+| `device-verified` | Device command, full source commit, result and accessible log identifying the device, firmware and image |
+| `not-applicable` | Scope explanation in `limits`, with an empty component list |
+
+Each evidence entry has `kind`, `reference`, and `result`. Host and device
+entries also have `command` and a full 40-character `revision`. References use
+HTTPS or a committed file relative to the device repository. Store large logs
+as linked release or CI artifacts. Record unavailable inputs in `limits` and
+the measurement needed to resolve them in `next_action`.
+
+## Change workflow
+
+1. Read the device record and the relevant common guide before implementation.
+2. Identify the affected areas and their existing components.
+3. Update the implementation and each affected area's findings or evidence.
+4. Update configuration, procedure and completion criteria when the interface changes.
+5. Run the record checker and the existing checks for the changed implementation.
+6. Submit code and documentation in separate commits in the same pull request.
+7. After the device change is published, update its revision in UniXNU's `devices.toml`.
+
+```sh
+python3 scripts/porting-record.py check --device ../UniXNU-sheng
+python3 scripts/porting-record.py check --device ../UniXNU-sheng --base origin/main
+```
+
+Run the second command on the proposed device branch. It compares committed
+changes against the base. Every changed code path needs an owning area;
+each matching area needs updated findings or evidence. Markdown edits use the
+documentation review workflow. `porting.toml` is the authoritative device record.
+
+The device template includes `.github/workflows/porting-record.yml`. Official
+device branches require its `Porting record` check. Reviewers verify hardware
+facts, evidence quality, component reuse and the stated completion level.
+
+## Publishing and reuse
+
+`npm run build` fetches each registered device's pinned `porting.toml` and
+`board.toml`, checks them and renders the device page. English and Chinese
+pages consume the same record. The record body uses concise English. Site
+sources and deployment remain in UniXNU.
+
+For a local preview:
+
+```sh
+python3 scripts/porting-record.py site --local sheng=../UniXNU-sheng
+cd docs
+npx vitepress build
+```
+
+Move a reusable procedure into the relevant common guide after checking its
+hardware and ABI assumptions. Keep the device's values and evidence in its
+record, and link the guide from that section. The README carries the device's
+scope, dependencies, build entry points and link to this record. `AGENTS.md`
+points to the same required reading.
+
+- [UFS porting](/porting/ufs)
+- [Device repository](/porting/device-repository)
+- [Bring-up order](/porting/bring-up)
@@ -0,0 +1,118 @@
+# UFS porting
+
+Start with the storage section of the device's `porting.toml` and the
+[component catalog](/reference/components). The official implementation is
+[ShengUfs](/drivers/sheng-ufs), with runtime class `NativeUfs`.
+
+ShengUfs combines SM8550 controller access, firmware adoption, SMMU handling,
+GPT/window parsing and sheng persistence policy. Its hardware constants and
+board policy require review for each target.
+
+## Hardware inventory
+
+| Input | Record before implementation |
+| --- | --- |
+| Controller | Compatible value, revision, MMIO base/length, capabilities and interrupt routing |
+| PHY | Register ranges, lanes, reference clock, tuning source and initialization owner |
+| Clocks | Provider, clock IDs, rates, parent selection, branch gates and interconnect votes |
+| Reset and power | Reset lines, regulators, power domains, sequence and firmware ownership |
+| SMMU | Instance, stream IDs, stream masks, context banks, address width and existing mappings |
+| DMA | Buffer allocation, physical/IOVA relationship, alignment, coherency and cache maintenance |
+| Handoff | HCE/HCS, link state, power mode, request-list base and outstanding commands |
+| Storage layout | LUNs, block sizes, capacity, GPT, root windows, Data and log reservations |
+| OS interface | Storage ABI, prelink inputs, publication/matching and completion behavior |
+
+Cite the board DTS, SoC documentation, firmware code or measured state for each
+value. Put shared controller resources in the SoC DTSI and board wiring or
+policy in the device repository. Describe register widths, parent address cells,
+`ranges`, interrupt providers and IOMMU references using the
+[device-tree bindings](/porting/device-tree).
+
+For sheng, the SoC DTSI exports host `0x01d84000/0x3000` and PHY
+`0x01d80000/0x2000`. GCC at `0x00100000` and apps-SMMU handling for stream
+`0x60` are implemented in ShengUfs. The current driver reads those resources
+through its C++ constants and operations. Converting a resource to a DTS property
+also requires changing its consumer and validating the generated ADT value.
+
+## Initialization and ownership
+
+1. Read controller, clock, PHY, link and SMMU state using the documented access widths.
+2. Establish which clocks, resets and power domains firmware has configured.
+3. Select firmware-state adoption or a fully specified controller/PHY initialization sequence.
+4. Allocate request descriptors and data buffers; establish their DMA reachability.
+5. Establish exclusive ownership of the request list and selected SMMU context.
+6. Submit a bounded command and inspect transfer, response and SCSI status.
+7. Read capacity and known blocks before publishing a root device.
+
+ShengUfs adopts an existing firmware request list and uses a polled request slot.
+Porting this path requires the request-list state and ownership checks in
+`NativeUfs.cpp`. A board requiring cold initialization needs its PHY, reset,
+clock and power sequence implemented and recorded.
+
+## Findings to reuse
+
+- An idle hardware-gated AHB branch can report `CLK_OFF`. Inspect the branch
+  enable and hardware-gating bits together. See `GccUfs.h`.
+- SMMU bypass is bounded by supported address widths. Check the complete DMA
+  range and existing stream/context-bank ownership. See `SmmuTakeover.h`.
+- Capacity, GPT and root-window bounds are separate checks. Keep all LBA-to-byte
+  conversions tied to the observed logical block size. See `RootLayout.h`.
+- Root reads, persistent Data writes and reset handling have separate completion
+  criteria. Record the allocation and recovery method for each write exercise.
+
+The [sheng storage record](/devices/sheng#storage) supplies board values,
+implementation references and current limits.
+
+## Configuration
+
+Select the matching storage component in the complete `[components] include`
+array. Add its recipe at the required position in `[kernel] archives`. Arrays
+replace inherited arrays. The sheng selection includes:
+
+```toml
+# Entries within the complete device selections:
+# [components] include: "ShengUfs"
+# [kernel] archives: "component:ShengUfs"
+
+[userdata]
+first_lba = 3094592
+last_lba = 64007162
+lba_bytes = 4096
+windows = [
+  { name = "OS", component = "OS" },
+  { name = "SystemOS", component = "Cryptex1,SystemOS" },
+]
+
+[payload.adt]
+root_match_volume_uuid = "04769D26-2CA0-4825-B443-E2E5F88300F2"
+```
+
+These values describe sheng. Obtain another board's geometry from its GPT and
+its root UUID from the selected volume. Preserve other required `payload.adt`
+fields. Enable `CONFIG_XNU_NATIVE_UFS=y` in the selected defconfig and include
+`native-ufs-root=1` in the complete kernel argument array for this runtime.
+
+The component source is pinned in the device repository. Shared build tools
+assemble it into the target's `drivers/ShengUfs` path. Storage ABI bindings need
+the selected kernelcache and matching audit inputs.
+
+## Completion criteria
+
+| Milestone | Required observation |
+| --- | --- |
+| Hardware inventory | Controller, PHY, clock/reset/power and SMMU values have sources and ownership |
+| Host access | Registers are readable and clock/link state matches the chosen initialization path |
+| DMA and commands | Buffers are reachable; command completion and failures are handled |
+| Block reads | Capacity and known-block reads match the selected LUN and logical block size |
+| Root | GPT and root windows are bounded; the configured root mounts and starts userland |
+| Persistence | Writes remain in the allocated Data region and survive the documented reboot/reset sequence |
+
+Update the storage record at each milestone. Keep source, host and device
+results at their corresponding [completion levels](/porting/records#completion-levels).
+
+```sh
+./unixnu defconfig sheng_defconfig -D ../UniXNU-sheng
+./unixnu status --json -D ../UniXNU-sheng
+./unixnu build kernel -D ../UniXNU-sheng
+python3 scripts/porting-record.py check --device ../UniXNU-sheng
+```
@@ -83,3 +83,9 @@ VitePress 在内部链接断开时构建失败。

 - [仓库布局](/zh/contributing/repository)
 - [总览](/zh/guide/overview)
+
+## 设备记录
+
+站点构建需要 Python 3.11 或更新版本。`npm run build` 从 `devices.toml` 的固定版本
+获取设备记录，检查后生成页面。更新记录时修改设备仓库的 `porting.toml`，发布后更新
+注册版本。中英文设备页引用同一份记录。详见[记录指南](/zh/porting/records)。
@@ -76,3 +76,9 @@ UniXNU/
 - [组件目录](/zh/reference/components)
 - [文档站](/zh/contributing/documentation)
 - [构建](/zh/building)
+
+## 设备记录与源码所有权
+
+主仓库的子模块提供共享组件，板级驱动子模块由设备仓库维护。组件目录用于发现和选择。
+官方设备的 `porting.toml` 供维护者和 agent 共用，设备页按 `devices.toml` 固定版本生成。
+代码改动需要更新对应部分的经验或证据。参见[记录指南](/zh/porting/records)。
@@ -4,7 +4,7 @@

 | 设备 | SoC | 支持功能 | 设备仓库 | 固件 |
 | --- | --- | --- | --- | --- |
-| 小米平板 6S Pro（sheng） | SM8550 | 显示、触控、UFS、GPU | [UniXNU-sheng](https://github.com/UniXNU/UniXNU-sheng) | [uefi-sheng](https://github.com/UniXNU/uefi-sheng) |
+| 小米平板 6S Pro（sheng） | SM8550 | [各部分的实现与证据](/zh/devices/sheng) | [UniXNU-sheng](https://github.com/UniXNU/UniXNU-sheng) | [uefi-sheng](https://github.com/UniXNU/uefi-sheng) |

 ## 社区移植

@@ -117,3 +117,5 @@
 ## sheng

 [sheng 页面](/zh/devices/sheng)记录小米平板 6S Pro 移植。它是一个设备条目。[Novatek 触控驱动](/zh/drivers/sheng-novatek-touch)把 sheng 的触控驱动作为内置 XNU 驱动的完整示例。
+
+官方设备页由设备仓库的 `porting.toml` 生成，更新流程见[适配记录](/zh/porting/records)。
@@ -1,121 +1,11 @@
 # 小米平板 6S Pro（sheng）

-sheng 使用 SM8550 SoC 和 `ipados-17.7.11-21H461` OS 配置。
+[设备仓库](https://github.com/UniXNU/UniXNU-sheng)、
+[SM8550 支持](/zh/porting/sm8550)、
+[固件](https://github.com/UniXNU/uefi-sheng)。

-| 仓库 | 职责 |
-| --- | --- |
-| [UniXNU-sm8550-common](https://github.com/UniXNU/UniXNU-sm8550-common) | SoC 配置、DTSI、GPU 平台操作和共享补丁 |
-| [UniXNU-sheng](https://github.com/UniXNU/UniXNU-sheng) | 板级 DTS、外设、组件选择、固件策略、分区和打包 |
-| [uefi-sheng](https://github.com/UniXNU/uefi-sheng) | UEFI 平台集成 |
+设备仓库维护板级驱动、硬件配置和适配记录。结合
+[记录指南](/zh/porting/records)、[仓库规范](/zh/porting/device-repository)和
+[UFS 指南](/zh/porting/ufs)阅读下方对应部分。

-## 配置
-
-```toml
-schema_version = 2
-
-[board]
-name = "sheng"
-soc = "SM8550"
-soc_source = "sm8550"
-os_profile = "ipados-17.7.11-21H461"
-kit = "sheng"
-
-[device_tree]
-source = "device:dts/sheng.dts"
-include_dirs = ["soc:dts"]
-```
-
-设备 feed 固定 SoC 提交。配置按 ARM64、SoC、OS、设备顺序合并，所选
-`sheng_defconfig` 在配置片段之后应用。输出根目录为
-`out/sheng/ipados-17.7.11-21H461/sheng/`。
-
-OS 配置提供 XNU 10063.141.1、iPad7,1 iPadOS 17.7.11 build 21H461、IPSW 成员固定
-哈希、预链接根组件、Apple 身份和 OS ABI 要求。`payload.adt` 提供设备根卷 UUID、
-内存请求和平台种子规则。
-
-## 硬件描述
-
-`dts/sheng.dts` 包含 `sm8550.dtsi`，提供型号、compatible、DRAM 范围、splash
-保留区域、CPU 选择和启用的外设。共享 ADT 生成器结合 OS 配置与 payload 输入完成转换。
-
-| 输入 | 值 |
-| --- | --- |
-| 交接使用的 DRAM 范围 | 基址 `0x80000000`，长度 `0x80000000` |
-| Splash 区域 | 基址 `0xb8000000`，长度 `0x2b00000` |
-| 连续内存请求 | `0x130000000` |
-| 根卷 UUID | `04769D26-2CA0-4825-B443-E2E5F88300F2` |
-| 平台种子 | 通过 `--unique-chip-id` 提供 |
-
-## 组件
-
-设备选择 ArmDTPlatform、ArmCpu、SoftwareAES、ShengUfs、VirtioMmioBlock、RamBlock、
-Adreno740、AdrenoMetal、GopFramebuffer、ShengHidInput、ShengNovatekTouch、QcomGeniSpi、
-AppleKeyStoreState、XnuPrelink、DarwinBoot、VerifiedRoot、ShengPreflight、AirNir 和 Ath12kWifi。
-解析器补全共享 SM8550 GPU kit 等依赖。
-
-Adreno740 和 AdrenoMetal 实现 A740/SM8550 图形栈。sheng 提供签名固件、电源策略、
-内存和显示输入。[GPU 页面](/zh/drivers/adreno740)说明运行时提交与插件发布。
-插件文件名和运行时类保持其 ABI 标识符。
-
-ShengUfs 使用 SM8550 UFS 资源和 sheng 存储策略。userdata 分区为
-`first_lba = 0x2f3840`、`last_lba = 0x3d0abfa`，逻辑块大小为 4096 字节。
-OS 和 SystemOS 窗口来自所选 IPSW。`sheng-data-persist=2` 将 Data 写入 userdata
-末尾、1024 MiB 日志保留区之前的存储区域。
-
-Ath12kWifi 使用板级 PCIe、MSI、DMA 和网络接口。设备配置选择 208 MiB payload、
-sRGB 显示属性和 120 Hz 时序请求。
-
-## 构建
-
-```sh
-git clone --recurse-submodules https://github.com/UniXNU/UniXNU
-git clone --recurse-submodules https://github.com/UniXNU/UniXNU-sheng
-git clone https://github.com/UniXNU/uefi-sheng
-cd UniXNU
-./unixnu defconfig sheng_defconfig -D ../UniXNU-sheng
-./unixnu fetch
-./unixnu status --json
-./unixnu ipsw fetch
-./unixnu build kernel
-./unixnu build package
-./unixnu build firmware --uefi ../uefi-sheng
-./unixnu build payload --unique-chip-id <hex> --trust-cache <bundle> --data-ramdisk <seed>
-./unixnu bootimg --uefi ../uefi-sheng --dtb <firmware.dtb>
-```
-
-平台种子、trust cache、Data seed 和厂商固件来自设备输入清单。
-`proprietary-files.txt` 记录固件来源与哈希，OS 配置记录接受的 trust cache 哈希。
-
-内核依次选择 ARM64、SoC、OS 和设备补丁 series。
-archive 计划将组件构建命令与 ABI 绑定、板级辅助脚本按顺序排列。使用
-`status --json` 检查两者。
-
-## 启动
-
-```sh
-fastboot boot out/sheng/ipados-17.7.11-21H461/sheng/boot/boot.img
-```
-
-userdata 安装使用上述分区布局：
-
-```sh
-./unixnu build userdata
-fastboot flash userdata out/sheng/ipados-17.7.11-21H461/sheng/userdata/userdata-root.img
-fastboot reboot bootloader
-fastboot boot out/sheng/ipados-17.7.11-21H461/sheng/boot/boot.img
-```
-
-## 验证
-
-运行 `unixnu status --json` 检查源码版本、配置、组件和补丁顺序。使用
-[所需输入](/zh/porting/migration#构建输入)构建所选目标。检查 DTS/ADT 输出、
-内核与预链接日志、payload 内容和固件打包结果。
-
-使用[迁移报告](/zh/porting/migration#验证报告)记录镜像版本、命令、输出和硬件观察。
-完整板级输入由设备仓库维护。
-
- [SM8550 支持](/zh/porting/sm8550)
- [Adreno740](/zh/drivers/adreno740)
- [Novatek 触控](/zh/drivers/sheng-novatek-touch)
- [无人值守检查](/zh/devices/sheng-unattended-test)
- [迁移指南](/zh/porting/migration)
+<!--@include: ../../.vitepress/records/sheng.zh.md-->
@@ -16,3 +16,9 @@ ShengUfs 为 SM8550 上的 sheng 提供 UFS 存储路径，管理主机控制器
 ```sh
 ./unixnu build kernel -D ../UniXNU-sheng
 ```
+
+## 移植与记录
+
+ShengUfs 由 sheng 设备仓库作为子模块提供。阅读 [UFS 移植指南](/zh/porting/ufs)，
+按[设备存储记录](/zh/devices/sheng#storage)维护控制器、时钟、PHY、SMMU、DMA、
+分区和完成条件。
@@ -9,6 +9,8 @@ UniXNU-<device>/
  AGENTS.md
  README.md
  board.toml
+  porting.toml
+  .github/workflows/porting-record.yml
  feeds.toml
  configs/<device>_defconfig
  dts/<device>.dts
@@ -384,3 +386,12 @@ entry = "<entry id>"
 - [设备树](/zh/porting/device-tree)
 - [设备配置参考](/zh/reference/configuration)
 - [设备](/zh/devices/)
+
+## 适配记录
+
+`porting.toml` 与 `board.toml` 位于设备仓库根目录。每个部分包含开发经验、证据和
+完成条件，记录字段与 `board.toml` 及组件依赖匹配。设备 CI 检查代码路径对应部分
+的经验或证据更新。字段、状态和发布流程见[记录指南](/zh/porting/records)。
+
+板级驱动子模块归属设备仓库。sheng 在设备仓库固定 ShengUfs、ShengHidInput、
+ShengNovatekTouch 和 ShengPreflight。
@@ -41,3 +41,9 @@ sheng 提供其固件、电源、内存和显示输入。参见 [SM8550 支持](
 - [组件目录](/zh/reference/components)
 - [迁移指南](/zh/porting/migration)
 - [UEFI 固件](/zh/porting/uefi-firmware)
+
+## 适配记录
+
+官方设备使用 `porting.toml` 逐项记录硬件、配置、经验、证据和完成条件。维护者与 agent
+使用同一份记录，设备页从固定版本生成。实现前阅读[记录指南](/zh/porting/records)，
+存储适配同时阅读 [UFS 指南](/zh/porting/ufs)。
@@ -212,3 +212,11 @@ sheng 的 archive 和镜像步骤需要：
 无法执行的硬件检查记为待验证。构建完成与设备观察分别记录。
 用最终名称和命令更新中英文文档、根目录 README、根目录 `AGENTS.md`、组件元数据
 和固件引用。
+
+## 结构化适配记录
+
+复制模板中的 `porting.toml` 和 `.github/workflows/porting-record.yml`。按实际代码
+为每个部分填写硬件、配置、操作、经验、完成条件和证据，并覆盖所选组件及依赖。
+把板级驱动子模块放入设备仓库。运行记录检查，将 `Porting record` 设为官方设备分支
+的必需检查，并更新 UniXNU `devices.toml` 的发布版本。设备页由这份记录生成。
+详见[记录指南](/zh/porting/records)和 [UFS 指南](/zh/porting/ufs)。
@@ -0,0 +1,108 @@
+# 设备适配记录
+
+每个官方设备仓库维护一份 `porting.toml`。维护者和 agent 在适配过程中使用同一份
+记录。文档站按 `devices.toml` 固定的版本生成设备页。
+
+## 必需部分
+
+每个部分记录输入、配置、步骤、开发经验、完成条件、当前范围、下一步和证据。
+
+| 部分 | 必需技术信息 |
+| --- | --- |
+| 配置 | SoC 和 OS 配置、源码固定版本、组件选择、数组替换、defconfig 和补丁顺序 |
+| 固件与启动 | 启动格式、固件版本、PSCI、framebuffer 和内存交接 |
+| CPU 与中断 | CPU affinity、启用核心、GIC 范围、定时器频率、中断和 IPI |
+| 内存与 DMA | DRAM、保留区、地址转换、DMA 位宽、缓存规则和 SMMU 所有权 |
+| 存储与根卷 | 控制器、PHY、时钟、复位、电源、SMMU stream、DMA、LUN、GPT、根卷和持久 Data |
+| 显示 | 控制器或 GOP、面板、stride、格式、时序、背光和呈现 |
+| 输入 | 总线、传感器协议、引脚、中断、固件、触点 ID 和坐标映射 |
+| GPU | GPU/GMU 型号、固件、电源请求、SMMU、提交、fence、前端 ABI 和呈现 |
+| 网络 | 总线、固件、中断、DMA、OS 接口、连接和数据包传输 |
+| 音频 | DSP、codec、时钟、固件服务、路由和播放/录音 |
+| 电源 | 稳压器、时钟、电池单位、固件所有权和支持的状态转换 |
+| 镜像组装 | XNU/IPSW 版本、ABI 输入、补丁顺序、ADT、payload 和启动镜像格式 |
+| 诊断 | 日志通道、检查点、恢复方法、命令和镜像/源码版本 |
+
+其他外设增加独立部分。所选组件及其目录依赖必须归属某个部分。超出设备范围的功能
+使用 `not-applicable`，在 `limits` 中说明原因；待开发功能使用 `planned`。
+
+## 记录格式
+
+复制 `examples/device/porting.toml`。设备名称、SoC 和 OS 配置必须与 `board.toml`
+一致。每个 `[[area]]` 包含以下字段：
+
+| 字段 | 内容 |
+| --- | --- |
+| `id` | 稳定的部分标识符 |
+| `status` | 下表定义的完成等级 |
+| `components` | 组件规范名称，包括依赖 |
+| `paths` | 该部分负责的仓库相对路径模式 |
+| `inputs` | 硬件资源、外部输入和依赖 |
+| `configuration` | 实际 TOML 字段、DTS 属性和内核选项 |
+| `procedure` | 有序操作与命令 |
+| `findings` | 观察、已确认原因、实现决策和复用条件 |
+| `completion` | 各阶段需要观察到的结果 |
+| `limits` | 当前实现范围和待确认输入 |
+| `next_action` | 下一项测量或实现操作 |
+| `evidence` | 源码、主机或设备记录，包含引用和结果 |
+
+开发经验使用具体技术事实。例如，启用硬件门控的 UFS AHB 分支在空闲时可能报告
+`CLK_OFF`，探测过程需要一起检查使能位和门控位，并引用实现或寄存器记录。
+原因未查明时，记录现象和下一项测量。
+
+## 完成等级
+
+| 状态 | 必需证据 |
+| --- | --- |
+| `planned` | 所需输入和下一步 |
+| `implemented` | 源码引用和实现范围 |
+| `host-verified` | 主机命令、完整源码提交、结果和可访问的日志 |
+| `device-verified` | 设备命令、完整源码提交、结果，以及标明设备、固件和镜像的日志 |
+| `not-applicable` | `limits` 中的范围说明，组件列表为空 |
+
+每项证据包含 `kind`、`reference` 和 `result`。主机与设备证据还需要 `command`
+和完整的 40 字符 `revision`。引用使用 HTTPS 或设备仓库内已提交文件的相对路径。
+大型日志使用 release 或 CI 产物链接。缺少的输入记入 `limits`，对应测量记入
+`next_action`。
+
+## 改动流程
+
+1. 实现前阅读设备记录和相关公共指南。
+2. 确定受影响部分及已有组件。
+3. 修改实现，并更新各受影响部分的经验或证据。
+4. 接口变化时同步更新配置、步骤和完成条件。
+5. 运行记录检查和实现已有的相关检查。
+6. 代码和文档分别提交，放在同一个 pull request 中。
+7. 设备改动发布后，更新 UniXNU 的 `devices.toml` 固定版本。
+
+```sh
+python3 scripts/porting-record.py check --device ../UniXNU-sheng
+python3 scripts/porting-record.py check --device ../UniXNU-sheng --base origin/main
+```
+
+第二条命令在待提交的设备分支上运行，比较已提交改动与基准版本。每个代码路径
+需要归属部分，每个匹配部分需要更新经验或证据。Markdown 改动按文档流程审阅。
+`porting.toml` 是设备记录的权威来源。
+
+设备模板包含 `.github/workflows/porting-record.yml`。官方设备分支要求其
+`Porting record` 检查通过。审阅者确认硬件事实、证据质量、组件复用和完成等级。
+
+## 发布与复用
+
+`npm run build` 获取注册设备固定版本的 `porting.toml` 和 `board.toml`，检查后生成
+设备页。中英文页面使用同一份记录，记录正文使用简洁英语。站点源码和部署保留在 UniXNU。
+
+本地预览：
+
+```sh
+python3 scripts/porting-record.py site --local sheng=../UniXNU-sheng
+cd docs
+npx vitepress build
+```
+
+通用方法经过硬件和 ABI 条件检查后写入对应公共指南。设备记录保留具体参数和证据，
+并链接指南。README 包含职责、依赖、构建入口和记录链接；`AGENTS.md` 指向相同的必读内容。
+
+- [UFS 移植](/zh/porting/ufs)
+- [设备仓库](/zh/porting/device-repository)
+- [Bring-up 顺序](/zh/porting/bring-up)
@@ -0,0 +1,106 @@
+# UFS 移植
+
+先阅读设备 `porting.toml` 的存储部分和[组件目录](/zh/reference/components)。
+官方实现为 [ShengUfs](/zh/drivers/sheng-ufs)，运行时类名为 `NativeUfs`。
+
+ShengUfs 包含 SM8550 控制器访问、固件状态接管、SMMU、GPT/窗口解析和 sheng
+持久存储策略。每个目标需要检查其硬件常量和板级策略。
+
+## 硬件清单
+
+| 输入 | 实现前记录 |
+| --- | --- |
+| 控制器 | compatible、版本、MMIO 基址/长度、能力和中断路由 |
+| PHY | 寄存器范围、lane、参考时钟、调优来源和初始化责任方 |
+| 时钟 | provider、clock ID、频率、父时钟、分支门控和互联带宽请求 |
+| 复位与电源 | 复位线、稳压器、电源域、时序和固件所有权 |
+| SMMU | 实例、stream ID、掩码、context bank、地址位宽和现有映射 |
+| DMA | 缓冲区分配、物理地址/IOVA 关系、对齐、一致性和缓存维护 |
+| 交接 | HCE/HCS、链路、电源模式、请求列表基址和未完成命令 |
+| 存储布局 | LUN、块大小、容量、GPT、根卷窗口、Data 和日志保留区 |
+| OS 接口 | 存储 ABI、预链接输入、发布/匹配和完成处理 |
+
+每个值引用板级 DTS、SoC 资料、固件源码或测量记录。共享控制器资源放在 SoC DTSI，
+板级连接和策略放在设备仓库。按[设备树绑定](/zh/porting/device-tree)描述寄存器宽度、
+父节点 address cells、`ranges`、中断 provider 和 IOMMU 引用。
+
+sheng 的 SoC DTSI 导出控制器 `0x01d84000/0x3000` 和 PHY `0x01d80000/0x2000`。
+GCC `0x00100000` 和 stream `0x60` 的 apps-SMMU 操作位于 ShengUfs。当前驱动通过
+C++ 常量和操作访问这些资源。资源改为 DTS 属性时，还需要修改读取方并检查生成的 ADT 值。
+
+## 初始化与所有权
+
+1. 按规定宽度读取控制器、时钟、PHY、链路和 SMMU 状态。
+2. 确认固件已配置的时钟、复位和电源域。
+3. 选择固件状态接管，或完整定义的控制器/PHY 初始化序列。
+4. 分配请求描述符和数据缓冲区，确认 DMA 可达范围。
+5. 确认请求列表和所选 SMMU context 的独占所有权。
+6. 提交有界命令并检查传输、响应和 SCSI 状态。
+7. 发布根设备前读取容量和已知数据块。
+
+ShengUfs 接管已有固件请求列表，使用轮询请求槽。移植此流程需要检查
+`NativeUfs.cpp` 中的请求列表状态与所有权。需要冷初始化的设备应实现并记录
+PHY、复位、时钟和电源序列。
+
+## 可复用经验
+
+- 空闲且启用硬件门控的 AHB 分支可能报告 `CLK_OFF`，需要一起检查分支使能和
+  硬件门控位。参见 `GccUfs.h`。
+- SMMU bypass 受支持的地址位宽约束。检查完整 DMA 范围及已有 stream/context-bank
+  所有权。参见 `SmmuTakeover.h`。
+- 容量、GPT 和根卷窗口边界分别检查。LBA 转字节始终使用实际逻辑块大小。
+  参见 `RootLayout.h`。
+- 根卷读取、持久 Data 写入和复位处理分别定义完成条件。每次写入验证记录分配范围和恢复方法。
+
+[sheng 存储记录](/zh/devices/sheng#storage)提供板级参数、实现引用和当前范围。
+
+## 配置
+
+在完整 `[components] include` 数组中选择匹配的存储组件，在 `[kernel] archives`
+的适当位置加入构建项。数组会替换继承值。sheng 使用以下配置：
+
+```toml
+# 完整设备选择中的条目：
+# [components] include: "ShengUfs"
+# [kernel] archives: "component:ShengUfs"
+
+[userdata]
+first_lba = 3094592
+last_lba = 64007162
+lba_bytes = 4096
+windows = [
+  { name = "OS", component = "OS" },
+  { name = "SystemOS", component = "Cryptex1,SystemOS" },
+]
+
+[payload.adt]
+root_match_volume_uuid = "04769D26-2CA0-4825-B443-E2E5F88300F2"
+```
+
+这些值描述 sheng。其他设备的分区参数取自该设备 GPT，根卷 UUID 取自所选卷。
+保留其他必需的 `payload.adt` 字段。所选 defconfig 启用 `CONFIG_XNU_NATIVE_UFS=y`，
+该运行时的完整内核参数数组加入 `native-ufs-root=1`。
+
+组件源码版本固定在设备仓库。共享构建工具将其放入目标的 `drivers/ShengUfs`。
+存储 ABI 绑定需要所选 kernelcache 和匹配的审计输入。
+
+## 完成条件
+
+| 阶段 | 必需观察 |
+| --- | --- |
+| 硬件清单 | 控制器、PHY、时钟/复位/电源和 SMMU 参数有来源与责任方 |
+| 控制器访问 | 寄存器可读，时钟和链路状态符合初始化方式 |
+| DMA 与命令 | 缓冲区可达，命令完成和失败均被处理 |
+| 块读取 | 容量和已知数据块匹配所选 LUN 与逻辑块大小 |
+| 根卷 | GPT 和根卷窗口边界正确，配置的根卷挂载并启动用户态 |
+| 持久化 | 写入位于分配的 Data 区域，经过规定重启/复位序列后保留 |
+
+每个阶段更新存储记录。源码、主机和设备结果使用对应的
+[完成等级](/zh/porting/records#完成等级)。
+
+```sh
+./unixnu defconfig sheng_defconfig -D ../UniXNU-sheng
+./unixnu status --json -D ../UniXNU-sheng
+./unixnu build kernel -D ../UniXNU-sheng
+python3 scripts/porting-record.py check --device ../UniXNU-sheng
+```
@@ -46,4 +46,13 @@ Run from UniXNU, replacing the device path and defconfig:

 Record commands, revisions, output paths, results, and unresolved inputs.
 Report hardware boot, storage, display, input, and GPU results separately.
-Update the device page in UniXNU's documentation site and keep this README concise.
+Update the device revision in UniXNU's devices.toml for publication and keep this README concise.
+
+## Porting record
+
+Read the device's `porting.toml` and the
+[record guide](https://unixnu.com/porting/records) before implementation.
+For storage, also read the [UFS guide](https://unixnu.com/porting/ufs).
+Update each affected area's findings or evidence with its code change.
+The documentation site renders this same record. Follow its schema and
+completion levels for both maintainer and agent work.
@@ -9,7 +9,9 @@ hardware inputs before building.
 4. Fill the DTS model, compatible values, memory map, CPU selection, and peripherals.
 5. List firmware sources and hashes in `proprietary-files.txt`.
 6. Set partition geometry and payload inputs from the device's records.
-7. Set `example = false`, select the defconfig, fetch, and inspect `status --json`.
+7. Complete each area in `porting.toml`, including ownership paths, findings and completion criteria.
+8. Enable the template CI workflow and require its `Porting record` check on the official device branch.
+9. Set `example = false`, select the defconfig, fetch, and inspect `status --json`.

 The zero memory range and `REQUIRED_` values identify inputs to complete.
 `patches/xnu/series` lists board patches in application order. `package/` contains
@@ -19,3 +21,15 @@ board packaging. Shared resources come from the selected SoC and component sourc
 - [Device tree](https://unixnu.com/porting/device-tree)
 - [Component catalog](https://unixnu.com/reference/components)
 - [Migration](https://unixnu.com/porting/migration)
+
+`porting.toml` is the shared maintainer and agent record. The site renders it
+from the device commit pinned in UniXNU's `devices.toml`. Publish that pin with
+the English and Chinese device pages. Put board driver submodules in this
+device repository. See the [record guide](https://unixnu.com/porting/records)
+and [UFS guide](https://unixnu.com/porting/ufs).
+
+```sh
+python3 scripts/porting-record.py check --device ../UniXNU-example
+```
+
+Run this command from UniXNU.
@@ -0,0 +1,189 @@
+schema_version = 1
+
+[device]
+name = "example"
+soc = "SM8550"
+os_profile = "ipados-17.7.11-21H461"
+summary = "Device template. Complete each area with board-specific inputs and evidence."
+
+[[area]]
+id = "configuration"
+status = "planned"
+components = ["ArmDTPlatform", "ArmCpu", "SoftwareAES", "XnuPrelink", "DarwinBoot"]
+paths = ["board.toml", "feeds.toml", "configs/**", ".gitmodules", ".github/**", ".gitignore"]
+inputs = ["Identify the configuration hardware, resources and existing component interfaces for this board."]
+configuration = ["Record the board.toml fields, DTS properties and defconfig values used for configuration."]
+procedure = ["Follow the configuration stage in the porting guide and record the actual commands."]
+findings = ["Collect the first configuration observation, its cause when established, and the resulting implementation decision."]
+completion = ["All source pins resolve; every selected component has a record; status shows the intended overrides and patch order."]
+limits = ["Hardware inputs and implementation are pending for this example board."]
+next_action = ["Inventory the required configuration inputs before implementation."]
+evidence = []
+
+[[area]]
+id = "firmware"
+status = "planned"
+components = []
+paths = ["proprietary-files.txt", "scripts/extract-files.py", "scripts/gen-touch-firmware.py"]
+inputs = ["Identify the firmware and boot hardware, resources and existing component interfaces for this board."]
+configuration = ["Record the board.toml fields, DTS properties and defconfig values used for firmware and boot."]
+procedure = ["Follow the firmware and boot stage in the porting guide and record the actual commands."]
+findings = ["Collect the first firmware and boot observation, its cause when established, and the resulting implementation decision."]
+completion = ["Firmware image builds, enters UniXNU, publishes the framebuffer and preserves the documented memory reservations."]
+limits = ["Hardware inputs and implementation are pending for this example board."]
+next_action = ["Inventory the required firmware and boot inputs before implementation."]
+evidence = []
+
+[[area]]
+id = "cpu"
+status = "planned"
+components = []
+paths = ["package/CpuFreq*", "scripts/*armcpu*"]
+inputs = ["Identify the cpu and interrupts hardware, resources and existing component interfaces for this board."]
+configuration = ["Record the board.toml fields, DTS properties and defconfig values used for cpu and interrupts."]
+procedure = ["Follow the cpu and interrupts stage in the porting guide and record the actual commands."]
+findings = ["Collect the first cpu and interrupts observation, its cause when established, and the resulting implementation decision."]
+completion = ["Every enabled CPU reaches its entry checkpoint and timer/IPI handling works on each enabled CPU."]
+limits = ["Hardware inputs and implementation are pending for this example board."]
+next_action = ["Inventory the required cpu and interrupts inputs before implementation."]
+evidence = []
+
+[[area]]
+id = "memory"
+status = "planned"
+components = []
+paths = ["dts/**", "package/*Smmu*", "package/*Memory*", "scripts/*smmu*", "scripts/*memory*"]
+inputs = ["Identify the memory and dma hardware, resources and existing component interfaces for this board."]
+configuration = ["Record the board.toml fields, DTS properties and defconfig values used for memory and dma."]
+procedure = ["Follow the memory and dma stage in the porting guide and record the actual commands."]
+findings = ["Collect the first memory and dma observation, its cause when established, and the resulting implementation decision."]
+completion = ["All handoff regions are accounted for and each enabled DMA engine accesses its allocated range with the documented cache policy."]
+limits = ["Hardware inputs and implementation are pending for this example board."]
+next_action = ["Inventory the required memory and dma inputs before implementation."]
+evidence = []
+
+[[area]]
+id = "storage"
+status = "planned"
+components = []
+paths = ["drivers/ShengUfs", "scripts/*ufs*", "scripts/*storage*", "scripts/*userdata*", "scripts/*root*"]
+inputs = ["Identify the storage and root hardware, resources and existing component interfaces for this board."]
+configuration = ["Record the board.toml fields, DTS properties and defconfig values used for storage and root."]
+procedure = ["Follow the storage and root stage in the porting guide and record the actual commands."]
+findings = ["Collect the first storage and root observation, its cause when established, and the resulting implementation decision."]
+completion = ["Host: register, clock, link and SMMU facts match the board inventory.", "Reads: SCSI capacity, GPT and known blocks are correct; OS/SystemOS windows stay within userdata.", "Root: the configured volume mounts and launchd starts. Persistence: writes survive reboot within the allocated Data region."]
+limits = ["Hardware inputs and implementation are pending for this example board."]
+next_action = ["Inventory the required storage and root inputs before implementation."]
+evidence = []
+
+[[area]]
+id = "display"
+status = "planned"
+components = []
+paths = ["package/*Display*", "package/*Framebuffer*", "package/*Backlight*", "package/AppleARMBacklight.cpp", "package/GeniI2c*", "scripts/*display*", "scripts/*gop*", "scripts/*framebuffer*"]
+inputs = ["Identify the display hardware, resources and existing component interfaces for this board."]
+configuration = ["Record the board.toml fields, DTS properties and defconfig values used for display."]
+procedure = ["Follow the display stage in the porting guide and record the actual commands."]
+findings = ["Collect the first display observation, its cause when established, and the resulting implementation decision."]
+completion = ["A known frame appears with correct geometry and colors, then userland presentation and backlight controls work."]
+limits = ["Hardware inputs and implementation are pending for this example board."]
+next_action = ["Inventory the required display inputs before implementation."]
+evidence = []
+
+[[area]]
+id = "input"
+status = "planned"
+components = []
+paths = ["drivers/ShengHidInput", "drivers/ShengNovatekTouch", "package/*Touch*", "package/*Button*", "scripts/*touch*", "scripts/*hid*"]
+inputs = ["Identify the input hardware, resources and existing component interfaces for this board."]
+configuration = ["Record the board.toml fields, DTS properties and defconfig values used for input."]
+procedure = ["Follow the input stage in the porting guide and record the actual commands."]
+findings = ["Collect the first input observation, its cause when established, and the resulting implementation decision."]
+completion = ["Touches map to the display, simultaneous contacts keep stable IDs, release events arrive, and buttons produce expected HID reports."]
+limits = ["Hardware inputs and implementation are pending for this example board."]
+next_action = ["Inventory the required input inputs before implementation."]
+evidence = []
+
+[[area]]
+id = "gpu"
+status = "planned"
+components = []
+paths = ["package/*Gpu*", "package/*Gmu*", "package/*Adreno*", "scripts/*adreno*", "scripts/*gpu*", "scripts/*metal*", "scripts/*turnip*", "scripts/*air*"]
+inputs = ["Identify the gpu hardware, resources and existing component interfaces for this board."]
+configuration = ["Record the board.toml fields, DTS properties and defconfig values used for gpu."]
+procedure = ["Follow the gpu stage in the porting guide and record the actual commands."]
+findings = ["Collect the first gpu observation, its cause when established, and the resulting implementation decision."]
+completion = ["GPU submissions complete, mapping/fence handling is correct, a known image renders, and the selected Metal client presents it."]
+limits = ["Hardware inputs and implementation are pending for this example board."]
+next_action = ["Inventory the required gpu inputs before implementation."]
+evidence = []
+
+[[area]]
+id = "network"
+status = "planned"
+components = []
+paths = ["drivers/Ath12kWifi", "package/*Wifi*", "package/MhiBoot*", "scripts/*wifi*", "scripts/*mhi*"]
+inputs = ["Identify the network hardware, resources and existing component interfaces for this board."]
+configuration = ["Record the board.toml fields, DTS properties and defconfig values used for network."]
+procedure = ["Follow the network stage in the porting guide and record the actual commands."]
+findings = ["Collect the first network observation, its cause when established, and the resulting implementation decision."]
+completion = ["Scanning, association, address configuration and sustained receive/transmit traffic pass with the selected firmware."]
+limits = ["Hardware inputs and implementation are pending for this example board."]
+next_action = ["Inventory the required network inputs before implementation."]
+evidence = []
+
+[[area]]
+id = "audio"
+status = "planned"
+components = []
+paths = ["package/*Adsp*", "package/*Audio*", "package/*Gpr*", "package/QcomGlink*", "package/QcomMdt*", "package/QcomSmem*", "package/QcomSmp2p*", "scripts/*adsp*", "scripts/*audio*", "scripts/*gpr*"]
+inputs = ["Identify the audio hardware, resources and existing component interfaces for this board."]
+configuration = ["Record the board.toml fields, DTS properties and defconfig values used for audio."]
+procedure = ["Follow the audio stage in the porting guide and record the actual commands."]
+findings = ["Collect the first audio observation, its cause when established, and the resulting implementation decision."]
+completion = ["Each declared route carries the selected audio format through playback or capture and handles start/stop correctly."]
+limits = ["Hardware inputs and implementation are pending for this example board."]
+next_action = ["Inventory the required audio inputs before implementation."]
+evidence = []
+
+[[area]]
+id = "power"
+status = "planned"
+components = []
+paths = ["package/*Battery*", "package/*Battmgr*", "package/*Power*", "package/*PlatformPower*", "package/QcomQmp*", "package/QcomRpmh*", "package/QcomScm.h", "scripts/*power*", "scripts/*battery*", "scripts/*pmgr*"]
+inputs = ["Identify the power hardware, resources and existing component interfaces for this board."]
+configuration = ["Record the board.toml fields, DTS properties and defconfig values used for power."]
+procedure = ["Follow the power stage in the porting guide and record the actual commands."]
+findings = ["Collect the first power observation, its cause when established, and the resulting implementation decision."]
+completion = ["Declared power controls and battery readings match observations; each claimed sleep/resume transition restores its dependent peripherals."]
+limits = ["Hardware inputs and implementation are pending for this example board."]
+next_action = ["Inventory the required power inputs before implementation."]
+evidence = []
+
+[[area]]
+id = "packaging"
+status = "planned"
+components = []
+paths = ["scripts/*payload*", "scripts/*image*", "scripts/*flash*", "patches/**", "package/Kit.toml"]
+inputs = ["Identify the image assembly hardware, resources and existing component interfaces for this board."]
+configuration = ["Record the board.toml fields, DTS properties and defconfig values used for image assembly."]
+procedure = ["Follow the image assembly stage in the porting guide and record the actual commands."]
+findings = ["Collect the first image assembly observation, its cause when established, and the resulting implementation decision."]
+completion = ["Kernel and prelink succeed, payload contains all declared inputs, and the boot image matches the bootloader format and size limit."]
+limits = ["Hardware inputs and implementation are pending for this example board."]
+next_action = ["Inventory the required image assembly inputs before implementation."]
+evidence = []
+
+[[area]]
+id = "diagnostics"
+status = "planned"
+components = []
+paths = ["scripts/check-*", "scripts/probe-*", "scripts/audit-*", "scripts/read-*", "scripts/prepare-*", "scripts/data/**", "package/tests/**", "package/*Tests*", "package/*Diagnostic*", "package/*Probe*", "package/Boot*", "package/linux-log/**", "unixnu.lock"]
+inputs = ["Identify the diagnostics hardware, resources and existing component interfaces for this board."]
+configuration = ["Record the board.toml fields, DTS properties and defconfig values used for diagnostics."]
+procedure = ["Follow the diagnostics stage in the porting guide and record the actual commands."]
+findings = ["Collect the first diagnostics observation, its cause when established, and the resulting implementation decision."]
+completion = ["Each claimed milestone has a reproducible command, a matching source/image revision and an accessible result."]
+limits = ["Hardware inputs and implementation are pending for this example board."]
+next_action = ["Inventory the required diagnostics inputs before implementation."]
+evidence = []