Part 1
요약·해설
No-diode·양방향 diode 회로, interrupt 제한, port-wide access, 16-bit row, actual-key-mask와 shell 검증을 설명합니다.
gpio-kbd-matrix
Interrupt · poll · scan
X/Y/Touch → key
Part 2
접을 수 있는 영어 원문 전체
영어 원문 전체 펼치기
725D560041B75FC4CA7713954D3246262EB83689EF68AE72B0F7143DB7D9CD30
.. _gpio-kbd:
GPIO Keyboard Matrix
####################
The :dtcompatible:`gpio-kbd-matrix` driver supports a large variety of keyboard
matrix hardware configurations and has numerous options to change its behavior.
This is an overview of some common setups and how they can be supported by the
driver.
The conventional configuration for all of these is that the driver reads on the
row GPIOs (inputs) and selects on the columns GPIOs (output).
Base use case, no isolation diodes, interrupt capable GPIOs
***********************************************************
This is the common configuration found on consumer keyboards with membrane
switches and flexible circuit boards, no isolation diodes, requires ghosting
detection (which is enabled by default).
.. figure:: ../../../../services/input/no-diodes.svg
:align: center
:width: 50%
A 3x3 matrix, no diodes
The system must support GPIO interrupts, and the interrupt can be enabled on all
row GPIOs at the same time.
.. code-block:: devicetree
kbd-matrix {
compatible = "gpio-kbd-matrix";
row-gpios = <&gpio0 0 (GPIO_PULL_UP | GPIO_ACTIVE_LOW)>,
<&gpio0 1 (GPIO_PULL_UP | GPIO_ACTIVE_LOW)>,
<&gpio0 2 (GPIO_PULL_UP | GPIO_ACTIVE_LOW)>;
col-gpios = <&gpio0 3 GPIO_ACTIVE_LOW>,
<&gpio0 4 GPIO_ACTIVE_LOW>,
<&gpio0 5 GPIO_ACTIVE_LOW>;
};
In this configuration the matrix scanning library enters idle mode once all
keys are released, and the keyboard matrix thread only wakes up when a key has
been pressed.
GPIOs for columns that are not currently selected are configured in high
impedance mode. This means that the row state may need some time to settle to
avoid misreading the key state from a column to the following one. The settle
time can be tweaked by changing the ``settle-time-us`` property.
Isolation diodes
****************
If the matrix has isolation diodes for every key, then it's possible to:
- disable ghosting detection, allowing any key combination to be detected
- configuring the driver to drive unselected columns GPIO to inactive state
rather than high impedance, this allows to reduce the settle time
(potentially down to 0), and use the more efficient port wide GPIO read APIs
(happens automatically if the GPIO pins are sequential)
Matrixes with diodes going from rows to columns must use pull-ups on rows and
active low columns.
.. figure:: ../../../../services/input/diodes-rc.svg
:align: center
:width: 50%
A 3x3 matrix with row to column isolation diodes.
.. code-block:: devicetree
kbd-matrix {
compatible = "gpio-kbd-matrix";
row-gpios = <&gpio0 0 (GPIO_PULL_UP | GPIO_ACTIVE_LOW)>,
<&gpio0 1 (GPIO_PULL_UP | GPIO_ACTIVE_LOW)>,
<&gpio0 2 (GPIO_PULL_UP | GPIO_ACTIVE_LOW)>;
col-gpios = <&gpio0 3 GPIO_ACTIVE_LOW>,
<&gpio0 4 GPIO_ACTIVE_LOW>,
<&gpio0 5 GPIO_ACTIVE_LOW>;
col-drive-inactive;
settle-time-us = <0>;
no-ghostkey-check;
};
Matrixes with diodes going from columns to rows must use pull-downs on rows and
active high columns.
.. figure:: ../../../../services/input/diodes-cr.svg
:align: center
:width: 50%
A 3x3 matrix with column to row isolation diodes.
.. code-block:: devicetree
kbd-matrix {
compatible = "gpio-kbd-matrix";
row-gpios = <&gpio0 0 (GPIO_PULL_DOWN | GPIO_ACTIVE_HIGH)>,
<&gpio0 1 (GPIO_PULL_DOWN | GPIO_ACTIVE_HIGH)>,
<&gpio0 2 (GPIO_PULL_DOWN | GPIO_ACTIVE_HIGH)>;
col-gpios = <&gpio0 3 GPIO_ACTIVE_HIGH>,
<&gpio0 4 GPIO_ACTIVE_HIGH>,
<&gpio0 5 GPIO_ACTIVE_HIGH>;
col-drive-inactive;
settle-time-us = <0>;
no-ghostkey-check;
};
GPIO with no interrupt support
******************************
Some GPIO controllers have limitations on GPIO interrupts, and may not support
enabling interrupts on all row GPIOs at the same time.
In this case, the driver can be configured to not use interrupt at all, and
instead idle by selecting all columns and keep polling on the row GPIOs, which
is a single GPIO API operation if the pins are sequential.
This configuration can be enabled by setting the ``idle-mode`` property to
``poll``:
.. code-block:: devicetree
kbd-matrix {
compatible = "gpio-kbd-matrix";
...
idle-mode = "poll";
};
GPIO multiplexer
****************
In more extreme cases, such as if the columns are using a multiplexer and it's
impossible to select all of them at the same time, the driver can be configured
to scan continuously.
This can be done by setting ``idle-mode`` to ``scan`` and ``poll-timeout-ms``
to ``0``.
.. code-block:: devicetree
kbd-matrix {
compatible = "gpio-kbd-matrix";
...
poll-timeout-ms = <0>;
idle-mode = "scan";
};
Row and column GPIO selection
*****************************
If the row GPIOs are sequential and on the same gpio controller, the driver
automatically switches API to read from the whole GPIO port rather than the
individual pins. This is particularly useful if the GPIOs are not memory
mapped, for example on an I2C or SPI port expander, as this significantly
reduces the number of transactions on the corresponding bus.
The same is true for column GPIOs, but only if the matrix is configured for
``col-drive-inactive``, so that is only usable for matrixes with isolation
diodes.
16-bit row support
******************
The driver uses an 8-bit datatype to store the row state by default, which
limits the matrix row size to 8. This can be increased to 16 by enabling the
:kconfig:option:`CONFIG_INPUT_KBD_MATRIX_16_BIT_ROW` option.
Actual key mask configuration
*****************************
If the key matrix is not complete, a map of the keys that are actually
populated can be specified using the `actual-key-mask` property. This allows
the matrix state to be filtered to remove keys that are not present before
ghosting detection, potentially allowing key combinations that would otherwise
be blocked by it.
For example for a 3x3 matrix missing a key:
.. figure:: ../../../../services/input/no-sw4.svg
:align: center
:width: 50%
A 3x3 matrix missing a key.
.. code-block:: devicetree
kbd-matrix {
compatible = "gpio-kbd-matrix";
...
actual-key-mask = <0x07 0x05 0x07>;
};
This would allow, for example, to detect pressing ``Sw1``, ``SW2`` and ``SW4``
at the same time without triggering anti ghosting.
The actual key mask can be changed at runtime by enabling
:kconfig:option:`CONFIG_INPUT_KBD_ACTUAL_KEY_MASK_DYNAMIC` and the using the
:c:func:`input_kbd_matrix_actual_key_mask_set` API.
Keymap configuration
********************
Keyboard matrix devices report a series of x/y/touch events. These can be
mapped to normal key events using the :dtcompatible:`input-keymap` driver.
For example, the following would setup a ``keymap`` device that take the
x/y/touch events as an input and generate corresponding key events as an
output:
.. code-block:: devicetree
kbd {
...
keymap {
compatible = "input-keymap";
keymap = <
MATRIX_KEY(0, 0, INPUT_KEY_1)
MATRIX_KEY(0, 1, INPUT_KEY_2)
MATRIX_KEY(0, 2, INPUT_KEY_3)
MATRIX_KEY(1, 0, INPUT_KEY_4)
MATRIX_KEY(1, 1, INPUT_KEY_5)
MATRIX_KEY(1, 2, INPUT_KEY_6)
MATRIX_KEY(2, 0, INPUT_KEY_7)
MATRIX_KEY(2, 1, INPUT_KEY_8)
MATRIX_KEY(2, 2, INPUT_KEY_9)
>;
row-size = <3>;
col-size = <3>;
};
};
Keyboard matrix shell commands
******************************
The shell command ``kbd_matrix_state_dump`` can be used to test the
functionality of any keyboard matrix driver implemented using the keyboard
matrix library. Once enabled it logs the state of the matrix every time it
changes, and once disabled it prints an or-mask of any key that has been
detected, which can be used to set the ``actual-key-mask`` property.
The command can be enabled using the
:kconfig:option:`CONFIG_INPUT_SHELL_KBD_MATRIX_STATE`.
Example usage:
.. code-block:: console
uart:~$ device list
devices:
- kbd-matrix (READY)
uart:~$ input kbd_matrix_state_dump kbd-matrix
Keyboard state logging enabled for kbd-matrix
[00:01:41.678,466] <inf> input: kbd-matrix state [01 -- -- --] (1)
[00:01:41.784,912] <inf> input: kbd-matrix state [-- -- -- --] (0)
...
press more buttons
...
uart:~$ input kbd_matrix_state_dump off
Keyboard state logging disabled
[00:01:47.967,651] <inf> input: kbd-matrix key-mask [07 05 07 --] (8)
Keyboard matrix library
***********************
The GPIO keyboard matrix driver is based on a generic keyboard matrix library,
which implements the core functionalities such as scanning delays, debouncing,
idle mode etc. This can be reused to implement other keyboard matrix drivers,
potentially application specific.
.. doxygengroup:: input_kbd_matrix
Part 3
한국어 전문 번역
gpio-kbd-matrix driver는 여러 keyboard matrix hardware 구성을 지원하며 동작을 조절하는 option도 많습니다. 이 문서는 흔한 hardware setup과 driver configuration을 설명합니다.
모든 구성에서 일반적인 연결 방식은 driver가 row GPIO를 input으로 읽고 column GPIO를 output으로 선택하는 것입니다.
기본 사용 사례: isolation diode 없음, interrupt 지원 GPIO
Membrane switch와 flexible circuit board를 쓰는 consumer keyboard에서 흔한 구성입니다. Isolation diode가 없으므로 ghosting detection이 필요하며 기본값으로 활성화됩니다.
System은 GPIO interrupt를 지원해야 하고 모든 row GPIO에서 동시에 interrupt를 활성화할 수 있어야 합니다.
kbd-matrix {
compatible = "gpio-kbd-matrix";
row-gpios = <&gpio0 0 (GPIO_PULL_UP | GPIO_ACTIVE_LOW)>,
<&gpio0 1 (GPIO_PULL_UP | GPIO_ACTIVE_LOW)>,
<&gpio0 2 (GPIO_PULL_UP | GPIO_ACTIVE_LOW)>;
col-gpios = <&gpio0 3 GPIO_ACTIVE_LOW>,
<&gpio0 4 GPIO_ACTIVE_LOW>,
<&gpio0 5 GPIO_ACTIVE_LOW>;
};
이 구성에서는 모든 key가 release되면 matrix scanning library가 idle mode에 들어갑니다. Keyboard matrix thread는 key가 눌렸을 때만 깨어납니다.
현재 선택하지 않은 column GPIO는 high-impedance mode로 설정합니다. Column을 바꾼 직후 row state가 안정되는 데 시간이 걸릴 수 있으며, 너무 빨리 읽으면 이전 column의 key state로 잘못 판단할 수 있습니다. settle-time-us property로 settle time을 조정합니다.
Isolation diode
모든 key에 isolation diode가 있으면 다음 최적화를 적용할 수 있습니다.
- Ghosting detection을 끄고 임의의 key combination을 모두 감지할 수 있습니다.
- 선택하지 않은 column GPIO를 high impedance 대신 inactive state로 drive할 수 있습니다. Settle time을 0까지 줄일 수 있고, pin이 연속적이면 더 효율적인 port-wide GPIO read API를 자동으로 사용할 수 있습니다.
Diode가 row에서 column 방향으로 연결된 matrix는 row에 pull-up을 사용하고 column을 active low로 설정해야 합니다.
kbd-matrix {
compatible = "gpio-kbd-matrix";
row-gpios = <&gpio0 0 (GPIO_PULL_UP | GPIO_ACTIVE_LOW)>,
<&gpio0 1 (GPIO_PULL_UP | GPIO_ACTIVE_LOW)>,
<&gpio0 2 (GPIO_PULL_UP | GPIO_ACTIVE_LOW)>;
col-gpios = <&gpio0 3 GPIO_ACTIVE_LOW>,
<&gpio0 4 GPIO_ACTIVE_LOW>,
<&gpio0 5 GPIO_ACTIVE_LOW>;
col-drive-inactive;
settle-time-us = <0>;
no-ghostkey-check;
};
Diode가 column에서 row 방향으로 연결된 matrix는 row에 pull-down을 사용하고 column을 active high로 설정해야 합니다.
kbd-matrix {
compatible = "gpio-kbd-matrix";
row-gpios = <&gpio0 0 (GPIO_PULL_DOWN | GPIO_ACTIVE_HIGH)>,
<&gpio0 1 (GPIO_PULL_DOWN | GPIO_ACTIVE_HIGH)>,
<&gpio0 2 (GPIO_PULL_DOWN | GPIO_ACTIVE_HIGH)>;
col-gpios = <&gpio0 3 GPIO_ACTIVE_HIGH>,
<&gpio0 4 GPIO_ACTIVE_HIGH>,
<&gpio0 5 GPIO_ACTIVE_HIGH>;
col-drive-inactive;
settle-time-us = <0>;
no-ghostkey-check;
};
Interrupt를 지원하지 않는 GPIO
일부 GPIO controller는 interrupt 기능에 제한이 있어 모든 row GPIO의 interrupt를 동시에 활성화하지 못합니다.
이때 driver가 interrupt를 전혀 사용하지 않게 설정할 수 있습니다. Idle 동안 모든 column을 선택하고 row GPIO를 계속 polling합니다. Row pin이 연속적이면 이 작업은 GPIO API 한 번으로 수행됩니다. idle-mode property를 poll로 설정합니다.
kbd-matrix {
compatible = "gpio-kbd-matrix";
...
idle-mode = "poll";
};
GPIO multiplexer
Column이 multiplexer에 연결돼 모든 column을 동시에 선택할 수 없는 경우처럼 더 제한적인 hardware에서는 driver가 계속 scan하도록 설정할 수 있습니다. idle-mode를 scan으로, poll-timeout-ms를 0으로 설정합니다.
kbd-matrix {
compatible = "gpio-kbd-matrix";
...
poll-timeout-ms = <0>;
idle-mode = "scan";
};
Row와 column GPIO 선택
Row GPIO가 같은 GPIO controller에 있고 pin 번호가 연속적이면 driver가 개별 pin API 대신 전체 GPIO port를 읽는 API로 자동 전환합니다. GPIO가 memory-mapped 방식이 아닌 I2C 또는 SPI port expander에 있을 때 bus transaction 수를 크게 줄일 수 있어 특히 유용합니다.
Column GPIO에도 같은 최적화가 적용되지만 matrix가 col-drive-inactive로 구성돼 있어야 합니다. 따라서 isolation diode가 있는 matrix에서만 사용할 수 있습니다.
16-bit row 지원
Driver는 기본적으로 8-bit datatype에 row state를 저장하므로 matrix의 row 수가 8개로 제한됩니다. CONFIG_INPUT_KBD_MATRIX_16_BIT_ROW option을 활성화하면 16개까지 늘릴 수 있습니다.
실제 key mask 구성
Key matrix가 완전히 채워져 있지 않다면 actual-key-mask property로 실제 존재하는 key의 map을 지정할 수 있습니다. Ghosting detection 전에 matrix state에서 존재하지 않는 key를 제거하므로, 원래라면 차단됐을 key combination을 허용할 수 있습니다.
다음은 key 하나가 빠진 3x3 matrix 예입니다.
kbd-matrix {
compatible = "gpio-kbd-matrix";
...
actual-key-mask = <0x07 0x05 0x07>;
};
이 mask라면 예를 들어 Sw1, SW2, SW4를 동시에 눌러도 anti-ghosting에 걸리지 않고 감지할 수 있습니다.
CONFIG_INPUT_KBD_ACTUAL_KEY_MASK_DYNAMIC을 활성화하면 runtime에 input_kbd_matrix_actual_key_mask_set() API로 actual key mask를 바꿀 수 있습니다.
Keymap 구성
Keyboard matrix device는 X/Y/Touch event 묶음을 report합니다. input-keymap driver를 사용하면 이를 일반 key event로 변환할 수 있습니다.
다음 예는 X/Y/Touch event를 input으로 받아 대응하는 key event를 output하는 keymap device를 구성합니다.
kbd {
...
keymap {
compatible = "input-keymap";
keymap = <
MATRIX_KEY(0, 0, INPUT_KEY_1)
MATRIX_KEY(0, 1, INPUT_KEY_2)
MATRIX_KEY(0, 2, INPUT_KEY_3)
MATRIX_KEY(1, 0, INPUT_KEY_4)
MATRIX_KEY(1, 1, INPUT_KEY_5)
MATRIX_KEY(1, 2, INPUT_KEY_6)
MATRIX_KEY(2, 0, INPUT_KEY_7)
MATRIX_KEY(2, 1, INPUT_KEY_8)
MATRIX_KEY(2, 2, INPUT_KEY_9)
>;
row-size = <3>;
col-size = <3>;
};
};
Keyboard matrix shell command
kbd_matrix_state_dump shell command로 keyboard matrix library를 사용하는 driver를 시험할 수 있습니다. 활성화하면 matrix state가 바뀔 때마다 log를 출력합니다. 비활성화할 때까지 감지된 모든 key의 OR mask도 출력하므로 actual-key-mask property 값을 만드는 데 활용할 수 있습니다.
CONFIG_INPUT_SHELL_KBD_MATRIX_STATE를 활성화하면 이 command를 사용할 수 있습니다.
사용 예는 다음과 같습니다.
uart:~$ device list
devices:
- kbd-matrix (READY)
uart:~$ input kbd_matrix_state_dump kbd-matrix
Keyboard state logging enabled for kbd-matrix
[00:01:41.678,466] <inf> input: kbd-matrix state [01 -- -- --] (1)
[00:01:41.784,912] <inf> input: kbd-matrix state [-- -- -- --] (0)
...
press more buttons
...
uart:~$ input kbd_matrix_state_dump off
Keyboard state logging disabled
[00:01:47.967,651] <inf> input: kbd-matrix key-mask [07 05 07 --] (8)
Keyboard matrix library
GPIO keyboard matrix driver는 generic keyboard matrix library를 기반으로 합니다. 이 library가 scanning delay, debouncing, idle mode 같은 핵심 기능을 구현합니다. Application-specific driver를 포함한 다른 keyboard matrix driver에서도 재사용할 수 있습니다.
관련 API는 input_kbd_matrix Doxygen group에 정의돼 있습니다.
Source
출처
영어 원문에는 문단, 문서 지시문, 표, 코드, 코드 심벌, 경로를 그대로 보존했습니다.