Software APIs
Data Structures | Typedefs | Enumerations | Functions
dif_gpio.h File Reference

(dcee03a)

GPIO Device Interface Functions More...

#include <stddef.h>
#include <stdint.h>
#include "sw/device/lib/base/mmio.h"
#include "sw/device/lib/dif/dif_warn_unused_result.h"

Go to the source code of this file.

Data Structures

struct  dif_gpio_params
 Hardware instantiation parameters for GPIO. More...
 
struct  dif_gpio
 A handle to GPIO. More...
 

Typedefs

typedef enum dif_gpio_toggle dif_gpio_toggle_t
 A toggle state: enabled, or disabled. More...
 
typedef struct dif_gpio_params dif_gpio_params_t
 Hardware instantiation parameters for GPIO. More...
 
typedef struct dif_gpio dif_gpio_t
 A handle to GPIO. More...
 
typedef enum dif_gpio_result dif_gpio_result_t
 The result of a GPIO operation.
 
typedef enum dif_gpio_irq_trigger dif_gpio_irq_trigger_t
 A GPIO interrupt request trigger. More...
 
typedef uint32_t dif_gpio_pin_t
 A GPIO pin index, ranging from 0 to 31. More...
 
typedef uint32_t dif_gpio_state_t
 State for all 32 GPIO pins, given as bit fields. More...
 
typedef uint32_t dif_gpio_mask_t
 A mask for selecting GPIO pins. More...
 

Enumerations

enum  dif_gpio_toggle {
  kDifGpioToggleEnabled = true,
  kDifGpioToggleDisabled = false
}
 A toggle state: enabled, or disabled. More...
 
enum  dif_gpio_result {
  kDifGpioOk = 0,
  kDifGpioError = 1,
  kDifGpioBadArg = 2
}
 The result of a GPIO operation. More...
 
enum  dif_gpio_irq_trigger {
  kDifGpioIrqTriggerEdgeRising,
  kDifGpioIrqTriggerEdgeFalling,
  kDifGpioIrqTriggerLevelLow,
  kDifGpioIrqTriggerLevelHigh,
  kDifGpioIrqTriggerEdgeRisingFalling,
  kDifGpioIrqTriggerEdgeRisingLevelLow,
  kDifGpioIrqTriggerEdgeFallingLevelHigh
}
 A GPIO interrupt request trigger. More...
 

Functions

DIF_WARN_UNUSED_RESULT dif_gpio_result_t dif_gpio_init (dif_gpio_params_t params, dif_gpio_t *gpio)
 Creates a new handle for GPIO. More...
 
DIF_WARN_UNUSED_RESULT dif_gpio_result_t dif_gpio_reset (const dif_gpio_t *gpio)
 Resets a GPIO device. More...
 
DIF_WARN_UNUSED_RESULT dif_gpio_result_t dif_gpio_irq_is_pending (const dif_gpio_t *gpio, dif_gpio_pin_t pin, bool *is_pending)
 Returns whether a particular pin's interrupt is currently pending. More...
 
DIF_WARN_UNUSED_RESULT dif_gpio_result_t dif_gpio_irq_is_pending_all (const dif_gpio_t *gpio, dif_gpio_state_t *is_pending)
 Returns a GPIO state representing which pins have interrupts enabled. More...
 
DIF_WARN_UNUSED_RESULT dif_gpio_result_t dif_gpio_irq_acknowledge (const dif_gpio_t *gpio, dif_gpio_pin_t pin)
 Acknowledges a particular pin's interrupt, indicating to the hardware that it has been successfully serviced. More...
 
DIF_WARN_UNUSED_RESULT dif_gpio_result_t dif_gpio_irq_get_enabled (const dif_gpio_t *gpio, dif_gpio_pin_t pin, dif_gpio_toggle_t *state)
 Checks whether a particular pin's interrupt is currently enabled or disabled. More...
 
DIF_WARN_UNUSED_RESULT dif_gpio_result_t dif_gpio_irq_set_enabled (const dif_gpio_t *gpio, dif_gpio_pin_t pin, dif_gpio_toggle_t state)
 Sets whether a particular pin's interrupt is currently enabled or disabled. More...
 
DIF_WARN_UNUSED_RESULT dif_gpio_result_t dif_gpio_irq_set_enabled_masked (const dif_gpio_t *gpio, dif_gpio_mask_t mask, dif_gpio_toggle_t state)
 Sets whether a particular pin's interrupt is currently enabled or disabled. More...
 
