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