MutekH reference manual
Table of contents   List of declarations
MutekH reference manual » Developer reference » List of headers » device/class/gpio.h header reference
Previous   Next

device/class/gpio.h header reference
[Devices support library module]

The source code of this header can be browsed online.

Description [link] 

See also DRIVER_CLASS_GPIO.

Purpose [link] 

This class provides functions to read and update pins of a GPIO controller device.

This class enables performing the following operations on a GPIO device:

  • setting the mode of a set of pins,

  • reading the current value of a set of pins,

  • setting or toggling the value of a set of pins.

  • waiting until the value of a set of pins is not as expected.

An operation involving multiple pins must be performed atomically by the driver, provided that it is supported by the hardware. Groups of pins which reside in the same IO bank can usually be accessed atomically. These constraints are implementation dependent.

Synchronous and asynchronous operation [link] 

Most GPIO controller devices are memory-mapped. Most client use cases are synchronous. Nevertheless, some GPIO controller devices are behind I2C or SPI buses which can not be accessed instantaneously; that's why the GPIO driver API provide both, a synchronous and an asynchronous request based set of functions.

As most driver do not care for asynchronous operations, libdevice provides a generic asynchonous wrapper that relies on synchronous operations provided by the driver. This way, all drivers are able to provide asynchonous request handling without additional code.

On the other hand, drivers for GPIO controllers behind buses cannot implement synchronous operations and can only implement the asynchronous request handling approach.

Client code relying upon GPIO class should consider whether supporting only synchronous capable drivers is a strong limitation for code portability. The asynchronous request based API is more cumbersome to use directly and may be slower but it will work with any driver. Some convenient helpers are provided which rely on the scheduler to put the current context in wait state during an asynchronous request. This offers the most portable and easy to use API when the client code runs in a scheduler context (thread).

Members [link] 

Types [link] 

Functions [link] 

Constants [link] 

Macros [link] 

Members detail [link] 

#define DEV_GPIO_CANCEL(n) [link] 

This macro is declared in device/class/gpio.h source file, line 202.

See also dev_gpio_cancel_t.

#define DEV_GPIO_GET_INPUT(n) [link] 

This macro is declared in device/class/gpio.h source file, line 175.

See also dev_gpio_get_input_t.

#define DEV_GPIO_REQUEST(n) [link] 

This macro is declared in device/class/gpio.h source file, line 192.

See also dev_gpio_request_t.

#define DEV_GPIO_SET_MODE(n) [link] 

This macro is declared in device/class/gpio.h source file, line 117.

See also dev_gpio_set_mode_t.

#define DEV_GPIO_SET_OUTPUT(n) [link] 

This macro is declared in device/class/gpio.h source file, line 139.

See also dev_gpio_set_output_t.

#define DEV_STATIC_RES_DEV_GPIO(path_) [link] 

This macro is declared in device/class/gpio.h source file, line 450.

This macro provides a DEV_RES_DEV_PARAM resource entry which specifies the GPIO controller device relevant for the DEV_RES_GPIO entries.

Preprocessor condition: defined( CONFIG_DEVICE_GPIO )

#define DEV_STATIC_RES_DEV_GPIO(path_) [link] 

This macro is declared in device/class/gpio.h source file, line 460.

Documentation from alternate declaration:

This macro provides a DEV_RES_DEV_PARAM resource entry which specifies the GPIO controller device relevant for the DEV_RES_GPIO entries.

Preprocessor condition: not defined( CONFIG_DEVICE_GPIO )

#define DEV_STATIC_RES_GPIO(label_, id_, width_) [link] 

This macro is declared in device/class/gpio.h source file, line 437.

This macro specifies a GPIO resource entry in a static device resources table declaration.

Preprocessor condition: defined( CONFIG_DEVICE_GPIO )

See also DEV_RES_GPIO, DEV_DECLARE_STATIC and DEV_STATIC_RES_DEV_GPIO.

#define DEV_STATIC_RES_GPIO(label_, id_, width_) [link] 