DIF_WARN_UNUSED_RESULT dif_gpio_result_t dif_gpio_irq_force (const dif_gpio_t *gpio, dif_gpio_pin_t pin)
 Forces a particular pin's interrupt, causing it to be serviced as if hardware had asserted it. More...
 
DIF_WARN_UNUSED_RESULT dif_gpio_result_t dif_gpio_irq_disable_all (const dif_gpio_t *gpio, dif_gpio_state_t *snapshot)
 Disables all interrupts, optionally snapshotting all toggle state for later restoration. More...
 
DIF_WARN_UNUSED_RESULT dif_gpio_result_t dif_gpio_irq_restore_all (const dif_gpio_t *gpio, const dif_gpio_state_t *snapshot)
 Restores interrupts from the given snapshot. More...
 
DIF_WARN_UNUSED_RESULT dif_gpio_result_t dif_gpio_irq_set_trigger (const dif_gpio_t *gpio, dif_gpio_mask_t mask, dif_gpio_irq_trigger_t trigger)
 Configures interrupt triggers for a set of pins. More...
 
DIF_WARN_UNUSED_RESULT dif_gpio_result_t dif_gpio_read (const dif_gpio_t *gpio, dif_gpio_pin_t pin, bool *state)
 Reads from a pin. More...
 
DIF_WARN_UNUSED_RESULT dif_gpio_result_t dif_gpio_read_all (const dif_gpio_t *gpio, dif_gpio_state_t *state)
 Reads from all pins. More...
 
DIF_WARN_UNUSED_RESULT dif_gpio_result_t dif_gpio_write (const dif_gpio_t *gpio, dif_gpio_pin_t pin, bool state)
 Writes to a pin. More...
 
DIF_WARN_UNUSED_RESULT dif_gpio_result_t dif_gpio_write_all (const dif_gpio_t *gpio, dif_gpio_state_t state)
 Writes to all pins. More...
 
DIF_WARN_UNUSED_RESULT dif_gpio_result_t dif_gpio_write_masked (const dif_gpio_t *gpio, dif_gpio_mask_t mask, dif_gpio_state_t state)
 Writes to the pins identified by a mask. More...
 
DIF_WARN_UNUSED_RESULT dif_gpio_result_t dif_gpio_output_set_enabled (const dif_gpio_t *gpio, dif_gpio_pin_t pin, dif_gpio_toggle_t state)
 Sets output enable mode of a pin. More...
 
DIF_WARN_UNUSED_RESULT dif_gpio_result_t dif_gpio_output_set_enabled_all (const dif_gpio_t *gpio, dif_gpio_state_t state)
 Sets output modes of all pins. More...
 
DIF_WARN_UNUSED_RESULT dif_gpio_result_t dif_gpio_output_set_enabled_masked (const dif_gpio_t *gpio, dif_gpio_mask_t mask, dif_gpio_state_t state)
 Sets the output modes of the pins identified by a mask. More...
 
DIF_WARN_UNUSED_RESULT dif_gpio_result_t dif_gpio_input_noise_filter_set_enabled (const dif_gpio_t *gpio, dif_gpio_mask_t mask, dif_gpio_toggle_t state)
 Enable noise filter for GPIO inputs. More...
 

Detailed Description

GPIO Device Interface Functions

Definition in file dif_gpio.h.


Data Structure Documentation

◆ dif_gpio_params

struct dif_gpio_params

Hardware instantiation parameters for GPIO.

This struct describes information about the underlying hardware that is not determined until the hardware design is used as part of a top-level design.

Definition at line 51 of file dif_gpio.h.

Data Fields
mmio_region_t base_addr The base address for the GPIO hardware registers.

◆ dif_gpio

struct dif_gpio

A handle to GPIO.

This type should be treated as opaque by users.

Definition at line 63 of file dif_gpio.h.

Data Fields
dif_gpio_params_t params

Typedef Documentation

◆ dif_gpio_irq_trigger_t

A GPIO interrupt request trigger.

Each GPIO pin has an associated interrupt that can be independently configured to be edge and/or level sensitive. This enum defines supported configurations for these interrupts.

◆ dif_gpio_mask_t

typedef uint32_t dif_gpio_mask_t

A mask for selecting GPIO pins.

If the Nth bit is enabled, then the Nth pin is selected by the mask.

Definition at line 152 of file dif_gpio.h.

◆ dif_gpio_params_t

Hardware instantiation parameters for GPIO.

This struct describes information about the underlying hardware that is not determined until the hardware design is used as part of a top-level design.

◆ dif_gpio_pin_t

typedef uint32_t dif_gpio_pin_t

A GPIO pin index, ranging from 0 to 31.

