Writing Surface Aggregator Client Drivers

Client driver 문서와 API 치환

이 문서는 `GPL-2.0+` SPDX license를 사용하며 Surface Aggregator client driver 작성 방법을 설명합니다.

머리말의 replace 지시문은 `ssam_controller`, `ssam_device`, `ssam_device_driver` 구조체와 client bind·link, controller reference, device lifecycle, driver 등록, notifier, synchronous request, event mask API를 본문에서 일관된 교차 참조로 표시합니다.

API 세부 문서는 `client-api` 문서를 포함하는 `toctree`에서 최대 깊이 2로 연결합니다.

.. SPDX-License-Identifier: GPL-2.0+

.. |ssam_controller| replace:: :c:type:`struct ssam_controller <ssam_controller>`
.. |ssam_device| replace:: :c:type:`struct ssam_device <ssam_device>`
.. |ssam_device_driver| replace:: :c:type:`struct ssam_device_driver <ssam_device_driver>`
.. |ssam_client_bind| replace:: :c:func:`ssam_client_bind`
.. |ssam_client_link| replace:: :c:func:`ssam_client_link`
.. |ssam_get_controller| replace:: :c:func:`ssam_get_controller`
.. |ssam_controller_get| replace:: :c:func:`ssam_controller_get`
.. |ssam_controller_put| replace:: :c:func:`ssam_controller_put`
.. |ssam_device_alloc| replace:: :c:func:`ssam_device_alloc`
.. |ssam_device_add| replace:: :c:func:`ssam_device_add`
.. |ssam_device_remove| replace:: :c:func:`ssam_device_remove`
.. |ssam_device_driver_register| replace:: :c:func:`ssam_device_driver_register`
.. |ssam_device_driver_unregister| replace:: :c:func:`ssam_device_driver_unregister`
.. |module_ssam_device_driver| replace:: :c:func:`module_ssam_device_driver`
.. |SSAM_DEVICE| replace:: :c:func:`SSAM_DEVICE`
.. |ssam_notifier_register| replace:: :c:func:`ssam_notifier_register`
.. |ssam_notifier_unregister| replace:: :c:func:`ssam_notifier_unregister`
.. |ssam_device_notifier_register| replace:: :c:func:`ssam_device_notifier_register`
.. |ssam_device_notifier_unregister| replace:: :c:func:`ssam_device_notifier_unregister`
.. |ssam_request_do_sync| replace:: :c:func:`ssam_request_do_sync`
.. |ssam_event_mask| replace:: :c:type:`enum ssam_event_mask <ssam_event_mask>`


======================
Writing Client Drivers
======================

For the API documentation, refer to:

.. toctree::
   :maxdepth: 2

   client-api

Client driver 구성 방식 개요

Client driver는 대응 device가 system에 제공되는 방식에 따라 크게 두 가지로 구성합니다.

첫 번째는 ACPI를 통해 platform device로 제공되는 경우처럼 conventional discovery 경로로 system에 나타나는 device입니다. 두 번째는 discover할 수 없어서 다른 mechanism이 명시적으로 제공해야 하는 device입니다.

Overview
========

Client drivers can be set up in two main ways, depending on how the
corresponding device is made available to the system. We specifically
differentiate between devices that are presented to the system via one of
the conventional ways, e.g. as platform devices via ACPI, and devices that
are non-discoverable and instead need to be explicitly provided by some
other mechanism, as discussed further below.

Non-SSAM Client Driver 연결

SAM EC와의 모든 통신은 kernel에서 해당 EC를 나타내는 `struct ssam_controller`를 거칩니다. Non-SSAM device를 대상으로 하여 `ssam_device_driver`가 아닌 driver는 이 controller와의 연결 또는 관계를 명시적으로 설정해야 합니다.

`ssam_client_bind()`는 SSAM controller reference를 반환하면서 client device와 controller 사이에 device link도 만듭니다. Link만 별도로 만들 때는 `ssam_client_link()`를 사용할 수 있습니다.

