Skip to content

Commit f5f80ba

Browse files
GuEe-GUIGuEe-GUI
committed
[docs] device-driver: add DM subsystem docs and expand INDEX
Add Doxygen pages for RT-Thread device-model drivers: platform/OFW, DM core (bus, dm, power), clk/regulator/reset/power-domain, PCI/PIC, Phye, DMA/hwcache, block/SCSI/ATA/NVMe/UFS/SDIO, SCMI, RPMsg, mailbox, NVMem, NUMA, syscon, thermal, input/LED/IIO/graphic, and related power/charger/supply docs. Expand device-driver INDEX.md with ~90 @subpage entries so all new pages appear in the driver chapter navigation. Update existing UART/SPI/RTC/pin/framework/dtc pages: UART docs moved from serial/ to uart/ (uart + uart_dm + uart_earlycon); SPI and RTC gain DM companion pages; pin links to pin_dm; framework points at DM topics. Focus on registration/probe flow and in-tree APIs; no standalone VirtIO subsystem page (transport code still incomplete). Test plan: build Doxygen for documentation/ and verify device-driver INDEX links resolve without missing @ref/@subpage warnings. Signed-off-by: GuEe-GUI <2991707448@qq.com>
1 parent 3f6a21d commit f5f80ba

102 files changed

Lines changed: 13983 additions & 29 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎documentation/6.components/device-driver/INDEX.md‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,15 +2,110 @@
22

33
- @subpage page_device_framework
44
- @subpage page_device_pin
5+
- @subpage page_device_pin_dm
6+
- @subpage page_device_pinctrl
57
- @subpage page_device_uart
8+
- @subpage page_device_uart_dm
9+
- @subpage page_device_uart_earlycon
610
- @subpage page_device_adc
711
- @subpage page_device_i2c
12+
- @subpage page_device_i2c_dm
813
- @subpage page_device_spi
14+
- @subpage page_device_spi_dm
915
- @subpage page_device_pwm
1016
- @subpage page_device_rtc
17+
- @subpage page_device_rtc_dm
1118
- @subpage page_device_clock_time
19+
- @subpage page_device_hwtimer
1220
- @subpage page_device_watchdog
1321
- @subpage page_device_wlan
1422
- @subpage page_device_sensor
1523
- @subpage page_device_audio
24+
- @subpage page_device_ofw
25+
- @subpage page_device_ofw_base
26+
- @subpage page_device_ofw_boot
27+
- @subpage page_device_ofw_io
28+
- @subpage page_device_ofw_irq
29+
- @subpage page_device_ofw_raw
30+
- @subpage page_device_ofw_platform
1631
- @subpage page_device_dtc
32+
- @subpage page_device_ata
33+
- @subpage page_device_blk
34+
- @subpage page_device_disk
35+
- @subpage page_device_partitions
36+
- @subpage page_device_hwcache
37+
- @subpage page_device_can
38+
- @subpage page_device_can_dm
39+
- @subpage page_device_clk
40+
- @subpage page_device_clk_fixed
41+
- @subpage page_device_bus
42+
- @subpage page_device_dm
43+
- @subpage page_device_dm_power
44+
- @subpage page_device_dma
45+
- @subpage page_device_dma_pool
46+
- @subpage page_device_graphic_dm
47+
- @subpage page_device_graphic_backlight
48+
- @subpage page_device_graphic_framebuffer
49+
- @subpage page_device_graphic_logo
50+
- @subpage page_device_hwspinlock
51+
- @subpage page_device_iio
52+
- @subpage page_device_iio_dm
53+
- @subpage page_device_input
54+
- @subpage page_device_input_dm
55+
- @subpage page_device_input_uapi
56+
- @subpage page_device_input_touch
57+
- @subpage page_device_input_power
58+
- @subpage page_device_led
59+
- @subpage page_device_led_dm
60+
- @subpage page_device_mailbox
61+
- @subpage page_device_mailbox_dm
62+
- @subpage page_device_numa
63+
- @subpage page_device_nvme
64+
- @subpage page_device_nvme_dm
65+
- @subpage page_device_nvmem
66+
- @subpage page_device_nvmem_dm
67+
- @subpage page_device_pci
68+
- @subpage page_device_pci_probe
69+
- @subpage page_device_pci_access
70+
- @subpage page_device_pci_host
71+
- @subpage page_device_pci_irq
72+
- @subpage page_device_pci_pme
73+
- @subpage page_device_pci_msi
74+
- @subpage page_device_pci_ofw
75+
- @subpage page_device_pci_bridge
76+
- @subpage page_device_pci_endpoint
77+
- @subpage page_device_phye
78+
- @subpage page_device_phye_core
79+
- @subpage page_device_phye_ofw
80+
- @subpage page_device_phye_provider
81+
- @subpage page_device_phye_consumer
82+
- @subpage page_device_phye_generic_usb
83+
- @subpage page_device_pic
84+
- @subpage page_device_pic_irq_domain
85+
- @subpage page_device_pic_core
86+
- @subpage page_device_pic_cascade
87+
- @subpage page_device_pic_ofw
88+
- @subpage page_device_pic_msi
89+
- @subpage page_device_pic_examples
90+
- @subpage page_device_platform
91+
- @subpage page_device_power
92+
- @subpage page_device_power_supply
93+
- @subpage page_device_power_charger
94+
- @subpage page_device_power_board_reset
95+
- @subpage page_device_power_domain
96+
- @subpage page_device_regulator
97+
- @subpage page_device_reset
98+
- @subpage page_device_rpmsg
99+
- @subpage page_device_rpmsg_char
100+
- @subpage page_device_rpmsg_ns
101+
- @subpage page_device_scmi
102+
- @subpage page_device_scmi_agent
103+
- @subpage page_device_scsi
104+
- @subpage page_device_sdio
105+
- @subpage page_device_sdio_dm
106+
- @subpage page_device_sdio_regulator
107+
- @subpage page_device_sdhci
108+
- @subpage page_device_syscon
109+
- @subpage page_device_thermal
110+
- @subpage page_device_thermal_cool
111+
- @subpage page_device_ufs

