driver-api/surface_aggregator/internal.rst

1 .. SPDX-License-Identifier: GPL-2.0+
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),
90 Refer to Documentation/driver-api/surface_aggregator/client.rst for
93 that chapter and the Documentation/driver-api/surface_aggregator/ssh.rst
104 -------
153 ------------
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 ------------------
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 ---------------
204 corresponding payload. It prepares and submits the necessary ACK (and on
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
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
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
247 -----------------------
277 read-only access is only allowed when stale values are not critical.
281 (|ssh_ptl_rx_rcvbuf|), and layer shutdown (|ssh_ptl_shutdown|) may always be
284 Equally, shutdown and data receival may also not run concurrently with
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
330 via its request ID (which happens on the packet layer's data-received
357 -------------
366 not be re-submitted, and will not be re-submitted automatically on timeout.
372 -----------
380 ----------------
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.
418 --------------
420 The request-response-timeout is a per-request timeout for requests expecting
427 essentially a work-item (re-)scheduled to run when the next request is set
429 requests that have timed out and completes them with ``-ETIMEDOUT`` as
430 status. Requests will not be re-submitted automatically. Instead, the issuer
438 -----------------------
452 ensured by employing ``WRITE_ONCE()`` and ``READ_ONCE()``. Such read-only
457 shutdown (|ssh_rtl_shutdown|) may always be executed concurrently with
460 request). Equally, shutdown may also not run concurrently with itself.
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
494 enable-event request. This parameter does not influence the class of events
505 counting, storing the counter inside an RB-tree based mapping with event
511 the next section) via the top-level |ssam_notifier_register| and
515 --------------
538 All notifier callbacks are executed on a dedicated workqueue, the so-called
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