driver-api/surface_aggregator/client.rst

1 .. SPDX-License-Identifier: GPL-2.0+
35    client-api
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
67 .. code-block:: c
71            struct ssam_controller *ctrl;
73            ctrl = ssam_client_bind(&pdev->dev);
74            if (IS_ERR(ctrl))
75                    return PTR_ERR(ctrl) == -ENODEV ? -EPROBE_DEFER : PTR_ERR(ctrl);
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
134 (:c:type:`SSAM_DOMAIN_VIRTUAL <ssam_device_domain>`), such as client-device
136 the kernel/driver-side. For physical devices, ``category`` represents the
144 |module_ssam_device_driver| macro may be used to define module init- and
145 exit-functions registering the driver.
148 :c:type:`struct ssam_device.ctrl <ssam_device>` member. This reference is
153 (un-)registering event notifiers (and thus should generally be avoided). This
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
175    int perform_request(struct ssam_controller *ctrl, u32 arg, u32 *ret)
181            /* Convert request argument to little-endian. */
212            status = ssam_request_do_sync(ctrl, &rqst, &resp);
217             *   ssam_request_do_sync_onstack(ctrl, &rqst, &resp, sizeof(arg_le));
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
253    static int __ssam_tmp_perf_mode_set(struct ssam_controller *ctrl, const __le32 *arg);
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`
283 the device target and instance IDs are not fixed for the generated function,
290 .. code-block:: c
299 .. code-block:: c
303 executing the specified request, using the device IDs and controller given
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.
335 notifier IDs (in case of target ID, the target ID of the registry), by
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;
378             * don't have target or instance IDs matching those of the event.
380            nf->event.mask = SSAM_EVENT_MASK_STRICT;
383            nf->event.flags = SSAM_EVENT_SEQUENCED;
385            return ssam_notifier_register(sdev->ctrl, nf);