Device link는 client driver가 bind되어 있는 동안 반환된 controller가 유효하도록 하여 controller가 무효가 되기 전에 client driver가 먼저 unbind되게 합니다. 또한 suspend/resume ordering을 올바르게 보장합니다.

이 설정은 driver의 `probe` 함수에서 수행해야 하며 SSAM subsystem이 아직 준비되지 않았다면 `-EPROBE_DEFER`로 probing을 미룰 수 있습니다. 예제는 `ssam_client_bind(&pdev->dev)`가 `-ENODEV`를 반환한 경우 이를 probe defer로 바꿉니다.

Controller는 `ssam_get_controller()`로 별도 획득하고 `ssam_controller_get()`과 `ssam_controller_put()`으로 lifetime을 유지할 수도 있습니다. 그러나 이 함수들은 controller가 shutdown 또는 suspend되지 않는다고 보장하지 않으며, reference 수준의 최소 접근성만 보장할 뿐 실제 동작 가능성은 보장하지 않습니다.

Non-SSAM Client Drivers
=======================

All communication with the SAM EC is handled via the |ssam_controller|
representing that EC to the kernel. Drivers targeting a non-SSAM device (and
thus not being a |ssam_device_driver|) need to explicitly establish a
connection/relation to that controller. This can be done via the
|ssam_client_bind| function. Said function returns a reference to the SSAM
controller, but, more importantly, also establishes a device link between
client device and controller (this can also be done separate via
|ssam_client_link|). It is important to do this, as it, first, guarantees
that the returned controller is valid for use in the client driver for as
long as this driver is bound to its device, i.e. that the driver gets
unbound before the controller ever becomes invalid, and, second, as it
ensures correct suspend/resume ordering. This setup should be done in the
driver's probe function, and may be used to defer probing in case the SSAM
subsystem is not ready yet, for example:

.. code-block:: c

   static int client_driver_probe(struct platform_device *pdev)
   {
           struct ssam_controller *ctrl;

           ctrl = ssam_client_bind(&pdev->dev);
           if (IS_ERR(ctrl))
                   return PTR_ERR(ctrl) == -ENODEV ? -EPROBE_DEFER : PTR_ERR(ctrl);

           // ...

           return 0;
   }

The controller may be separately obtained via |ssam_get_controller| and its
lifetime be guaranteed via |ssam_controller_get| and |ssam_controller_put|.
Note that none of these functions, however, guarantee that the controller
will not be shut down or suspended. These functions essentially only operate
on the reference, i.e. only guarantee a bare minimum of accessibility
without any guarantees at all on practical operability.

SSAM device 추가와 제거

Device가 conventional 방식으로 이미 존재하거나 제공되지 않는다면 SSAM client device hub를 통해 `ssam_device`로 제공해야 합니다. 대응 registry에 UID를 입력하면 새 device를 hub에 추가할 수 있습니다.

SSAM device를 수동으로 만들 때는 `ssam_device_alloc()`으로 할당하고 `ssam_device_add()`로 추가한 뒤 최종적으로 `ssam_device_remove()`로 제거합니다.

기본 parent는 allocation에 제공한 controller device입니다. Device를 추가하기 전에 parent를 바꿀 수 있지만, 기본 parent-child relation이 제공하던 controller lifetime과 suspend/resume ordering 보장을 유지해야 합니다. 필요하면 Non-SSAM client와 마찬가지로 `ssam_client_link()`를 사용합니다.

Client device를 추가한 주체는 controller가 shutdown되기 전에 반드시 그 device를 제거해야 합니다. SSAM device를 제공하는 driver를 `ssam_client_link()`로 controller에 연결하면 controller driver보다 먼저 unbind되므로 이를 보장할 수 있습니다.

Controller를 parent로 등록한 client device는 controller shutdown 때 자동 제거되지만 여기에 의존해서는 안 됩니다. 특히 parent가 다른 client device에는 이 자동 제거가 적용되지 않습니다.

Adding SSAM Devices
===================

