docs: reorganize T153MX Linux guides

Author: codebug8

docs/T153MX/01-BoardIntroduction.md

@@ -16,6 +16,29 @@ OmniGate-T153 是一款基于全志 T153MX 的工业边缘网关开发板，由
 
 :::
 
+## 目标
+
+通过本页确认 OmniGate-T153 的核心板、扩展底板、主要接口和软件支持状态，并找到从获取板级 overlay 到首次进入 Linux Shell 的最短路径。
+
+## 准备工作
+
+- OmniGate-T153 开发板及对应批次的原理图、BOM 或硬件说明。
+- 稳定电源、USB 数据线和调试串口连接。
+- Ubuntu 开发主机及可用的 T153 Tina SDK。
+
+不同批次的内存、eMMC、无线和 4G 模块可能不同。开始实验前应以实物和当前批次资料核对，不能只根据同系列板卡推断。
+
+## 操作步骤
+
+1. 查看下方产品组成和资源表，确认核心板与底板版本。
+2. 克隆板级适配仓库，将 overlay 应用到完整 Tina SDK。
+3. 选择 `t153_omnigate_mmc-buildroot`，完成编译和打包。
+4. 核对镜像路径和目标设备后烧录，通过调试串口观察首次启动。
+
+## 验证方法
+
+启动后应能从串口进入开发板 Linux Shell。使用 `uname -a`、`cat /proc/partitions` 和对应接口的设备节点确认运行内核、存储与板级配置；未完成板端验证的功能仍以本页状态表为准。
+
 ## 产品组成
 
 ### mCore-T153MX 核心板
@@ -44,6 +67,37 @@ OmniGate 扩展底板为核心板提供双 4G、双千兆以太网、工业总
 
 ![OmniGate-T153 背面双 4G 模块位](./images/DshanPI-OminiGate-2.png)
 
+### 硬件功能关系示意
+
+```mermaid
+flowchart TB
+    SOC[T153MX<br/>4× Cortex-A7 + E907]
+    DDR[DDR4]
+    EMMC[eMMC]
+    NET[2× 千兆以太网]
+    CELL[2× 4G / SIM]
+    BUS[2× CAN FD<br/>2× RS485]
+    WIFI[Wi-Fi 6 / Bluetooth 5]
+    DISP[MIPI DSI / RGB LCD]
+    CAM[MIPI CSI]
+    USB[USB Type-C / USB 3.0]
+    DEBUG[UART0 调试串口]
+
+    SOC --- DDR
+    SOC --- EMMC
+    SOC --- NET
+    SOC --- CELL
+    SOC --- BUS
+    SOC --- WIFI
+    SOC --- DISP
+    SOC --- CAM
+    SOC --- USB
+    SOC --- DEBUG
+```
+
+该图表示功能连接关系，不表示具体引脚号。电平、复用、供电和连接器脚位仍应以对应批次原理图
+及设备树为准。
+
 ## 主要硬件资源
 
 | 类别 | 板载资源 |
@@ -81,7 +135,25 @@ OmniGate 扩展底板为核心板提供双 4G、双千兆以太网、工业总
 
 “已配置”表示板级配置中已经启用相关控制器，不代表所有外接设备、线材和应用场景均完成验证。
 
