(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

typedef enum dif_gpio_irq_trigger 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

typedef struct dif_gpio_params 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

typedef enum dif_gpio_toggle 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

enum 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

enum 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

enum 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

	params	Hardware instantiation parameters.
[out]	gpio	Out 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

gpio	A GPIO handle.
mask	Mask that identifies pins to set the filter state of.
state	The 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

gpio	A GPIO handle.
pin	A 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

	gpio	A GPIO handle.
[out]	snapshot	Out-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

gpio	A GPIO handle.
pin	A 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

	gpio	A GPIO handle.
	pin	A GPIO pin.
[out]	state	Out-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

	gpio	A GPIO handle.
	pin	A GPIO pin.
[out]	is_pending	Out-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

	gpio	A GPIO handle.
[out]	is_pending	Out-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

gpio	A GPIO handle.
snapshot	A 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

gpio	A GPIO handle.
pin	A GPIO pin.
state	The 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

gpio	A GPIO handle.
mask	Mask that identifies the pins whose interrupt triggers will be configured.
state	The 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

gpio	A GPIO handle.
mask	Mask that identifies the pins whose interrupt triggers will be configured.
trigger	New 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

gpio	A GPIO handle.
pin	A GPIO pin.
state	Output 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

gpio	A GPIO handle.
state	Output 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

gpio	A GPIO handle.
mask	Mask that identifies the pins whose output modes will be set.
state	Output 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

	gpio	A GPIO handle.
	pin	A GPIO pin.
[out]	state	Pin 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

	gpio	A GPIO handle.
[out]	state	Pin 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

gpio	A 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

gpio	A GPIO handle.
pin	A GPIO pin.
state	Value 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

gpio	A GPIO handle.
state	Value 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

gpio	A GPIO handle.
mask	Mask that identifies the pins to write to.
state	Value to write.

Returns: The result of the operation.

Definition at line 380 of file dif_gpio.c.

(dcee03a)

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Data Structure Documentation

◆ dif_gpio_params

◆ dif_gpio

Typedef Documentation

◆ dif_gpio_irq_trigger_t

◆ dif_gpio_mask_t

◆ dif_gpio_params_t

◆ dif_gpio_pin_t

◆ dif_gpio_state_t

◆ dif_gpio_t

◆ dif_gpio_toggle_t

Enumeration Type Documentation

◆ dif_gpio_irq_trigger

◆ dif_gpio_result

◆ dif_gpio_toggle

Function Documentation

◆ dif_gpio_init()

◆ dif_gpio_input_noise_filter_set_enabled()

◆ dif_gpio_irq_acknowledge()

◆ dif_gpio_irq_disable_all()

◆ dif_gpio_irq_force()

◆ dif_gpio_irq_get_enabled()

◆ dif_gpio_irq_is_pending()

◆ dif_gpio_irq_is_pending_all()

◆ dif_gpio_irq_restore_all()

◆ dif_gpio_irq_set_enabled()

◆ dif_gpio_irq_set_enabled_masked()

◆ dif_gpio_irq_set_trigger()

◆ dif_gpio_output_set_enabled()

◆ dif_gpio_output_set_enabled_all()

◆ dif_gpio_output_set_enabled_masked()

◆ dif_gpio_read()

◆ dif_gpio_read_all()

◆ dif_gpio_reset()

◆ dif_gpio_write()

◆ dif_gpio_write_all()

◆ dif_gpio_write_masked()