周邊 I/O¶

GPIO、UART、SPI、I2C、PWM、ADC、DAC、類比比較器、KeyScan、QDEC 與 DMA。說明取自標頭檔註解（英文）。

hal_gpio.h¶

#include "hal_gpio.h"（原始碼）

GPIO driver: pin mode, read/write and pin interrupts.

Pins are addressed by their GPIO number. gpio_set_mode() routes the pin to the GPIO function and sets direction and pull resistor (or an interrupt trigger). All pin interrupts share one CPU interrupt line; to get a callback for a pin:

1. gpio_set_mode() with one of the interrupt modes (this leaves the pin interrupt masked),
2. gpio_attach_irq() to register the callback,
3. gpio_irq_enable() with enabled = 1 to unmask the pin interrupt.

gpio_set_mode¶

void gpio_set_mode(uint32_t pin, uint32_t mode);

Configure a pin as GPIO with the given mode.

Selects the GPIO function, drive strength 0 and the Schmitt-trigger input. For the interrupt modes the shared GPIO interrupt is disabled in the CPU while the pin is being set up and enabled again afterwards. Unknown mode values are ignored.

gpio_write¶

void gpio_write(uint32_t pin, uint32_t value);

Set the output level of a pin.

gpio_toggle¶

void gpio_toggle(uint32_t pin);

Invert the output level of a pin.

gpio_read¶

int gpio_read(uint32_t pin);

Read the input level of a pin.

回傳值：1 if the pin is high, 0 if it is low.

gpio_attach_irq¶

void gpio_attach_irq(uint32_t pin, void(*cbfun)(uint32_t pin));

Register a callback for a pin interrupt.

Adds the pin to the list served by the shared GPIO interrupt handler, installs that handler and enables the GPIO interrupt in the CPU. The callback runs in interrupt context; the driver clears the pin's interrupt status after the callback returns. Each call allocates a list entry with malloc(); there is no function to remove an entry.

gpio_irq_enable¶

void gpio_irq_enable(uint32_t pin, uint8_t enabled);

Unmask or mask the interrupt of a pin.

gpio_pin_type¶

GPIO numbers 0 to 31.

The pin argument of the GPIO functions is the plain GPIO number, so these names are optional.

巨集¶

hal_uart.h¶

#include "hal_uart.h"（原始碼）

UART driver: configuration, polling and DMA transfers, interrupts.

Each UART has a device record (uart_device_t) initialised from the board configuration (UART0_CONFIG, UART1_CONFIG). uart_init() applies it and selects the transfer mode with COMMON_CAPS_* flags:

• Polling (flags 0): uart_write() blocks until the data is in the TX FIFO; uart_read() and uart_read_available() return the bytes already received.
• DMA (COMMON_CAPS_DMA_TX / COMMON_CAPS_DMA_RX): attach a configured DMA channel (see hal_dma.h) with UART_CTRL_ATTACH_TX_DMA / UART_CTRL_ATTACH_RX_DMA after uart_init(); uart_write() and uart_read() then start a DMA transfer and return immediately.

For interrupt-driven reception, register a callback with uart_set_callback() and enable the interrupts with UART_CTRL_SET_INT, then read the data with uart_read_available() when UART_EVENT_RX_FIFO arrives. Compile-time line options are in uart_config.h.

uart_init¶

int uart_init(int uart_id, uint16_t oflag);

Initialise a UART from its device record.

Applies baud rate, data bits, stop bits and parity from the device record (board configuration or uart_set_baudrate()), the options of uart_config.h, the FIFO threshold and the RX time-out (UART_DEFAULT_RTO_TIMEOUT); enables TX free-run mode and the RX deglitch filter; clears both FIFOs; enables the transmitter and receiver; and installs the UART interrupt handler. All UART interrupts stay masked and the CPU interrupt stays disabled until UART_CTRL_SET_INT. Any DMA channels attached earlier are detached.

回傳值：0.

uart_uninit¶

int uart_uninit(int uart_id);

Reset a UART.

Applies a software reset to the UART block. Call uart_init() before using the UART again.

回傳值：0.

uart_ioctl¶

int uart_ioctl(int uart_id, int cmd, void *args);

