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