[processor-sdk/pdk.git] / packages / ti / drv / sciclient / soc / sysfw / binaries / system-firmware-public-documentation / _sources / 3_boardcfg / BOARDCFG_PM.rst.txt
1 =======================================
2 Power Management Board Configuration
3 =======================================
5 .. _pub_boardcfg_pm_intro:
7 Introduction
8 ============
10 The PM board configuration message initializes the PM subsystem.
11 The PM subsystem is not considered functional until after the PM board
12 configuration message is received by DMSC. The PM board configuration data can
13 be sent any time after the standard boardcfg message (:ref:`pub_boardcfg_cfg`)
14 is received.
16 The system remains in ROM configured PLL and clock configuration till this
17 message is invoked. On invoking this call, the OFC associated with the
18 SoC is configured. This implies that many of PLLs and clock tree will
19 get reconfigured. The OFC settings set by the PM board configuration is as given in
20 :doc:`../5_soc_doc/am6x/pll_data`. Since the device is capable of deriving the
21 clock from different supported input HFOSC frequencies, |sysfw| reads the DEVSTAT
22 to identify the HFOSC frequency and programs the PLLs and Dividers according to the
23 input HFOSC to derive the Original Frequency Combination (OFC). The OFC is a fixed
24 table built into the DMSC |sysfw|. This is derived from silicon characterization
25 data. The user is expected to ensure the device is first configured to this OFC
26 frequency and then tweak specific device clock frequencies based on their usecase
27 needs by using the PM messages for :ref:`TISCI_MSG_SET_FREQ <pm_clocks_msg_set_freq>`
28 and :ref:`TISCI_MSG_SET_CLOCK_PARENT <pm_clocks_msg_set_clock_parent>`.
30 It is strongly recommended for proper care to be taken for key peripherals
31 that may be operational and communicating external to SoC. For example,
32 depending on the SoC and product, pinmux can be used to move the IP's pins
33 into isolation to prevent glitch events from being exported from the IP at
34 the point of reconfiguration of PLLs system wide to the official OFC
35 configuration.
37 Device Groups for Power Management Board Configuration
38 ---------------------------------------------------------
40 The PM board configuration TISCI message allows the user to specify the DEVGRP
41 under which the PM subsystem operates. A specified DEVGRP defines which PM
42 driver instances are capable of usage by the host applications. The host
43 application can implement PM subsystem DEVGRP usage by sending a
44 :ref:`TISCI_MSG_PM_BOARD_CONFIG_PM <pub_boardcfg_pm_tisci>` message with the
45 boardcfg_pm_devgrp parameter populated with one or more SoC-specific device
46 group values. The DEVGRP value specifying whole device is mapped to zero so
47 existing PM board configurations not explicitly defining a DEVGRP for the
48 boardcfg_pm_devgrp parameter will be backwards compatible.
50 DEVGRPS are cumulative so if multiple PM board configurations are received,
51 each with a unique DEVGRP defined, all received DEVGRPs will be active. To
52 support accumulation of DEVGRPs the PM board configuration message can be sent
53 any number of times.
55 .. _pub_boardcfg_pm_tisci:
57 TISCI API for Power Management Board Config
58 -------------------------------------------
60 The following are the parameters required in the TI-SCI message to pass power management
61 board configuration data to DMSC after DMSC sends boot notification complete.
62 The PM board configuration message is not dependent on receipt of the
63 standard board configuration message.
65 Usage
66 ^^^^^
68 +------------------------+--------+
69 | **Message Type** | Normal |
70 +------------------------+--------+
71 | **Secure Queue Only?** | No |
72 +------------------------+--------+
74 TISCI Message ID
75 ^^^^^^^^^^^^^^^^
77 .. sysfwapimacro:: TISCI_MSG_BOARD_CONFIG_PM
79 Message Data Structures
80 ^^^^^^^^^^^^^^^^^^^^^^^
82 .. sysfwapistruct:: tisci_msg_board_config_pm_req
84 .. sysfwapistruct:: tisci_msg_board_config_pm_resp
86 .. _pub_boardcfg_pm:
88 boardcfg_pm structure
89 ---------------------
91 This is a fixed size c-structure which both defines the format of the
92 configuration as well as reserves DMSC memory to store the configuration.
93 However, the boardcfg_pm data structure is **currently empty**.
95 .. warning::
97 Although currently empty, in order to properly initialize the PM subsystem
98 this message must still be sent with the address and size parameters all
99 configured to 0.
102 .. note::
104 Although currently empty, PM Board configuration requires to be signed and
105 encrypted on HS devices to ensure authenticity and protect secrets. Please
106 refer to :doc:`../6_topic_user_guides/hs_boardcfg_signing` on how to sign and
107 encrypt board configuration on HS devices.
109 Power Management Initialization after receiving board configuration
110 ===================================================================
112 Once the PM board configuration message is received by the System Firmware, it
113 performs the following operations:
115 Board Configuration Receive and Validate
116 ----------------------------------------
118 The first step after receiving the board configuration by the
119 tisci_msg_board_config_pm_handler is to identify which DEVGRP the message is for.
121 .. image:: ../img/tisci-boardcfg/PM_BRD_CFG_2.JPG
123 PM Initialization - DMSC Init
124 -----------------------------
126 The next step of the tisci_msg_board_config_pm_handler is to perform the PM
127 initialization. This involves multiple steps starting with DMSC initialization.
128 The DMSC initialization involves unlocking the WKUP and MAIN CTRL MMRs. This is
129 SoC specific.
131 .. image:: ../img/tisci-boardcfg/PM_BRD_CFG_3.JPG
133 PM Initialization - Clock Init
134 ------------------------------
136 The next step of the tisci_msg_board_config_pm_handler is to perform the clock
137 initialization. As part of this step the code initializes the PLLs and dividers
138 as per the OFC for the input device group. The UART is re-initialized after the
139 PLL is locked. The software reference counts for the clocks initialized at power
140 up is updated.
142 The Clock init initialization sequence is as below:
144 .. image:: ../img/tisci-boardcfg/PM_BRD_CFG_4.JPG
146 PM Initialization - Device Init
147 -------------------------------
149 The next step of the tisci_msg_board_config_pm_handler is to perform the device
150 initialization. As part of this step the code loops through all the devices in the
151 devgrp. For each device the PSC connection is verified and the current state of
152 the device PSC is captured. The module clock default flags are initialized in this
153 function. After this the API clears the software state of the modules and clocks
154 enabled at power up.
156 The Device init initialization sequence is as below:
158 .. image:: ../img/tisci-boardcfg/PM_BRD_CFG_5.JPG
160 PM Initialization - Clock Messages Init
161 ---------------------------------------
163 The next step of the tisci_msg_board_config_pm_handler is to
164 register the software handler for the
166 - :ref:`TISCI_MSG_SET_CLOCK <pm_clocks_msg_set_clock>` message
167 - :ref:`TISCI_MSG_GET_CLOCK <pm_clocks_msg_get_clock>` message
168 - :ref:`TISCI_MSG_SET_CLOCK_PARENT <pm_clocks_msg_set_clock_parent>` message
169 - :ref:`TISCI_MSG_GET_CLOCK_PARENT <pm_clocks_msg_get_clock_parent>` message
170 - :ref:`TISCI_MSG_GET_NUM_CLOCK_PARENTS <pm_clocks_msg_get_num_clock_parents>` message
171 - :ref:`TISCI_MSG_SET_FREQ <pm_clocks_msg_set_freq>` message
172 - :ref:`TISCI_MSG_QUERY_FREQ <pm_clocks_msg_query_freq>` message
173 - :ref:`TISCI_MSG_GET_FREQ <pm_clocks_msg_get_freq>` message
175 .. image:: ../img/tisci-boardcfg/PM_BRD_CFG_6.JPG
177 PM Initialization - Device Messages Init
178 ----------------------------------------
180 The next step of the tisci_msg_board_config_pm_handler is to
181 register the software handler for the
183 - :ref:`TISCI_MSG_SET_DEVICE <pm_devices_msg_set_device>` message
184 - :ref:`TISCI_MSG_GET_DEVICE <pm_devices_msg_get_device>` message
185 - :ref:`TISCI_MSG_SET_DEVICE_RESETS <pm_devices_msg_set_device_resets>` message
187 .. image:: ../img/tisci-boardcfg/PM_BRD_CFG_7.JPG
189 PM Initialization - Core Messages Init
190 --------------------------------------
192 The next step of the tisci_msg_board_config_pm_handler is to
193 register the software handler for the
195 - :ref:`TISCI_MSG_SYS_RESET <pm_sysreset_msg_sys_reset>` message
197 .. image:: ../img/tisci-boardcfg/PM_BRD_CFG_8.JPG
199 OSAL PM Subsystem Init
200 ----------------------
202 The UART clock dividers are re-programmed to make sure the UART logging function
203 is still available from the system firmware after the PLLs are re-initialized.
205 This is the last step in tisci_msg_board_config_pm_handler where the software
206 state is updated to reflect the power management is initialized and now
207 can accept power management messages.
209 After this step the host response is sent. If for any reason any of the above
210 steps fail the API would return with a NACK.
212 .. image:: ../img/tisci-boardcfg/PM_BRD_CFG_9.JPG