Execute a UART control command.

回傳值：For UART_CTRL_GET_TX_FIFO and UART_CTRL_GET_RX_FIFO: the FIFO count. 0 for all other commands; unknown commands are ignored.

uart_write¶

int uart_write(int uart_id, const void *buffer, uint32_t size);

Send data.

• Polling mode: blocks until every byte has been written into the TX FIFO (not until it has left the wire).
• DMA mode: starts a DMA transfer from buffer and returns immediately. The buffer must stay valid until the transfer completes (DMA callback, or dma_channel_check_busy()); a new call stops a transfer still in progress. The data cache is not cleaned for buffer.
• Interrupt mode (COMMON_CAPS_INT_TX): not supported, returns -2.

回傳值：0 on success. In polling mode, a non-zero status if the TX FIFO stays full for too long. In DMA mode, -1 if no TX DMA channel is attached, or the negative error of dma_reload(). -2 in interrupt mode.

uart_read¶

int uart_read(int uart_id, void *buffer, uint32_t size);

Receive data.

• Polling mode: does not block; copies up to size bytes that are already in the RX FIFO.
• DMA mode: starts a DMA transfer of exactly size bytes into buffer and returns immediately; completion is reported by the DMA callback. The data cache is not invalidated for buffer.
• Interrupt mode (COMMON_CAPS_INT_RX): not supported, returns -2.

回傳值：Polling mode: number of bytes copied (0 if none). DMA mode: 0 on success, -1 if no RX DMA channel is attached, or the negative error of dma_reload(). -2 in interrupt mode.

uart_int_tx_enable¶

int uart_int_tx_enable(uint8_t id);

Unmask the TX FIFO request interrupt.

The UART interrupt must also be enabled in the CPU (UART_CTRL_SET_INT) for UART_EVENT_TX_FIFO to be delivered.

回傳值：0.

uart_int_tx_disable¶

int uart_int_tx_disable(uint8_t id);

Mask the TX FIFO request interrupt.

回傳值：0.

uart_set_baudrate¶

void uart_set_baudrate(int uart_id, int baudrate);

Store the baud rate used by the next uart_init().

The hardware is not changed; use UART_CTRL_CONFIG to change the baud rate of a running UART.

uart_set_callback¶

void uart_set_callback(int uart_id, void *args);

Set the event callback of a UART.

uart_getDevice¶

uart_device_t * uart_getDevice(int uart_id);

Get the driver's device record of a UART.

回傳值：Pointer to the internal record.

uart_read_available¶

int uart_read_available(int uart_id, void *buffer, uint32_t max_size);

Read available data from the UART RX FIFO (non-blocking).

Copies the bytes already in the RX FIFO, up to max_size, in any transfer mode. It can be called from the UART callback.

回傳值：Number of bytes actually read (0 if the FIFO is empty).

匿名列舉¶

Commands for uart_ioctl().

uart_index_type¶

UART index (the uart_id argument of the UART functions).

uart_databits_t¶

Number of data bits per character.

uart_stopbits_t¶

Number of stop bits.

uart_parity_t¶

Parity mode.

uart_event_type¶

Events passed to the UART callback (uart_device_t::callback).

The callback runs in the UART interrupt handler.

uart_it_type¶

Interrupt flags for UART_CTRL_SET_INT and UART_CTRL_CLR_INT.

uart_param_cfg_t¶

Line settings for UART_CTRL_CONFIG.

uart_device_t¶

Configuration and state of one UART.

The driver keeps one record per UART; get it with uart_getDevice().

巨集¶

uart_config.h¶

#include "uart_config.h"（原始碼）

Compile-time UART line options used by the UART driver (hal_uart.h).

uart_init() and UART_CTRL_CONFIG apply these values to every UART. A value of 1 enables an option, 0 disables it.

巨集¶

hal_spi.h¶

#include "hal_spi.h"（原始碼）

SPI controller driver: configuration, blocking transfers, FIFO and DMA control, interrupt callback.