If a device does not already exist/is not already provided via conventional
means, it should be provided as |ssam_device| via the SSAM client device
hub. New devices can be added to this hub by entering their UID into the
corresponding registry. SSAM devices can also be manually allocated via
|ssam_device_alloc|, subsequently to which they have to be added via
|ssam_device_add| and eventually removed via |ssam_device_remove|. By
default, the parent of the device is set to the controller device provided
for allocation, however this may be changed before the device is added. Note
that, when changing the parent device, care must be taken to ensure that the
controller lifetime and suspend/resume ordering guarantees, in the default
setup provided through the parent-child relation, are preserved. If
necessary, by use of |ssam_client_link| as is done for non-SSAM client
drivers and described in more detail above.

A client device must always be removed by the party which added the
respective device before the controller shuts down. Such removal can be
guaranteed by linking the driver providing the SSAM device to the controller
via |ssam_client_link|, causing it to unbind before the controller driver
unbinds. Client devices registered with the controller as parent are
automatically removed when the controller shuts down, but this should not be
relied upon, especially as this does not extend to client devices with a
different parent.

SSAM Client Driver와 UID matching

SSAM client device driver는 본질적으로 다른 device driver 유형과 같습니다. `struct ssam_device_driver`로 표현되며 `struct ssam_device.uid`와 `struct ssam_device_driver.match_table`을 통해 `ssam_device`에 bind합니다. Driver 구조체를 선언할 때 match table을 설정하고 entry 정의 방식은 `SSAM_DEVICE` macro 문서를 따릅니다.

SSAM client device UID는 `domain`, `category`, `target`, `instance`, `function`으로 구성됩니다.

`domain`은 Surface Serial Hub를 통해 접근할 수 있는 물리 SAM device인 `SSAM_DOMAIN_SERIALHUB`와, SAM EC에 실제 표현이 없고 kernel/driver 쪽에서만 사용하는 client-device hub 같은 virtual device인 `SSAM_DOMAIN_VIRTUAL`을 구분합니다.

물리 device에서 `category`는 target category, `target`은 target ID, `instance`는 physical SAM device 접근에 사용하는 instance ID입니다. `function`은 특정 device 기능을 가리키지만 SAM EC 자체에는 의미가 없습니다. Client device의 기본 이름은 UID를 바탕으로 생성합니다.

Driver instance는 `ssam_device_driver_register()`로 등록하고 `ssam_device_driver_unregister()`로 해제합니다. `module_ssam_device_driver` macro는 driver를 등록하는 module init·exit function을 간편하게 정의합니다.

SSAM client device와 연관된 controller는 `struct ssam_device.ctrl`에 있습니다. 이 reference는 적어도 client driver가 bind된 동안 유효하고 일반적으로 client device가 존재하는 동안 유효해야 합니다.

Bind된 client driver 바깥에서 controller에 접근할 때는 request 또는 event notifier 등록·해제 중 controller device가 suspend되지 않도록 직접 보장해야 하므로 일반적으로 피해야 합니다. Bind된 client driver 내부 접근에는 이 보장이 제공됩니다.

SSAM Client Drivers
===================

SSAM client device drivers are, in essence, no different than other device
driver types. They are represented via |ssam_device_driver| and bind to a
|ssam_device| via its UID (:c:type:`struct ssam_device.uid <ssam_device>`)
member and the match table
(:c:type:`struct ssam_device_driver.match_table <ssam_device_driver>`),
which should be set when declaring the driver struct instance. Refer to the
|SSAM_DEVICE| macro documentation for more details on how to define members
of the driver's match table.

The UID for SSAM client devices consists of a ``domain``, a ``category``,
a ``target``, an ``instance``, and a ``function``. The ``domain`` is used
differentiate between physical SAM devices
(:c:type:`SSAM_DOMAIN_SERIALHUB <ssam_device_domain>`), i.e. devices that can
be accessed via the Surface Serial Hub, and virtual ones
(:c:type:`SSAM_DOMAIN_VIRTUAL <ssam_device_domain>`), such as client-device
hubs, that have no real representation on the SAM EC and are solely used on
the kernel/driver-side. For physical devices, ``category`` represents the
target category, ``target`` the target ID, and ``instance`` the instance ID
used to access the physical SAM device. In addition, ``function`` references
a specific device functionality, but has no meaning to the SAM EC. The
(default) name of a client device is generated based on its UID.

