.\" .\" Copyright (c) 2014 Rui Paulo .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .Dd September 3, 2025 .Dt GPIO 3 .Os .Sh NAME .Nm gpio_open , .Nm gpio_close .Nd "library to handle GPIO pins" .Sh LIBRARY .Lb libgpio .Sh SYNOPSIS .In sys/types.h .In libgpio.h .Ft "gpio_handle_t" .Fn gpio_open "unsigned int unit" .Ft "gpio_handle_t" .Fn gpio_open_device "const char *device" .Ft void .Fn gpio_close "gpio_handle_t handle" .Ft int .Fn gpio_pin_list "gpio_handle_t handle" "gpio_config_t **pcfgs" .Ft int .Fn gpio_pin_config "gpio_handle_t handle" "gpio_config_t *cfg" .Ft int .Fn gpio_pin_set_name "gpio_handle_t handle" "gpio_pin_t pin" "char *name" .Ft int .Fn gpio_pin_set_flags "gpio_handle_t handle" "gpio_config_t *cfg" .Ft gpio_value_t .Fn gpio_pin_get "gpio_handle_t handle" "gpio_pin_t pin" .Ft int .Fn gpio_pin_set "gpio_handle_t handle" "gpio_pin_t pin" "gpio_value_t value" .Ft int .Fn gpio_pin_toggle "gpio_handle_t handle" "gpio_pin_t pin" .Ft int .Fn gpio_pin_low "gpio_handle_t handle" "gpio_pin_t pin" .Ft int .Fn gpio_pin_high "gpio_handle_t handle" "gpio_pin_t pin" .Ft int .Fn gpio_pin_input "gpio_handle_t handle" "gpio_pin_t pin" .Ft int .Fn gpio_pin_output "gpio_handle_t handle" "gpio_pin_t pin" .Ft int .Fn gpio_pin_opendrain "gpio_handle_t handle" "gpio_pin_t pin" .Ft int .Fn gpio_pin_pushpull "gpio_handle_t handle" "gpio_pin_t pin" .Ft int .Fn gpio_pin_tristate "gpio_handle_t handle" "gpio_pin_t pin" .Ft int .Fn gpio_pin_pullup "gpio_handle_t handle" "gpio_pin_t pin" .Ft int .Fn gpio_pin_pulldown "gpio_handle_t handle" "gpio_pin_t pin" .Ft int .Fn gpio_pin_invin "gpio_handle_t handle" "gpio_pin_t pin" .Ft int .Fn gpio_pin_invout "gpio_handle_t handle" "gpio_pin_t pin" .Ft int .Fn gpio_pin_pulsate "gpio_handle_t handle" "gpio_pin_t pin" .Ft int .Fn gpio_configure_events "gpio_handle_t handle" "uint32_t report_type" "uint32_t fifo_size" .Ft int .Fn gpio_fileno "gpio_handle_t handle" .Sh DESCRIPTION The .Nm libgpio library provides an interface to configure GPIO pins. The library operates with a .Ft gpio_handle_t opaque type which can be created with .Fn gpio_open or .Fn gpio_open_device . When no more GPIO operations are needed, this handle can be destroyed with .Fn gpio_close . .Pp To get a list of all available pins, one can call .Fn gpio_pin_list . This function takes a pointer to a .Ft gpio_config_t which is dynamically allocated. This pointer should be freed with .Xr free 3 when it is no longer necessary. .Pp The function .Fn gpio_pin_config retrieves the current configuration of a pin. The pin number should be passed in via the .Ft g_pin variable which is part of the .Ft gpio_config_t structure. .Pp The function .Fn gpio_pin_set_name sets the name used to describe a pin. .Pp The function .Fn gpio_pin_set_flags configures a pin with the flags passed in by the .Ft gpio_config_t structure. The pin number should also be passed in through the .Ft g_pin variable. All other structure members will be ignored by this function. The list of flags can be found in .In sys/gpio.h . .Pp The get or set the state of a GPIO pin, the functions .Fn gpio_pin_get and .Fn gpio_pin_set are available, respectively. To toggle the state, use .Fn gpio_pin_toggle . .Pp The functions .Fn gpio_pin_low and .Fn gpio_pin_high are wrappers around .Fn gpio_pin_set . .Pp The functions .Fn gpio_pin_input , .Fn gpio_pin_output , .Fn gpio_pin_opendrain , .Fn gpio_pin_pushpull , .Fn gpio_pin_tristate , .Fn gpio_pin_pullup , .Fn gpio_pin_pulldown , .Fn gpio_pin_invin , .Fn gpio_pin_invout and .Fn gpio_pin_pulsate are wrappers around .Fn gpio_pin_set_flags . .Pp The function .Fn gpio_configure_events configures the interrupt report type and FIFO size for buffered gpio interrupts. The report type is specified by one of the following values: .Bl -tag -width indent .It Dv GPIO_EVENT_REPORT_DETAIL Events are reported using .Ft struct gpio_event_detail . .It Dv GPIO_EVENT_REPORT_SUMMARY Events are reported using .Ft struct gpio_event_summary . .El .Pp By default, the report type is .Dv GPIO_EVENT_REPORT_DETAIL , with a default FIFO size of 2 * number of pins belonging to the .Ft gpio_device_t instance. The FIFO argument is only meaningful when .Fa report_type is .Dv GPIO_EVENT_REPORT_DETAIL . The structures associated with each report type are defined in .In sys/gpio.h . This setting is tracked on a per device instance basis. The FIFO size cannot be reduced below the default value, nor can it be decreased after it has been increased. If any pin on the device has already been configured for interrupts, .Fn gpio_configure_events fails and returns -1. On success 0 is returned. .Pp The function .Fn gpio_fileno returns the file descriptor associated with the .Ft gpio_handle_t instance. .Pp File operations have the following semantics: .Bl -tag -width "read (2)" .It Xr read 2 Read one or more gpio interrupts that have occured since the last successful .Xr read 2 . The results are placed into the output buffer of the type previously established via .Fn gpio_configure_events . If there are no pending interrupts, .Xr read 2 blocks until an interrupt occurs, unless .Dv O_NONBLOCK is set. .It Xr poll 2 When receiving notification via .Xr poll 2 or similar interfaces, the file descriptor becomes readable when one or more gpio interrupts are pending. .El .Sh EXAMPLES The following example shows how to configure pin 16 as output and then drive it high: .Bd -literal #include #include #include gpio_handle_t handle; handle = gpio_open(0); if (handle == GPIO_INVALID_HANDLE) err(1, "gpio_open failed"); gpio_pin_output(handle, 16); gpio_pin_high(handle, 16); gpio_close(handle); .Ed .Pp The following example shows how to get a configuration of a pin: .Bd -literal gpio_config_t cfg; cfg.g_pin = 32; gpio_pin_config(handle, &cfg); .Ed .Pp The structure will contain the name of the pin and its flags. .Sh SEE ALSO .Xr gpiobus 4 , .Xr gpioctl 8 .Sh HISTORY The .Nm libgpio library first appeared in .Fx 11.0 . .Sh AUTHORS The .Nm libgpio library was implemented by .An Rui Paulo Aq Mt rpaulo@FreeBSD.org .