1 files changed, 262 insertions, 0 deletions
diff --git a/lib/libgpio/gpio.3 b/lib/libgpio/gpio.3
new file mode 100644
index 000000000000..cb413b838bd0
--- /dev/null
+++ b/lib/libgpio/gpio.3
@@ -0,0 +1,262 @@
+.\"
+.\" 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 <sys/types.h>
+#include <err.h>
+#include <libgpio.h>
+
+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 .