A driver instance can be registered via |ssam_device_driver_register| and
unregistered via |ssam_device_driver_unregister|. For convenience, the
|module_ssam_device_driver| macro may be used to define module init- and
exit-functions registering the driver.

The controller associated with a SSAM client device can be found in its
:c:type:`struct ssam_device.ctrl <ssam_device>` member. This reference is
guaranteed to be valid for at least as long as the client driver is bound,
but should also be valid for as long as the client device exists. Note,
however, that access outside of the bound client driver must ensure that the
controller device is not suspended while making any requests or
(un-)registering event notifiers (and thus should generally be avoided). This
is guaranteed when the controller is accessed from inside the bound client
driver.

Synchronous request 계약과 endianness

Synchronous request는 현재 host가 시작하는 EC communication의 주된 형태입니다. 여러 정의·실행 방식이 있지만 대부분 뒤의 예제와 같은 구조로 귀결됩니다.

예제는 caller가 SAM EC에 argument를 제공하고 response를 받는 write-read request입니다. Caller는 response payload의 최대 길이를 알아야 하며 이를 담을 buffer를 제공해야 합니다.

SAM EC로 전달하는 command payload data는 little-endian format이어야 합니다. 반대로 수신한 response payload data는 little-endian에서 host endianness로 변환해야 합니다.

Making Synchronous Requests
===========================

Synchronous requests are (currently) the main form of host-initiated
communication with the EC. There are a couple of ways to define and execute
such requests, however, most of them boil down to something similar as shown
in the example below. This example defines a write-read request, meaning
that the caller provides an argument to the SAM EC and receives a response.
The caller needs to know the (maximum) length of the response payload and
provide a buffer for it.

Care must be taken to ensure that any command payload data passed to the SAM
EC is provided in little-endian format and, similarly, any response payload
data received from it is converted from little-endian to host endianness.

수동 synchronous request 실행

수동 예제는 `struct ssam_request`와 `struct ssam_response`를 초기화합니다. Argument는 `cpu_to_le32()`로 little-endian으로 바꾸고 response 저장소도 `__le32`로 준비합니다.

Request specification에는 `target_category`, `target_id`, `command_id`, `instance_id`, `flags`, payload `length`, `payload` pointer를 지정합니다. Payload가 없는 request는 `length`를 0으로 두고 `payload`를 `NULL`로 둘 수 있습니다. 예제의 parameter는 설명용이며 실제 SAM/EC request와 대응하지 않습니다.

Response에는 buffer `capacity`, 현재 `length`, `pointer`를 지정합니다. Response가 없는 request라면 response pointer를 null로 둘 수 있지만 specification의 `SSAM_REQUEST_HAS_RESPONSE` flag와 반드시 일치해야 합니다.

`ssam_request_do_sync()`가 실제 request를 수행합니다. 대안인 `ssam_request_do_sync_onstack()`은 `kzalloc()` allocation 대신 message buffer를 stack에 둡니다.

완료 뒤 `le32_to_cpu()`로 response를 native format으로 변환합니다. Error 경로에서는 SSAM core가 response 값을 건드리지 않으므로 예제의 `ret_le`는 초기값 0을 유지합니다.

`ssam_request_do_sync()`는 본질적으로 더 낮은 수준의 request primitive를 감싼 wrapper이며, 필요하면 그 primitive를 직접 사용할 수도 있습니다.

