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