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.\" $FreeBSD$ 27.\" 28.Dd March 8, 2015 29.Dt GPIO 3 30.Os 31.Sh NAME 32.Nm gpio_open , 33.Nm gpio_close 34.Nd "library to handle GPIO pins" 35.Sh LIBRARY 36.Lb libgpio 37.Sh SYNOPSIS 38.In libgpio.h 39.Ft "gpio_handle_t" 40.Fn gpio_open "unsigned int unit" 41.Ft "gpio_handle_t" 42.Fn gpio_open_device "const char *device" 43.Ft void 44.Fn gpio_close "gpio_handle_t handle" 45.Ft int 46.Fn gpio_pin_list "gpio_handle_t handle" "gpio_config_t **pcfgs" 47.Ft int 48.Fn gpio_pin_config "gpio_handle_t handle" "gpio_config_t *cfg" 49.Ft int 50.Fn gpio_pin_set_name "gpio_handle_t handle" "gpio_pin_t pin" "char *name" 51.Ft int 52.Fn gpio_pin_set_flags "gpio_handle_t handle" "gpio_config_t *cfg" 53.Ft gpio_value_t 54.Fn gpio_pin_get "gpio_handle_t handle" "gpio_pin_t pin" 55.Ft int 56.Fn gpio_pin_set "gpio_handle_t handle" "gpio_pin_t pin" "gpio_value_t value" 57.Ft int 58.Fn gpio_pin_toggle "gpio_handle_t handle" "gpio_pin_t pin" 59.Ft int 60.Fn gpio_pin_low "gpio_handle_t handle" "gpio_pin_t pin" 61.Ft int 62.Fn gpio_pin_high "gpio_handle_t handle" "gpio_pin_t pin" 63.Ft int 64.Fn gpio_pin_input "gpio_handle_t handle" "gpio_pin_t pin" 65.Ft int 66.Fn gpio_pin_output "gpio_handle_t handle" "gpio_pin_t pin" 67.Ft int 68.Fn gpio_pin_opendrain "gpio_handle_t handle" "gpio_pin_t pin" 69.Ft int 70.Fn gpio_pin_pushpull "gpio_handle_t handle" "gpio_pin_t pin" 71.Ft int 72.Fn gpio_pin_tristate "gpio_handle_t handle" "gpio_pin_t pin" 73.Ft int 74.Fn gpio_pin_pullup "gpio_handle_t handle" "gpio_pin_t pin" 75.Ft int 76.Fn gpio_pin_pulldown "gpio_handle_t handle" "gpio_pin_t pin" 77.Ft int 78.Fn gpio_pin_invin "gpio_handle_t handle" "gpio_pin_t pin" 79.Ft int 80.Fn gpio_pin_invout "gpio_handle_t handle" "gpio_pin_t pin" 81.Ft int 82.Fn gpio_pin_pulsate "gpio_handle_t handle" "gpio_pin_t pin" 83.Sh DESCRIPTION 84The 85.Nm libgpio 86library provides an interface to configure GPIO pins. 87The library operates with a 88.Ft gpio_handle_t 89opaque type which can be created with 90.Fn gpio_open 91or 92.Fn gpio_open_device . 93When no more GPIO operations are needed, this handle can be destroyed 94with 95.Fn gpio_close . 96.Pp 97To get a list of all available pins, one can call 98.Fn gpio_pin_list . 99This function takes a pointer to a 100.Ft gpio_config_t 101which is dynamically allocated. 102This pointer should be freed with 103.Xr free 3 104when it is no longer necessary. 105.Pp 106The function 107.Fn gpio_pin_config 108retrieves the current configuration of a pin. 109The pin number should be passed in via the 110.Ft g_pin 111variable which is part of the 112.Ft gpio_config_t 113structure. 114.Pp 115The function 116.Fn gpio_pin_set_name 117sets the name used to describe a pin. 118.Pp 119The function 120.Fn gpio_pin_set_flags 121configures a pin with the flags passed in by the 122.Ft gpio_config_t 123structure. 124The pin number should also be passed in through the 125.Ft g_pin 126variable. 127All other structure members will be ignored by this function. 128The list of flags can be found in 129.Pa /usr/include/sys/gpio.h . 130.Pp 131The get or set the state of a GPIO pin, the functions 132.Fn gpio_pin_get 133and 134.Fn gpio_pin_set 135are available, respectively. 136To toggle the state, use 137.Fn gpio_pin_toggle . 138.Pp 139The functions 140.Fn gpio_pin_low 141and 142.Fn gpio_pin_high 143are wrappers around 144.Fn gpio_pin_set . 145.Pp 146The functions 147.Fn gpio_pin_input , 148.Fn gpio_pin_output , 149.Fn gpio_pin_opendrain , 150.Fn gpio_pin_pushpull , 151.Fn gpio_pin_tristate , 152.Fn gpio_pin_pullup , 153.Fn gpio_pin_pulldown , 154.Fn gpio_pin_invin , 155.Fn gpio_pin_invout 156and 157.Fn gpio_pin_pulsate 158are wrappers around 159.Fn gpio_pin_set_flags . 160.Sh EXAMPLES 161The following example shows how to configure pin 16 as output and then 162drive it high: 163.Bd -literal 164#include <err.h> 165#include <libgpio.h> 166 167gpio_handle_t handle; 168 169handle = gpio_open(0); 170if (handle == GPIO_HANDLE_INVALID) 171 err(1, "gpio_open failed"); 172gpio_pin_output(handle, 16); 173gpio_pin_high(handle, 16); 174gpio_close(handle); 175.Ed 176.Pp 177The following example shows how to get a configuration of a pin: 178.Bd -literal 179gpio_config_t cfg; 180 181cfg.g_pin = 32; 182gpio_pin_config(handle, &cfg); 183.Ed 184.Pp 185The structure will contain the name of the pin and its flags. 186.Sh SEE ALSO 187.Xr gpiobus 4 , 188.Xr gpioctl 8 189.Sh HISTORY 190The 191.Nm libgpio 192library first appeared in 193.Fx 11.0 . 194.Sh AUTHORS 195The 196.Nm libgpio 197library was implemented by 198.An Rui Paulo Aq Mt rpaulo@FreeBSD.org . 199