gpio.h

Go to the documentation of this file.

/*
 * This file is part of the Ultibo project, https://ultibo.org/
 *
 * The MIT License (MIT)
 *
 * Copyright (c) 2026 Garry Wood <garry@softoz.com.au>
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 * THE SOFTWARE.
 */
#ifndef _ULTIBO_GPIO_H
#define _ULTIBO_GPIO_H
 
#ifdef __cplusplus
extern "C" {
#endif
 
#include "ultibo/globaltypes.h"
#include "ultibo/globalconst.h"
#include "ultibo/devices.h"

#define GPIO_NAME_PREFIX    "GPIO" 

#define GPIO_TYPE_NONE  0
 
#define GPIO_TYPE_MAX   0

#define GPIO_STATE_DISABLED 0
#define GPIO_STATE_ENABLED  1
 
#define GPIO_STATE_MAX  1

#define GPIO_FLAG_NONE  0x00000000
#define GPIO_FLAG_PULL_UP   0x00000001 
#define GPIO_FLAG_PULL_DOWN 0x00000002 
#define GPIO_FLAG_TRIGGER_LOW   0x00000004 
#define GPIO_FLAG_TRIGGER_HIGH  0x00000008 
#define GPIO_FLAG_TRIGGER_RISING    0x00000010 
#define GPIO_FLAG_TRIGGER_FALLING   0x00000020 
#define GPIO_FLAG_TRIGGER_EDGE  0x00000040 
#define GPIO_FLAG_TRIGGER_ASYNC 0x00000080 

#define GPIO_EVENT_FLAG_NONE    0x00000000
#define GPIO_EVENT_FLAG_REPEAT  0x00000001 
#define GPIO_EVENT_FLAG_INTERRUPT   0x00000002 
                                               // Caution: Events called by the interrupt handler must obey interrupt
                                               //          rules with regard to locks, memory allocation and latency


typedef struct _GPIO_PROPERTIES GPIO_PROPERTIES;
struct _GPIO_PROPERTIES
{
    uint32_t flags; 
    uint32_t pinmin;
    uint32_t pinmax;
    uint32_t pincount;
    uint32_t functionmin;
    uint32_t functionmax;
    uint32_t functioncount;
};

typedef struct _GPIO_DEVICE GPIO_DEVICE; 
typedef struct _GPIO_PIN GPIO_PIN; 

typedef struct _GPIO_EVENT GPIO_EVENT;
struct _GPIO_EVENT
{
    GPIO_PIN *pin; 
    gpio_event_cb callback; 
    void *data; 
    uint32_t timeout; 
    GPIO_EVENT *prev; 
    GPIO_EVENT *next; 
};

struct _GPIO_PIN
{
    GPIO_DEVICE *gpio; 
    uint32_t pin; 
    uint32_t flags; 
    uint32_t trigger; 
    uint32_t count; 
    EVENT_HANDLE event; 
    GPIO_EVENT *events; 
};

typedef uint32_t STDCALL (*gpio_enumerate_cb)(GPIO_DEVICE *gpio, void *data);
typedef uint32_t STDCALL (*gpio_notification_cb)(DEVICE *device, void *data, uint32_t notification);

typedef uint32_t STDCALL (*gpio_device_start_proc)(GPIO_DEVICE *gpio);
typedef uint32_t STDCALL (*gpio_device_stop_proc)(GPIO_DEVICE *gpio);
 
typedef uint32_t STDCALL (*gpio_device_read_proc)(GPIO_DEVICE *gpio, uint32_t reg);
typedef void STDCALL (*gpio_device_write_proc)(GPIO_DEVICE *gpio, uint32_t reg, uint32_t value);
 
typedef uint32_t STDCALL (*gpio_device_input_get_proc)(GPIO_DEVICE *gpio, uint32_t pin);
typedef uint32_t STDCALL (*gpio_device_input_wait_proc)(GPIO_DEVICE *gpio, uint32_t pin, uint32_t trigger, uint32_t timeout);
typedef uint32_t STDCALL (*gpio_device_input_event_proc)(GPIO_DEVICE *gpio, uint32_t pin, uint32_t trigger, uint32_t flags, uint32_t timeout, gpio_event_cb callback, void *data);
typedef uint32_t STDCALL (*gpio_device_input_cancel_proc)(GPIO_DEVICE *gpio, uint32_t pin);
 
typedef uint32_t STDCALL (*gpio_device_output_set_proc)(GPIO_DEVICE *gpio, uint32_t pin, uint32_t level);
 
typedef uint32_t STDCALL (*gpio_device_pull_get_proc)(GPIO_DEVICE *gpio, uint32_t pin);
typedef uint32_t STDCALL (*gpio_device_pull_select_proc)(GPIO_DEVICE *gpio, uint32_t pin, uint32_t mode);
 
typedef uint32_t STDCALL (*gpio_device_function_get_proc)(GPIO_DEVICE *gpio, uint32_t pin);
typedef uint32_t STDCALL (*gpio_device_function_select_proc)(GPIO_DEVICE *gpio, uint32_t pin, uint32_t mode);
 
typedef uint32_t STDCALL (*gpio_device_get_properties_proc)(GPIO_DEVICE *gpio, GPIO_PROPERTIES *properties);
 
struct _GPIO_DEVICE
{
    // Device Properties
    DEVICE device; 
    // GPIO Properties
    uint32_t gpioid; 
    uint32_t gpiostate; 
    gpio_device_start_proc devicestart; 
    gpio_device_stop_proc devicestop; 
    gpio_device_read_proc deviceread; 
    gpio_device_write_proc devicewrite; 
    gpio_device_input_get_proc deviceinputget; 
    gpio_device_input_wait_proc deviceinputwait; 
    gpio_device_input_event_proc deviceinputevent; 
    gpio_device_input_cancel_proc deviceinputcancel; 
    gpio_device_output_set_proc deviceoutputset; 
    gpio_device_pull_get_proc devicepullget; 
    gpio_device_pull_select_proc devicepullselect; 
    gpio_device_function_get_proc devicefunctionget; 
    gpio_device_function_select_proc devicefunctionselect; 
    gpio_device_get_properties_proc devicegetproperties; 
    // Driver Properties
    MUTEX_HANDLE lock; 
    void *address; 
    GPIO_PIN *pins; 
    GPIO_PROPERTIES properties; 
    // Statistics Properties
    uint32_t getcount;
    uint32_t setcount;
    uint32_t waitcount;
    uint32_t eventcount;
    // Internal Properties
    GPIO_DEVICE *prev; 
    GPIO_DEVICE *next; 
};

typedef struct _GPIO_INFO GPIO_INFO;
struct _GPIO_INFO
{
    GPIO_DEVICE *gpio; 
    uint32_t pin; 
    uint32_t func; 
    uint32_t pull; 
    uint32_t trigger; 
};

static const GPIO_INFO GPIO_INFO_UNKNOWN = {
  NULL,
  GPIO_PIN_UNKNOWN,
  GPIO_FUNCTION_UNKNOWN,
  GPIO_PULL_UNKNOWN,
  GPIO_TRIGGER_UNKNOWN};


uint32_t STDCALL gpio_device_start(GPIO_DEVICE *gpio);

uint32_t STDCALL gpio_device_stop(GPIO_DEVICE *gpio);

uint32_t STDCALL gpio_device_read(GPIO_DEVICE *gpio, uint32_t reg);

void STDCALL gpio_device_write(GPIO_DEVICE *gpio, uint32_t reg, uint32_t value);

uint32_t STDCALL gpio_device_input_get(GPIO_DEVICE *gpio, uint32_t pin);

uint32_t STDCALL gpio_device_input_wait(GPIO_DEVICE *gpio, uint32_t pin, uint32_t trigger, uint32_t timeout);

uint32_t STDCALL gpio_device_input_event(GPIO_DEVICE *gpio, uint32_t pin, uint32_t trigger, uint32_t flags, uint32_t timeout, gpio_event_cb callback, void *data);

uint32_t STDCALL gpio_device_input_cancel(GPIO_DEVICE *gpio, uint32_t pin);

uint32_t STDCALL gpio_device_output_set(GPIO_DEVICE *gpio, uint32_t pin, uint32_t level);

uint32_t STDCALL gpio_device_level_get(GPIO_DEVICE *gpio, uint32_t pin);

uint32_t STDCALL gpio_device_level_set(GPIO_DEVICE *gpio, uint32_t pin, uint32_t level);

uint32_t STDCALL gpio_device_pull_get(GPIO_DEVICE *gpio, uint32_t pin);

uint32_t STDCALL gpio_device_pull_select(GPIO_DEVICE *gpio, uint32_t pin, uint32_t mode);

uint32_t STDCALL gpio_device_function_get(GPIO_DEVICE *gpio, uint32_t pin);

uint32_t STDCALL gpio_device_function_select(GPIO_DEVICE *gpio, uint32_t pin, uint32_t mode);

uint32_t STDCALL gpio_device_properties(GPIO_DEVICE *gpio, GPIO_PROPERTIES *properties);

uint32_t STDCALL gpio_device_get_properties(GPIO_DEVICE *gpio, GPIO_PROPERTIES *properties);

GPIO_DEVICE * STDCALL gpio_device_create(void);

GPIO_DEVICE * STDCALL gpio_device_create_ex(uint32_t size);

uint32_t STDCALL gpio_device_destroy(GPIO_DEVICE *gpio);

uint32_t STDCALL gpio_device_register(GPIO_DEVICE *gpio);

uint32_t STDCALL gpio_device_deregister(GPIO_DEVICE *gpio);

GPIO_DEVICE * STDCALL gpio_device_find(uint32_t gpioid);

GPIO_DEVICE * STDCALL gpio_device_find_by_name(const char *name);

GPIO_DEVICE * STDCALL gpio_device_find_by_description(const char *description);

uint32_t STDCALL gpio_device_enumerate(gpio_enumerate_cb callback, void *data);

uint32_t STDCALL gpio_device_notification(GPIO_DEVICE *gpio, gpio_notification_cb callback, void *data, uint32_t notification, uint32_t flags);


uint32_t STDCALL gpio_get_count(void);

GPIO_DEVICE * STDCALL gpio_device_get_default(void);

uint32_t STDCALL gpio_device_set_default(GPIO_DEVICE *gpio);

GPIO_DEVICE * STDCALL gpio_device_check(GPIO_DEVICE *gpio);

uint32_t STDCALL gpio_type_to_string(uint32_t gpiotype, char *string, uint32_t len);

uint32_t STDCALL gpio_state_to_string(uint32_t gpiostate, char *string, uint32_t len);

GPIO_EVENT * STDCALL gpio_device_create_event(GPIO_DEVICE *gpio, GPIO_PIN *pin, gpio_event_cb callback, void *data, uint32_t timeout);

uint32_t STDCALL gpio_device_destroy_event(GPIO_DEVICE *gpio, GPIO_EVENT *event);

uint32_t STDCALL gpio_device_register_event(GPIO_DEVICE *gpio, GPIO_PIN *pin, GPIO_EVENT *event);

uint32_t STDCALL gpio_device_deregister_event(GPIO_DEVICE *gpio, GPIO_PIN *pin, GPIO_EVENT *event);
 
uint32_t STDCALL gpio_pin_to_string(uint32_t pin, char *string, uint32_t len);
uint32_t STDCALL gpio_level_to_string(uint32_t level, char *string, uint32_t len);
uint32_t STDCALL gpio_trigger_to_string(uint32_t trigger, char *string, uint32_t len);
 
uint32_t STDCALL gpio_pull_to_string(uint32_t value, char *string, uint32_t len);
uint32_t STDCALL gpio_function_to_string(uint32_t value, char *string, uint32_t len);
 
#ifdef __cplusplus
}
#endif
 
#endif // _ULTIBO_GPIO_H