Differential D1183 Diff 2540 head/lib/libgpio/gpio.3

Changeset View

Standalone View

head/lib/libgpio/gpio.3

Property	Old Value	New Value
svn:eol-style	null	native \ No newline at end of property
svn:keywords	null	FreeBSD=%H \ No newline at end of property
svn:mime-type	null	text/plain \ No newline at end of property

				.\"
				.\" Copyright (c) 2014 Rui Paulo
				.\" All rights reserved.
				.\"
				.\" Redistribution and use in source and binary forms, with or without
				.\" modification, are permitted provided that the following conditions
				.\" are met:
				.\" 1. Redistributions of source code must retain the above copyright
				.\" notice, this list of conditions and the following disclaimer.
				.\" 2. Redistributions in binary form must reproduce the above copyright
				.\" notice, this list of conditions and the following disclaimer in the
				.\" documentation and/or other materials provided with the distribution.
				.\"
				.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
				.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
				.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
				.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
				.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
				.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
				.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
				.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
				.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
				.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
				.\" SUCH DAMAGE.
				.\"
				.\" $FreeBSD$
				.\"
				.Dd November 17, 2014
				.Dt GPIO 3
				.Os
				.Sh NAME
				.Nm gpio_open ,
				.Nm gpio_close
				.Nd "library to handle GPIO pins"
				.Sh LIBRARY
				.Lb libgpio
				.Sh SYNOPSIS
				.In libgpio.h
				.Ft "gpio_handle_t"
				.Fn gpio_open "unsigned int unit"
				.Ft "gpio_handle_t"
				.Fn gpio_open_device "const char *device"
				.Ft void
				.Fn gpio_close "gpio_handle_t handle"
				.Ft int
				.Fn gpio_pin_list "gpio_handle_t handle, gpio_config_t **pcfgs"
				.Ft int
				.Fn gpio_pin_config "gpio_handle_t handle, gpio_config *cfg"
				.Ft int
				.Fn gpio_pin_set_flags "gpio_handle_t handle, gpio_config_t *cfg"
				.Ft gpio_value_t
				.Fn gpio_pin_get "gpio_handle_t handle, gpio_pin_t pin"
				.Ft int
				.Fn gpio_pin_set "gpio_handle_t handle, gpio_pin_t pin, gpio_value_t value"
				.Ft int
				.Fn gpio_pin_toggle "gpio_handle_t handle, gpio_pin_t pin"
				.Ft int
				.Fn gpio_pin_low "gpio_handle_t handle, gpio_pin_t pin"
				.Ft int
				.Fn gpio_pin_high "gpio_handle_t handle, gpio_pin_t pin"
				.Ft int
				.Fn gpio_pin_input "gpio_handle_t handle, gpio_pin_t pin"
				.Ft int
				.Fn gpio_pin_output "gpio_handle_t handle, gpio_pin_t pin"
				.Ft int
				.Fn gpio_pin_opendrain "gpio_handle_t handle, gpio_pin_t pin"
				.Ft int
				.Fn gpio_pin_pushpull "gpio_handle_t handle, gpio_pin_t pin"
				.Ft int
				.Fn gpio_pin_tristate "gpio_handle_t handle, gpio_pin_t pin"
				.Ft int
				.Fn gpio_pin_pullup "gpio_handle_t handle, gpio_pin_t pin"
				.Ft int
				.Fn gpio_pin_pulldown "gpio_handle_t handle, gpio_pin_t pin"
				.Ft int
				.Fn gpio_pin_invin "gpio_handle_t handle, gpio_pin_t pin"
				.Ft int
				.Fn gpio_pin_invout "gpio_handle_t handle, gpio_pin_t pin"
				.Ft int
				.Fn gpio_pin_pulsate "gpio_handle_t handle, gpio_pin_t pin"
				.Sh DESCRIPTION
				The
				.Nm libgpio
				library provides an interface to configure GPIO pins.
				The library operates with a
				.Ft gpio_handle_t
				opaque type which can be created with
				.Fn gpio_open
				or
				.Fn gpio_open_device .
				When no more GPIO operations are needed, this handle can be destroyed
				with
				.Fn gpio_close .
				.Pp
				To get a list of all available pins, one can call
				.Fn gpio_pin_list .
				This function takes a pointer to a
				.Ft gpio_config_t
				which is dynamically allocated.
				This pointer should be freed with
				.Xr free 3
				when it's no longer necessary.
				.Pp
				The function
				.Fn gpio_pin_config
				retrieves the current configuration of a pin.
				The pin number should be passed in via the
				.Ft g_pin
				variable which is part of the
				.Ft gpio_config_t
				structure.
				.Pp
				The function
				.Fn gpio_pin_set_flags
				configures a pin with the flags passed in by the
				.Ft gpio_config_t
				structure.
				The pin number should also be passed in through the
				.Ft g_pin
				variable.
				All other structure members will be ignored by this function.
				The list of flags can be found in
				.Pa /usr/include/sys/gpio.h .
				.Pp
				The get or set the state of a GPIO pin, the functions
				.Fn gpio_pin_get
				and
				.Fn gpio_pin_set
				are available, respectively.
				To toggle the state, use
				.Fn gpio_pin_toggle .
				.Pp
				The functions
				.Fn gpio_pin_low
				and
				.Fn gpio_pin_high
				are wrappers around
				.Fn gpio_pin_set .
				.Pp
				The functions
				.Fn gpio_pin_input ,
				.Fn gpio_pin_output ,
				.Fn gpio_pin_opendrain ,
				.Fn gpio_pin_pushpull ,
				.Fn gpio_pin_tristate ,
				.Fn gpio_pin_pullup ,
				.Fn gpio_pin_pulldown ,
				.Fn gpio_pin_invin ,
				.Fn gpio_pin_invout
				and
				.Fn gpio_pin_pulsate
				are wrappers around
				.Fn gpio_pin_set_flags .
				.Sh EXAMPLES
				The following example shows how to configure pin 16 as output and then
				drive it high:
				.Bd -literal
				#include <err.h>
				#include <libgpio.h>

				gpio_handle_t handle;

				handle = gpio_open(0);
				if (handle == GPIO_HANDLE_INVALID)
				err(1, "gpio_open failed");
				gpio_pin_output(handle, 16);
				gpio_pin_high(handle, 16);
				gpio_close(handle);
				.Ed
				.Pp
				The following example shows how to get a configuration of a pin:
				.Bd -literal
				gpio_config_t cfg;

				cfg.g_pin = 32;
				gpio_pin_config(handle, &cfg);
				.Ed
				.Pp
				The structure will contain the name of the pin and its flags.
				.Sh SEE ALSO
				.Xr gpiobus 4 ,
				.Xr gpioctl 8
				.Sh HISTORY
				The
				.Nm libgpio
				library first appeared in
				.Fx 11.0 .
				.Sh AUTHORS
				The
				.Nm libgpio
				library was implemented by
				.An Rui Paulo Aq Mt rpaulo@FreeBSD.org .