share/man/man4/gpiokeys.4

   1 .\"
   2 .\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD
   3 .\"
   4 .\" Copyright (c) 2020 Andriy Gapon <avg@FreeBSD.org>
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  18 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  25 .\" SUCH DAMAGE.
  26 .\"
  27 .\" $FreeBSD$
  28 .\"
  29 .Dd August 5, 2020
  30 .Dt GPIOKEYS 4
  31 .Os
  32 .Sh NAME
  33 .Nm gpiokeys
  34 .Nd GPIO keys device driver
  35 .Sh SYNOPSIS
  36 To compile this driver into the kernel,
  37 place the following lines in your
  38 kernel configuration file:
  39 .Bd -ragged -offset indent
  40 .Cd "options FDT"
  41 .Cd "device gpio"
  42 .Cd "device gpiokeys"
  43 .Ed
  44 .Pp
  45 Alternatively, to load the driver as a
  46 module at boot time, place the following line in
  47 .Xr loader.conf 5 :
  48 .Bd -literal -offset indent
  49 gpiokeys_load="YES"
  50 .Ed
  51 .Sh DESCRIPTION
  52 The
  53 .Nm
  54 driver provides a way to represent a set of general purpose inputs as a
  55 .Xr keyboard 4
  56 device.
  57 At the moment the driver supports only
  58 .Xr FDT 4
  59 based systems.
  60 The DTS determines what pins are mapped to buttons and what key codes are
  61 generated for each virtual button.
  62 The
  63 .Xr keyboard 4
  64 device can be used from userland to monitor for input changes.
  65 .Pp
  66 On an
  67 .Xr FDT 4
  68 based system
  69 the DTS part for a
  70 .Nm
  71 device usually looks like:
  72 .Bd -literal
  73 / {
  74
  75         ...
  76
  77         gpio_keys {
  78                 compatible = "gpio-keys";
  79
  80                 btn1 {
  81                         label = "button1";
  82                         linux,code = <KEY_1>;
  83                         gpios = <&gpio 0 3 GPIO_ACTIVE_LOW>
  84                 };
  85
  86                 btn2 {
  87                         label = "button2";
  88                         linux,code = <KEY_2>;
  89                         gpios = <&gpio 0 4 GPIO_ACTIVE_LOW>
  90                 };
  91         };
  92 };
  93 .Ed
  94 .Pp
  95 For more details about the
  96 .Va gpios
  97 property, please consult
  98 .Pa /usr/src/sys/dts/bindings-gpio.txt .
  99 .Pp
 100 The
 101 .Nm
 102 driver supports two properties for specifying a key code.
 103 .Pp
 104 The property
 105 .Va freebsd,code
 106 specifies a
 107 .Fx
 108 native scancode compatible with
 109 .Xr kbdmap 5
 110 keyboard maps.
 111 .Pp
 112 The property
 113 .Va linux,code
 114 specifies an evdev scancode.
 115 That scancode is internally translated to a native scancode.
 116 Note that not all evdev scancodes have corresponding native scancodes.
 117 If a scancode cannot be translated, then a diagnostic message is printed
 118 and the input is ignored.
 119 .Pp
 120 The property
 121 .Va label
 122 is a descriptive name of a button.
 123 It is used for diagnostic messages only.
 124 This property is optional.
 125 If not set, the node name is used in its place.
 126 .Pp
 127 The property
 128 .Va autorepeat
 129 determines whether autorepeat is enabled for a button.
 130 .Pp
 131 The property
 132 .Va debounce-interval
 133 defines debouncing interval time in milliseconds.
 134 If not specified the interval defaults to 5.
 135 .Sh SEE ALSO
 136 .Xr fdt 4 ,
 137 .Xr gpio 4 ,
 138 .Xr keyboard 4 ,
 139 .Xr kbdmap 5
 140 .Sh HISTORY
 141 The
 142 .Nm
 143 manual page first appeared in
 144 .Fx 12.2 .
 145 .Sh AUTHORS
 146 The
 147 .Nm
 148 driver was written by
 149 .An Oleksandr Tymoshenko Aq Mt gonzo@FreeBSD.org .
 150 This
 151 manual page was written by
 152 .An Andriy Gapon Aq Mt avg@FreeBSD.org .