Lines Matching +full:lock +full:- +full:state
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 -------
131 The state of a packet is managed via its ``state`` flags
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
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
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 -----------------------
251 collections may only be accessed and modified under the respective lock. If
252 access to both collections is needed, the pending lock must be acquired
253 before the queue lock to avoid deadlocks.
258 queue lock and the packet timestamp must only be accessed while holding the
259 pending lock.
261 Other parts of the packet transport layer are guarded independently. State
264 are guarded by their own lock.
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.
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
335 The state of a request is again managed via its ``state`` flags
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 -----------------------
443 and modified under the respective lock.
445 Other parts of the request transport layer are guarded independently. State
448 are guarded by their own lock.
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
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.
560 Access to the controller state is guarded by the state lock. This lock is a
561 read/write semaphore. The reader part can be used to ensure that the state
562 does not change while functions depending on the state to stay the same
567 the state, i.e. initialization, destruction, suspension, and resumption.
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|).
575 Assuming any preconditions on the state not changing have been satisfied,
576 all non-initialization and non-shutdown functions may run concurrently with