First, What Is It

• Device model: through the HOSAL unified peripheral layer, the SDK abstracts every peripheral as a "device struct" (hosal_uart_dev_t, hosal_gpio_dev_t, etc.). The application simply defines a struct variable (e.g., hosal_uart_dev_t uart0;) and passes it to the peripheral APIs via &uart0 — the same pattern for every peripheral.
• Driver layering: the hosal_xxx_* APIs you call are the driver layer; internally they manipulate registers (LL layer) to control the hardware.
• Three data paths: polling (program reads actively), interrupt (hardware notifies), DMA (hardware moves data directly) — understanding these is understanding peripheral implementation.

Breaking Down the Principle

1. Unified Device Model

HOSAL abstracts each peripheral into a device struct hosal_xxx_dev_t (xxx is uart/gpio/i2c/spi/timer...); define the struct variable and fill in its config before using the peripheral:

hosal_uart_dev_t uart0;   /* Define the UART device struct */
hosal_gpio_dev_t gpio;    /* Define the GPIO device struct */

hosal_xxx_dev_t holds the port number (port) and configuration fields (config, e.g., pins, mode, speed). Once filled, every hosal_uart_*/hosal_gpio_* API takes its address (&dev) as the first argument — the universal pattern of all WB2 SDK examples.

2. Driver Layering

• API layer: application-facing, e.g., hosal_xxx_init, hosal_xxx_send/recv/output_set/input_get.
• HAL/LL layer: reads/writes registers directly (e.g., clock gating GLB_CGEN_* — see bl602_glb.h in the SDK; data registers); implementations differ per chip while the API layer stays stable.

3. The Standard Init and Operation Flow

Almost every peripheral example follows:

Example: UART is defining hosal_uart_dev_t uart0 (baud/data/parity/stop in config) → hosal_uart_init(&uart0) → receive interrupt or poll hosal_uart_receive.

4. Polling vs Interrupt vs DMA

Method	Principle	Pros	Cons	Use case
Polling	Loop checking status register	Simple, easy to debug	Occupies CPU	Low frequency, simple I/O
Interrupt	Hardware triggers a callback	Non-blocking, responsive	No heavy work in ISR	Buttons, UART receive
DMA	Hardware moves data into memory	CPU almost free, fast	Complex config, cache coherency	Bulk data (Flash, audio, display)

How the SDK Implements It

• Related pages: GPIO Output, UART, DMA Transfer, System & Software

GPIO as an example — "device model + init + operation":

hosal_gpio_dev_t gpio;                                              /* Define the device struct */
hosal_gpio_init(&gpio, GPIO_PIN_12, HOSAL_GPIO_OUTPUT_PUSH_PULL);  /* init mode: push-pull output */
hosal_gpio_output_set(&gpio, 1);                                    /* operate: output high */

All basic-peripheral pages (GPIO/UART/SPI/I2C/ADC/PWM/Timer...) share this skeleton — learn one, generalize to all.

Common Exam & Interview Questions

Why HOSAL device structs instead of direct register access?

The unified device model decouples driver APIs from the concrete chip: changing chip/instance only means redefining the struct and adjusting its config, and the application style stays the same; it also centralizes IRQ/clock resource management.

Difference between interrupt and DMA?

Interrupt: hardware calls the CPU to handle data. DMA: hardware moves data by itself and notifies the CPU when done. DMA frees the CPU from copying, ideal for large transfers.

Why define the device struct before peripheral init?

The struct encapsulates the port number, pins, mode, and speed; driver APIs access the specific peripheral through it — also the basis for driving multiple instances (e.g., two UARTs) with the same code: just define one struct instance per device.

Relation between the LL layer and the API layer?

The API layer is application-facing and stable across chips; the LL/HAL layer touches registers and changes with the chip. Platform changes usually only swap the LL implementation, leaving app code untouched.

When is polling unacceptable?

When events are sparse but the program is busy (receiving UART, scanning keys, running a UI), polling wastes CPU and adds latency — switch to interrupt or DMA.

Have questions?

For any other questions, visit the unified Q&A and discussion board: Ai-Thinker Discussions