Lines Matching +full:client +full:- +full:id
1 .. SPDX-License-Identifier: GPL-2.0+
27 Writing Client Drivers
35 client-api
41 Client drivers can be set up in two main ways, depending on how the
45 are non-discoverable and instead need to be explicitly provided by some
49 Non-SSAM Client Drivers
53 representing that EC to the kernel. Drivers targeting a non-SSAM device (and
58 client device and controller (this can also be done separate via
60 that the returned controller is valid for use in the client driver for as
67 .. code-block:: c
73 ctrl = ssam_client_bind(&pdev->dev);
75 return PTR_ERR(ctrl) == -ENODEV ? -EPROBE_DEFER : PTR_ERR(ctrl);
94 means, it should be provided as |ssam_device| via the SSAM client device
103 setup provided through the parent-child relation, are preserved. If
104 necessary, by use of |ssam_client_link| as is done for non-SSAM client
107 A client device must always be removed by the party which added the
111 unbinds. Client devices registered with the controller as parent are
113 relied upon, especially as this does not extend to client devices with a
117 SSAM Client Drivers
120 SSAM client device drivers are, in essence, no different than other device
129 The UID for SSAM client devices consists of a ``domain``, a ``category``,
134 (:c:type:`SSAM_DOMAIN_VIRTUAL <ssam_device_domain>`), such as client-device
136 the kernel/driver-side. For physical devices, ``category`` represents the
137 target category, ``target`` the target ID, and ``instance`` the instance ID
140 (default) name of a client device is generated based on its UID.
144 |module_ssam_device_driver| macro may be used to define module init- and
145 exit-functions registering the driver.
147 The controller associated with a SSAM client device can be found in its
149 guaranteed to be valid for at least as long as the client driver is bound,
150 but should also be valid for as long as the client device exists. Note,
151 however, that access outside of the bound client driver must ensure that the
153 (un-)registering event notifiers (and thus should generally be avoided). This
154 is guaranteed when the controller is accessed from inside the bound client
161 Synchronous requests are (currently) the main form of host-initiated
164 in the example below. This example defines a write-read request, meaning
170 EC is provided in little-endian format and, similarly, any response payload
171 data received from it is converted from little-endian to host endianness.
173 .. code-block:: c
181 /* Convert request argument to little-endian. */
233 Note that |ssam_request_do_sync| in its essence is a wrapper over lower-level
237 An arguably more user-friendly way of defining such functions is by using
240 .. code-block:: c
251 .. code-block:: c
260 previous non-macro example, this function does not do any endianness
263 provided in the non-macro example above.
265 The full list of such function-generating macros is
267 - :c:func:`SSAM_DEFINE_SYNC_REQUEST_N` for requests without return value and
269 - :c:func:`SSAM_DEFINE_SYNC_REQUEST_R` for requests with return value but no
271 - :c:func:`SSAM_DEFINE_SYNC_REQUEST_W` for requests without return value but
278 - :c:func:`SSAM_DEFINE_SYNC_REQUEST_MD_N`
279 - :c:func:`SSAM_DEFINE_SYNC_REQUEST_MD_R`
280 - :c:func:`SSAM_DEFINE_SYNC_REQUEST_MD_W`
286 Additionally, variants for direct use with client devices, i.e.
290 .. code-block:: c
299 .. code-block:: c
304 in the client device. The full list of such macros for client devices is:
306 - :c:func:`SSAM_DEFINE_SYNC_REQUEST_CL_N`
307 - :c:func:`SSAM_DEFINE_SYNC_REQUEST_CL_R`
308 - :c:func:`SSAM_DEFINE_SYNC_REQUEST_CL_W`
319 handle hot-removal of client devices.
323 should be enabled, an event ID specifying for which target category and,
324 optionally and depending on the registry used, for which instance ID events
326 events. If the specific registry does not enable events by instance ID, the
327 instance ID must be set to zero. Additionally, a priority for the respective
332 category, regardless of the instance ID specified when registering the
334 ID or instance ID (or both) of the event match the ones implied by the
335 notifier IDs (in case of target ID, the target ID of the registry), by
338 In general, the target ID of the registry is also the target ID of the
340 Surface Laptop 1 and 2, which are enabled via a registry with target ID 1,
341 but provide events with target ID 2).
346 .. code-block:: c
363 nf->base.priority = 1;
366 nf->base.fn = notifier_callback;
369 nf->event.reg = SSAM_EVENT_REGISTRY_KIP;
372 nf->event.id.target_category = sdev->uid.category;
373 nf->event.id.instance = sdev->uid.instance;
380 nf->event.mask = SSAM_EVENT_MASK_STRICT;
383 nf->event.flags = SSAM_EVENT_SEQUENCED;
385 return ssam_notifier_register(sdev->ctrl, nf);
392 instance ID) are currently registered. This means that a specific event will