The HAL keeps one spi_device_t per controller, initialised from the board's SPI0_CONFIG / SPI1_CONFIG defaults. Typical sequence: fill an spi_device_t and pass it to spi_setConfig(), then spi_init(), spi_enable() with 1, then spi_transmit(), spi_receive() or spi_transmit_receive(). spi_init() programs the hardware from the stored configuration, so call spi_setConfig() first.

Transfer lengths count frames: a frame is 1, 2 or 4 bytes of the buffer for 8-, 16- and 24/32-bit frame sizes. The transfer functions poll the FIFOs without a timeout.

spi_init¶

int spi_init(int spi_id);

Program the controller from its stored configuration.

Disables the controller, applies the clock, bit and byte order, polarity, phase, frame size, de-glitch and FIFO settings of the configuration set with spi_setConfig() (or the board default), flushes both FIFOs, unmasks all SPI interrupt sources in the controller and registers the SPI0 interrupt handler when caps requests interrupts. The controller stays disabled; call spi_enable().

回傳值：0 (always).

spi_deinit¶

int spi_deinit(int spi_id);

Disable the controller and reset it.

回傳值：0 (always).

spi_setConfig¶

void spi_setConfig(spi_device_t *dev);

Store a configuration for the controller given by dev->id.

The structure is copied; the hardware is not touched until spi_init().

spi_enable¶

int spi_enable(int spi_id, int en);

Enable or disable the controller.

回傳值：0 (always).

spi_ioctl¶

int spi_ioctl(int spi_id, int cmd, void *args);

Run a control command.

回傳值：The FIFO count or busy status for the SPI_CTRL_GET_* commands, otherwise 0. Unknown commands are ignored.

spi_transmit¶

int spi_transmit(int spi_id, void *buffer, uint32_t size);

Send size frames and wait until the transfer has finished.

Received data is discarded.

spi_receive¶

int spi_receive(int spi_id, void *buffer, uint32_t size);

Receive size frames, sending all-ones frames meanwhile.

spi_transmit_receive¶

int spi_transmit_receive(int spi_id, const void *send_buf, void *recv_buf, uint32_t length);

Send and receive length frames in full duplex.

匿名列舉¶

Commands for spi_ioctl().

Unless stated otherwise args is not used and spi_ioctl() returns 0.

spi_index_type¶

SPI controller index, passed as spi_id.

HAL_SPI_INT_Type¶

SPI interrupt sources, passed as the event argument of the callback and as the args of SPI_CTRL_SET_INT_MASK and SPI_CTRL_SET_INT_UNMASK.

spi_event_type¶

SPI event codes.

Not used by this driver: the callback receives HAL_SPI_INT_Type values.

spi_device_t¶

SPI controller configuration and state.

Fill it and pass it to spi_setConfig() before spi_init().

巨集¶

hal_i2c.h¶

#include "hal_i2c.h"（原始碼）

I2C master driver: blocking register-style transfers.

Each controller has a configuration record initialised from the board configuration (I2C0_CONFIG, I2C1_CONFIG); replace it with i2c_setConfig() if needed, call i2c_init(), then exchange data with i2c_transfer(). A register read or write is one i2c_msg_t with a SUB_ADDR_* flag: the controller sends the register (sub-)address before the data.

i2c_init¶

int i2c_init(int i2c_id);

Initialise an I2C controller from its configuration record.

In I2C_HW_MODE, writes i2c_device_t::phase to the phase-period registers. Pin multiplexing is not configured here.

回傳值：0.

i2c_transfer¶

int i2c_transfer(int i2c_id, i2c_msg_t msgs[], uint32_t num);

Execute an I2C master transfer (blocking).

Sends or receives the first message with a 7-bit address. The function busy-waits until the transfer ends or times out.

回傳值：0 on success (also when num is 0 or in I2C_SW_MODE), or the non-zero timeout status of the low-level transfer, which also covers a slave that does not acknowledge.

i2c_setConfig¶

void i2c_setConfig(i2c_device_t *dev);

Replace the configuration record of a controller.

Copies dev into the record of controller dev->id. Call i2c_init() afterwards to apply it.

i2c_index_type¶

I2C controller index (the i2c_id argument of the I2C functions).

Only the controllers enabled in the board configuration are listed, so the numbering depends on the build.