This type serves as the GPIO interrupt request type.

Definition at line 131 of file dif_gpio.h.

◆ dif_gpio_state_t

typedef uint32_t dif_gpio_state_t

State for all 32 GPIO pins, given as bit fields.

The Nth bit represents the state of the Nth pin.

This type is also used as a vector of dif_gpio_toggle_ts, to indicate toggle state across all 32 pins. A set bit corresponds to kDifGpioToggleEnabled.

It is also used with dif_gpio_irq_disable_all() and dif_gpio_irq_restore_all().

Definition at line 145 of file dif_gpio.h.

◆ dif_gpio_t

typedef struct dif_gpio dif_gpio_t

A handle to GPIO.

This type should be treated as opaque by users.

◆ dif_gpio_toggle_t

A toggle state: enabled, or disabled.

This enum may be used instead of a bool when describing an enabled/disabled state.

This enum may be used with dif_gpio_toggle_vec_t to set individual bits within it; dif_gpio_toggle_t's variants are guaranteed to be compatible with dif_gpio_toggle_vec_t.

Enumeration Type Documentation

◆ dif_gpio_irq_trigger

A GPIO interrupt request trigger.

Each GPIO pin has an associated interrupt that can be independently configured to be edge and/or level sensitive. This enum defines supported configurations for these interrupts.

Enumerator
kDifGpioIrqTriggerEdgeRising 

Trigger on rising edge.

kDifGpioIrqTriggerEdgeFalling 

Trigger on falling edge.

kDifGpioIrqTriggerLevelLow 

Trigger when input is low.

kDifGpioIrqTriggerLevelHigh 

Trigger when input is high.

kDifGpioIrqTriggerEdgeRisingFalling 

Trigger on rising and falling edges.

kDifGpioIrqTriggerEdgeRisingLevelLow 

Trigger on rising edge or when the input is low.

kDifGpioIrqTriggerEdgeFallingLevelHigh 

Trigger on falling edge or when the input is high.

Definition at line 95 of file dif_gpio.h.

◆ dif_gpio_result

The result of a GPIO operation.

Enumerator
kDifGpioOk 

Indicates that the operation succeeded.

kDifGpioError 

Indicates some unspecified failure.

kDifGpioBadArg 

Indicates that some parameter passed into a function failed a precondition.

When this value is returned, no hardware operations occurred.

Definition at line 68 of file dif_gpio.h.

◆ dif_gpio_toggle

A toggle state: enabled, or disabled.

This enum may be used instead of a bool when describing an enabled/disabled state.

This enum may be used with dif_gpio_toggle_vec_t to set individual bits within it; dif_gpio_toggle_t's variants are guaranteed to be compatible with dif_gpio_toggle_vec_t.

Enumerator
kDifGpioToggleDisabled 

The "disabled" state.

Definition at line 33 of file dif_gpio.h.

Function Documentation

◆ dif_gpio_init()

DIF_WARN_UNUSED_RESULT dif_gpio_result_t dif_gpio_init ( dif_gpio_params_t  params,
dif_gpio_t gpio 
)

Creates a new handle for GPIO.

This function does not actuate the hardware.

Parameters
paramsHardware instantiation parameters.
[out]gpioOut param for the initialized handle.
Returns
The result of the operation.

Definition at line 102 of file dif_gpio.c.

◆ dif_gpio_input_noise_filter_set_enabled()

DIF_WARN_UNUSED_RESULT dif_gpio_result_t dif_gpio_input_noise_filter_set_enabled ( const dif_gpio_t gpio,
dif_gpio_mask_t  mask,
dif_gpio_toggle_t  state 
)

Enable noise filter for GPIO inputs.

When enabled, changes in the pin value will be ignored unless stable for 16 cycles.

Parameters
gpioA GPIO handle.
maskMask that identifies pins to set the filter state of.
stateThe new toggle state for the filter.
Returns
The result of the operation.

Definition at line 418 of file dif_gpio.c.

◆ dif_gpio_irq_acknowledge()

DIF_WARN_UNUSED_RESULT dif_gpio_result_t dif_gpio_irq_acknowledge ( const dif_gpio_t gpio,
dif_gpio_pin_t  pin 
)

Acknowledges a particular pin's interrupt, indicating to the hardware that it has been successfully serviced.

Parameters
gpioA GPIO handle.
pinA GPIO pin.
Returns
The result of the operation.

Definition at line 164 of file dif_gpio.c.

◆ dif_gpio_irq_disable_all()

DIF_WARN_UNUSED_RESULT dif_gpio_result_t dif_gpio_irq_disable_all ( const dif_gpio_t gpio,
dif_gpio_state_t snapshot 
)

