driver-api/surface_aggregator/internal.rst

1 .. SPDX-License-Identifier: GPL-2.0+
49 and Surface Serial Hub (SSH) driver. For the API documentation, refer to:
54    internal-api
63 Lower-level packet transport is implemented in the *packet transport layer
68 packet payloads to higher-level layers.
71 around command-type packet payloads, i.e. requests (sent from host to EC),
79 workqueue for event and asynchronous request completion, and also manages
80 the message counters required for building command messages (``SEQ``,
82 EC for use in other kernel drivers.
84 While the controller layer already provides an interface for other kernel
85 drivers, the client *bus* extends this interface to provide support for
90 Refer to Documentation/driver-api/surface_aggregator/client.rst for
92 for other kernel drivers. It is recommended to familiarize oneself with
93 that chapter and the Documentation/driver-api/surface_aggregator/ssh.rst
104 -------
116 contains an internal reference count, which is used for managing its
127 always guaranteed to be executed before the ``release()`` callback, i.e. the
128 packet will always be completed, either successfully, with an error, or due
139   responsible for removing any references to this packet from the packet
153 ------------
158 (minor). See |SSH_PACKET_PRIORITY| for more details on the priority value.
163 re-submitted to this queue due to timeouts or NAK packets sent by the EC.
166 -----------
170 been transmitted, but wait for acknowledgment (e.g. the corresponding ACK
174 re-submitted due to a packet acknowledgment timeout or NAK. On such a
175 re-submission, packets are not removed from the pending set.
178 ------------------
180 The transmitter thread is responsible for most of the actual work regarding
181 packet transmission. In each iteration, it (waits for and) checks if the
183 from the queue and increments its counter for the number of transmission
184 attempts, i.e. tries. If the packet is sequenced, i.e. requires an ACK by
189 unsequenced, i.e. does not require an ACK by the EC, the packet is completed
193 pending packets, i.e. a limit on how many packets may be waiting for an ACK
195 Documentation/driver-api/surface_aggregator/ssh.rst for the reasoning behind
196 this). Control packets (i.e. ACK and NAK) can always be transmitted.
199 ---------------
201 Any data received from the EC is put into a FIFO buffer for further
204 corresponding payload. It prepares and submits the necessary ACK (and on
205 validation error or invalid data NAK) packets for the received messages.
207 This thread also handles further processing, such as matching ACK messages
209 well as initiating re-submission of all currently pending packets on
210 receival of a NAK message (re-submission in case of a NAK is similar to
211 re-submission due to timeout, see below for more details on that). Note that
212 the successful completion of a sequenced packet will always run on the
213 receiver thread (whereas any failure-indicating completion will run on the
220 --------------
222 The packet acknowledgment timeout is a per-packet timeout for sequenced
223 packets, started when the respective packet begins (re-)transmission (i.e.
225 thread). It is used to trigger re-submission or, when the number of tries
229 work item (re-)scheduled to run when the next packet is set to time out. The
230 work item then checks the set of pending packets for any packets that have
231 exceeded the timeout and, if there are any remaining packets, re-schedules
235 re-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
239 timeout for the packet will be disabled until the next transmission attempt
243 transport layer is always guaranteed to make progress, if only through
247 -----------------------
272 setting ``ptl`` is equally guarded with ``WRITE_ONCE()`` for symmetry.
275 them, specifically priority and state for tracing. In those cases, proper
277 read-only access is only allowed when stale values are not critical.
279 With respect to the interface for higher layers, packet submission
281 (|ssh_ptl_rx_rcvbuf|), and layer shutdown (|ssh_ptl_shutdown|) may always be
283 submission may not run concurrently with itself for the same packet.
301 -------
303 Requests are packets with a command-type payload, sent from host to EC to
307 all top-level representations, e.g. |ssam_request_sync| are built upon this
317 message with command-type payload (from EC to host). The party constructing
320 can wait for this response.
325 layer via |ssh_rtl_submit|. For a request without a response, successful
328 completion callback). For a request with response, successful completion
330 via its request ID (which happens on the packet layer's data-received
343   responsible for removing any references to this request from the request
357 -------------
366 not be re-submitted, and will not be re-submitted automatically on timeout.
368 caller can create and submit a new request for another try, but it must not
372 -----------
377 pending set of the packet transport layer does for packets).
380 ----------------
382 The transmitter task is scheduled when a new request is available for
386 requests can be pending, i.e. waiting for a response, at the same time. If
391 --------------------------
403 Data-Received Callback
404 ----------------------
407 being received by the underlying packet transport layer via a data-type
408 frame. In general, this is expected to be a command-type payload.
410 If the request ID of the command is one of the request IDs reserved for
418 --------------
420 The request-response-timeout is a per-request timeout for requests expecting
421 a response. It is used to ensure that a request does not wait indefinitely
427 essentially a work-item (re-)scheduled to run when the next request is set
428 to time out. The work item then scans the set of pending requests for any
429 requests that have timed out and completes them with ``-ETIMEDOUT`` as
430 status. Requests will not be re-submitted automatically. Instead, the issuer
434 acknowledgment timeouts, guarantees that the request layer will always make
438 -----------------------
451 them, specifically the state for tracing. In those cases, proper access is
452 ensured by employing ``WRITE_ONCE()`` and ``READ_ONCE()``. Such read-only
455 With respect to the interface for higher layers, request submission
457 shutdown (|ssh_rtl_shutdown|) may always be executed concurrently with
459 with itself for the same request (and also may only be called once per
467 easy-to-use interface for client drivers. It is represented by
475 ------------------
479 be the exception). This is done via an event-enable request (similarly,
480 events should be disabled via an event-disable request once no longer
493 Note that a further *request ID* parameter must be provided for the
494 enable-event request. This parameter does not influence the class of events
497 number of request IDs is reserved for use in events only, specifically one
499 class. Currently, the controller always sets this parameter to the target
505 counting, storing the counter inside an RB-tree based mapping with event
508 |ssam_nf_refcount_dec| for details.
511 the next section) via the top-level |ssam_notifier_register| and
515 --------------
518 |ssam_notifier_register|. This increments the reference counter for that
532 for them. Specifically, they will, by default, receive all events from the
538 All notifier callbacks are executed on a dedicated workqueue, the so-called
548 This is done to ensure that notifier callbacks are executed in sequence for
550 in parallel for events with a different combination of target ID and target
554 -----------------------
557 provided by the lower-level request transport layer. In addition to this,
558 event (un-)registration is guarded by its own lock.
569 The controller state may be accessed (read-only) outside the state lock for
570 smoke-testing against invalid API usage (e.g. in |ssam_request_sync_submit|).
576 all non-initialization and non-shutdown functions may run concurrently with