1Deferred Response Architecture
2==============================
3
4# Overview                            {#deferred_response_architecture_overview}
5
6This document describes at high level the typical interactions between the
7following actors:
8- A client requesting some data/operations from a module.
9- A HAL module defining an interface to request operations.
10- A driver interacting with the hardware and bound to the HAL.
11This document particularly focuses on the interactions when the requests are
12deferred and thus acknowledged as pending.
13
14# Architecture                    {#deferred_response_architecture_architecture}
15
16## Client-HAL Interaction           {#deferred_response_architecture_client_hal}
17
18A call to an HAL API can be handled asynchronously by the HAL module. The call
19to the HAL API returns with one of the following status code:
20- FWK_SUCCESS: the requested operation has completed. The data requested, if
21any, is available.
22- FWK_PENDING: the call has been acknowledged and the response to the request
23will be sent subsequently via a *HAL_module_event_id_request* response event.
24In this case, the client must handle the response event.
25- FWK_E_X: the request failed.
26
27## Driver-HAL Interaction           {#deferred_response_architecture_driver_hal}
28
29When the HAL calls the driver, it acts in different manners depending on the
30status returned by the driver:
31- FWK_SUCCESS: the driver has successfully completed the request and the
32value/operation has completed immediately. The HAL returns the data, if any, to
33the client.
34- FWK_PENDING: the driver has deferred the requested operation and will provide
35the response later through the *driver_response_api*. In this case, the HAL
36sends an *HAL_module_event_id_request* event to itself, the response of which
37will be sent to the client when the operation will be completed.
38- FWK_E_X: the request failed.
39
40## Note                                   {#deferred_response_architecture_note}
41
42A call to an HAL API is done as part of the processing of an event by a given
43entity and, when processing pending requests, this entity is the target of the
44response event. In order for the client to receive the response event, the
45client is required to call the HAL API within the context of processing an event
46targeting itself. In other words, the caller may be required to send an event
47targeting itself first and then call the HAL module when processing such event.
48
49# Flow                                    {#deferred_response_architecture_flow}
50
51Below is a typical execution flow for a call to the HAL when the driver defers
52the requested operation.
53
54       Client            HAL Module           Driver           Driver ISR
55
56          |                  |                  |                  |
57          |                  |                  |                  |
58         +++     get/set     |                  |                  |
59         | +--------------->+++                 |                  |
60         | |                | |     get/set     |                  |
61         | |                | +--------------->+++                 |
62         | |                | |                | |                 |
63         | |                | +<---------------+++                 |
64         | |                | |       PENDING   |                  |
65         | |                | +-----+           |                  |
66         | |                | |     |           |                  |
67         | |                | +<----+ PE1       |                  |
68         | |                | |                 |                  |
69         | +<---------------+++                 |                  |
70         +++        PENDING  |                  |                  |
71          |                  |                  |                  |
72          |         E1>>>>>>+++                 |                  |
73          |                 | |                 |                  |
74          |                 +++                 |                  |
75          |                  |                  |    DRV_RESP     +++
76          |                 +++<----------------------------------+ |
77          |                 | |                 |                 | |
78          |                 | +-----+           |                 | |
79          |                 | |     |           |                 | |
80          |                 | +<----+ PE2       |                 | |
81          |                 | |                 |                 | |
82          |                 +++---------------------------------->+ |
83          |                  |                  |                 +++
84          |                  |                  |                  |
85          |         E2>>>>>>+++                 |                  |
86          |                 | +-----+           |                  |
87          |                 | |     |           |                  |
88          |                 | +<----+ PE3       |                  |
89          |                 +++                 |                  |
90          |                  |                  |                  |
91         +++<<<<<<RE         |                  |                  |
92         | |                 |                  |                  |
93         | |                 |                  |                  |
94         +++                 |                  |                  |
95          |                  |                  |                  |
96
97    LEGEND
98    get/set  : A request to the HAL interface
99    PENDING  : The call returns with the FWK_PENDING status code
100    PEx      : An event is sent (put_event)
101    E1       : Processing event E1 (request event)
102    DRV_RESP : driver_response_api
103    E2       : Processing event E2 (request complete event)
104    RE       : Processing the response event
105    ----->   : Direct call/return API
106    >>>>>>   : Asynchronous call via the event interface
107
108    EVENTS CORRESPONDENCE
109    PE1 > > > E1
110    PE2 > > > E2
111    PE3 > > > RE
112
113A client calls *get/set* HAL module API which directly calls the driver.
114
115The driver cannot do the operation immediately, it returns FWK_PENDING.
116
117The HAL module sends a *REQUEST* event (PE1) to itself and returns FWK_PENDING
118to the client. The request event contains all the information needed for the
119deferred response.
120
121The HAL receives and processes the *REQUEST* event E1, and it stores the event's
122cookie and delays its response.
123
124When the requested *get/set* operation is completed, the driver calls the
125*driver_response_api* providing the result of operation.
126In this call, the driver sends a *REQUEST_COMPLETE* event (PE2) for the HAL
127to defer post-processing and to provide the result of the operation.
128
129Then, the HAL module receives and processes the *REQUEST_COMPLETE* event E2,
130retrieving the result of the operation from the event E2's parameters. At the
131same time the HAL get back the response event that was delayed, and sends the
132event (PE3) containing the result of the operation.
133
134Finally, the client receives and processes the *HAL_module_event_id_request*
135response event RE sent by the HAL module.
136