.. code-block:: c

   int perform_request(struct ssam_controller *ctrl, u32 arg, u32 *ret)
   {
           struct ssam_request rqst;
           struct ssam_response resp;
           int status;

           /* Convert request argument to little-endian. */
           __le32 arg_le = cpu_to_le32(arg);
           __le32 ret_le = cpu_to_le32(0);

           /*
            * Initialize request specification. Replace this with your values.
            * The rqst.payload field may be NULL if rqst.length is zero,
            * indicating that the request does not have any argument.
            *
            * Note: The request parameters used here are not valid, i.e.
            *       they do not correspond to an actual SAM/EC request.
            */
           rqst.target_category = SSAM_SSH_TC_SAM;
           rqst.target_id = SSAM_SSH_TID_SAM;
           rqst.command_id = 0x02;
           rqst.instance_id = 0x03;
           rqst.flags = SSAM_REQUEST_HAS_RESPONSE;
           rqst.length = sizeof(arg_le);
           rqst.payload = (u8 *)&arg_le;

           /* Initialize request response. */
           resp.capacity = sizeof(ret_le);
           resp.length = 0;
           resp.pointer = (u8 *)&ret_le;

           /*
            * Perform actual request. The response pointer may be null in case
            * the request does not have any response. This must be consistent
            * with the SSAM_REQUEST_HAS_RESPONSE flag set in the specification
            * above.
            */
           status = ssam_request_do_sync(ctrl, &rqst, &resp);

           /*
            * Alternatively use
            *
            *   ssam_request_do_sync_onstack(ctrl, &rqst, &resp, sizeof(arg_le));
            *
            * to perform the request, allocating the message buffer directly
            * on the stack as opposed to allocation via kzalloc().
            */

           /*
            * Convert request response back to native format. Note that in the
            * error case, this value is not touched by the SSAM core, i.e.
            * 'ret_le' will be zero as specified in its initialization.
            */
           *ret = le32_to_cpu(ret_le);

           return status;
   }

Note that |ssam_request_do_sync| in its essence is a wrapper over lower-level
request primitives, which may also be used to perform requests. Refer to its
implementation and documentation for more details.

Synchronous request generator macro

Generator macro를 사용하면 request function을 더 편리하게 정의할 수 있습니다. 예제의 `SSAM_DEFINE_SYNC_REQUEST_W`는 `__ssam_tmp_perf_mode_set()` 함수를 만들고 target category·ID, command ID, instance ID를 고정합니다.

생성된 함수는 호출 때 `struct ssam_controller *ctrl`과 `const __le32 *arg`를 받습니다. Message buffer는 stack에 할당하므로 argument가 크면 이런 macro를 피해야 합니다.

Macro가 생성한 함수는 이전 수동 예제와 달리 endianness conversion을 하지 않으므로 caller가 처리해야 합니다. 이 차이와 stack allocation 외의 동작은 수동 예제와 유사합니다.

일반 macro 계열은 return value와 argument가 모두 없는 `SSAM_DEFINE_SYNC_REQUEST_N`, return value만 있는 `SSAM_DEFINE_SYNC_REQUEST_R`, argument만 있는 `SSAM_DEFINE_SYNC_REQUEST_W`입니다.

동일 device type의 여러 instance에 적용하는 `SSAM_DEFINE_SYNC_REQUEST_MD_N`, `_MD_R`, `_MD_W` 변형도 있습니다. 이 macro는 target ID와 instance ID를 생성 함수에 고정하지 않고 caller가 제공하게 합니다.

An arguably more user-friendly way of defining such functions is by using
one of the generator macros, for example via:

.. code-block:: c

   SSAM_DEFINE_SYNC_REQUEST_W(__ssam_tmp_perf_mode_set, __le32, {
           .target_category = SSAM_SSH_TC_TMP,
           .target_id       = SSAM_SSH_TID_SAM,
           .command_id      = 0x03,
           .instance_id     = 0x00,
   });

This example defines a function

.. code-block:: c

   static int __ssam_tmp_perf_mode_set(struct ssam_controller *ctrl, const __le32 *arg);

executing the specified request, with the controller passed in when calling
said function. In this example, the argument is provided via the ``arg``
pointer. Note that the generated function allocates the message buffer on
the stack. Thus, if the argument provided via the request is large, these
kinds of macros should be avoided. Also note that, in contrast to the
previous non-macro example, this function does not do any endianness
conversion, which has to be handled by the caller. Apart from those
differences the function generated by the macro is similar to the one
provided in the non-macro example above.

The full list of such function-generating macros is

- :c:func:`SSAM_DEFINE_SYNC_REQUEST_N` for requests without return value and
  without argument.
