Lines Matching full:and
49 and Surface Serial Hub (SSH) driver. For the API documentation, refer to:
66 the packet transport logic and handles things like packet validation, packet
67 acknowledgment (ACKing), packet (retransmission) timeouts, and relaying
72 responses of the EC to those requests, and events (sent from EC to host).
74 responses to their corresponding requests, and implements request timeouts.
76 The *controller* layer is building on top of this and essentially decides
77 how request responses and, especially, events are dealt with. It provides an
79 workqueue for event and asynchronous request completion, and also manages
86 native SSAM devices, i.e. devices that are not defined in ACPI and not
87 implemented as platform devices, via |ssam_device| and |ssam_device_driver|
88 simplify management of client devices and client drivers.
91 documentation regarding the client device/driver API and interface options
93 that chapter and the Documentation/driver-api/surface_aggregator/ssh.rst
100 The packet transport layer is represented via |ssh_ptl| and is structured
108 of the driver and is built upon by other components of the SSAM core.
111 structure and are managed entirely via the raw |ssh_frame|).
117 lifetime (accessible via |ssh_packet_get| and |ssh_packet_put|). When this
124 completed and provides the status of this completion, i.e. zero on success
137 references of the packet should be taken and any existing references
140 queue and pending set.
143 ``complete()`` callback and is used to ensure that this callback only runs
147 the packet queue and cleared when it is dequeued.
150 the pending set and cleared when it is removed from it.
157 respective packets based on the packet type (major) and number of tries
173 Note that a packet may both be pending and queued if it has been
181 packet transmission. In each iteration, it (waits for and) checks if the
182 next packet on the queue (if any) can be transmitted and, if so, removes it
183 from the queue and increments its counter for the number of transmission
196 this). Control packets (i.e. ACK and NAK) can always be transmitted.
203 thread parses and validates the received message into its |ssh_frame| and
204 corresponding payload. It prepares and submits the necessary ACK (and on
208 to the corresponding pending packet (via sequence ID) and completing it, as
231 exceeded the timeout and, if there are any remaining packets, re-schedules
236 ``-ETIMEDOUT`` as status if not. Note that re-submission, in this case and
240 and the packet remains on the pending set.
242 Note that due to transmission and packet acknowledgment timeouts, the packet
244 timing out packets, and will never fully block.
246 Concurrency and Locking
250 to the packet queue and one guarding access to the pending set. These
251 collections may only be accessed and modified under the respective lock. If
258 queue lock and the packet timestamp must only be accessed while holding the
262 flags are managed by atomic bit operations and, if necessary, memory
263 barriers. Modifications to the timeout reaper work item and expiration date
275 them, specifically priority and state for tracing. In those cases, proper
276 access is ensured by employing ``WRITE_ONCE()`` and ``READ_ONCE()``. Such
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
291 The request transport layer is represented via |ssh_rtl| and builds on top
312 |ssh_request_get| and |ssh_request_put|). Once the counter reaches zero, the
318 the request must know if a response is expected and mark this in the request
323 provided via its request ops reference and is guaranteed to be completed
329 will occur once the response has been received and matched to the request
341 references of the request should be taken and any existing references
344 queue and pending set.
347 ``complete()`` callback and is used to ensure that this callback only runs
351 the request queue and cleared when it is dequeued.
354 the pending set and cleared when it is removed from it.
361 transport layer, it is not a priority queue and the simple first come first
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
384 transmitted and, if so, submits its underlying packet to the packet
399 If the request expects a response, it is marked as transmitted and the
414 the pending set and, if found and marked as transmitted, completed with
422 on a response from the EC and is started after the underlying packet has
429 requests that have timed out and completes them with ``-ETIMEDOUT`` as
431 of the request must construct and submit a new request, if so desired.
433 Note that this timeout, in combination with packet transmission and
435 progress, even if only through timing out packets, and never fully block.
437 Concurrency and Locking
441 request transport layer: One guarding access to the request queue and one
443 and modified under the respective lock.
446 flags are (again) managed by atomic bit operations and, if necessary, memory
447 barriers. Modifications to the timeout reaper work item and expiration date
452 ensured by employing ``WRITE_ONCE()`` and ``READ_ONCE()``. Such read-only
456 (|ssh_rtl_submit|), request cancellation (|ssh_rtl_cancel|), and layer
459 with itself for the same request (and also may only be called once per
468 |ssam_controller| and the SSH driver. While the lower level transport layers
469 take care of transmitting and handling packets and requests, the controller
471 initialization, power management, and event handling, including event
472 delivery and registration via the (event) completion system (|ssam_cplt|).
486 target category and, depending on the event registry, instance ID of the
488 zero if the registry does not use it. Together, target category and instance
490 registry and event ID, are required to uniquely identify a respective class
498 to ``SSH_NUM_EVENTS`` inclusively) and also map events to their specific
503 events and enable/disable calls are strictly binary (i.e. on/off), the
506 registry and ID as key (there is no known list of valid event registry and
507 event ID combinations). See |ssam_nf|, |ssam_nf_refcount_inc|, and
511 the next section) via the top-level |ssam_notifier_register| and
520 class on the EC (if it has not been enabled already), and installs the
526 event registry and event ID to the command data (target ID, target category,
527 command ID, and instance ID) that can be provided by an event class, apart
528 from target category and instance ID given via the event ID.
531 drivers may receive events that they have not requested and need to account
534 target ID (provided via the event registry) and instance ID (provided via
543 queue (running on the completion workqueue) will pick up the event and
547 There is one event queue per combination of target ID and target category.
549 events of the same target ID and target category. Callbacks can be executed
550 in parallel for events with a different combination of target ID and target
553 Concurrency and Locking
564 |ssam_request_sync_submit|, and derivatives) are executed and this guarantee
567 the state, i.e. initialization, destruction, suspension, and resumption.
571 Note that such checks are not supposed to (and will not) protect against all
573 variable access is ensured by employing ``WRITE_ONCE()`` and ``READ_ONCE()``.
576 all non-initialization and non-shutdown functions may run concurrently with