1.\" 2.\" Copyright (c) 2014 Rui Paulo 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.Dd September 3, 2025 27.Dt GPIO 3 28.Os 29.Sh NAME 30.Nm gpio_open , 31.Nm gpio_close 32.Nd "library to handle GPIO pins" 33.Sh LIBRARY 34.Lb libgpio 35.Sh SYNOPSIS 36.In sys/types.h 37.In libgpio.h 38.Ft "gpio_handle_t" 39.Fn gpio_open "unsigned int unit" 40.Ft "gpio_handle_t" 41.Fn gpio_open_device "const char *device" 42.Ft void 43.Fn gpio_close "gpio_handle_t handle" 44.Ft int 45.Fn gpio_pin_list "gpio_handle_t handle" "gpio_config_t **pcfgs" 46.Ft int 47.Fn gpio_pin_config "gpio_handle_t handle" "gpio_config_t *cfg" 48.Ft int 49.Fn gpio_pin_set_name "gpio_handle_t handle" "gpio_pin_t pin" "char *name" 50.Ft int 51.Fn gpio_pin_set_flags "gpio_handle_t handle" "gpio_config_t *cfg" 52.Ft gpio_value_t 53.Fn gpio_pin_get "gpio_handle_t handle" "gpio_pin_t pin" 54.Ft int 55.Fn gpio_pin_set "gpio_handle_t handle" "gpio_pin_t pin" "gpio_value_t value" 56.Ft int 57.Fn gpio_pin_toggle "gpio_handle_t handle" "gpio_pin_t pin" 58.Ft int 59.Fn gpio_pin_low "gpio_handle_t handle" "gpio_pin_t pin" 60.Ft int 61.Fn gpio_pin_high "gpio_handle_t handle" "gpio_pin_t pin" 62.Ft int 63.Fn gpio_pin_input "gpio_handle_t handle" "gpio_pin_t pin" 64.Ft int 65.Fn gpio_pin_output "gpio_handle_t handle" "gpio_pin_t pin" 66.Ft int 67.Fn gpio_pin_opendrain "gpio_handle_t handle" "gpio_pin_t pin" 68.Ft int 69.Fn gpio_pin_pushpull "gpio_handle_t handle" "gpio_pin_t pin" 70.Ft int 71.Fn gpio_pin_tristate "gpio_handle_t handle" "gpio_pin_t pin" 72.Ft int 73.Fn gpio_pin_pullup "gpio_handle_t handle" "gpio_pin_t pin" 74.Ft int 75.Fn gpio_pin_pulldown "gpio_handle_t handle" "gpio_pin_t pin" 76.Ft int 77.Fn gpio_pin_invin "gpio_handle_t handle" "gpio_pin_t pin" 78.Ft int 79.Fn gpio_pin_invout "gpio_handle_t handle" "gpio_pin_t pin" 80.Ft int 81.Fn gpio_pin_pulsate "gpio_handle_t handle" "gpio_pin_t pin" 82.Ft int 83.Fn gpio_configure_events "gpio_handle_t handle" "uint32_t report_type" "uint32_t fifo_size" 84.Ft int 85.Fn gpio_fileno "gpio_handle_t handle" 86.Sh DESCRIPTION 87The 88.Nm libgpio 89library provides an interface to configure GPIO pins. 90The library operates with a 91.Ft gpio_handle_t 92opaque type which can be created with 93.Fn gpio_open 94or 95.Fn gpio_open_device . 96When no more GPIO operations are needed, this handle can be destroyed 97with 98.Fn gpio_close . 99.Pp 100To get a list of all available pins, one can call 101.Fn gpio_pin_list . 102This function takes a pointer to a 103.Ft gpio_config_t 104which is dynamically allocated. 105This pointer should be freed with 106.Xr free 3 107when it is no longer necessary. 108.Pp 109The function 110.Fn gpio_pin_config 111retrieves the current configuration of a pin. 112The pin number should be passed in via the 113.Ft g_pin 114variable which is part of the 115.Ft gpio_config_t 116structure. 117.Pp 118The function 119.Fn gpio_pin_set_name 120sets the name used to describe a pin. 121.Pp 122The function 123.Fn gpio_pin_set_flags 124configures a pin with the flags passed in by the 125.Ft gpio_config_t 126structure. 127The pin number should also be passed in through the 128.Ft g_pin 129variable. 130All other structure members will be ignored by this function. 131The list of flags can be found in 132.In sys/gpio.h . 133.Pp 134The get or set the state of a GPIO pin, the functions 135.Fn gpio_pin_get 136and 137.Fn gpio_pin_set 138are available, respectively. 139To toggle the state, use 140.Fn gpio_pin_toggle . 141.Pp 142The functions 143.Fn gpio_pin_low 144and 145.Fn gpio_pin_high 146are wrappers around 147.Fn gpio_pin_set . 148.Pp 149The functions 150.Fn gpio_pin_input , 151.Fn gpio_pin_output , 152.Fn gpio_pin_opendrain , 153.Fn gpio_pin_pushpull , 154.Fn gpio_pin_tristate , 155.Fn gpio_pin_pullup , 156.Fn gpio_pin_pulldown , 157.Fn gpio_pin_invin , 158.Fn gpio_pin_invout 159and 160.Fn gpio_pin_pulsate 161are wrappers around 162.Fn gpio_pin_set_flags . 163.Pp 164The function 165.Fn gpio_configure_events 166configures the interrupt report type and FIFO size for buffered 167gpio interrupts. 168The report type is specified by one of the following values: 169.Bl -tag -width indent 170.It Dv GPIO_EVENT_REPORT_DETAIL 171Events are reported using 172.Ft struct gpio_event_detail . 173.It Dv GPIO_EVENT_REPORT_SUMMARY 174Events are reported using 175.Ft struct gpio_event_summary . 176.El 177.Pp 178By default, the report type is 179.Dv GPIO_EVENT_REPORT_DETAIL , 180with a default FIFO size of 2 * number of pins belonging to the 181.Ft gpio_device_t 182instance. 183The FIFO argument is only meaningful when 184.Fa report_type 185is 186.Dv GPIO_EVENT_REPORT_DETAIL . 187The structures associated with each report type are defined in 188.In sys/gpio.h . 189This setting is tracked on a per device instance basis. 190The FIFO size cannot be reduced below the default value, 191nor can it be decreased after it has been increased. 192If any pin on the device has already been configured for interrupts, 193.Fn gpio_configure_events 194fails and returns -1. 195On success 0 is returned. 196.Pp 197The function 198.Fn gpio_fileno 199returns the file descriptor associated with the 200.Ft gpio_handle_t 201instance. 202.Pp 203File operations have the following semantics: 204.Bl -tag -width "read (2)" 205.It Xr read 2 206Read one or more gpio interrupts that have occured 207since the last successful 208.Xr read 2 . 209The results are placed into the output buffer 210of the type previously established via 211.Fn gpio_configure_events . 212If there are no pending interrupts, 213.Xr read 2 214blocks until an interrupt occurs, unless 215.Dv O_NONBLOCK 216is set. 217.It Xr poll 2 218When receiving notification via 219.Xr poll 2 220or similar interfaces, the file descriptor becomes readable when 221one or more gpio interrupts are pending. 222.El 223.Sh EXAMPLES 224The following example shows how to configure pin 16 as output and then 225drive it high: 226.Bd -literal 227#include <sys/types.h> 228#include <err.h> 229#include <libgpio.h> 230 231gpio_handle_t handle; 232 233handle = gpio_open(0); 234if (handle == GPIO_INVALID_HANDLE) 235 err(1, "gpio_open failed"); 236gpio_pin_output(handle, 16); 237gpio_pin_high(handle, 16); 238gpio_close(handle); 239.Ed 240.Pp 241The following example shows how to get a configuration of a pin: 242.Bd -literal 243gpio_config_t cfg; 244 245cfg.g_pin = 32; 246gpio_pin_config(handle, &cfg); 247.Ed 248.Pp 249The structure will contain the name of the pin and its flags. 250.Sh SEE ALSO 251.Xr gpiobus 4 , 252.Xr gpioctl 8 253.Sh HISTORY 254The 255.Nm libgpio 256library first appeared in 257.Fx 11.0 . 258.Sh AUTHORS 259The 260.Nm libgpio 261library was implemented by 262.An Rui Paulo Aq Mt rpaulo@FreeBSD.org . 263