i2c_msg_t¶

One I2C message for i2c_transfer().

i2c_device_t¶

Configuration of one I2C controller.

巨集¶

hal_pwm.h¶

#include "hal_pwm.h"（原始碼）

PWM driver: one PWM group with four channels; period, duty cycle and polarity control.

The IPRO7 has a single PWM group, so pass 0 as pwm_id. pwm_init() sets up the group (counter clock divider 32, period 1000 counts) with all channel outputs disabled; PWM_CTRL_RESUME starts the group and enables the outputs. The output frequency is the PWM counter clock divided by the period.

Per-channel commands act on the channel recorded in pwm_device_t::ch of device slot pwm_id (channel 0 for slot 0 with the default board configuration). For finer control, use the PWM driver in drv_pwm.h directly.

pwm_init¶

int pwm_init(int pwm_id, uint16_t caps);

Initialize the PWM group.

Selects the crystal clock with a divider of 32 and a period of 1000 counts, graceful stop mode, and configures all four channels with their outputs disabled. Prints the PWM clock frequency.

回傳值：Always 0.

pwm_ioctl¶

int pwm_ioctl(int pwm_id, int cmd, void *args);

Control the PWM group or a channel.

pwm_close¶

int pwm_close(int pwm_id, int ch);

Disable one channel's outputs or the whole PWM group.

回傳值：Always 0.

匿名列舉¶

Command codes for pwm_ioctl().

pwm_index_type¶

PWM device slot index (one per channel).

pwm_event_type¶

Event codes passed to pwm_device_t::callback.

pwm_dutycycle_config_t¶

Channel thresholds for PWM_CTRL_DUTYCYCLE_CONFIG.

Within each period the output is active from threshold_low to threshold_high counts, so the duty cycle is (threshold_high - threshold_low) / period.

pwm_device_t¶

PWM device slot.

The slots are initialized from the board configuration (PWM_CH0_CONFIG to PWM_CH3_CONFIG).

巨集¶

hal_adc.h¶

#include "hal_adc.h"（原始碼）

General-purpose ADC driver: channel selection, polled, interrupt and DMA reads, battery and die-temperature measurement.

The SoC has one general-purpose ADC (ADC0_INDEX). A typical sequence is: fill an adc_device_t, call hal_adc_setConfig() and hal_adc_init(), select the input with ADC_CTRL_CHANNEL_CONFIG, start conversions with ADC_CTRL_CHANNEL_START, then read results with hal_adc_read().

External input pins must be set to GPIO_FUN_ANALOG before they are sampled. Fixed analog front-end settings (reference trims, PGA stage gains, chopper mode) come from adc_config.h. For audio capture use hal_auadc.h instead.

hal_adc_init¶

int hal_adc_init(int adc_id);

Initialize the ADC with the configuration stored by hal_adc_setConfig().

Selects the 32 MHz ADC source clock, resets and configures the converter and its FIFO, and installs the ADC interrupt handler when adc_device_t::caps requests interrupts. Resets adc_device_t::rx_dma to -1, so attach a DMA channel afterwards.

回傳值：Always 0.

hal_adc_read¶

int hal_adc_read(int adc_id, void *buffer, uint32_t size);

Read conversion results.

• DMA mode (COMMON_CAPS_DMA_RX): reloads the attached DMA channel to copy size bytes of raw FIFO words into buffer and starts it; returns at once. Convert the words with ADC_CTRL_DATA_PARSE once the transfer completes.
• Otherwise: busy-waits until the FIFO holds size results, then writes size parsed adc_channel_val_t entries to buffer.

回傳值：DMA mode: 0 on success, -1 if no DMA channel is attached or the length is invalid, other negative values on DMA set-up failure. Otherwise: size on success, -1 if size is greater than 32.

hal_adc_trim_tsen¶

int hal_adc_trim_tsen(uint16_t *tsen_offset);

Read the factory temperature-sensor offset from eFuse.

hal_adc_get_tsen¶

float hal_adc_get_tsen(uint16_t tsen_offset);

Measure the die temperature.

