lib/libgpio/gpio.3

   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
  85 The
  86 .Nm libgpio
  87 library provides an interface to configure GPIO pins.
  88 The library operates with a
  89 .Ft gpio_handle_t
  90 opaque type which can be created with
  91 .Fn gpio_open
  92 or
  93 .Fn gpio_open_device .
  94 When no more GPIO operations are needed, this handle can be destroyed
  95 with
  96 .Fn gpio_close .
  97 .Pp
  98 To get a list of all available pins, one can call
  99 .Fn gpio_pin_list .
 100 This function takes a pointer to a
 101 .Ft gpio_config_t
 102 which is dynamically allocated.
 103 This pointer should be freed with
 104 .Xr free 3
 105 when it is no longer necessary.
 106 .Pp
 107 The function
 108 .Fn gpio_pin_config
 109 retrieves the current configuration of a pin.
 110 The pin number should be passed in via the
 111 .Ft g_pin
 112 variable which is part of the
 113 .Ft gpio_config_t
 114 structure.
 115 .Pp
 116 The function
 117 .Fn gpio_pin_set_name
 118 sets the name used to describe a pin.
 119 .Pp
 120 The function
 121 .Fn gpio_pin_set_flags
 122 configures a pin with the flags passed in by the
 123 .Ft gpio_config_t
 124 structure.
 125 The pin number should also be passed in through the
 126 .Ft g_pin
 127 variable.
 128 All other structure members will be ignored by this function.
 129 The list of flags can be found in
 130 .Pa /usr/include/sys/gpio.h .
 131 .Pp
 132 The get or set the state of a GPIO pin, the functions
 133 .Fn gpio_pin_get
 134 and
 135 .Fn gpio_pin_set
 136 are available, respectively.
 137 To toggle the state, use
 138 .Fn gpio_pin_toggle .
 139 .Pp
 140 The functions
 141 .Fn gpio_pin_low
 142 and
 143 .Fn gpio_pin_high
 144 are wrappers around
 145 .Fn gpio_pin_set .
 146 .Pp
 147 The 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
 157 and
 158 .Fn gpio_pin_pulsate
 159 are wrappers around
 160 .Fn gpio_pin_set_flags .
 161 .Sh EXAMPLES
 162 The following example shows how to configure pin 16 as output and then
 163 drive it high:
 164 .Bd -literal
 165 #include <sys/types.h>
 166 #include <err.h>
 167 #include <libgpio.h>
 168
 169 gpio_handle_t handle;
 170
 171 handle = gpio_open(0);
 172 if (handle == GPIO_INVALID_HANDLE)
 173         err(1, "gpio_open failed");
 174 gpio_pin_output(handle, 16);
 175 gpio_pin_high(handle, 16);
 176 gpio_close(handle);
 177 .Ed
 178 .Pp
 179 The following example shows how to get a configuration of a pin:
 180 .Bd -literal
 181 gpio_config_t cfg;
 182
 183 cfg.g_pin = 32;
 184 gpio_pin_config(handle, &cfg);
 185 .Ed
 186 .Pp
 187 The 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
 192 The
 193 .Nm libgpio
 194 library first appeared in
 195 .Fx 11.0 .
 196 .Sh AUTHORS
 197 The
 198 .Nm libgpio
 199 library was implemented by
 200 .An Rui Paulo Aq Mt rpaulo@FreeBSD.org .