Disables all interrupts, optionally snapshotting all toggle state for later restoration.

Parameters
gpioA GPIO handle.
[out]snapshotOut-param for the snapshot; may be NULL.
Returns
The result of the operation.

Definition at line 248 of file dif_gpio.c.

◆ dif_gpio_irq_force()

DIF_WARN_UNUSED_RESULT dif_gpio_result_t dif_gpio_irq_force ( const dif_gpio_t gpio,
dif_gpio_pin_t  pin 
)

Forces a particular pin's interrupt, causing it to be serviced as if hardware had asserted it.

Parameters
gpioA GPIO handle.
pinA GPIO pin.
Returns
The result of the operation.

Definition at line 236 of file dif_gpio.c.

◆ dif_gpio_irq_get_enabled()

DIF_WARN_UNUSED_RESULT dif_gpio_result_t dif_gpio_irq_get_enabled ( const dif_gpio_t gpio,
dif_gpio_pin_t  pin,
dif_gpio_toggle_t state 
)

Checks whether a particular pin's interrupt is currently enabled or disabled.

Parameters
gpioA GPIO handle.
pinA GPIO pin.
[out]stateOut-param toggle state of the interrupt.
Returns
The result of the operation.

Definition at line 176 of file dif_gpio.c.

◆ dif_gpio_irq_is_pending()

DIF_WARN_UNUSED_RESULT dif_gpio_result_t dif_gpio_irq_is_pending ( const dif_gpio_t gpio,
dif_gpio_pin_t  pin,
bool *  is_pending 
)

Returns whether a particular pin's interrupt is currently pending.

Parameters
gpioA GPIO handle.
pinA GPIO pin.
[out]is_pendingOut-param for whether the interrupt is pending.
Returns
The result of the operation.

Definition at line 139 of file dif_gpio.c.

◆ dif_gpio_irq_is_pending_all()

DIF_WARN_UNUSED_RESULT dif_gpio_result_t dif_gpio_irq_is_pending_all ( const dif_gpio_t gpio,
dif_gpio_state_t is_pending 
)

Returns a GPIO state representing which pins have interrupts enabled.

Parameters
gpioA GPIO handle.
[out]is_pendingOut-param for which interrupts are pending.
Returns
The result of the operation.

Definition at line 152 of file dif_gpio.c.

◆ dif_gpio_irq_restore_all()

DIF_WARN_UNUSED_RESULT dif_gpio_result_t dif_gpio_irq_restore_all ( const dif_gpio_t gpio,
const dif_gpio_state_t snapshot 
)

Restores interrupts from the given snapshot.

This function can be used with dif_gpio_irq_disable_all() to temporary interrupt save-and-restore.

Parameters
gpioA GPIO handle.
snapshotA snapshot to restore from.
Returns
The result of the operation.

Definition at line 263 of file dif_gpio.c.

◆ dif_gpio_irq_set_enabled()

DIF_WARN_UNUSED_RESULT dif_gpio_result_t dif_gpio_irq_set_enabled ( const dif_gpio_t gpio,
dif_gpio_pin_t  pin,
dif_gpio_toggle_t  state 
)

Sets whether a particular pin's interrupt is currently enabled or disabled.

Parameters
gpioA GPIO handle.
pinA GPIO pin.
stateThe new toggle state for the interrupt.
Returns
The result of the operation.

Definition at line 190 of file dif_gpio.c.

◆ dif_gpio_irq_set_enabled_masked()

DIF_WARN_UNUSED_RESULT dif_gpio_result_t dif_gpio_irq_set_enabled_masked ( const dif_gpio_t gpio,
dif_gpio_mask_t  mask,
dif_gpio_toggle_t  state 
)

Sets whether a particular pin's interrupt is currently enabled or disabled.

Parameters
gpioA GPIO handle.
maskMask that identifies the pins whose interrupt triggers will be configured.
stateThe new toggle state for the interrupt.
Returns
The result of the operation.

Definition at line 213 of file dif_gpio.c.

◆ dif_gpio_irq_set_trigger()

DIF_WARN_UNUSED_RESULT dif_gpio_result_t dif_gpio_irq_set_trigger ( const dif_gpio_t gpio,
dif_gpio_mask_t  mask,
dif_gpio_irq_trigger_t  trigger 
)

Configures interrupt triggers for a set of pins.

This function configures interrupt triggers, i.e. rising-edge, falling-edge, level-high, and level-low, for the pins given by the mask. Note that interrupt of the pin must also be enabled to generate interrupts.

