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
52 All communication with the SAM EC is handled via the |ssam_controller|
53 representing that EC to the kernel. Drivers targeting a non-SSAM device (and
67 .. code-block:: c
73            ctrl = ssam_client_bind(&pdev->dev);
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
131 differentiate between physical SAM devices
133 be accessed via the Surface Serial Hub, and virtual ones
134 (:c:type:`SSAM_DOMAIN_VIRTUAL <ssam_device_domain>`), such as client-device
135 hubs, that have no real representation on the SAM EC and are solely used on
136 the kernel/driver-side. For physical devices, ``category`` represents the
138 used to access the physical SAM device. In addition, ``function`` references
139 a specific device functionality, but has no meaning to the SAM EC. The
144 |module_ssam_device_driver| macro may be used to define module init- and
145 exit-functions registering the driver.
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
165 that the caller provides an argument to the SAM EC and receives a response.
169 Care must be taken to ensure that any command payload data passed to the SAM
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. */
191             *       they do not correspond to an actual SAM/EC request.
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`
290 .. code-block:: c
299 .. code-block:: c
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`
314 To receive events from the SAM EC, an event notifier must be registered for
319 handle hot-removal of client devices.
340 Surface Laptop 1 and 2, which are enabled via a registry with target ID 1,
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);