- :c:func:`SSAM_DEFINE_SYNC_REQUEST_R` for requests with return value but no
  argument.
- :c:func:`SSAM_DEFINE_SYNC_REQUEST_W` for requests without return value but
  with argument.

Refer to their respective documentation for more details. For each one of
these macros, a special variant is provided, which targets request types
applicable to multiple instances of the same device type:

- :c:func:`SSAM_DEFINE_SYNC_REQUEST_MD_N`
- :c:func:`SSAM_DEFINE_SYNC_REQUEST_MD_R`
- :c:func:`SSAM_DEFINE_SYNC_REQUEST_MD_W`

The difference of those macros to the previously mentioned versions is, that
the device target and instance IDs are not fixed for the generated function,
but instead have to be provided by the caller of said function.

Client device용 request macro

`ssam_device`와 직접 사용하는 client device 전용 macro 변형도 제공합니다.

예제의 `SSAM_DEFINE_SYNC_REQUEST_CL_R`은 `ssam_bat_get_sta(struct ssam_device *sdev, __le32 *ret)` 함수를 정의합니다. 생성 함수는 client device에 들어 있는 device ID와 controller를 사용해 지정된 request를 실행합니다.

Client device용 전체 macro는 argument와 return이 없는 `SSAM_DEFINE_SYNC_REQUEST_CL_N`, return만 있는 `_CL_R`, argument만 있는 `_CL_W`입니다.

Additionally, variants for direct use with client devices, i.e.
|ssam_device|, are also provided. These can, for example, be used as
follows:

.. code-block:: c

   SSAM_DEFINE_SYNC_REQUEST_CL_R(ssam_bat_get_sta, __le32, {
           .target_category = SSAM_SSH_TC_BAT,
           .command_id      = 0x01,
   });

This invocation of the macro defines a function

.. code-block:: c

   static int ssam_bat_get_sta(struct ssam_device *sdev, __le32 *ret);

executing the specified request, using the device IDs and controller given
in the client device. The full list of such macros for client devices is:

- :c:func:`SSAM_DEFINE_SYNC_REQUEST_CL_N`
- :c:func:`SSAM_DEFINE_SYNC_REQUEST_CL_R`
- :c:func:`SSAM_DEFINE_SYNC_REQUEST_CL_W`

Event notifier 등록과 filtering

SAM EC event를 받으려면 원하는 event에 대해 `ssam_notifier_register()`로 event notifier를 등록하고 더 필요하지 않을 때 `ssam_notifier_unregister()`로 해제해야 합니다.

`ssam_device` 유형 client는 client device의 hot-removal을 올바르게 처리하는 `ssam_device_notifier_register()`와 `ssam_device_notifier_unregister()` wrapper를 우선 사용해야 합니다.

Notifier 등록에는 최소한 event 수신 시 호출할 callback, event enable 방법을 지정하는 registry, target category와 registry에 따라 선택적인 instance ID를 지정하는 event ID, EC가 event를 보내는 방식을 나타내는 flag가 필요합니다.

Registry가 instance ID별 enable을 지원하지 않으면 instance ID를 0으로 설정해야 합니다. 같은 target category에 등록된 notifier 사이의 호출 순서는 선택적인 priority로 정합니다.

기본적으로 notifier는 등록 때 지정한 instance ID와 관계없이 특정 target category의 모든 event를 받습니다. `ssam_event_mask`를 제공하면 event의 target ID나 instance ID 또는 둘 다 notifier가 암시하는 ID와 일치할 때만 callback을 호출하도록 core에 지시할 수 있습니다.

일반적으로 registry의 target ID는 enable된 event의 target ID이기도 합니다. 예외로 Surface Laptop 1·2 keyboard input event는 target ID 1 registry로 enable하지만 target ID 2 event를 제공합니다.

Handling Events
===============

To receive events from the SAM EC, an event notifier must be registered for
the desired event via |ssam_notifier_register|. The notifier must be
unregistered via |ssam_notifier_unregister| once it is not required any
more. For |ssam_device| type clients, the |ssam_device_notifier_register| and
|ssam_device_notifier_unregister| wrappers should be preferred as they properly
handle hot-removal of client devices.

