1.. SPDX-License-Identifier: GPL-2.0+
2
3.. |ssh_ptl| replace:: :c:type:`struct ssh_ptl <ssh_ptl>`
4.. |ssh_ptl_submit| replace:: :c:func:`ssh_ptl_submit`
5.. |ssh_ptl_cancel| replace:: :c:func:`ssh_ptl_cancel`
6.. |ssh_ptl_shutdown| replace:: :c:func:`ssh_ptl_shutdown`
7.. |ssh_ptl_rx_rcvbuf| replace:: :c:func:`ssh_ptl_rx_rcvbuf`
8.. |ssh_rtl| replace:: :c:type:`struct ssh_rtl <ssh_rtl>`
9.. |ssh_rtl_submit| replace:: :c:func:`ssh_rtl_submit`
10.. |ssh_rtl_cancel| replace:: :c:func:`ssh_rtl_cancel`
11.. |ssh_rtl_shutdown| replace:: :c:func:`ssh_rtl_shutdown`
12.. |ssh_packet| replace:: :c:type:`struct ssh_packet <ssh_packet>`
13.. |ssh_packet_get| replace:: :c:func:`ssh_packet_get`
14.. |ssh_packet_put| replace:: :c:func:`ssh_packet_put`
15.. |ssh_packet_ops| replace:: :c:type:`struct ssh_packet_ops <ssh_packet_ops>`
16.. |ssh_packet_base_priority| replace:: :c:type:`enum ssh_packet_base_priority <ssh_packet_base_priority>`
17.. |ssh_packet_flags| replace:: :c:type:`enum ssh_packet_flags <ssh_packet_flags>`
18.. |SSH_PACKET_PRIORITY| replace:: :c:func:`SSH_PACKET_PRIORITY`
19.. |ssh_frame| replace:: :c:type:`struct ssh_frame <ssh_frame>`
20.. |ssh_command| replace:: :c:type:`struct ssh_command <ssh_command>`
21.. |ssh_request| replace:: :c:type:`struct ssh_request <ssh_request>`
22.. |ssh_request_get| replace:: :c:func:`ssh_request_get`
23.. |ssh_request_put| replace:: :c:func:`ssh_request_put`
24.. |ssh_request_ops| replace:: :c:type:`struct ssh_request_ops <ssh_request_ops>`
25.. |ssh_request_init| replace:: :c:func:`ssh_request_init`
26.. |ssh_request_flags| replace:: :c:type:`enum ssh_request_flags <ssh_request_flags>`
27.. |ssam_controller| replace:: :c:type:`struct ssam_controller <ssam_controller>`
28.. |ssam_device| replace:: :c:type:`struct ssam_device <ssam_device>`
29.. |ssam_device_driver| replace:: :c:type:`struct ssam_device_driver <ssam_device_driver>`
30.. |ssam_client_bind| replace:: :c:func:`ssam_client_bind`
31.. |ssam_client_link| replace:: :c:func:`ssam_client_link`
32.. |ssam_request_sync| replace:: :c:type:`struct ssam_request_sync <ssam_request_sync>`
33.. |ssam_event_registry| replace:: :c:type:`struct ssam_event_registry <ssam_event_registry>`
34.. |ssam_event_id| replace:: :c:type:`struct ssam_event_id <ssam_event_id>`
35.. |ssam_nf| replace:: :c:type:`struct ssam_nf <ssam_nf>`
36.. |ssam_nf_refcount_inc| replace:: :c:func:`ssam_nf_refcount_inc`
37.. |ssam_nf_refcount_dec| replace:: :c:func:`ssam_nf_refcount_dec`
38.. |ssam_notifier_register| replace:: :c:func:`ssam_notifier_register`
39.. |ssam_notifier_unregister| replace:: :c:func:`ssam_notifier_unregister`
40.. |ssam_cplt| replace:: :c:type:`struct ssam_cplt <ssam_cplt>`
41.. |ssam_event_queue| replace:: :c:type:`struct ssam_event_queue <ssam_event_queue>`
42.. |ssam_request_sync_submit| replace:: :c:func:`ssam_request_sync_submit`
43
44=====================
45Core Driver Internals
46=====================
47
48Architectural overview of the Surface System Aggregator Module (SSAM) core
49and Surface Serial Hub (SSH) driver. For the API documentation, refer to:
50
51.. toctree::
52   :maxdepth: 2
53
54   internal-api
55
56
57Overview
58========
59
60The SSAM core implementation is structured in layers, somewhat following the
61SSH protocol structure:
62
63Lower-level packet transport is implemented in the *packet transport layer
64(PTL)*, directly building on top of the serial device (serdev)
65infrastructure of the kernel. As the name indicates, this layer deals with
66the packet transport logic and handles things like packet validation, packet
67acknowledgment (ACKing), packet (retransmission) timeouts, and relaying
68packet payloads to higher-level layers.
69
70Above this sits the *request transport layer (RTL)*. This layer is centered
71around command-type packet payloads, i.e. requests (sent from host to EC),
72responses of the EC to those requests, and events (sent from EC to host).
73It, specifically, distinguishes events from request responses, matches
74responses to their corresponding requests, and implements request timeouts.
75
76The *controller* layer is building on top of this and essentially decides
77how request responses and, especially, events are dealt with. It provides an
78event notifier system, handles event activation/deactivation, provides a
79workqueue for event and asynchronous request completion, and also manages
80the message counters required for building command messages (``SEQ``,
81``RQID``). This layer basically provides a fundamental interface to the SAM
82EC for use in other kernel drivers.
83
84While the controller layer already provides an interface for other kernel
85drivers, the client *bus* extends this interface to provide support for
86native SSAM devices, i.e. devices that are not defined in ACPI and not
87implemented as platform devices, via |ssam_device| and |ssam_device_driver|
88simplify management of client devices and client drivers.
89
90Refer to Documentation/driver-api/surface_aggregator/client.rst for
91documentation regarding the client device/driver API and interface options
92for other kernel drivers. It is recommended to familiarize oneself with
93that chapter and the Documentation/driver-api/surface_aggregator/ssh.rst
94before continuing with the architectural overview below.
95
96
97Packet Transport Layer
98======================
99
100The packet transport layer is represented via |ssh_ptl| and is structured
101around the following key concepts:
102
103Packets
104-------
105
106Packets are the fundamental transmission unit of the SSH protocol. They are
107managed by the packet transport layer, which is essentially the lowest layer
108of the driver and is built upon by other components of the SSAM core.
109Packets to be transmitted by the SSAM core are represented via |ssh_packet|
110(in contrast, packets received by the core do not have any specific
111structure and are managed entirely via the raw |ssh_frame|).
112
113This structure contains the required fields to manage the packet inside the
114transport layer, as well as a reference to the buffer containing the data to
115be transmitted (i.e. the message wrapped in |ssh_frame|). Most notably, it
116contains an internal reference count, which is used for managing its
117lifetime (accessible via |ssh_packet_get| and |ssh_packet_put|). When this
118counter reaches zero, the ``release()`` callback provided to the packet via
119its |ssh_packet_ops| reference is executed, which may then deallocate the
120packet or its enclosing structure (e.g. |ssh_request|).
121
122In addition to the ``release`` callback, the |ssh_packet_ops| reference also
123provides a ``complete()`` callback, which is run once the packet has been
124completed and provides the status of this completion, i.e. zero on success
125or a negative errno value in case of an error. Once the packet has been
126submitted to the packet transport layer, the ``complete()`` callback is
127always guaranteed to be executed before the ``release()`` callback, i.e. the
128packet will always be completed, either successfully, with an error, or due
129to cancellation, before it will be released.
130
131The state of a packet is managed via its ``state`` flags
132(|ssh_packet_flags|), which also contains the packet type. In particular,
133the following bits are noteworthy:
134
135* ``SSH_PACKET_SF_LOCKED_BIT``: This bit is set when completion, either
136  through error or success, is imminent. It indicates that no further
137  references of the packet should be taken and any existing references
138  should be dropped as soon as possible. The process setting this bit is
139  responsible for removing any references to this packet from the packet
140  queue and pending set.
141
142* ``SSH_PACKET_SF_COMPLETED_BIT``: This bit is set by the process running the
143  ``complete()`` callback and is used to ensure that this callback only runs
144  once.
145
146* ``SSH_PACKET_SF_QUEUED_BIT``: This bit is set when the packet is queued on
147  the packet queue and cleared when it is dequeued.
148
149* ``SSH_PACKET_SF_PENDING_BIT``: This bit is set when the packet is added to
150  the pending set and cleared when it is removed from it.
151
152Packet Queue
153------------
154
155The packet queue is the first of the two fundamental collections in the
156packet transport layer. It is a priority queue, with priority of the
157respective packets based on the packet type (major) and number of tries
158(minor). See |SSH_PACKET_PRIORITY| for more details on the priority value.
159
160All packets to be transmitted by the transport layer must be submitted to
161this queue via |ssh_ptl_submit|. Note that this includes control packets
162sent by the transport layer itself. Internally, data packets can be
163re-submitted to this queue due to timeouts or NAK packets sent by the EC.
164
165Pending Set
166-----------
167
168The pending set is the second of the two fundamental collections in the
169packet transport layer. It stores references to packets that have already
170been transmitted, but wait for acknowledgment (e.g. the corresponding ACK
171packet) by the EC.
172
173Note that a packet may both be pending and queued if it has been
174re-submitted due to a packet acknowledgment timeout or NAK. On such a
175re-submission, packets are not removed from the pending set.
176
177Transmitter Thread
178------------------
179
180The transmitter thread is responsible for most of the actual work regarding
181packet transmission. In each iteration, it (waits for and) checks if the
182next packet on the queue (if any) can be transmitted and, if so, removes it
183from the queue and increments its counter for the number of transmission
184attempts, i.e. tries. If the packet is sequenced, i.e. requires an ACK by
185the EC, the packet is added to the pending set. Next, the packet's data is
186submitted to the serdev subsystem. In case of an error or timeout during
187this submission, the packet is completed by the transmitter thread with the
188status value of the callback set accordingly. In case the packet is
189unsequenced, i.e. does not require an ACK by the EC, the packet is completed
190with success on the transmitter thread.
191
192Transmission of sequenced packets is limited by the number of concurrently
193pending packets, i.e. a limit on how many packets may be waiting for an ACK
194from the EC in parallel. This limit is currently set to one (see
195Documentation/driver-api/surface_aggregator/ssh.rst for the reasoning behind
196this). Control packets (i.e. ACK and NAK) can always be transmitted.
197
198Receiver Thread
199---------------
200
201Any data received from the EC is put into a FIFO buffer for further
202processing. This processing happens on the receiver thread. The receiver
203thread parses and validates the received message into its |ssh_frame| and
204corresponding payload. It prepares and submits the necessary ACK (and on
205validation error or invalid data NAK) packets for the received messages.
206
207This thread also handles further processing, such as matching ACK messages
208to the corresponding pending packet (via sequence ID) and completing it, as
209well as initiating re-submission of all currently pending packets on
210receival of a NAK message (re-submission in case of a NAK is similar to
211re-submission due to timeout, see below for more details on that). Note that
212the successful completion of a sequenced packet will always run on the
213receiver thread (whereas any failure-indicating completion will run on the
214process where the failure occurred).
215
216Any payload data is forwarded via a callback to the next upper layer, i.e.
217the request transport layer.
218
219Timeout Reaper
220--------------
221
222The packet acknowledgment timeout is a per-packet timeout for sequenced
223packets, started when the respective packet begins (re-)transmission (i.e.
224this timeout is armed once per transmission attempt on the transmitter
225thread). It is used to trigger re-submission or, when the number of tries
226has been exceeded, cancellation of the packet in question.
227
228This timeout is handled via a dedicated reaper task, which is essentially a
229work item (re-)scheduled to run when the next packet is set to time out. The
230work item then checks the set of pending packets for any packets that have
231exceeded the timeout and, if there are any remaining packets, re-schedules
232itself to the next appropriate point in time.
233
234If a timeout has been detected by the reaper, the packet will either be
235re-submitted if it still has some remaining tries left, or completed with
236``-ETIMEDOUT`` as status if not. Note that re-submission, in this case and
237triggered by receival of a NAK, means that the packet is added to the queue
238with a now incremented number of tries, yielding a higher priority. The
239timeout for the packet will be disabled until the next transmission attempt
240and the packet remains on the pending set.
241
242Note that due to transmission and packet acknowledgment timeouts, the packet
243transport layer is always guaranteed to make progress, if only through
244timing out packets, and will never fully block.
245
246Concurrency and Locking
247-----------------------
248
249There are two main locks in the packet transport layer: One guarding access
250to the packet queue and one guarding access to the pending set. These
251collections may only be accessed and modified under the respective lock. If
252access to both collections is needed, the pending lock must be acquired
253before the queue lock to avoid deadlocks.
254
255In addition to guarding the collections, after initial packet submission
256certain packet fields may only be accessed under one of the locks.
257Specifically, the packet priority must only be accessed while holding the
258queue lock and the packet timestamp must only be accessed while holding the
259pending lock.
260
261Other parts of the packet transport layer are guarded independently. State
262flags are managed by atomic bit operations and, if necessary, memory
263barriers. Modifications to the timeout reaper work item and expiration date
264are guarded by their own lock.
265
266The reference of the packet to the packet transport layer (``ptl``) is
267somewhat special. It is either set when the upper layer request is submitted
268or, if there is none, when the packet is first submitted. After it is set,
269it will not change its value. Functions that may run concurrently with
270submission, i.e. cancellation, can not rely on the ``ptl`` reference to be
271set. Access to it in these functions is guarded by ``READ_ONCE()``, whereas
272setting ``ptl`` is equally guarded with ``WRITE_ONCE()`` for symmetry.
273
274Some packet fields may be read outside of the respective locks guarding
275them, specifically priority and state for tracing. In those cases, proper
276access is ensured by employing ``WRITE_ONCE()`` and ``READ_ONCE()``. Such
277read-only access is only allowed when stale values are not critical.
278
279With respect to the interface for higher layers, packet submission
280(|ssh_ptl_submit|), packet cancellation (|ssh_ptl_cancel|), data receival
281(|ssh_ptl_rx_rcvbuf|), and layer shutdown (|ssh_ptl_shutdown|) may always be
282executed concurrently with respect to each other. Note that packet
283submission may not run concurrently with itself for the same packet.
284Equally, shutdown and data receival may also not run concurrently with
285themselves (but may run concurrently with each other).
286
287
288Request Transport Layer
289=======================
290
291The request transport layer is represented via |ssh_rtl| and builds on top
292of the packet transport layer. It deals with requests, i.e. SSH packets sent
293by the host containing a |ssh_command| as frame payload. This layer
294separates responses to requests from events, which are also sent by the EC
295via a |ssh_command| payload. While responses are handled in this layer,
296events are relayed to the next upper layer, i.e. the controller layer, via
297the corresponding callback. The request transport layer is structured around
298the following key concepts:
299
300Request
301-------
302
303Requests are packets with a command-type payload, sent from host to EC to
304query data from or trigger an action on it (or both simultaneously). They
305are represented by |ssh_request|, wrapping the underlying |ssh_packet|
306storing its message data (i.e. SSH frame with command payload). Note that
307all top-level representations, e.g. |ssam_request_sync| are built upon this
308struct.
309
310As |ssh_request| extends |ssh_packet|, its lifetime is also managed by the
311reference counter inside the packet struct (which can be accessed via
312|ssh_request_get| and |ssh_request_put|). Once the counter reaches zero, the
313``release()`` callback of the |ssh_request_ops| reference of the request is
314called.
315
316Requests can have an optional response that is equally sent via a SSH
317message with command-type payload (from EC to host). The party constructing
318the request must know if a response is expected and mark this in the request
319flags provided to |ssh_request_init|, so that the request transport layer
320can wait for this response.
321
322Similar to |ssh_packet|, |ssh_request| also has a ``complete()`` callback
323provided via its request ops reference and is guaranteed to be completed
324before it is released once it has been submitted to the request transport
325layer via |ssh_rtl_submit|. For a request without a response, successful
326completion will occur once the underlying packet has been successfully
327transmitted by the packet transport layer (i.e. from within the packet
328completion callback). For a request with response, successful completion
329will occur once the response has been received and matched to the request
330via its request ID (which happens on the packet layer's data-received
331callback running on the receiver thread). If the request is completed with
332an error, the status value will be set to the corresponding (negative) errno
333value.
334
335The state of a request is again managed via its ``state`` flags
336(|ssh_request_flags|), which also encode the request type. In particular,
337the following bits are noteworthy:
338
339* ``SSH_REQUEST_SF_LOCKED_BIT``: This bit is set when completion, either
340  through error or success, is imminent. It indicates that no further
341  references of the request should be taken and any existing references
342  should be dropped as soon as possible. The process setting this bit is
343  responsible for removing any references to this request from the request
344  queue and pending set.
345
346* ``SSH_REQUEST_SF_COMPLETED_BIT``: This bit is set by the process running the
347  ``complete()`` callback and is used to ensure that this callback only runs
348  once.
349
350* ``SSH_REQUEST_SF_QUEUED_BIT``: This bit is set when the request is queued on
351  the request queue and cleared when it is dequeued.
352
353* ``SSH_REQUEST_SF_PENDING_BIT``: This bit is set when the request is added to
354  the pending set and cleared when it is removed from it.
355
356Request Queue
357-------------
358
359The request queue is the first of the two fundamental collections in the
360request transport layer. In contrast to the packet queue of the packet
361transport layer, it is not a priority queue and the simple first come first
362serve principle applies.
363
364All requests to be transmitted by the request transport layer must be
365submitted to this queue via |ssh_rtl_submit|. Once submitted, requests may
366not be re-submitted, and will not be re-submitted automatically on timeout.
367Instead, the request is completed with a timeout error. If desired, the
368caller can create and submit a new request for another try, but it must not
369submit the same request again.
370
371Pending Set
372-----------
373
374The pending set is the second of the two fundamental collections in the
375request transport layer. This collection stores references to all pending
376requests, i.e. requests awaiting a response from the EC (similar to what the
377pending set of the packet transport layer does for packets).
378
379Transmitter Task
380----------------
381
382The transmitter task is scheduled when a new request is available for
383transmission. It checks if the next request on the request queue can be
384transmitted and, if so, submits its underlying packet to the packet
385transport layer. This check ensures that only a limited number of
386requests can be pending, i.e. waiting for a response, at the same time. If
387the request requires a response, the request is added to the pending set
388before its packet is submitted.
389
390Packet Completion Callback
391--------------------------
392
393The packet completion callback is executed once the underlying packet of a
394request has been completed. In case of an error completion, the
395corresponding request is completed with the error value provided in this
396callback.
397
398On successful packet completion, further processing depends on the request.
399If the request expects a response, it is marked as transmitted and the
400request timeout is started. If the request does not expect a response, it is
401completed with success.
402
403Data-Received Callback
404----------------------
405
406The data received callback notifies the request transport layer of data
407being received by the underlying packet transport layer via a data-type
408frame. In general, this is expected to be a command-type payload.
409
410If the request ID of the command is one of the request IDs reserved for
411events (one to ``SSH_NUM_EVENTS``, inclusively), it is forwarded to the
412event callback registered in the request transport layer. If the request ID
413indicates a response to a request, the respective request is looked up in
414the pending set and, if found and marked as transmitted, completed with
415success.
416
417Timeout Reaper
418--------------
419
420The request-response-timeout is a per-request timeout for requests expecting
421a response. It is used to ensure that a request does not wait indefinitely
422on a response from the EC and is started after the underlying packet has
423been successfully completed.
424
425This timeout is, similar to the packet acknowledgment timeout on the packet
426transport layer, handled via a dedicated reaper task. This task is
427essentially a work-item (re-)scheduled to run when the next request is set
428to time out. The work item then scans the set of pending requests for any
429requests that have timed out and completes them with ``-ETIMEDOUT`` as
430status. Requests will not be re-submitted automatically. Instead, the issuer
431of the request must construct and submit a new request, if so desired.
432
433Note that this timeout, in combination with packet transmission and
434acknowledgment timeouts, guarantees that the request layer will always make
435progress, even if only through timing out packets, and never fully block.
436
437Concurrency and Locking
438-----------------------
439
440Similar to the packet transport layer, there are two main locks in the
441request transport layer: One guarding access to the request queue and one
442guarding access to the pending set. These collections may only be accessed
443and modified under the respective lock.
444
445Other parts of the request transport layer are guarded independently. State
446flags are (again) managed by atomic bit operations and, if necessary, memory
447barriers. Modifications to the timeout reaper work item and expiration date
448are guarded by their own lock.
449
450Some request fields may be read outside of the respective locks guarding
451them, specifically the state for tracing. In those cases, proper access is
452ensured by employing ``WRITE_ONCE()`` and ``READ_ONCE()``. Such read-only
453access is only allowed when stale values are not critical.
454
455With respect to the interface for higher layers, request submission
456(|ssh_rtl_submit|), request cancellation (|ssh_rtl_cancel|), and layer
457shutdown (|ssh_rtl_shutdown|) may always be executed concurrently with
458respect to each other. Note that request submission may not run concurrently
459with itself for the same request (and also may only be called once per
460request). Equally, shutdown may also not run concurrently with itself.
461
462
463Controller Layer
464================
465
466The controller layer extends on the request transport layer to provide an
467easy-to-use interface for client drivers. It is represented by
468|ssam_controller| and the SSH driver. While the lower level transport layers
469take care of transmitting and handling packets and requests, the controller
470layer takes on more of a management role. Specifically, it handles device
471initialization, power management, and event handling, including event
472delivery and registration via the (event) completion system (|ssam_cplt|).
473
474Event Registration
475------------------
476
477In general, an event (or rather a class of events) has to be explicitly
478requested by the host before the EC will send it (HID input events seem to
479be the exception). This is done via an event-enable request (similarly,
480events should be disabled via an event-disable request once no longer
481desired).
482
483The specific request used to enable (or disable) an event is given via an
484event registry, i.e. the governing authority of this event (so to speak),
485represented by |ssam_event_registry|. As parameters to this request, the
486target category and, depending on the event registry, instance ID of the
487event to be enabled must be provided. This (optional) instance ID must be
488zero if the registry does not use it. Together, target category and instance
489ID form the event ID, represented by |ssam_event_id|. In short, both, event
490registry and event ID, are required to uniquely identify a respective class
491of events.
492
493Note that a further *request ID* parameter must be provided for the
494enable-event request. This parameter does not influence the class of events
495being enabled, but instead is set as the request ID (RQID) on each event of
496this class sent by the EC. It is used to identify events (as a limited
497number of request IDs is reserved for use in events only, specifically one
498to ``SSH_NUM_EVENTS`` inclusively) and also map events to their specific
499class. Currently, the controller always sets this parameter to the target
500category specified in |ssam_event_id|.
501
502As multiple client drivers may rely on the same (or overlapping) classes of
503events and enable/disable calls are strictly binary (i.e. on/off), the
504controller has to manage access to these events. It does so via reference
505counting, storing the counter inside an RB-tree based mapping with event
506registry and ID as key (there is no known list of valid event registry and
507event ID combinations). See |ssam_nf|, |ssam_nf_refcount_inc|, and
508|ssam_nf_refcount_dec| for details.
509
510This management is done together with notifier registration (described in
511the next section) via the top-level |ssam_notifier_register| and
512|ssam_notifier_unregister| functions.
513
514Event Delivery
515--------------
516
517To receive events, a client driver has to register an event notifier via
518|ssam_notifier_register|. This increments the reference counter for that
519specific class of events (as detailed in the previous section), enables the
520class on the EC (if it has not been enabled already), and installs the
521provided notifier callback.
522
523Notifier callbacks are stored in lists, with one (RCU) list per target
524category (provided via the event ID; NB: there is a fixed known number of
525target categories). There is no known association from the combination of
526event registry and event ID to the command data (target ID, target category,
527command ID, and instance ID) that can be provided by an event class, apart
528from target category and instance ID given via the event ID.
529
530Note that due to the way notifiers are (or rather have to be) stored, client
531drivers may receive events that they have not requested and need to account
532for them. Specifically, they will, by default, receive all events from the
533same target category. To simplify dealing with this, filtering of events by
534target ID (provided via the event registry) and instance ID (provided via
535the event ID) can be requested when registering a notifier. This filtering
536is applied when iterating over the notifiers at the time they are executed.
537
538All notifier callbacks are executed on a dedicated workqueue, the so-called
539completion workqueue. After an event has been received via the callback
540installed in the request layer (running on the receiver thread of the packet
541transport layer), it will be put on its respective event queue
542(|ssam_event_queue|). From this event queue the completion work item of that
543queue (running on the completion workqueue) will pick up the event and
544execute the notifier callback. This is done to avoid blocking on the
545receiver thread.
546
547There is one event queue per combination of target ID and target category.
548This is done to ensure that notifier callbacks are executed in sequence for
549events of the same target ID and target category. Callbacks can be executed
550in parallel for events with a different combination of target ID and target
551category.
552
553Concurrency and Locking
554-----------------------
555
556Most of the concurrency related safety guarantees of the controller are
557provided by the lower-level request transport layer. In addition to this,
558event (un-)registration is guarded by its own lock.
559
560Access to the controller state is guarded by the state lock. This lock is a
561read/write semaphore. The reader part can be used to ensure that the state
562does not change while functions depending on the state to stay the same
563(e.g. |ssam_notifier_register|, |ssam_notifier_unregister|,
564|ssam_request_sync_submit|, and derivatives) are executed and this guarantee
565is not already provided otherwise (e.g. through |ssam_client_bind| or
566|ssam_client_link|). The writer part guards any transitions that will change
567the state, i.e. initialization, destruction, suspension, and resumption.
568
569The controller state may be accessed (read-only) outside the state lock for
570smoke-testing against invalid API usage (e.g. in |ssam_request_sync_submit|).
571Note that such checks are not supposed to (and will not) protect against all
572invalid usages, but rather aim to help catch them. In those cases, proper
573variable access is ensured by employing ``WRITE_ONCE()`` and ``READ_ONCE()``.
574
575Assuming any preconditions on the state not changing have been satisfied,
576all non-initialization and non-shutdown functions may run concurrently with
577each other. This includes |ssam_notifier_register|, |ssam_notifier_unregister|,
578|ssam_request_sync_submit|, as well as all functions building on top of those.
579