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 -------
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
142 * ``SSH_PACKET_SF_COMPLETED_BIT``: This bit is set by the process running the
153 ------------
163 re-submitted to this queue due to timeouts or NAK packets sent by the EC.
166 -----------
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 ------------------
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 ---------------
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
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
243 transport layer is always guaranteed to make progress, if only through
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
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
331 callback running on the receiver thread). If the request is completed with
346 * ``SSH_REQUEST_SF_COMPLETED_BIT``: This bit is set by the process running the
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
434 acknowledgment timeouts, guarantees that the request layer will always make
438 -----------------------
452 ensured by employing ``WRITE_ONCE()`` and ``READ_ONCE()``. Such read-only
457 shutdown (|ssh_rtl_shutdown|) may always be executed concurrently with
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
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
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
540 installed in the request layer (running on the receiver thread of the packet
543 queue (running on the completion workqueue) will pick up the event and
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