92ced822d1
If a pin can pulse in hardware, that will be used, else it will be pulsed in software. There is no way yet to set the pulse frequency for pins that pulse in hardware. While here, make the code mpsafe and allow more than one thread in the driver (access to ioctl is serialized).
267 lines
6.2 KiB
Groff
267 lines
6.2 KiB
Groff
.\" $NetBSD: gpio.4,v 1.19 2011/08/28 07:48:50 mbalmer Exp $
|
|
.\" $OpenBSD: gpio.4,v 1.5 2004/11/23 09:39:29 reyk Exp $
|
|
.\"
|
|
.\" Copyright (c) 2004 Alexander Yurchenko <grange@openbsd.org>
|
|
.\"
|
|
.\" Permission to use, copy, modify, and distribute this software for any
|
|
.\" purpose with or without fee is hereby granted, provided that the above
|
|
.\" copyright notice and this permission notice appear in all copies.
|
|
.\"
|
|
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
|
|
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
|
|
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
|
|
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
|
|
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
|
|
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
|
|
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
|
.\"
|
|
.Dd August 21, 2011
|
|
.Dt GPIO 4
|
|
.Os
|
|
.Sh NAME
|
|
.Nm gpio
|
|
.Nd General Purpose Input/Output
|
|
.Sh SYNOPSIS
|
|
.Cd "gpio* at elansc?"
|
|
.Cd "gpio* at epgpio?"
|
|
.Cd "gpio* at gcscpcib?"
|
|
.Cd "gpio* at gpiosim?"
|
|
.Cd "gpio* at gscpcib?"
|
|
.Cd "gpio* at ichlpcib?"
|
|
.Cd "gpio* at nsclpcsio?"
|
|
.Cd "gpio* at ppbus?"
|
|
.Pp
|
|
.In sys/types.h
|
|
.In sys/gpio.h
|
|
.In sys/ioctl.h
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
device attaches to the
|
|
.Tn GPIO
|
|
controller and provides a uniform programming interface to its pins.
|
|
.Pp
|
|
Each
|
|
.Tn GPIO
|
|
controller with an attached
|
|
.Nm
|
|
device has an associated device file under the
|
|
.Pa /dev
|
|
directory, e.g.\&
|
|
.Pa /dev/gpio0 .
|
|
Access from userland is performed through
|
|
.Xr ioctl 2
|
|
calls on these devices.
|
|
.Pp
|
|
Whether the layout of the GPIO device can be configured is subject to
|
|
authorization by the
|
|
.Xr kauth 9
|
|
framework.
|
|
.Pp
|
|
If for example
|
|
.Xr secmodel_securelevel 9
|
|
is active, the layout of the GPIO device is defined at a securelevel
|
|
less than 1, i.e. typically during system boot, and cannot be changed later.
|
|
GPIO pins can be configured and given a symbolic name and device drivers
|
|
that use GPIO pins can be attached to the
|
|
.Nm
|
|
device at a securelevel less than 1.
|
|
All other pins will not be accessible once the runlevel has been raised.
|
|
.Sh IOCTL INTERFACE
|
|
The following structures and constants are defined in the
|
|
.In sys/gpio.h
|
|
header file:
|
|
.Pp
|
|
.Bl -tag -width XXXX -compact
|
|
.It Dv GPIOINFO (struct gpio_info)
|
|
Returns information about the
|
|
.Tn GPIO
|
|
controller in the
|
|
.Fa gpio_info
|
|
structure:
|
|
.Bd -literal
|
|
struct gpio_info {
|
|
int gpio_npins; /* total number of pins available */
|
|
};
|
|
.Ed
|
|
.Pp
|
|
.It Dv GPIOREAD (struct gpio_req)
|
|
Returns the input pin value in the
|
|
.Fa gpio_pin_op
|
|
structure:
|
|
.Bd -literal
|
|
#define GPIOMAXNAME 64
|
|
|
|
struct gpio_req {
|
|
char gp_name[GPIOMAXNAME]; /* pin name */
|
|
int gp_pin; /* pin number */
|
|
int gp_value; /* value */
|
|
};
|
|
.Ed
|
|
.Pp
|
|
The
|
|
.Fa gp_name
|
|
or
|
|
.Fa gp_pin
|
|
field must be set before calling.
|
|
.Pp
|
|
.It Dv GPIOWRITE (struct gpio_req)
|
|
Writes the output value to the pin.
|
|
The value set in the
|
|
.Fa gp_value
|
|
field must be either
|
|
.Dv GPIO_PIN_LOW
|
|
(logical 0) or
|
|
.Dv GPIO_PIN_HIGH
|
|
(logical 1).
|
|
On return, the
|
|
.Fa gp_value
|
|
field contains the old pin state.
|
|
.Pp
|
|
.It Dv GPIOTOGGLE (struct gpio_req)
|
|
Toggles the pin output value, i.e. changes it to the opposite.
|
|
.Fa gp_value
|
|
field is ignored and on return contains the old pin state.
|
|
.Pp
|
|
.It Dv GPIOPULSE (struct gpio_pulse)
|
|
Starts pulsing the pin:
|
|
.Bd -literal
|
|
/* GPIO pulse request */
|
|
struct gpio_pulse {
|
|
char gp_name[GPIOMAXNAME]; /* pin name */
|
|
int gp_pin; /* pin number */
|
|
struct timeval gp_pulse_on; /* "on" period */
|
|
struct timeval gp_pulse_off; /* "off" period */
|
|
};
|
|
.Ed
|
|
.Pp
|
|
The
|
|
.Fa gp_name
|
|
or
|
|
.Fa gp_pin
|
|
field must be set before calling.
|
|
If
|
|
.Fa gp_pulse_on
|
|
or
|
|
.Fa gp_pulse_off
|
|
is set to zero, a default of
|
|
.Xr hz 9 / 2
|
|
is assumed for both periods.
|
|
.Pp
|
|
.It Dv GPIOSET (struct gpio_set)
|
|
Changes pin configuration flags with the new ones provided in the
|
|
.Fa gpio_set
|
|
structure:
|
|
.Bd -literal
|
|
#define GPIOMAXNAME 64
|
|
|
|
struct gpio_set {
|
|
char gp_name[GPIOMAXNAME]; /* pin name */
|
|
int gp_pin; /* pin number */
|
|
int gp_caps; /* pin capabilities (ro) */
|
|
int gp_flags; /* pin configuration flags */
|
|
char gp_name2[GPIOMAXNAME]; /* new name */
|
|
};
|
|
.Ed
|
|
.Pp
|
|
The
|
|
.Fa gp_flags
|
|
field is a combination of the following flags:
|
|
.Pp
|
|
.Bl -tag -width GPIO_PIN_OPENDRAIN -compact
|
|
.It Dv GPIO_PIN_INPUT
|
|
input direction
|
|
.It Dv GPIO_PIN_OUTPUT
|
|
output direction
|
|
.It Dv GPIO_PIN_INOUT
|
|
bi-directional
|
|
.It Dv GPIO_PIN_OPENDRAIN
|
|
open-drain output
|
|
.It Dv GPIO_PIN_PUSHPULL
|
|
push-pull output
|
|
.It Dv GPIO_PIN_TRISTATE
|
|
output disabled
|
|
.It Dv GPIO_PIN_PULLUP
|
|
internal pull-up enabled
|
|
.It Dv GPIO_PIN_PULLDOWN
|
|
internal pull-down enabled
|
|
.It Dv GPIO_PIN_INVIN
|
|
invert input
|
|
.It Dv GPIO_PIN_INVOUT
|
|
invert output
|
|
.It Dv GPIO_PIN_PULSE
|
|
pulse output
|
|
.El
|
|
.Pp
|
|
Note that the GPIO controller
|
|
may not support all of these flags.
|
|
On return the
|
|
.Fa gp_caps
|
|
field contains flags that are supported.
|
|
If no flags are specified, the pin configuration stays unchanged.
|
|
.Pp
|
|
Only GPIO pins that have been set using
|
|
.Ar GPIOSET
|
|
will be accessible at securelevels greater than 0.
|
|
.Pp
|
|
.It Dv GPIOUNSET (struct gpio_set)
|
|
Unset the specified pin, i.e. clear its name and make it unaccessible
|
|
at securelevels greater than 0.
|
|
.Pp
|
|
.It Dv GPIOATTACH (struct gpio_attach)
|
|
Attach the device described in the
|
|
.Fa gpio_attach
|
|
structure on this gpio device.
|
|
.Bd -literal
|
|
struct gpio_attach {
|
|
char ga_dvname[16]; /* device name */
|
|
int ga_offset; /* pin number */
|
|
u_int32_t ga_mask; /* binary mask */
|
|
};
|
|
.Ed
|
|
.Pp
|
|
.It Dv GPIODETACH (struct gpio_attach)
|
|
Detach a device from this gpio device that was previously attached using the
|
|
.Dv GPIOATTACH
|
|
.Xr ioctl 2 .
|
|
The
|
|
.Fa ga_offset
|
|
and
|
|
.Fa ga_mask
|
|
fields of the
|
|
.Fa gpio_attach
|
|
structure are ignored.
|
|
.El
|
|
.Sh FILES
|
|
.Bl -tag -width "/dev/gpiou" -compact
|
|
.It /dev/gpio Ns Ar u
|
|
GPIO device unit
|
|
.Ar u
|
|
file.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr ioctl 2 ,
|
|
.Xr gpioctl 8
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
device first appeared in
|
|
.Ox 3.6
|
|
and
|
|
.Nx 4.0 .
|
|
.Sh AUTHORS
|
|
.An -nosplit
|
|
The
|
|
.Nm
|
|
driver was written by
|
|
.An Alexander Yurchenko Aq grange@openbsd.org .
|
|
.Nm
|
|
and was ported to
|
|
.Nx
|
|
by
|
|
.An Jared D. McNeill Aq jmcneill@NetBSD.org .
|
|
Runtime device attachment was added by
|
|
.An Marc Balmer Aq marc@msys.ch .
|
|
.Sh BUGS
|
|
Event capabilities are not supported.
|