This macro is declared in device/class/gpio.h source file, line 454.

Documentation from alternate declaration:

This macro specifies a GPIO resource entry in a static device resources table declaration.

Preprocessor condition: not defined( CONFIG_DEVICE_GPIO )

See also DEV_RES_GPIO, DEV_DECLARE_STATIC and DEV_STATIC_RES_DEV_GPIO.

#define DRIVER_GPIO_METHODS(prefix) [link] 

This macro is declared in device/class/gpio.h source file, line 302.

See also struct driver_gpio_s.

#define GCT_CONTAINER_ALGO_dev_gpio_queue [link] 

This macro is declared in device/class/gpio.h source file, line 238.

#define GPIO_INVALID_ID [link] 

This macro is declared in device/class/gpio.h source file, line 101.

Preprocessor condition: CONFIG_DEVICE_GPIO_MAX_ID < 255

#define GPIO_INVALID_ID [link] 

This macro is declared in device/class/gpio.h source file, line 104.

Preprocessor condition: not ( CONFIG_DEVICE_GPIO_MAX_ID < 255 )

#define __DEVICE_GPIO_H__ [link] 

This macro is declared in device/class/gpio.h source file, line 82.

typedef error_t (dev_gpio_cancel_t)(const struct device_gpio_s *gpio, struct dev_gpio_rq_s *rq) [link] 

This typedef is declared in device/class/gpio.h source file, line 212.

This function cancels a GPIO request.

The function returns 0 if the request has been cancelled or -EBUSY if the request has already ended or will terminate very soon. It may also return -ENOTSUP. The request kroutine is not executed when this function returns 0.

This declaration involves expansion of the DEV_GPIO_CANCEL macro.

typedef error_t (dev_gpio_get_input_t)(const struct device_gpio_s *gpio, gpio_id_t io_first, gpio_id_t io_last, uint8_t *data) [link] 

This typedef is declared in device/class/gpio.h source file, line 188.

This function reads the input value of one or several IOs.

The lsb of the first byte in the data vector contains the value of the IO at index io_first.

The size of the data array must be a multiple of 8 bytes. The values of the unused bits at the end of the array are undefined.

This declaration involves expansion of the DEV_GPIO_GET_INPUT macro.

bool_t dev_gpio_input(const struct device_gpio_s *accessor, gpio_id_t id, error_t *err) [link] 

This function is declared in device/class/gpio.h source file, line 380.

This function reads the value of a single gpio pin relying on the synchronous driver API. This will not work with all GPIO controllers.

This is available when CONFIG_DEVICE_GPIO is defined.

See also dev_gpio_get_input_t, dev_gpio_wait_input and Synchronous and asynchronous operation.

const uint8_t dev_gpio_mask0[8] [link] 

This constant is declared in device/class/gpio.h source file, line 115.

const uint8_t dev_gpio_mask1[8] [link] 

This constant is declared in device/class/gpio.h source file, line 114.

error_t dev_gpio_mode(const struct device_gpio_s *accessor, gpio_id_t id, enum dev_pin_driving_e mode) [link] 

This function is declared in device/class/gpio.h source file, line 350.

This function changes the mode of a single gpio pin relying on the synchronous driver API. This will not work with all GPIO controllers.

This is available when CONFIG_DEVICE_GPIO is defined.

See also dev_gpio_set_mode_t, dev_gpio_wait_mode and Synchronous and asynchronous operation.

error_t dev_gpio_out(const struct device_gpio_s *accessor, gpio_id_t id, bool_t x) [link] 

This function is declared in device/class/gpio.h source file, line 324.

This function sets the value of a single gpio pin relying on the synchronous driver API. This will not work with all GPIO controllers.

This is available when CONFIG_DEVICE_GPIO is defined.

See also dev_gpio_set_output_t, dev_gpio_wait_out and Synchronous and asynchronous operation.

void dev_gpio_request_async_to_sync(const struct device_gpio_s *gpio, struct dev_gpio_rq_s *rq) [link] 

