70 Above this sits the *request transport layer (RTL)*. This layer is centered
73 It, specifically, distinguishes events from request responses, matches
74 responses to their corresponding requests, and implements request timeouts.
77 how request responses and, especially, events are dealt with. It provides an
79 workqueue for event and asynchronous request completion, and also manages
217 the request transport layer.
267 somewhat special. It is either set when the upper layer request is submitted
288 Request Transport Layer
291 The request transport layer is represented via |ssh_rtl| and builds on top
297 the corresponding callback. The request transport layer is structured around
300 Request  section in Request Transport Layer
313 ``release()`` callback of the |ssh_request_ops| reference of the request is
318 the request must know if a response is expected and mark this in the request
319 flags provided to |ssh_request_init|, so that the request transport layer
323 provided via its request ops reference and is guaranteed to be completed
324 before it is released once it has been submitted to the request transport
325 layer via |ssh_rtl_submit|. For a request without a response, successful
328 completion callback). For a request with response, successful completion
329 will occur once the response has been received and matched to the request
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
335 The state of a request is again managed via its ``state`` flags
336 (|ssh_request_flags|), which also encode the request type. In particular,
341   references of the request should be taken and any existing references
343   responsible for removing any references to this request from the request
350 * ``SSH_REQUEST_SF_QUEUED_BIT``: This bit is set when the request is queued on
351   the request queue and cleared when it is dequeued.
353 * ``SSH_REQUEST_SF_PENDING_BIT``: This bit is set when the request is added to
356 Request Queue
359 The request queue is the first of the two fundamental collections in the
360 request transport layer. In contrast to the packet queue of the packet
364 All requests to be transmitted by the request transport layer must be
367 Instead, the request is completed with a timeout error. If desired, the
368 caller can create and submit a new request for another try, but it must not
369 submit the same request again.
375 request transport layer. This collection stores references to all pending
382 The transmitter task is scheduled when a new request is available for
383 transmission. It checks if the next request on the request queue can be
387 the request requires a response, the request is added to the pending set
394 request has been completed. In case of an error completion, the
395 corresponding request is completed with the error value provided in this
398 On successful packet completion, further processing depends on the request.
399 If the request expects a response, it is marked as transmitted and the
400 request timeout is started. If the request does not expect a response, it is
406 The data received callback notifies the request transport layer of data
410 If the request ID of the command is one of the request IDs reserved for
412 event callback registered in the request transport layer. If the request ID
413 indicates a response to a request, the respective request is looked up in
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
431 of the request must construct and submit a new request, if so desired.
434 acknowledgment timeouts, guarantees that the request layer will always make
441 request transport layer: One guarding access to the request queue and one
445 Other parts of the request transport layer are guarded independently. State
450 Some request fields may be read outside of the respective locks guarding
455 With respect to the interface for higher layers, request submission
456 (|ssh_rtl_submit|), request cancellation (|ssh_rtl_cancel|), and layer
458 respect to each other. Note that request submission may not run concurrently
459 with itself for the same request (and also may only be called once per
460 request). Equally, shutdown may also not run concurrently with itself.
466 The controller layer extends on the request transport layer to provide an
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
483 The specific request used to enable (or disable) an event is given via an
485 represented by |ssam_event_registry|. As parameters to this request, the
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
495 being enabled, but instead is set as the request ID (RQID) on each event of
497 number of request IDs is reserved for use in events only, specifically one
540 installed in the request layer (running on the receiver thread of the packet
557 provided by the lower-level request transport layer. In addition to this,