1.\" $NetBSD: gpioirq.4,v 1.5 2024/09/14 21:12:10 andvar Exp $ 2.\" 3.\" Copyright (c) 2016, 2023 Brad Spencer <brad@anduin.eldar.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd November 5, 2023 18.Dt GPIOIRQ 4 19.Os 20.Sh NAME 21.Nm gpioirq 22.Nd Install an interrupt handler on GPIO pins 23.Sh SYNOPSIS 24.Cd "gpioirq* at gpio? offset 0 mask 0x1 flag 0x00" 25.Sh DESCRIPTION 26The 27.Nm 28driver attaches an interrupt handler to a one or more GPIO pins. 29.Pp 30The base pin number is specified in the kernel configuration file with the 31.Ar offset 32locator. 33The 34.Ar mask 35locator can be 0x01 or greater to indicate that more pins should have an 36interrupt handler attached to them. 37.Pp 38The 39.Ar flag 40locator specifies the interrupt mode to use: 41.Bl -tag -width "XXXXXXXX" 42.It Dv 0x01 43Interrupt on the positive 44.Pq rising 45edge of the pin. 46.It Dv 0x02 47Interrupt on the negative 48.Pq falling 49edge of the pin. 50.It Dv 0x04 51Interrupt on both edges of the pin. 52.It Dv 0x08 53Assert the interrupt as long as the pin is high. 54.It Dv 0x10 55Assert the interrupt as long as the pin is low. 56.El 57.Pp 58Note that the interrupts modes are mutually-exclusive, and exactly one 59interrupt mode must be specified. 60These flags correspond to the 61.Dv GPIO_INTR 62mode bits defined in 63.Pa sys/gpio.h . 64In addition to the interrupt mode, setting 65.Dv 0x1000 66in 67.Ar flags 68will enable the printing of a message to the console whenever the 69interrupt handler is called. 70.Pp 71The 72.Ar offset , 73.Ar mask , 74and 75.Ar flag 76locators can also be specified when 77.Nm 78is attached at runtime using the 79.Dv GPIOATTACH 80.Xr ioctl 2 81on the 82.Xr gpio 4 83device. 84.Sh FILES 85.Bl -tag -width "/dev/gpioirqu" -compact 86.It /dev/gpioirq Ns Ar u 87GPIOIRQ device unit 88.Ar u 89file. 90The output from this device are three uint8_t bytes every time an interrupt fires. 91The bytes contain the device unit, pin number and the current state of the pin. 92.Sh EXAMPLES 93The following example will output the device unit, pin and 94the pins current state for pins 4, 5, 6, 7, 8, 9, 10, 11, 12 on gpio0: 95.Bd -literal -offset indent 96/etc/gpio.conf contains: 97gpio0 attach gpioirq 4 0x1ff 0x04 98 99or a kernel was compiled to have the same parameters. 100 101#!/usr/pkg/bin/perl 102 103$dev = "/dev/gpioirq0"; 104 105sysopen(DEV,$dev,O_RDONLY) || die "sysopen: $!"; 106 107while (sysread(DEV,$b,3)) { 108 @v = unpack("CCC",$b); 109 110 print join(',',@v); 111 print "\\n"; 112} 113 114.Sh SEE ALSO 115.Xr gpio 4 , 116.Xr drvctl 8 , 117.Xr gpioctl 8 118.Sh HISTORY 119The 120.Nm 121driver first appeared in 122.Nx 9.0 . 123.Sh AUTHORS 124.An -nosplit 125The 126.Nm 127driver was written by 128.An Brad Spencer Aq Mt brad@anduin.eldar.org . 129.Sh BUGS 130When an interrupt fires in most devices there is not any information carried 131along in the interrupt as to whether or not the pin is high or low. Hence the 132driver reads the current state of the pin after the interrupt has fired and it is 133possible that the state of the pin could have changed between the time the interrupt 134fired and the reading of the state. As a practical matter the only time the pin state 135will be reported wrong is if there is a very large number of interrupts happening. The 136driver could have made some assumptions if the interrupt was only for a rising edge or falling 137edge as in those cases it would be possible to know what the pin state would have been, but 138in the case of the double edge, there really will not be any way to be sure with most hardware 139and, in any case, the 140.Xr gpio 4 141infrastructure does not support getting at that information even if it did exist. 142.Pp 143It is important that if the 144.Xr gpioirq 4 145device is opened that it be read, as it may be possible 146to run the kernel out of memory if the device is opened but not read and interrupts 147occur on a pin tied to the driver. 148