services/input/index.html · services/input/index.rst 공식 원문 ↗

Zephyr 3.7.0 · OS Services · Input

Input

Device event를 sync 단위로 묶어 application callback에 전달하고 HID·legacy Kscan과 연결합니다.

Official pathservices/input/index.html
Source fileservices/input/index.rst
Source versionZephyr 3.7.0
TranslationFull · reviewed

본문 기준: Zephyr 3.7.0 LTS3 · 이후 유지보수 패치는 별도입니다.

Part 1

요약·해설

input_event와 sync bit, device filter, synchronous·threaded mode, HID mapping과 kscan-input bridge를 설명합니다.

Core

input_event

Delivery

Direct · queue

Compatibility

HID · Kscan

Part 2

접을 수 있는 영어 원문 전체

영어 원문 전체 펼치기
원문 SHA-256 F73D497F5E3FF5907FAE53B0B7B90FA9E6105DA3B57474189CFCAB93B821686A
.. _input:

Input
#####

The input subsystem provides an API for dispatching input events from input
devices to the application.

Input Events
************

The subsystem is built around the :c:struct:`input_event` structure. An input
event represents a change in an individual event entity, for example the state
of a single button, or a movement in a single axis.

The :c:struct:`input_event` structure describes the specific event, and
includes a synchronization bit to indicate that the device reached a stable
state, for example when the events corresponding to multiple axes of a
multi-axis device have been reported.

Input Devices
*************

An input device can report input events directly using :c:func:`input_report`
or any related function; for example buttons or other on-off input entities
would use :c:func:`input_report_key`.

Complex devices may use a combination of multiple events, and set the ``sync``
bit once the output is stable.

The ``input_report*`` functions take a :c:struct:`device` pointer, which is
used to indicate which device reported the event and can be used by subscribers
to only receive events from a specific device. If there's no actual device
associated with the event, it can be set to ``NULL``, in which case only
subscribers with no device filter will receive the event.

Application API
***************

An application can register a callback using the
:c:macro:`INPUT_CALLBACK_DEFINE` macro. If a device node is specified, the
callback is only invoked for events from the specific device, otherwise the
callback will receive all the events in the system. This is the only type of
filtering supported, any more complex filtering logic has to be implemented in
the callback itself.

The subsystem can operate synchronously or by using an event queue, depending
on the :kconfig:option:`CONFIG_INPUT_MODE` option. If the input thread is used,
all the events are added to a queue and executed in a common ``input`` thread.
If the thread is not used, the callback are invoked directly in the input
driver context.

The synchronous mode can be used in a simple application to keep a minimal
footprint, or in a complex application with an existing event model, where the
callback is just a wrapper to pipe back the event in a more complex application
specific event system.

HID code mapping
****************

A common use case for input devices is to use them to generate HID reports. For
this purpose, the :c:func:`input_to_hid_code` and
:c:func:`input_to_hid_modifier` functions can be used to map input codes to HID
codes and modifiers.

Kscan Compatibility
*******************

Input devices generating X/Y/Touch events can be used in existing applications
based on the :ref:`kscan_api` API by enabling both
:kconfig:option:`CONFIG_INPUT` and :kconfig:option:`CONFIG_KSCAN`, defining a
:dtcompatible:`zephyr,kscan-input` node as a child node of the corresponding
input device and pointing the ``zephyr,keyboard-scan`` chosen node to the
compatibility device node, for example:

.. code-block:: devicetree

    chosen {
        zephyr,keyboard-scan = &kscan_input;
    };

    ft5336@38 {
        ...
        kscan_input: kscan-input {
            compatible = "zephyr,kscan-input";
        };
    };

Driver Documentation
********************

.. toctree::
   :maxdepth: 1

   gpio-kbd.rst


API Reference
*************

.. doxygengroup:: input_interface

Input Event Definitions
***********************

.. doxygengroup:: input_events

Analog Axis API Reference
*************************

.. doxygengroup:: input_analog_axis

Part 3

한국어 전문 번역

Input subsystem은 input device에서 발생한 event를 application에 전달하는 API를 제공합니다.

Input Event

Subsystem의 중심에는 input_event structure가 있습니다. Input event 하나는 개별 event entity의 변화, 예를 들면 button 하나의 상태 변화나 axis 하나의 movement를 나타냅니다.

input_event structure는 구체적인 event를 설명하고 synchronization bit도 포함합니다. 이 bit는 device가 stable state에 도달했음을 나타냅니다. 예를 들어 multi-axis device가 여러 axis에 해당하는 event를 모두 report했을 때 설정합니다.

Input Device

Input device는 input_report() 또는 관련 function으로 event를 직접 report할 수 있습니다. Button이나 다른 on/off input entity는 input_report_key()를 사용합니다.

Complex device는 event 여러 개를 조합하고 output이 안정됐을 때 sync bit를 설정할 수 있습니다.

input_report* function은 event를 report한 device를 나타내는 device pointer를 받습니다. Subscriber는 이 pointer를 이용해 특정 device의 event만 받을 수 있습니다. 실제 연결된 device가 없으면 NULL로 설정할 수 있으며, 이때는 device filter가 없는 subscriber만 event를 받습니다.

Application API

Application은 INPUT_CALLBACK_DEFINE macro로 callback을 등록할 수 있습니다. Device node를 지정하면 그 device의 event에만 callback이 호출되고, 지정하지 않으면 system의 모든 event를 받습니다. Subsystem이 직접 지원하는 filtering은 이것뿐이며, 더 복잡한 filter logic은 callback에서 구현해야 합니다.

Subsystem은 CONFIG_INPUT_MODE option에 따라 synchronous mode 또는 event queue mode로 동작합니다. Input thread를 사용하면 모든 event를 queue에 넣고 공통 input thread에서 callback을 실행합니다. Thread를 사용하지 않으면 input driver context에서 callback을 직접 호출합니다.

Synchronous mode는 footprint를 최소화해야 하는 단순 application에 적합합니다. 이미 자체 event model이 있는 복잡한 application에서도 callback을 wrapper로 사용해 event를 application-specific system으로 넘길 수 있습니다.

HID code mapping

Input device event로 HID report를 만드는 경우 input_to_hid_code()와 input_to_hid_modifier()를 사용해 Zephyr input code를 HID code와 modifier로 변환할 수 있습니다.

Kscan Compatibility

X/Y/Touch event를 생성하는 input device는 기존 kscan_api 기반 application에서도 사용할 수 있습니다. CONFIG_INPUT과 CONFIG_KSCAN을 모두 활성화하고, 해당 input device의 child로 zephyr,kscan-input compatible node를 정의한 뒤 zephyr,keyboard-scan chosen node가 그 compatibility node를 가리키게 합니다.

chosen {
    zephyr,keyboard-scan = &kscan_input;
};

ft5336@38 {
    ...
    kscan_input: kscan-input {
        compatible = "zephyr,kscan-input";
    };
};

Driver Documentation

GPIO keyboard matrix driver의 hardware 구성과 tuning 방법은 별도 GPIO Keyboard Matrix 문서에서 설명합니다.

API Reference

Input subsystem의 공통 interface는 input_interface Doxygen group에 정의돼 있습니다.

Input Event Definitions

Event type과 code 정의는 input_events Doxygen group에 있습니다.

Analog Axis API Reference

Analog axis 지원 API는 input_analog_axis Doxygen group에 정의돼 있습니다.

Source

출처

영어 원문에는 문단, 문서 지시문, 표, 코드, 코드 심벌, 경로를 그대로 보존했습니다.