‎documentation/6.components/device-driver/ata/ata.md‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
@page page_device_ata ATA / AHCI
2+
3+
# AHCI host abstraction (`ahci.h`)
4+
5+
This page documents **`struct rt_ahci_host`**, **`struct rt_ahci_ops`**, and per-port **`struct rt_ahci_port`** in **`drivers/ahci.h`**, as driven by **`rt_ahci_host_register` / `rt_ahci_host_unregister`** in `components/drivers/ata/ahci.c`.
6+
7+
## `struct rt_ahci_host` (caller fills before `rt_ahci_host_register`)
8+
9+
```368:383:components/drivers/include/drivers/ahci.h
10+
struct rt_ahci_host
11+
{
12+
struct rt_scsi_host parent;
13+
14+
int irq;
15+
void *regs;
16+
17+
rt_size_t ports_nr;
18+
rt_uint32_t ports_map;
19+
struct rt_ahci_port ports[32];
20+
21+
rt_uint32_t cap;
22+
rt_uint32_t max_blocks;
23+
24+
const struct rt_ahci_ops *ops;
25+
};
26+
```
27+
28+
| Member | Owner | Meaning |
29+
| --- | --- | --- |
30+
| `parent` | **Caller** | Embedded **`rt_scsi_host`**; **`parent.dev` must be non-NULL** (used for `rt_dma_alloc_coherent`, etc.). |
31+
| `irq` | **Caller** | Global host IRQ; the core installs the ISR with `struct rt_ahci_host *` as parameter. |
32+
| `regs` | **Caller** | Virtual base of the HBA (AHCI 1.0) register block. |
33+
| `ports_nr` | **Core** | Filled from **`CAP.NP`**; do not rely on the initial value. |
34+
| `ports_map` | **Core (DT may override)** | Read from **`PI`**; if the node has **`ports-implemented`**, that property wins. |
35+
| `ports[]` | **Core + ops** | See **Per-port state** below. |
36+
| `cap` | **Core** | Read from **`RT_AHCI_HBA_CAP`** (masked); used with SG paths for **64-bit DMA** (**`RT_AHCI_CAP_64`**, etc.). |
37+
| `max_blocks` | **Caller (may be 0)** | Max blocks per SCSI split; **0** is replaced with **`0x80`** at register time. |
38+
| `ops` | **Caller** | **Required**; every callback is optional (**`NULL`** = core default), but failures in **`host_init` / `port_init` / `port_dma_init`** skip the port or log DMA errors. |
39+
40+
## `struct rt_ahci_port` (fields visible to `ops`)
41+
42+
```346:366:components/drivers/include/drivers/ahci.h
43+
struct rt_ahci_port
44+
{
45+
void *regs;
46+
47+
void *dma;
48+
rt_ubase_t dma_handle;
49+
50+
struct rt_ahci_cmd_hdr *cmd_slot;
51+
struct rt_ahci_sg *cmd_tbl_sg;
52+
void *cmd_tbl;
53+
rt_ubase_t cmd_tbl_dma;
54+
void *rx_fis;
55+
56+
rt_uint32_t int_enabled;
57+
rt_size_t block_size;
58+
59+
rt_uint16_t *ataid;
60+
61+
rt_bool_t link;
62+
struct rt_completion done;
63+
};
64+
```
65+
66+
| Member | Owner | Meaning |
67+
| --- | --- | --- |
68+
| `regs` | **Core** | `host->regs + 0x100 + port_index * 0x80`; valid before **`port_init`**. |
69+
| `dma`, `dma_handle`, `cmd_slot`, `rx_fis`, `cmd_tbl`, `cmd_tbl_dma`, `cmd_tbl_sg` | **Core** | After **`link == RT_TRUE`**, **`RT_AHCI_DMA_SIZE`** coherent memory is allocated and laid out; **`CLB`/`CLBU`**, **`FB`/`FBU`** programmed. |
70+
| `int_enabled` | **Core** | **`RT_AHCI_PORT_INTE_*`** mask written to **`PORT_INTE`** after DMA engines start. |
71+
| `block_size` | **Core** | **512** or **2048** from Identify / Inquiry and **SIG** / **ATAPI**. |
72+
| `ataid` | **Core** | Identify buffer; used with **`rt_ahci_ata_id_*`** helpers. |
73+
| `link` | **Core** | **`RT_TRUE`** when link is up; ISR calls **`port_isr`** and **`rt_completion_done`** only if **`link`**. |
74+
| `done` | **Core** | **`rt_completion_init`**; command path **`rt_completion_wait(&port->done, …)`** after **`PORT_CI`**; **`port_isr`** must stay consistent with **`done`**. |
75+
76+
In **`port_init` / `port_dma_init`** you may touch **`port->regs`** and other HW state not yet filled by the core. **Do not assume `dma` exists inside `port_init`** (DMA is allocated only after a successful link).
77+
78+
## `struct rt_ahci_ops` (order inside `rt_ahci_host_register`)
79+
80+
```385:392:components/drivers/include/drivers/ahci.h
81+
struct rt_ahci_ops
82+
{
83+
rt_err_t (*host_init)(struct rt_ahci_host *host);
84+
rt_err_t (*port_init)(struct rt_ahci_host *host, struct rt_ahci_port *port);
85+
rt_err_t (*port_link_up)(struct rt_ahci_host *host, struct rt_ahci_port *port);
86+
rt_err_t (*port_dma_init)(struct rt_ahci_host *host, struct rt_ahci_port *port);
87+
rt_err_t (*port_isr)(struct rt_ahci_host *host, struct rt_ahci_port *port, rt_uint32_t isr);
88+
};
89+
```
90+
91+
| Callback | When | Role |
92+
| --- | --- | --- |
93+
| **`host_init`** | After HBA soft reset, **`GHC.AHCI_EN`**, **CAP** read/mask, **`PI` write**, before port enumeration. | Optional. HBA-level, clocks, PHY, vendor regs; non-**`RT_EOK`** fails **`rt_ahci_host_register`**. |
94+
| **`port_init`** | After **`PORT_CMD`** has **LIST_ON/FIS_ON/START/FIS_RX** cleared and the port has quiesced, before **SPIN_UP**. | Optional. Port reset, **`SCTL`**, non-standard **SIG**; **`port->regs`** valid. Failure **`continue`**s the port. |
95+
| **`port_link_up`** | After **`port_init`** and the core has set **SPIN_UP**. | Optional. If **`NULL`**, core polls **`SSTS.DET`** for **`PHYRDY`**. Must return **`RT_EOK`** when the link is usable. |
96+
| **`port_dma_init`** | After **`CLB`/`FB`** and DMA buffers are programmed, before the core writes **`PORT_CMD`** (ACTIVE, FIS_RX, POWER_ON, SPIN_UP, START). | Optional. Extra SoC DMA/port setup; errors are logged but the core still asserts **`PORT_CMD`**. |
97+
| **`port_isr`** | Global ISR: bit set in **`HBA_INTS`**, **`port->link`**, **`PORT_INTS`** read into **`isr`**. | Optional. SoC-specific IRQ handling; core always **`rt_completion_done(&port->done)`** and clears **`PORT_INTS`**. |
98+
99+
### Common integration pitfalls
100+
101+
- **`port_init` vs DMA**: **`port->dma` is not allocated yet** inside **`port_init`**—only touch **`port->regs`** and PHY-level setup there.
102+
- **`port_dma_init` errors are logged only**: the core still enables **`PORT_CMD`**—if your SoC cannot run without extra setup, fail earlier in **`port_link_up`** instead.
103+
- **`port_isr`**: if you override, ensure you still cooperate with **`rt_completion_done`** semantics expected by **`ahci.c`** command path, or commands hang.
104+
- **64-bit DMA**: honor **`RT_AHCI_CAP_64`** when building PRDT—SG list addresses must match HBA capability.
105+
106+
## Registration API
107+
108+
| API | Role |
109+
| --- | --- |
110+
| **`rt_ahci_host_register(host)`** | Validates **`host`**, **`host->parent.dev`**, **`host->ops`**; HBA reset, ports, link, DMA, **`rt_scsi_host_register`**, IRQ. |
111+
| **`rt_ahci_host_unregister(host)`** | Masks IRQ, frees per-port DMA, unregisters the SCSI host. |
112+
113+
## See also
114+
115+
- `components/drivers/include/drivers/ahci.h` (**`RT_AHCI_*`**, **`struct rt_ahci_cmd_hdr`**, **`struct rt_ahci_sg`**)
116+
- `components/drivers/ata/ahci.c`
117+
118+
**Same documentation pattern** (fill structs + `ops` + register order): `documentation/6.components/device-driver/ufs/ufs.md`, `nvme/nvme.md`, `scsi/scsi.md` (section 1), `block/disk.md`, `dma/dma.md` (section 1).

0 commit comments

Comments
 (0)