Event notifiers are registered by providing (at minimum) a callback to call
in case an event has been received, the registry specifying how the event
should be enabled, an event ID specifying for which target category and,
optionally and depending on the registry used, for which instance ID events
should be enabled, and finally, flags describing how the EC will send these
events. If the specific registry does not enable events by instance ID, the
instance ID must be set to zero. Additionally, a priority for the respective
notifier may be specified, which determines its order in relation to any
other notifier registered for the same target category.

By default, event notifiers will receive all events for the specific target
category, regardless of the instance ID specified when registering the
notifier. The core may be instructed to only call a notifier if the target
ID or instance ID (or both) of the event match the ones implied by the
notifier IDs (in case of target ID, the target ID of the registry), by
providing an event mask (see |ssam_event_mask|).

In general, the target ID of the registry is also the target ID of the
enabled event (with the notable exception being keyboard input events on the
Surface Laptop 1 and 2, which are enabled via a registry with target ID 1,
but provide events with target ID 2).

Event callback과 enable reference counting

전체 예제에서 `notifier_callback()`은 event를 처리한 뒤 `ssam_notifier_from_errno(status) | SSAM_NOTIF_HANDLED`를 반환하여 status를 notifier 값으로 변환하고 event를 처리했음을 표시합니다.

`setup_notifier()`는 priority, callback, `SSAM_EVENT_REGISTRY_KIP` registry, client UID의 target category와 instance, `SSAM_EVENT_MASK_STRICT` mask, `SSAM_EVENT_SEQUENCED` flag를 설정한 뒤 `ssam_notifier_register(sdev->ctrl, nf)`를 호출합니다.

같은 event에 여러 notifier를 등록할 수 있습니다. Event handler core는 registry, event target category, event instance ID 조합별 현재 notifier 수를 추적하여 enable·disable을 관리합니다.

특정 event의 첫 notifier를 등록할 때 event를 enable하고 마지막 notifier를 해제할 때 disable합니다. 따라서 event flag는 처음 등록한 notifier의 값만 사용되지만, 같은 event의 모든 notifier는 동일한 flag로 등록해야 하며 이를 어기면 bug로 간주합니다.

A full example for registering an event notifier and handling received
events is provided below:

.. code-block:: c

   u32 notifier_callback(struct ssam_event_notifier *nf,
                         const struct ssam_event *event)
   {
           int status = ...

           /* Handle the event here ... */

           /* Convert return value and indicate that we handled the event. */
           return ssam_notifier_from_errno(status) | SSAM_NOTIF_HANDLED;
   }

   int setup_notifier(struct ssam_device *sdev,
                      struct ssam_event_notifier *nf)
   {
           /* Set priority wrt. other handlers of same target category. */
           nf->base.priority = 1;

           /* Set event/notifier callback. */
           nf->base.fn = notifier_callback;

           /* Specify event registry, i.e. how events get enabled/disabled. */
           nf->event.reg = SSAM_EVENT_REGISTRY_KIP;

           /* Specify which event to enable/disable */
           nf->event.id.target_category = sdev->uid.category;
           nf->event.id.instance = sdev->uid.instance;

           /*
            * Specify for which events the notifier callback gets executed.
            * This essentially tells the core if it can skip notifiers that
            * don't have target or instance IDs matching those of the event.
            */
           nf->event.mask = SSAM_EVENT_MASK_STRICT;

           /* Specify event flags. */
           nf->event.flags = SSAM_EVENT_SEQUENCED;

           return ssam_notifier_register(sdev->ctrl, nf);
   }

Multiple event notifiers can be registered for the same event. The event
handler core takes care of enabling and disabling events when notifiers are
registered and unregistered, by keeping track of how many notifiers for a
specific event (combination of registry, event target category, and event
instance ID) are currently registered. This means that a specific event will
be enabled when the first notifier for it is being registered and disabled
when the last notifier for it is being unregistered. Note that the event
flags are therefore only used on the first registered notifier, however, one
should take care that notifiers for a specific event are always registered
with the same flag and it is considered a bug to do otherwise.