Skip to content

api-reference.md

Latest commit

 

History

History
242 lines (165 loc) · 6.21 KB

api-reference.md

File metadata and controls

242 lines (165 loc) · 6.21 KB
Raw

DMGPIO API Reference

Types

dmgpio_mode_t

GPIO pin operating mode.

typedef enum
{
    dmgpio_mode_input = 0,      // Digital input
    dmgpio_mode_output_pp,      // Output push-pull
    dmgpio_mode_output_od,      // Output open-drain
    dmgpio_mode_af_pp,          // Alternate function push-pull
    dmgpio_mode_af_od,          // Alternate function open-drain
    dmgpio_mode_analog,         // Analog mode (ADC/DAC)
} dmgpio_mode_t;

dmgpio_pull_t

Internal pull resistor configuration.

typedef enum
{
    dmgpio_pull_none = 0,       // No pull resistor
    dmgpio_pull_up,             // Pull-up resistor
    dmgpio_pull_down,           // Pull-down resistor
} dmgpio_pull_t;

dmgpio_speed_t

GPIO output slew rate.

typedef enum
{
    dmgpio_speed_low = 0,       // Low speed (~2 MHz)
    dmgpio_speed_medium,        // Medium speed (~25 MHz)
    dmgpio_speed_high,          // High speed (~50 MHz)
    dmgpio_speed_very_high,     // Very high speed (~100 MHz)
} dmgpio_speed_t;

dmgpio_pin_state_t

GPIO pin logic level.

typedef enum
{
    dmgpio_pin_reset = 0,       // Logic low (0)
    dmgpio_pin_set,             // Logic high (1)
} dmgpio_pin_state_t;

dmgpio_ioctl_cmd_t

IOCTL command codes for dmgpio_dmdrvi_ioctl, numbered from DMDRVI_IOCTL_CUSTOM_BASE (0x1000, dmdrvi 2.0) - the range dmdrvi reserves for driver-specific commands. Everything below it is a standard dmdrvi command (network, block, monitor) that dmgpio does not implement.

Up to dmgpio 1.0 the commands were numbered from 0. Modules that send dmgpio ioctls must be rebuilt against dmgpio 1.1 or later.

typedef enum
{
    dmgpio_ioctl_cmd_toggle_pins = DMDRVI_IOCTL_CUSTOM_BASE,   // Toggle pins state (arg = NULL)
    dmgpio_ioctl_cmd_set_pins_state,            // arg = const dmgpio_pins_state_t*
    dmgpio_ioctl_cmd_get_high_pins_state,       // arg = dmgpio_pins_mask_t* - pins in high state
    dmgpio_ioctl_cmd_get_low_pins_state,        // arg = dmgpio_pins_mask_t* - pins in low state
    dmgpio_ioctl_cmd_set_interrupt_handler      // arg = dmgpio_interrupt_handler_t*
} dmgpio_ioctl_cmd_t;

DMDRVI Functions

dmgpio_dmdrvi_create

Create a new GPIO device context by reading configuration from an INI file.

dmdrvi_context_t dmgpio_dmdrvi_create(dmini_context_t config, dmdrvi_dev_num_t* dev_num);

Parameters:

  • config – INI configuration context (see Configuration Guide)
  • dev_num – Device number output

Returns: New context on success, NULL on failure.

dmgpio_dmdrvi_free

Free the GPIO device context and deinitialize the pin.

void dmgpio_dmdrvi_free(dmdrvi_context_t context);

dmgpio_dmdrvi_open

Open a handle to the GPIO device.

void* dmgpio_dmdrvi_open(dmdrvi_context_t context, int flags);

Parameters:

  • context – DMDRVI context
  • flags – Open flags (e.g., DMDRVI_O_RDWR)

Returns: Device handle on success, NULL on failure.

dmgpio_dmdrvi_close

Close the device handle.

void dmgpio_dmdrvi_close(dmdrvi_context_t context, void* handle);

dmgpio_dmdrvi_read

Read the current high-state pin bitmask as a hex string, with pread-style byte offset support.

size_t dmgpio_dmdrvi_read(dmdrvi_context_t context, void* handle, void* buffer, size_t size, uint32_t offset);

The device is modelled as a 6-byte virtual file whose content is always the current high-state bitmask formatted as "0x%04X" (e.g. "0x000A"). offset is a byte offset into that content, enabling standard pread()-style access. An offset at or beyond 6 returns 0 bytes (EOF).

Example:

// offset=0, size=16 → "0x000A"  (6 bytes, pin 1 and 3 are high)
// offset=6, size=16 → ""        (0 bytes, EOF)
// offset=2, size=2  → "00"      (mid-string slice)

Returns: Number of bytes copied into buffer, or 0 at EOF.

dmgpio_dmdrvi_write

Write the desired high-state pin bitmask to the device.

size_t dmgpio_dmdrvi_write(dmdrvi_context_t context, void* handle, const void* buffer, size_t size, uint32_t offset);

Accepts a decimal ("10") or hex ("0x000A") string. Trailing whitespace and newlines (e.g. appended by the shell's echo) are automatically stripped. Each bit in the value corresponds to a pin within the configured pins mask: a 1 sets the pin high, a 0 sets it low.

offset is not meaningful for GPIO (the state is a single atomic value) and is ignored.

dmgpio_dmdrvi_ioctl

Perform control and query operations on the GPIO device.

int dmgpio_dmdrvi_ioctl(dmdrvi_context_t context, void* handle, int command, void* arg);

Parameters:

  • command – IOCTL command from dmgpio_ioctl_cmd_t
  • arg – Command-specific argument (see command descriptions above)

Returns: 0 on success, -EINVAL for a missing arg, -ENOTTY for any command that is not a dmgpio_ioctl_cmd_t - for example the dmdrvi class probes (DMDRVI_IOCTL_BLOCK_GET_INFO, DMDRVI_IOCTL_MONITOR_GET_POLICY) dmdevfs sends to every node, so GPIO nodes are never reported as block or monitor devices. Unknown commands are not logged.

dmgpio_dmdrvi_stat

Get device statistics.

int dmgpio_dmdrvi_stat(dmdrvi_context_t context, void* handle, dmdrvi_stat_t* stat);

Port API

The port layer defines hardware-specific functions. See include/dmgpio_port.h.

dmgpio_port_init

Initialize a GPIO pin.

int dmgpio_port_init(dmgpio_port_t port, dmgpio_pin_t pin,
                     dmgpio_mode_t mode, dmgpio_pull_t pull,
                     dmgpio_speed_t speed, uint8_t alternate);

dmgpio_port_deinit

Deinitialize (reset) a GPIO pin.

int dmgpio_port_deinit(dmgpio_port_t port, dmgpio_pin_t pin);

dmgpio_port_read_pin

Read the current logical state of a GPIO pin.

dmgpio_pin_state_t dmgpio_port_read_pin(dmgpio_port_t port, dmgpio_pin_t pin);

dmgpio_port_write_pin

Set the logical state of a GPIO output pin.

void dmgpio_port_write_pin(dmgpio_port_t port, dmgpio_pin_t pin, dmgpio_pin_state_t state);

dmgpio_port_toggle_pin

Toggle the logical state of a GPIO output pin.

void dmgpio_port_toggle_pin(dmgpio_port_t port, dmgpio_pin_t pin);