This function is declared in device/class/gpio.h source file, line 291.

Helper that implements asynchronous f_request from other synchronous primitives.

This declaration involves expansion of the DEV_GPIO_REQUEST macro.

typedef void (dev_gpio_request_t)(const struct device_gpio_s *gpio, struct dev_gpio_rq_s *rq) [link] 

This typedef is declared in device/class/gpio.h source file, line 200.

This function enqueues a request to the GPIO driver.

Kroutine is callen upon completion.

This declaration involves expansion of the DEV_GPIO_REQUEST macro.

enum dev_gpio_request_type [link] 

This enum is declared in device/class/gpio.h source file, line 215.

IdentifierDescription
DEV_GPIO_MODEThis enum_value performs the same action as the dev_gpio_set_mode_t function. The request is handled in order, on the same queue as the DEV_GPIO_SET_OUTPUT and DEV_GPIO_GET_INPUT requests.
DEV_GPIO_SET_OUTPUTThis enum_value performs the same action as the dev_gpio_get_input_t function. The request is handled in order, on the same queue as the DEV_GPIO_MODE and DEV_GPIO_GET_INPUT requests.
DEV_GPIO_GET_INPUTThis enum_value performs the same action as the dev_gpio_set_output_t function. The request is handled in order, on the same queue as the DEV_GPIO_MODE and DEV_GPIO_SET_OUTPUT requests.
DEV_GPIO_UNTILThis enum_value waits until a masked set of input pins have a different value from what is specified in the request. The request is not handled in order with other requests. Not all implementation are required to handle multiple such requests at the same time. The request will terminate immediately with the -EBUSY error in this case. The request terminates immediately when the set of inputs is empty.

void dev_gpio_rq_done(struct dev_gpio_rq_s *rq) [link] 

This function is declared in device/class/gpio.h source file, line 286.

This function invokes or schedules execution of the gpio request callback associated to the request. For use in device drivers.

struct dev_gpio_rq_s * dev_gpio_rq_from_kr(struct kroutine_s *kr) [link] 

This function is declared in device/class/gpio.h source file, line 286.

This function retrieves a pointer to the request when in the request completion callback routine.

struct dev_gpio_rq_s * dev_gpio_rq_head(dev_request_queue_root_t *q) [link] 

This function is declared in device/class/gpio.h source file, line 286.

This function returns the oldest gpio request in the given queue. A NULL pointer is returned if the queue is empty. For use in device drivers.

void dev_gpio_rq_init(struct dev_gpio_rq_s *rq, kroutine_exec_t *exec) [link] 

This function is declared in device/class/gpio.h source file, line 286.

This function initializes the given gpio request callback. This must be used before submitting the request to a driver.

This is available when CONFIG_MUTEK_KROUTINE_SCHED is defined.

void dev_gpio_rq_init_immediate(struct dev_gpio_rq_s *rq, kroutine_exec_t *exec) [link] 

This function is declared in device/class/gpio.h source file, line 286.

This function initializes the given gpio request callback. This must be used before submitting the request to a driver.

void dev_gpio_rq_init_queue(struct dev_gpio_rq_s *rq, kroutine_exec_t *exec, struct kroutine_queue_s *queue) [link] 

This function is declared in device/class/gpio.h source file, line 286.

This function initializes the given gpio request callback. This must be used before submitting the request to a driver.

This is available when CONFIG_MUTEK_KROUTINE_QUEUE is defined.

void dev_gpio_rq_init_seq(struct dev_gpio_rq_s *rq, kroutine_exec_t *exec, struct kroutine_sequence_s *seq) [link] 

This function is declared in device/class/gpio.h source file, line 286.

This function initializes the given gpio request callback. This must be used before submitting the request to a driver.

This is available when CONFIG_MUTEK_KROUTINE_SCHED is defined.

struct dev_gpio_rq_s * dev_gpio_rq_pop(dev_request_queue_root_t *q) [link] 

This function is declared in device/class/gpio.h source file, line 286.