Performs two blocking conversions with different sensor bias settings and converts their difference to a temperature. Before calling, initialize the ADC with adc_device_t::continuous_conv_mode set to false, select ADC_CHANNEL_TSEN_P against ADC_CHANNEL_GND with ADC_CTRL_CHANNEL_CONFIG, and issue ADC_CTRL_TSEN_ON. Do not start conversions with ADC_CTRL_CHANNEL_START; this function starts them itself.

回傳值：Temperature in degrees Celsius.

hal_adc_getDevice¶

adc_device_t * hal_adc_getDevice(int index);

Get the driver's configuration slot for an ADC instance.

回傳值：Pointer to the internal adc_device_t.

hal_adc_setConfig¶

void hal_adc_setConfig(adc_device_t *dev);

Store an ADC configuration for the next hal_adc_init().

Copies dev into the driver slot selected by adc_device_t::id.

hal_adc_ioctl¶

int hal_adc_ioctl(int adc_id, int cmd, void *args);

Control the ADC.

回傳值：0 for every command except ADC_CTRL_CHANNEL_CONFIG, which returns non-zero if an external channel's pin is not in analog mode.

匿名列舉¶

Command codes for hal_adc_ioctl().

adc_index_type¶

ADC instance index.

adc_channel_t¶

ADC input channel.

Used as the entries of adc_channel_cfg_t::pos_channel and adc_channel_cfg_t::neg_channel. Channels 0 to 11 are external pins; the others are internal signals.

adc_clk_div_t¶

ADC clock divider, applied to the 32 MHz ADC source clock.

adc_vref_t¶

ADC reference voltage (full scale of a single-ended conversion).

adc_data_width_t¶

ADC result width and hardware averaging.

adc_fifo_threshold_t¶

ADC FIFO threshold.

Number of conversion results in the FIFO that raises the FIFO-ready interrupt (interrupt mode) or a DMA request (DMA mode). Despite the names, the unit is one 32-bit conversion result, not one byte.

adc_pga_gain_t¶

ADC PGA gain.

adc_event_type¶

Event codes passed to adc_device_t::callback.

adc_it_type¶

Interrupt source bits for ADC_CTRL_SET_INT and ADC_CTRL_CLEAR_INT.

adc_channel_cfg_t¶

Channel list for ADC_CTRL_CHANNEL_CONFIG.

With num equal to 1 the ADC converts one positive/negative pair; with a larger num it scans the pairs in order (up to 12 entries).

adc_channel_val_t¶

One parsed conversion result.

adc_data_parse_t¶

Argument of ADC_CTRL_DATA_PARSE.

adc_device_t¶

ADC configuration and run-time state.

Pass a filled copy to hal_adc_setConfig() before hal_adc_init().

adc_config.h¶

#include "adc_config.h"（原始碼）

Fixed analog front-end settings applied by hal_adc_init().

These values are written to the general-purpose ADC on every hal_adc_init() call and are not part of adc_device_t. Each value is an index into the corresponding hardware setting, as described per macro.

巨集¶

hal_dac.h¶

#include "hal_dac.h"（原始碼）

General-purpose DAC driver: two 10-bit output channels, register or DMA output.

Channel 0 (DAC output A) is on GPIO23 and channel 1 (DAC output B) on GPIO22. Set the pins to GPIO_FUN_ANALOG before hal_dac_init(); a channel whose pin is not in analog mode is not enabled. Typical sequence: fill a dac_device_t, hal_dac_setConfig(), hal_dac_init(), then, for DMA output, attach a DMA channel with DAC_CTRL_TX_DMA and stream samples with hal_dac_write().

Samples are 10-bit codes (0 to 1023, mid-scale 512) stored one per uint16_t.

hal_dac_setConfig¶

void hal_dac_setConfig(dac_device_t *dev);

Store a DAC configuration for the next hal_dac_init().

Copies dev into the driver slot selected by dac_device_t::id.

hal_dac_init¶

int hal_dac_init(int dac_id);

Initialize the DAC with the configuration stored by hal_dac_setConfig().

Selects the 32 MHz DAC clock, sets the divider for dac_device_t::sample_freq, selects the reference and the data source (DMA or registers) and enables the requested channels whose pins are in analog mode. Resets dac_device_t::tx_dma to -1, so attach a DMA channel afterwards. Channels enabled by an earlier call stay selected.