-## 获取板级适配仓库
+## 获取开发资料
+
+### 获取 T153MX 基础 SDK
+
+基础开发包通过百度网盘提供：
+
+- 文件夹：`DshanPI-OminiGate_T153MX`
+- 下载链接：[https://pan.baidu.com/s/1ai6yzYs5ujDba-luz-JeXw](https://pan.baidu.com/s/1ai6yzYs5ujDba-luz-JeXw)
+- 提取码：`6mtk`
+
+下载完成后，先阅读[Tina SDK 开发环境搭建](./part3/01-DevelopmentEnvironmentSetup.md)。网盘文件夹名称不等于解压后的 SDK 根目录；能够看到 `build/envsetup.sh`、`build.sh`、`device/`、`kernel/` 和 `buildroot/` 的目录才是 SDK 根目录。
+
+:::tip 建议保留原始包
+
+首次解压后不要直接覆盖唯一副本。建议保留一份未修改的基础 SDK，用于比对板级修改、恢复误删文件和重新生成 overlay 补丁。
+
+:::
+
+### 获取 OmniGate 板级适配仓库
 
 ```bash
 git clone https://github.com/dshanpi/T153MX-Tina5SDK_OmniGate.git
@@ -110,27 +182,39 @@ T153MX-Tina5SDK_OmniGate/
 
 ## 编译与打包
 
-在已经应用 overlay 的 Tina SDK 根目录执行：
+完整的主机依赖、SDK 检查、编译和产物验证步骤见[Tina SDK 开发环境搭建](./part3/01-DevelopmentEnvironmentSetup.md)。下面仅列出已经配置好环境后的最短命令。
+
+在已经应用 overlay 的 Tina SDK 根目录，首次先执行交互式方案配置：
 
 ```bash
 source build/envsetup.sh
-lunch t153_omnigate_mmc-buildroot
-make
-pack
+./build.sh config
+```
+
+按名称选择 `linux`、`buildroot`、`t153`、`omnigate`、`default` 和 `linux-5.10-origin`，该组合
+对应 `t153_omnigate_mmc-buildroot`。随后执行：
+
+```bash
+./build.sh
+./build.sh pack
 ```
 
 当前镜像输出名称：
 
 ```text
-out/t153_linux_omnigate_uart0.img
+out/t153/omnigate/buildroot/t153_linux_omnigate_uart0.img
 ```
 
+启用对应无线配置时，也可能生成 `t153_linux_omnigate_uart0-wifi1.img`。烧录前必须根据本次 `pack` 的时间戳和构建配置选择镜像，不能只按文件名猜测。
+
 烧录和串口调试前请确认目标设备、USB 连接和镜像路径，避免误写其他存储设备。
 
 ## 调试资料
 
+- [板载功能体验](./part2/01-Ethernet.md)
+- [HelloWorld 应用开发](./part4/01-HelloWorld.md)
 - [OmniGate 板级仓库](https://github.com/dshanpi/T153MX-Tina5SDK_OmniGate)
 - [WLAN、Bluetooth 与 PCM 调试记录](https://github.com/dshanpi/T153MX-Tina5SDK_OmniGate/blob/main/docs/wlan-bluetooth-bringup.md)
 - [MIPI DSI 4-Lane 屏调试记录](https://github.com/dshanpi/T153MX-Tina5SDK_OmniGate/blob/main/docs/mipi-dsi-debug-record.md)
 - [Bluetooth 音响交付变更说明](https://github.com/dshanpi/T153MX-Tina5SDK_OmniGate/blob/main/docs/bluetooth-speaker-change-set.md)
-- [OmniGate AMP Shell 异构开发](./02-DevelopmentGuides/09-omnigate-amp-shell-guide.md)
+- [OmniGate AMP Shell 异构开发](./part5/05-OmniGateAMPShell.md)

docs/T153MX/02-DevelopmentGuides/00-Overview.md

@@ -0,0 +1,48 @@
+---
+sidebar_position: 2
+sidebar_label: 源码、工具与手册
+---
+
+# 源码、工具与手册
+
+本页面汇总 OmniGate-T153 开发所需的 SDK、板级适配、烧录工具和参考资料。
+
+## 基础 SDK
+
+- 网盘文件夹：`DshanPI-OminiGate_T153MX`
+- 下载链接：[百度网盘](https://pan.baidu.com/s/1ai6yzYs5ujDba-luz-JeXw)
+- 提取码：`6mtk`
+
+下载并解压后，能同时看到 `build/envsetup.sh`、`build.sh`、`device/`、`kernel/` 和 `buildroot/` 的目录才是 SDK 根目录。
+
+## OmniGate 板级适配
+
+- 板级仓库：[T153MX-Tina5SDK_OmniGate](https://github.com/dshanpi/T153MX-Tina5SDK_OmniGate)
+- 编译方案：`t153_omnigate_mmc-buildroot`
+- Linux：5.10.198
+- Buildroot：2022.05
+
+基础 SDK 和板级适配不是同一份资料。先准备完整 SDK，再按仓库说明应用 OmniGate overlay。
+
+## 烧录和串口工具
+
+| 主机 | 工具 | 用途 |
+| --- | --- | --- |
+| Ubuntu | SDK `tools/OpenixCLI/openixcli` | 扫描设备、检查镜像、烧录 |
+| Windows | PhoenixSuit | 全志完整镜像烧录 |
+| Ubuntu | picocom/minicom | UART0 串口终端 |
+| Windows | MobaXterm/PuTTY | UART0 串口终端 |
+
+## 硬件资料
+
+OmniGate-T153 原理图、位号图和不同批次 BOM：`TODO: 待补充发布链接`。
+
+在链接补齐前，CAN、RS485、4G、显示和摄像头的具体连接器脚位以随板资料和 PCB 丝印为准，不从相似型号推断。
+
+## 文档入口
+
+- [快速启动](./part1/01-QuickStart.md)
+- [板载功能体验](./part2/01-Ethernet.md)
+- [Tina SDK 开发](./part3/01-DevelopmentEnvironmentSetup.md)
+- [应用开发](./part4/01-HelloWorld.md)
+- [进阶专题](./part5/01-USB.md)

docs/T153MX/02-DevelopmentGuides/_category_.json

@@ -0,0 +1,52 @@
+---
+sidebar_position: 3
+sidebar_label: 安装并配置开发环境
+---
+
+# 安装并配置开发环境
+
+本章节说明 OmniGate-T153 开发主机的基本要求。SDK 的完整编译步骤见[Tina SDK 开发环境搭建](./part3/01-DevelopmentEnvironmentSetup.md)。
+
+## 准备 Ubuntu 主机
+
+推荐使用 Ubuntu 20.04 或 22.04 64 位系统，预留不少于 100 GB 可用磁盘空间。SDK 不要放在 NTFS/FAT 共享目录，也不要使用包含空格和中文的路径。
+
+在 **Ubuntu 主机**执行：
+
+```bash
+uname -m
+lsb_release -ds
+df -h .
+```
+
+`uname -m` 应输出 `x86_64`。
+
+## 安装编译依赖
+
+```bash
+sudo apt update
+sudo apt install -y build-essential gcc-multilib g++-multilib \
+  git gawk flex bison gettext texinfo libncurses5-dev libncursesw5-dev \
+  libssl-dev python3 python-is-python3 rsync unzip zlib1g-dev file bc \
+  cpio wget curl patch device-tree-compiler adb
+```
+
+## 安装串口工具
+
+```bash
+sudo apt install -y picocom
+```
+
+连接 USB 转串口后查看设备：
+
+```bash
+ls -l /dev/ttyUSB* /dev/ttyACM* 2>/dev/null
+```
+
+找到实际串口后，以 115200 8N1 打开：
+
+```bash
+sudo picocom -b 115200 <SERIAL_DEVICE>
+```
+
+`<SERIAL_DEVICE>` 替换为实际节点，例如 `/dev/ttyUSB0`。按 `Ctrl+A`、再按 `Ctrl+X` 退出 picocom。

docs/T153MX/02-SourceCodeToolDocumentationManual.md

@@ -1,6 +1,6 @@
 {
   "label": "HAL V2",
-  "position": 3,
+  "position": 9,
   "link": {
     "type": "generated-index",
     "title": "HAL V2",

docs/T153MX/03-ConfigHostEnv.md

@@ -3,6 +3,7 @@
   "position": 2,
   "link": {
     "type": "generated-index",
-    "description": "5 minutes to learn the most important Docusaurus concepts."
+    "title": "T153MX",
+    "description": "DshanPi OmniGate-T153 单板介绍、Linux 开发指南与 HAL V2 参考。"
   }
 }

docs/T153MX/03-HALV2/_category_.json

@@ -0,0 +1,72 @@
+---
+sidebar_position: 1
+sidebar_label: 启动开发板
+---
+
+# 启动 OmniGate-T153
+
+本章节将完成 OmniGate-T153 的电源、调试串口和 USB 连接，并进入 Linux Shell。
+
+## 准备工作
+
+**硬件：**
+
+- OmniGate-T153 开发板
+- 与板卡要求匹配的稳定电源
+- 3.3 V USB 转串口模块
+- USB 数据线
+
+**软件：**
+
+- Ubuntu：picocom/minicom
+- Windows：MobaXterm/PuTTY
+
+## 连接开发板
+
+开发板外观如下：
+
+![OmniGate-T153 开发板接口](../images/DshanPI-OminiGate-1.png)
+
+调试串口接线：
+
+```text
+USB 转串口          OmniGate-T153 UART0
+GND       --------  GND
+TXD       --------  RXD
+RXD       --------  TXD
+VCC       --------  不连接
+```
+
+TX/RX 需要交叉连接，串口模块必须是 3.3 V TTL 电平，不能使用 RS232 电平。UART0 排针的准确位置以 PCB 丝印和对应批次原理图为准。
+
+## 打开串口终端
+
+在 **Ubuntu 主机**查看串口设备：
+
+```bash
+ls -l /dev/ttyUSB* /dev/ttyACM* 2>/dev/null
+```
+
+打开串口：
+
+```bash
+sudo picocom -b 115200 <SERIAL_DEVICE>
+```
+
+Windows 串口参数同样设置为 115200、8 数据位、无校验、1 停止位、无流控。
+
+## 启动开发板
+
+确认接线无误后接通板卡电源。串口终端会依次打印 Boot0、U-Boot 和 Linux 日志，最后进入 Linux Shell。
+
+在 **开发板 Linux Shell**执行：
+
+```bash
+uname -a
+uname -m
+cat /proc/partitions
+```
+
+可以看到 Linux 5.10、`armv7l` 和 eMMC 分区信息，说明开发板已经正常启动。
+
+如果串口完全没有输出，先检查供电、GND、TX/RX 是否接反和串口设备是否选错；如果输出乱码，确认波特率为 115200。