This function removes and return the oldest gpio request in the queue. A NULL pointer is returned if the queue is empty. For use in device drivers.

void dev_gpio_rq_pushback(dev_request_queue_root_t *q, struct dev_gpio_rq_s *rq) [link] 

This function is declared in device/class/gpio.h source file, line 286.

This function insert a new gpio request at the end of the given queue. For use in device drivers.

void dev_gpio_rq_remove(dev_request_queue_root_t *q, struct dev_gpio_rq_s *rq) [link] 

This function is declared in device/class/gpio.h source file, line 286.

This function removes the specified gpio request from the queue. For use in device drivers.

struct dev_gpio_rq_s [link] 

This struct is declared in device/class/gpio.h source file, line 242.

FieldDescription
union <anonymous> {
struct dev_request_s base;
typeof(struct dev_request_s::error) error;
typeof(struct dev_request_s::pvdata) pvdata;
};
gpio_id_t io_first;index of the first io to act on
gpio_id_t io_last;index of the last io to act on
enum dev_gpio_request_type type;
union <anonymous> {
struct <anonymous> {See DEV_GPIO_MODE and dev_gpio_set_mode_t.
const uint8_t * mask;
enum dev_pin_driving_e mode;
} mode;
struct <anonymous> {See DEV_GPIO_SET_OUTPUT and dev_gpio_set_output_t.
const uint8_t * set_mask;
const uint8_t * clear_mask;
} output;
struct <anonymous> {See DEV_GPIO_GET_INPUT and dev_gpio_get_input_t.
uint8_t * data;
} input;
struct <anonymous> {See DEV_GPIO_UNTIL.
const uint8_t * mask;This specifies which input bits are tested against the current data value.
const uint8_t * data;The request terminates when any masked input bit is not equal to data.
} until;
};

struct dev_request_s * dev_gpio_rq_s_base(struct dev_gpio_rq_s *x) [link] 

This function is declared in device/class/gpio.h source file, line 286.

struct dev_gpio_rq_s * dev_gpio_rq_s_cast(struct dev_request_s *x) [link] 

This function is declared in device/class/gpio.h source file, line 286.

typedef error_t (dev_gpio_set_mode_t)(const struct device_gpio_s *gpio, gpio_id_t io_first, gpio_id_t io_last, const uint8_t *mask, enum dev_pin_driving_e mode) [link] 

This typedef is declared in device/class/gpio.h source file, line 135.

This function changes the mode of one or several IOs.

The mask parameter is a bit vector which specifies IOs that will have their mode changed. The lsb of the first byte in the vector specifies the mode change for the IO at index io_first. The size of the mask array must be a multiple of 8 bytes. Padding bits at the end of the mask vectors can have any value.

When a single IO needs to be modified, the io_first and io_last parameters must be equal and the predefined vector dev_gpio_mask1 can be used.

This declaration involves expansion of the DEV_GPIO_SET_MODE macro.

typedef error_t (dev_gpio_set_output_t)(const struct device_gpio_s *gpio, gpio_id_t io_first, gpio_id_t io_last, const uint8_t *set_mask, const uint8_t *clear_mask) [link] 

This typedef is declared in device/class/gpio.h source file, line 171.

This function changes the output state of one or several IOs.

Two bit vectors are used to specify how to change the output values of the IOs in the given range:

set_mask
clear_mask
operation
0
0
clear
0
1
unchanged
1
0
toggle
1
1
set

The new value of an output can be computed using this formula: new = set_mask ^ (old & ( set_mask ^ clear_mask )).

The lsb of the first byte in the set_mask and clear_mask vectors specify the value change for the IO at index io_first. The size of the bit vector arrays must be be a multiple of 8 bytes. Padding bits at the end of the mask vectors can have any value.

When a single IO needs to be modified, the io_first and io_last parameters must be equal and the predefined vector dev_gpio_mask1 can be used.

This declaration involves expansion of the DEV_GPIO_SET_OUTPUT macro.