hal_dac_deinit¶

int hal_dac_deinit(int dac_id);

Disable both DAC channels and the DAC DMA request.

回傳值：Always 0.

hal_dac_control¶

int hal_dac_control(int dac_id, int cmd, void *args);

Control the DAC.

回傳值：Always 0.

hal_dac_write¶

int hal_dac_write(int dac_id, int channel, const void *buffer, uint32_t size);

Output samples.

• DMA mode (COMMON_CAPS_DMA_TX): reloads the attached DMA channel to send size bytes from buffer to the DAC and starts it; returns at once. channel is not used; the enabled channels are fed by the DMA data.
• Otherwise: writes the size codes of buffer one after another to the selected channel(s) without pacing, so the output settles at the last code. Use size = 1 to set a static level.

回傳值：0 on success. DMA mode: -1 if no DMA channel is attached, other negative values on DMA set-up failure. Register mode: -1 if channel selects no channel.

dac_index_type¶

DAC instance index.

匿名列舉¶

Command codes for hal_dac_control().

dac_sample_frequence¶

Supported DAC sample rates, in Hz.

The rate is derived from the 32 MHz DAC clock by integer division, so the actual rate can deviate slightly from the nominal value.

dac_device_t¶

DAC configuration and run-time state.

Pass a filled copy to hal_dac_setConfig() before hal_dac_init().

巨集¶

hal_acomp.h¶

#include "hal_acomp.h"（原始碼）

Analog comparator (ACOMP) driver: input selection, hysteresis, output and edge interrupts.

The SoC has two analog comparators in the always-on domain, selected by an index of 0 or 1. Typical sequence: acomp_init(), acomp_enable(), then poll acomp_get_result() or unmask an edge interrupt with acomp_interrupt_unmask().

acomp_init¶

void acomp_init(uint8_t idx, acomp_cfg_t *device);

Configure a comparator.

Disables the comparator, then programs the inputs and hysteresis with the input multiplexer enabled, a level scaling factor of 1 and the slow-response power mode. The comparator stays disabled; call acomp_enable() afterwards.

acomp_enable¶

void acomp_enable(uint8_t idx);

Enable a comparator.

acomp_disable¶

void acomp_disable(uint8_t idx);

Disable a comparator.

acomp_interrupt_mask¶

void acomp_interrupt_mask(uint8_t idx, uint8_t edge_type);

Mask (disable) a comparator edge interrupt.

acomp_interrupt_unmask¶

void acomp_interrupt_unmask(uint8_t idx, uint8_t edge_type);

Clear any pending interrupt of a comparator and unmask (enable) an edge interrupt.

acomp_get_result¶

int acomp_get_result(uint8_t idx);

Read the raw comparator output.

回傳值：1 if the comparator output is high, 0 if it is low.

acomp_channel_type¶

Comparator input selection, for either the positive or the negative input.

acomp_hysteresis_vol_type¶

Comparator hysteresis voltage.

acomp_it_type¶

Edge selector for acomp_interrupt_mask() and acomp_interrupt_unmask().

acomp_cfg_t¶

Comparator configuration for acomp_init().

hal_keyscan.h¶

#include "hal_keyscan.h"（原始碼）

Key-scan matrix controller definitions: control commands, matrix size, events and the device configuration.

The key-scan controller scans a key matrix of up to 20 columns by 8 rows and reports pressed keys as key codes. A key code is column x row_num + row, with column and row counted from 0. The device slot is initialized from the board configuration (KEYSCAN_CONFIG).

匿名列舉¶

Key-scan control command codes.

keyscan_index_type¶

Key-scan instance index.

col_num_type¶

Number of matrix columns (1 to 20).

row_num_type¶

Number of matrix rows (1 to 8).

keyscan_event_type¶

Event codes passed to keyscan_device_t::callback.

keyscan_device_t¶

Key-scan device configuration.

巨集¶

hal_qdec.h¶

#include "hal_qdec.h"（原始碼）

Quadrature decoder (QDEC) definitions: instances, control commands, events and the device configuration.