Parameters
gpioA GPIO handle.
maskMask that identifies the pins whose interrupt triggers will be configured.
triggerNew configuration of interrupt triggers.
Returns
The result of the operation.

Definition at line 275 of file dif_gpio.c.

◆ dif_gpio_output_set_enabled()

DIF_WARN_UNUSED_RESULT dif_gpio_result_t dif_gpio_output_set_enabled ( const dif_gpio_t gpio,
dif_gpio_pin_t  pin,
dif_gpio_toggle_t  state 
)

Sets output enable mode of a pin.

Parameters
gpioA GPIO handle.
pinA GPIO pin.
stateOutput mode of the pin.
Returns
The result of the operation.

Definition at line 398 of file dif_gpio.c.

◆ dif_gpio_output_set_enabled_all()

DIF_WARN_UNUSED_RESULT dif_gpio_result_t dif_gpio_output_set_enabled_all ( const dif_gpio_t gpio,
dif_gpio_state_t  state 
)

Sets output modes of all pins.

Parameters
gpioA GPIO handle.
stateOutput modes of the pins.
Returns
The result of the operation.

Definition at line 387 of file dif_gpio.c.

◆ dif_gpio_output_set_enabled_masked()

DIF_WARN_UNUSED_RESULT dif_gpio_result_t dif_gpio_output_set_enabled_masked ( const dif_gpio_t gpio,
dif_gpio_mask_t  mask,
dif_gpio_state_t  state 
)

Sets the output modes of the pins identified by a mask.

Parameters
gpioA GPIO handle.
maskMask that identifies the pins whose output modes will be set.
stateOutput modes of the pins.
Returns
The result of the operation.

Definition at line 411 of file dif_gpio.c.

◆ dif_gpio_read()

DIF_WARN_UNUSED_RESULT dif_gpio_result_t dif_gpio_read ( const dif_gpio_t gpio,
dif_gpio_pin_t  pin,
bool *  state 
)

Reads from a pin.

The value returned by this function is independent of the output enable setting and includes the effects of the input noise filter and the load on the pin.

Parameters
gpioA GPIO handle.
pinA GPIO pin.
[out]statePin value.
Returns
The result of the operation.

Definition at line 350 of file dif_gpio.c.

◆ dif_gpio_read_all()

DIF_WARN_UNUSED_RESULT dif_gpio_result_t dif_gpio_read_all ( const dif_gpio_t gpio,
dif_gpio_state_t state 
)

Reads from all pins.

The value returned by this function is independent of the output enable setting and includes the effects of the input noise filter and the load on the pins.

Parameters
gpioA GPIO handle.
[out]statePin values.
Returns
The result of the operation.

Definition at line 339 of file dif_gpio.c.

◆ dif_gpio_reset()

DIF_WARN_UNUSED_RESULT dif_gpio_result_t dif_gpio_reset ( const dif_gpio_t gpio)

Resets a GPIO device.

Resets the given GPIO device by setting its configuration registers to reset values. Disables interrupts, output, and input filter.

Parameters
gpioA GPIO handle.
Returns
The result of the operation.

Definition at line 112 of file dif_gpio.c.

◆ dif_gpio_write()

DIF_WARN_UNUSED_RESULT dif_gpio_result_t dif_gpio_write ( const dif_gpio_t gpio,
dif_gpio_pin_t  pin,
bool  state 
)

Writes to a pin.

The actual value on the pin depends on the output enable setting.

Parameters
gpioA GPIO handle.
pinA GPIO pin.
stateValue to write.
Returns
The result of the operation.

Definition at line 374 of file dif_gpio.c.

◆ dif_gpio_write_all()

DIF_WARN_UNUSED_RESULT dif_gpio_result_t dif_gpio_write_all ( const dif_gpio_t gpio,
dif_gpio_state_t  state 
)

Writes to all pins.

The actual values on the pins depend on the output enable setting.

Parameters
gpioA GPIO handle.
stateValue to write.
Returns
The result of the operation.

Definition at line 362 of file dif_gpio.c.

◆ dif_gpio_write_masked()

DIF_WARN_UNUSED_RESULT dif_gpio_result_t dif_gpio_write_masked ( const dif_gpio_t gpio,
dif_gpio_mask_t  mask,
dif_gpio_state_t  state 
)

Writes to the pins identified by a mask.

The actual values on the pins depend on the output enable setting.

Parameters
gpioA GPIO handle.
maskMask that identifies the pins to write to.
stateValue to write.
Returns
The result of the operation.

Definition at line 380 of file dif_gpio.c.