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