The SoC has three quadrature decoders (QDEC0_INDEX to QDEC2_INDEX) that sample a rotary encoder's A/B inputs, accumulate the movement and report it periodically. This header provides the configuration structure, the control command codes and the event codes used by the QDEC driver.

匿名列舉¶

QDEC control command codes.

qdec_index_type¶

QDEC instance index.

qdec_event_type¶

QDEC events: interrupt-source bits for QDEC_CTRL_SET_INT and QDEC_CTRL_CLR_INT, and the event value passed to the callback.

qdec_device_t¶

QDEC device configuration.

The device slots are initialized from the board configuration (QDEC0_CONFIG to QDEC2_CONFIG).

hal_dma.h¶

#include "hal_dma.h"（原始碼）

DMA driver: channel configuration, linked-list (LLI) transfers and completion callbacks.

The SoC has one DMA controller (DMA0_ID) with eight channels. Each transfer is described by a chain of linked-list items (dma_lli_ctrl_t) that dma_reload() builds from the channel configuration.

Typical sequence with fixed channels:

1. Fill a zero-initialised dma_device_t (channel, direction, request lines, widths, bursts, address increment, transfer mode) and install it with dma_setConfig().
2. Program the channel with dma_init().
3. Optionally register a callback with DMA_CTRL_SET_CALLBACK and unmask the channel interrupts with DMA_CTRL_SET_INT.
4. Build the transfer with dma_reload() and start it with dma_channel_start().

When CONFIG_DMA_CHANNEL_ALLOCATOR is enabled, dma_request_channel() hands out free channels at run time instead of fixed channel numbers.

Peripheral drivers that use DMA (for example hal_uart.h) take a channel configured this way.

dma_getDevice¶

dma_device_t * dma_getDevice(int dma_id, int dma_ch);

Get the driver's configuration record of a channel.

Changes made through the returned pointer are used by the next dma_init() / dma_channel_attach() (direction, request lines) and the next dma_reload() (widths, bursts, increments, mode).

回傳值：Pointer to the internal record. The arguments are not range-checked.

dma_ioctl¶

int dma_ioctl(int dma_id, int dma_ch, int cmd, void *args);

Execute a channel control command.

回傳值：For DMA_CTRL_CHANNEL_GET_STATUS: 1 if the channel is enabled, 0 if idle. 0 for all other commands; unknown commands are ignored.

dma_reload¶

int dma_reload(int dma_id, int dma_ch, uint32_t src_addr, uint32_t dst_addr, uint32_t transfer_size, dma_lli_ctrl_t **lliCfg);

Build the LLI chain of a transfer and load it into a channel.

Stops the channel first (a transfer still in progress is aborted), splits the transfer into items of at most DMA_MAX_TRANSFER_PER_LLI source-width items, links them according to dma_device_t::transfer_mode, writes the chain back from the data cache and loads the first item. The channel is not started; call dma_channel_start() afterwards. The function calls realloc() on every invocation.

In DMA_LLI_PINGPONG_MODE and DMA_LLI_CYCLE_N_MODE the memory buffer must hold 2 or dma_device_t::lli_count times transfer_size bytes.

dma_init¶

int dma_init(int dma_id, int dma_ch);

Program a channel from its configuration record.

Writes direction, request lines, widths, bursts and address increments into the channel, installs the DMA interrupt handler and enables the DMA interrupt in the CPU.

With CONFIG_DMA_CHANNEL_ALLOCATOR this is the same as dma_channel_attach().

回傳值：0.

dma_setConfig¶

void dma_setConfig(dma_device_t *dma_device);

Install a channel configuration.

Copies the whole structure into the driver's record of channel dma_device->ch, including the callback and lli_cfg members, so zero-initialise the structure before filling it. The hardware is not touched; call dma_init() or dma_channel_attach() afterwards.

dma_close¶

int dma_close(uint32_t dma_id, int dma_ch);

Stop a channel and clear its hardware configuration.

Frees the LLI chain owned by the driver, disables the channel and writes an all-zero channel configuration.

回傳值：0.

dma_controller_init¶

void dma_controller_init(int dma_id);

Enable a DMA controller and its interrupt (one time).