bool_t dev_gpio_wait_input(const struct device_gpio_s *accessor, gpio_id_t id, error_t *err) [link] 

This function is declared in device/class/gpio.h source file, line 398.

This function reads the value of a single gpio pin. This function uses the scheduler api to put the current context in wait state during the request.

This is available when CONFIG_DEVICE_GPIO and CONFIG_MUTEK_CONTEXT_SCHED are both defined.

See also dev_gpio_get_input_t, dev_gpio_input and Synchronous and asynchronous operation.

error_t dev_gpio_wait_mode(const struct device_gpio_s *accessor, gpio_id_t id, enum dev_pin_driving_e mode) [link] 

This function is declared in device/class/gpio.h source file, line 366.

This function changes the mode of a single gpio pin. This function uses the scheduler api to put the current context in wait state during the request.

This is available when CONFIG_DEVICE_GPIO and CONFIG_MUTEK_CONTEXT_SCHED are both defined.

See also dev_gpio_set_mode_t, dev_gpio_mode and Synchronous and asynchronous operation.

error_t dev_gpio_wait_out(const struct device_gpio_s *accessor, gpio_id_t id, bool_t x) [link] 

This function is declared in device/class/gpio.h source file, line 339.

This function sets the value of a single gpio pin. This function uses the scheduler api to put the current context in wait state during the request.

This is available when CONFIG_DEVICE_GPIO and CONFIG_MUTEK_CONTEXT_SCHED are both defined.

See also dev_gpio_set_output_t, dev_gpio_out and Synchronous and asynchronous operation.

error_t dev_gpio_wait_rq(const struct device_gpio_s *acc, struct dev_gpio_rq_s *rq) [link] 

This function is declared in device/class/gpio.h source file, line 313.

This function use the scheduler api to put current context in wait state during the request. This can only be called from a scheduler context.

This is available when CONFIG_MUTEK_CONTEXT_SCHED is defined.

error_t dev_gpio_wait_until(const struct device_gpio_s *accessor, gpio_id_t id, bool_t x) [link] 

This function is declared in device/class/gpio.h source file, line 415.

This function reads the value of a single gpio pin. This function uses the scheduler api to put the current context in wait state during the request.

This is available when CONFIG_DEVICE_GPIO and CONFIG_MUTEK_CONTEXT_SCHED are both defined.

See also dev_gpio_get_input_t, dev_gpio_input and Synchronous and asynchronous operation.

error_t device_gpio_get_setup(struct device_gpio_s *accessor, struct device_s *dev, const char *pin_list, gpio_id_t *map, gpio_width_t *wmap) [link] 

This function is declared in device/class/gpio.h source file, line 517.

This function setups an accessor to the gpio device declared using DEV_STATIC_RES_DEV_GPIO in the resources then calls the device_gpio_setup function.

When the function succeed, the accessor is left initialized and must be released by the caller.

This is available when CONFIG_DEVICE_GPIO is defined.

error_t device_gpio_map_set_mode(const struct device_gpio_s *accessor, const gpio_id_t *map, const gpio_width_t *wmap, uint_fast8_t count, ...) [link] 

This function is declared in device/class/gpio.h source file, line 526.

struct device_gpio_s [link] 

This struct is declared in device/class/spi.h source file, line 412.

This struct is the device accessor object type for the gpio device class. This accessor must be initialized by calling the device_get_accessor function.

See also DRIVER_CLASS_GPIO, struct device_accessor_s and Device accessor.

FieldDescription
union <anonymous> {
struct device_accessor_s base;
struct <anonymous> {
struct device_s * dev;
struct driver_gpio_s * api;
uint_fast8_t number;
};
};

struct device_accessor_s * device_gpio_s_base(struct device_gpio_s *x) [link] 

This function is declared in DRIVER_CLASS_TYPES function like macro expansion, line 43 in device/class/gpio.h source file, line 300.

This function casts a gpio device accessor to a generic device accessor

struct device_gpio_s * device_gpio_s_cast(struct device_accessor_s *x) [link] 

