1\ingroup GroupModules Modules
2\defgroup GroupDebug Debug HAL
3
4# DEBUG Module Architecture            {#module_debug_architecture_architecture}
5
6## Overview                                {#module_debug_architecture_overview}
7
8This module implements a Hardware Abstraction Layer (HAL) API for SCMI
9transactions targeting the DEBUG power domain.
10
11The DEBUG module provides an interface for modules to get and set the required
12status of the entire hardware debug infrastructure that can be available on a
13platform when it is required to perform a set of operations other than a
14simple power domain state change.
15
16The DEBUG module defines a driver interface on which it relies to get and set
17the power status of the debug system. It also provides a mechanism to allow the
18driver to submit requests to the HAL to enable/disable the debug system. This
19can be useful when an external device connected to the platform, such as a
20debugger, requires the debug infrastructure available to be functional.
21
22All the platform-specific operations can be implemented in the driver.
23
24The DEBUG module follows the deferred response architecture to deal with
25asynchronous drivers.
26
27### DEBUG software architecture            {#module_debug_software_architecture}
28
29The following diagram shows the software architecture. The left side is
30without the debug module whereas right side is with the debug module.
31
32Power domain module is sufficient in simple cases such as simply
33enabling/disabling DBGSYS power domain. However for platform specific needs,
34debug module can be plugged in.
35
36
37          standard - w/o debug   |    with debug module and debug driver
38                                 |
39              +------------+     |           +------------+
40              |    SCMI    |     |           |   SCMI     |
41              +------------+     |           +------------+
42                                 |
43                                 |
44              +------------+     |           +------------+
45              |  SCMI_PD   |     |           |  SCMI_PD   |
46              +------------+     |           +------------+
47                                 |
48                                 |
49              +------------+     |           +------------+
50              |    PD      |     |           |   DEBUG    |
51              +------------+     |           +------------+
52                                 |
53                                 |                                --+
54              +------------+     |           +------------+         |
55              |   DRIVER   |     |           |DEBUG-DRIVER|         |  platform
56              +------------+     |           +------------+         |  specific
57                                 |                                --+
58                                 |
59                                 |   +-----------+  +-----------+
60                                 |   | MODULE A  |  | MODULE B  |
61                                 |   +-----------+  +-----------+
62                                 |
63
64In the right-hand side case, the debug module offers a separation between the
65scmi_power_domain module and other HALs that will be used to fulfill the
66platform's needs. The debug driver will then contain all the logic without
67affecting core modules.
68
69### DEBUG asynchronous operations                {#module_debug_async_operation}
70
71The debug module follows the deferred response architecture. The driver can be
72either asynchronous or synchronous. There is only a minimal difference compared
73to the standard architecture. This is basically to keep the implementation of
74debug module compact.
75Specifically, when the DEBUG module processes the request event, it will not
76submit and defer the response event in case the original request came from the
77driver.
78The driver will then inform the HAL via the drv_resp api, and the HAL
79won't take any further action, but updating its internal state.
80
81                        DEBUG                   DEBUG-DRIVER
82                          ~                          ~
83                          |                          |
84                          |                          |
85            EV  >>>>>>>>+-+-+                        |
86                        |   |     set_enabled        |
87                        |   +--------------------->+-+-+
88                        |   |                      |   +-----+
89                        |   |                      |   |     |
90                        |   |          PENDING     |   +<----+ ev
91                        |   +<---------------------+-+-+
92                        |   |                        |
93                        +-+-+                        |
94                          |                          |
95                          |                          |
96                        +-+-+    drv_rsp           +-+-+<------ ISR/ev
97                        |   +<---------------------+   |
98                        |   |                      |   |
99                        |   +--------------------->+   |
100                        +-+-+                      |   |
101                          |                        +-+-+
102                          |                          |
103                          ~                          ~
104
105
106    LEGEND
107    EV           : The module processes the request event originated by the
108                   driver through the driver_input_api
109    ev           : (optional) A driver may internally generate an event to
110                   process later the request
111    ISR/ev       : Either and ISR or an event will cause the driver to call
112                   the driver_response api.
113    drv_rsp      : driver_response api.
114    PENDING      : The call returns with the FWK_PENDING status code
115    set_enabled  : A request to the driver
116    ----->       : Direct call/return API
117    >>>>>>       : Asynchronous call via the event interface
118
119
120### DEBUG set/get operations                   {#module_debug_set_get_operation}
121
122The DEBUG module offers two ways to submit requests for enable/disable the
123implemented features. The first is through its module API and the second is
124via the driver_input api.
125The following diagrams shows the latter case where the driver will forward the
126request coming from the hardware to the HAL. This mechanism ensures that the
127asynchronous support can be preserved.
128
129                        DEBUG                   DEBUG-DRIVER
130                          ~                          ~
131                          |                          |
132                          |                        +-+-+<----- ISR-PWR-UP
133                          |      enable_request    |   |
134                        +-+-+<---------------------+   |
135                        |   |                      |   |
136                        |   +-----+                |   |
137                        |   |     |                |   |
138                        |   +<----+ req_drv        |   |
139                        |   |                      |   |
140                        +-+-+--------------------->+   |
141                          |                        |   |
142                          |                        +-+-+
143                          |                          |
144                          ~                          ~
145
146    LEGEND
147    ISR-PWR-UP     : An interrupt is raised from the platform and the driver
148                     acts
149    enable_request : The driver calls the driver_input api to request the HAL
150                     to enable the debug features
151    req_drv        : The HAL generates the request_event
152    ----->         : Direct call/return API
153