Enables the controller, installs the DMA interrupt handler and enables the DMA interrupt in the CPU. Only the first call has an effect; later calls return immediately. All users (allocator or fixed channels) share the same controller.

dma_channel_attach¶

int dma_channel_attach(int dma_id, int dma_ch);

Program one channel without disturbing the other channels.

Calls dma_controller_init(), enables the per-channel DMA clock (channels 4-7 are clock-gated after reset), masks the channel interrupts and disables the channel, then writes the channel registers from the record installed with dma_setConfig(). The callback stored in that record is used by the interrupt handler.

Unlike dma_init() without CONFIG_DMA_CHANNEL_ALLOCATOR, it does not disable the controller, so transfers in progress on other channels keep running. Use it when several channels run at the same time (for example audio playback and capture).

回傳值：0.

dma_request_channel¶

dma_ch_handle_t dma_request_channel(uint32_t req, uint8_t dir, const char *owner);

Acquire a DMA channel routed to a peripheral request line.

Takes the first free channel, sets its direction and request routing (the peripheral side gets req, the memory side DMA_REQUEST_NONE) and programs it with dma_channel_attach(). Widths, bursts, address increments, transfer mode and callback still have to be set, for example through dma_getDevice() and dma_ioctl(); widths and bursts take effect at the next dma_reload(). Pass dma_handle_to_ch() of the handle as the channel index to the other DMA functions.

Calling it again with the same owner and req returns the same handle and increments its reference count; release it the same number of times. Memory-to-memory requests (DMA_REQUEST_NONE) always get a new channel.

回傳值：Handle on success; NULL if all channels are in use or if req is already bound to a channel by a different owner.

dma_release_channel¶

void dma_release_channel(dma_ch_handle_t h);

Release a channel obtained from dma_request_channel().

Decrements the reference count. On the final release the channel is stopped, its interrupts are masked, its LLI chain is freed, its callback is cleared and it returns to the free pool. NULL is ignored; releasing a channel that is not allocated prints a warning and does nothing.

dma_handle_to_ch¶

int dma_handle_to_ch(dma_ch_handle_t h);

Get the channel index of a handle.

Use the result as the dma_ch argument of dma_reload(), dma_channel_start() and the other channel functions.

回傳值：Channel index (0-7), or -1 if h is NULL.

dma_dump_allocation¶

void dma_dump_allocation(void);

Print the channel allocation table to the console.

Prints one line per channel with owner, request line, direction and reference count. Task context only (takes the allocator mutex).

dma_channel_is_allocator_owned¶

int dma_channel_is_allocator_owned(int dma_id, int dma_ch);

Check whether a channel is owned by the allocator.

Code that uses fixed channel numbers can call it to detect a conflict with an allocator user.

回傳值：1 if the channel was claimed with dma_request_channel(); 0 otherwise (also for out-of-range arguments or before the first request).

匿名列舉¶

Commands for dma_ioctl().

dma_index_type¶

DMA channel index (the dma_ch argument of the DMA functions).

匿名列舉¶

DMA controller index (the dma_id argument of the DMA functions).

dma_transfer_dir_type¶

Transfer direction (dma_device_t::direction).

匿名列舉¶

Events passed to the channel callback (dma_device_t::callback).

dma_control_data_t¶

Control word of an LLI item.

dma_reload() fills it from the channel configuration. In the field descriptions, "reset" is the hardware reset value of the field.

dma_lli_ctrl_t¶

One linked-list item (LLI) of a DMA transfer, as read by the controller.

Items reached through nextlli are fetched from memory by the controller, so a chain built by the application must be written back from the data cache before the transfer starts. dma_reload() does this for the chains it builds.

dma_trans_param_t¶

Parameter block for DMA_CTRL_CHANNEL_TRANS_PARAM_UPDATE.

Only the fields selected in map are copied into the channel configuration; they take effect at the next dma_reload().

dma_device_t¶

Configuration and state of one DMA channel.

The driver keeps one record per channel, initialised from the board configuration (DMA0_CHx_CONFIG). Install a new one with dma_setConfig() or modify the record returned by dma_getDevice().

型別定義¶

巨集¶