This function is declared in DRIVER_CLASS_TYPES function like macro expansion, line 36 in device/class/gpio.h source file, line 300.

This function casts a generic device accessor to a gpio device accessor

error_t device_gpio_setup(struct device_gpio_s *accessor, struct device_s *dev, const char *pin_list, gpio_id_t *map, gpio_width_t *wmap) [link] 

This function is declared in device/class/gpio.h source file, line 506.

This function retrieves index of GPIO pins declared device resources from a list of pin labels. It can optionally set the mode of the pins.

The index of the pins named in the pin_list string are stored in the map array. If the wmap parameter is not NULL, the associated size of pin range is also stored.

The list is composed by space separated pin label names. All pin names present in the list must match an available device resource unless the name is suffixed by ?. The value GPIO_INVALID_ID is stored in the map array if an optional pin is not declared.

If a label in the list is suffixed by :width, the pin width declared in the resource must match the specified width.

If a label is prefixed by a pin direction symbol, the mode of the associated pins is changed accordingly. The accessor parameter may be NULL if this feature is not used.

Examples [link] 

gpio_id_t map[3];
device_res_gpio_map(&gpio, dev, "<irq:1 >rst:1 <bus:8 >sleep?:1", map, NULL);
gpio_id_t map[2];
gpio_width_t wmap[2];
device_res_gpio_map(NULL, dev, "ioa iob?", map, wmap);

This is available when CONFIG_DEVICE_GPIO is defined.

See also dev_pin_driving_e and device_gpio_get_setup.

error_t device_res_add_gpio(struct device_s *dev, const char *label, gpio_id_t id, gpio_width_t width) [link] 

This function is declared in device/class/gpio.h source file, line 432.

This function adds a GPIO pins binding to the device resources list.

This is available when CONFIG_DEVICE_GPIO and CONFIG_DEVICE_RESOURCE_ALLOC are both defined.

See also DEV_RES_GPIO and DEV_STATIC_RES_GPIO.

error_t device_res_gpio_map(struct device_s *dev, const char *pin_list, gpio_id_t *map, gpio_width_t *wmap) [link] 

This function is declared in device/class/gpio.h source file, line 521.

struct driver_gpio_s [link] 

This struct is declared in DRIVER_CLASS_TYPES function like macro expansion, line 5 in device/class/gpio.h source file, line 300.

This struct is the driver API descriptor for the gpio device class.

See also DRIVER_CLASS_GPIO and struct driver_class_s.

FieldDescription
uint16_t class_;
uint16_t ctx_offset;
dev_gpio_set_mode_t * f_set_mode;
dev_gpio_set_output_t * f_set_output;
dev_gpio_get_input_t * f_get_input;
dev_gpio_request_t * f_request;
dev_gpio_cancel_t * f_cancel;

typedef uint8_t gpio_id_t [link] 

This typedef is declared in device/class/gpio.h source file, line 101.

Alternate declarations with same identifier: [1], [2].

Preprocessor condition: CONFIG_DEVICE_GPIO_MAX_ID < 255

typedef uint16_t gpio_id_t [link] 

This typedef is declared in device/class/gpio.h source file, line 104.

Alternate declarations with same identifier: [1], [2].

Preprocessor condition: not ( CONFIG_DEVICE_GPIO_MAX_ID < 255 )

typedef uint8_t gpio_width_t [link] 

This typedef is declared in device/class/gpio.h source file, line 109.

Alternate declarations with same identifier: [1], [2].

Preprocessor condition: CONFIG_DEVICE_GPIO_MAX_WIDTH < 255

typedef uint16_t gpio_width_t [link] 

This typedef is declared in device/class/gpio.h source file, line 111.

Alternate declarations with same identifier: [1], [2].

Preprocessor condition: not ( CONFIG_DEVICE_GPIO_MAX_WIDTH < 255 )

Valid XHTML 1.0 StrictGenerated by diaxen on Thu Aug 4 15:44:05 2022 using MkDoc