1 /*
2  * Texas Instruments System Control Interface API
3  *   Based on Linux and U-Boot implementation
4  *
5  * Copyright (C) 2018-2022 Texas Instruments Incorporated - https://www.ti.com/
6  *
7  * SPDX-License-Identifier: BSD-3-Clause
8  */
9 
10 #ifndef TI_SCI_H
11 #define TI_SCI_H
12 
13 #include <stdint.h>
14 #include <stdbool.h>
15 
16 /**
17  * Device control operations
18  *
19  * - ti_sci_device_get - command to request for device managed by TISCI
20  * - ti_sci_device_get_exclusive - exclusively request a device
21  * - ti_sci_device_idle - Command to idle a device managed by TISCI
22  * - ti_sci_device_idle_exclusive - exclusively idle a device
23  * - ti_sci_device_put - command to release a device managed by TISCI
24  * - ti_sci_device_put_no_wait - release a device without waiting for response
25  * - ti_sci_device_is_valid - Is the device valid
26  * - ti_sci_device_get_clcnt - Get context loss counter
27  *              @count: Pointer to Context Loss counter to populate
28  * - ti_sci_device_is_idle - Check if the device is requested to be idle
29  *              @r_state: true if requested to be idle
30  * - ti_sci_device_is_stop - Check if the device is requested to be stopped
31  *              @r_state: true if requested to be stopped
32  *              @curr_state: true if currently stopped.
33  * - ti_sci_device_is_on - Check if the device is requested to be ON
34  *              @r_state: true if requested to be ON
35  *              @curr_state: true if currently ON and active
36  * - ti_sci_device_is_trans - Check if the device is currently transitioning
37  *              @curr_state: true if currently transitioning.
38  * - ti_sci_device_set_resets - Command to set resets for
39  *                              device managed by TISCI
40  *              @reset_state: Device specific reset bit field
41  * - ti_sci_device_get_resets - Get reset state for device managed by TISCI
42  *              @reset_state: Pointer to reset state to populate
43  *
44  * NOTE: for all these functions, the following are generic in nature:
45  * @id:		Device Identifier
46  * Returns 0 for successful request, else returns corresponding error message.
47  *
48  * Request for the device - NOTE: the client MUST maintain integrity of
49  * usage count by balancing get_device with put_device. No refcounting is
50  * managed by driver for that purpose.
51  */
52 int ti_sci_device_get(uint32_t id);
53 int ti_sci_device_get_exclusive(uint32_t id);
54 int ti_sci_device_idle(uint32_t id);
55 int ti_sci_device_idle_exclusive(uint32_t id);
56 int ti_sci_device_put(uint32_t id);
57 int ti_sci_device_put_no_wait(uint32_t id);
58 int ti_sci_device_is_valid(uint32_t id);
59 int ti_sci_device_get_clcnt(uint32_t id, uint32_t *count);
60 int ti_sci_device_is_idle(uint32_t id, bool *r_state);
61 int ti_sci_device_is_stop(uint32_t id, bool *r_state,  bool *curr_state);
62 int ti_sci_device_is_on(uint32_t id, bool *r_state,  bool *curr_state);
63 int ti_sci_device_is_trans(uint32_t id, bool *curr_state);
64 int ti_sci_device_set_resets(uint32_t id, uint32_t reset_state);
65 int ti_sci_device_get_resets(uint32_t id, uint32_t *reset_state);
66 
67 /**
68  * Clock control operations
69  *
70  * - ti_sci_clock_get - Get control of a clock from TI SCI
71  *              @needs_ssc: 'true' iff Spread Spectrum clock is desired
72  *              @can_change_freq: 'true' iff frequency change is desired
73  *              @enable_input_term: 'true' iff input termination is desired
74  * - ti_sci_clock_idle - Idle a clock which is in our control
75  * - ti_sci_clock_put - Release a clock from our control
76  * - ti_sci_clock_is_auto - Is the clock being auto managed
77  *              @req_state: state indicating if the clock is auto managed
78  * - ti_sci_clock_is_on - Is the clock ON
79  *              @req_state: state indicating if the clock is managed by us and enabled
80  *              @curr_state: state indicating if the clock is ready for operation
81  * - ti_sci_clock_is_off - Is the clock OFF
82  *              @req_state: state indicating if the clock is managed by us and disabled
83  *              @curr_state: state indicating if the clock is NOT ready for operation
84  * - ti_sci_clock_set_parent - Set the clock source of a specific device clock
85  *              @parent_id: Parent clock identifier to set
86  * - ti_sci_clock_get_parent - Get current parent clock source
87  *              @parent_id: Current clock parent
88  * - ti_sci_clock_get_num_parents - Get num parents of the current clk source
89  *              @num_parents: Returns he number of parents to the current clock.
90  * - ti_sci_clock_get_match_freq - Find a good match for frequency
91  *              @match_freq: Frequency match in Hz response.
92  * - ti_sci_clock_set_freq - Set a frequency for clock
93  * - ti_sci_clock_get_freq - Get current frequency
94  *              @freq: Currently frequency in Hz
95  *
96  * NOTE: for all these functions, the following are generic in nature:
97  * @dev_id:	Device identifier this request is for
98  * @clk_id:	Clock identifier for the device for this request.
99  *		Each device has its own set of clock inputs. This indexes
100  *		which clock input to modify.
101  * @min_freq:	The minimum allowable frequency in Hz. This is the minimum
102  *		allowable programmed frequency and does not account for clock
103  *		tolerances and jitter.
104  * @target_freq: The target clock frequency in Hz. A frequency will be
105  *		processed as close to this target frequency as possible.
106  * @max_freq:	The maximum allowable frequency in Hz. This is the maximum
107  *		allowable programmed frequency and does not account for clock
108  *		tolerances and jitter.
109  * Returns 0 for successful request, else returns corresponding error message.
110  *
111  * Request for the clock - NOTE: the client MUST maintain integrity of
112  * usage count by balancing get_clock with put_clock. No refcounting is
113  * managed by driver for that purpose.
114  */
115 int ti_sci_clock_get(uint32_t dev_id, uint8_t clk_id,
116 		     bool needs_ssc, bool can_change_freq,
117 		     bool enable_input_term);
118 int ti_sci_clock_idle(uint32_t dev_id, uint8_t clk_id);
119 int ti_sci_clock_put(uint32_t dev_id, uint8_t clk_id);
120 int ti_sci_clock_is_auto(uint32_t dev_id, uint8_t clk_id,
121 			 bool *req_state);
122 int ti_sci_clock_is_on(uint32_t dev_id, uint8_t clk_id,
123 		       bool *req_state, bool *curr_state);
124 int ti_sci_clock_is_off(uint32_t dev_id, uint8_t clk_id,
125 			bool *req_state, bool *curr_state);
126 int ti_sci_clock_set_parent(uint32_t dev_id, uint8_t clk_id,
127 			    uint8_t parent_id);
128 int ti_sci_clock_get_parent(uint32_t dev_id, uint8_t clk_id,
129 			    uint8_t *parent_id);
130 int ti_sci_clock_get_num_parents(uint32_t dev_id, uint8_t clk_id,
131 				 uint8_t *num_parents);
132 int ti_sci_clock_get_match_freq(uint32_t dev_id, uint8_t clk_id,
133 				uint64_t min_freq, uint64_t target_freq,
134 				uint64_t max_freq, uint64_t *match_freq);
135 int ti_sci_clock_set_freq(uint32_t dev_id, uint8_t clk_id,
136 			  uint64_t min_freq, uint64_t target_freq,
137 			  uint64_t max_freq);
138 int ti_sci_clock_get_freq(uint32_t dev_id, uint8_t clk_id, uint64_t *freq);
139 
140 /**
141  * Core control operations
142  *
143  * - ti_sci_core_reboot() - Command to request system reset
144  *
145  * Return: 0 if all went well, else returns appropriate error value.
146  */
147 int ti_sci_core_reboot(void);
148 
149 /**
150  * Processor control operations
151  *
152  * - ti_sci_proc_request - Command to request a physical processor control
153  * - ti_sci_proc_release - Command to release a physical processor control
154  * - ti_sci_proc_handover - Command to handover a physical processor control to
155  *                          a host in the processor's access control list.
156  *              @host_id: Host ID to get the control of the processor
157  * - ti_sci_proc_set_boot_cfg - Command to set the processor boot configuration flags
158  *              @config_flags_set: Configuration flags to be set
159  *              @config_flags_clear: Configuration flags to be cleared.
160  * - ti_sci_proc_set_boot_ctrl - Command to set the processor boot control flags
161  *              @control_flags_set: Control flags to be set
162  *              @control_flags_clear: Control flags to be cleared
163  * - ti_sci_proc_set_boot_ctrl_no_wait - Same as above without waiting for response
164  * - ti_sci_proc_auth_boot_image - Command to authenticate and load the image
165  *                                 and then set the processor configuration flags.
166  *              @cert_addr: Memory address at which payload image certificate is located.
167  * - ti_sci_proc_get_boot_status - Command to get the processor boot status
168  * - ti_sci_proc_wait_boot_status - Command to wait for a processor boot status
169  * - ti_sci_proc_wait_boot_status_no_wait - Same as above without waiting for response
170  *
171  * NOTE: for all these functions, the following are generic in nature:
172  * @proc_id:	Processor ID
173  * Returns 0 for successful request, else returns corresponding error message.
174  */
175 int ti_sci_proc_request(uint8_t proc_id);
176 int ti_sci_proc_release(uint8_t proc_id);
177 int ti_sci_proc_handover(uint8_t proc_id, uint8_t host_id);
178 int ti_sci_proc_set_boot_cfg(uint8_t proc_id, uint64_t bootvector,
179 			     uint32_t config_flags_set,
180 			     uint32_t config_flags_clear);
181 int ti_sci_proc_set_boot_ctrl(uint8_t proc_id, uint32_t control_flags_set,
182 			      uint32_t control_flags_clear);
183 int ti_sci_proc_set_boot_ctrl_no_wait(uint8_t proc_id,
184 				      uint32_t control_flags_set,
185 				      uint32_t control_flags_clear);
186 int ti_sci_proc_auth_boot_image(uint8_t proc_id, uint64_t cert_addr);
187 int ti_sci_proc_get_boot_status(uint8_t proc_id, uint64_t *bv,
188 				uint32_t *cfg_flags,
189 				uint32_t *ctrl_flags,
190 				uint32_t *sts_flags);
191 int ti_sci_proc_wait_boot_status(uint8_t proc_id, uint8_t num_wait_iterations,
192 				 uint8_t num_match_iterations,
193 				 uint8_t delay_per_iteration_us,
194 				 uint8_t delay_before_iterations_us,
195 				 uint32_t status_flags_1_set_all_wait,
196 				 uint32_t status_flags_1_set_any_wait,
197 				 uint32_t status_flags_1_clr_all_wait,
198 				 uint32_t status_flags_1_clr_any_wait);
199 int ti_sci_proc_wait_boot_status_no_wait(uint8_t proc_id,
200 					 uint8_t num_wait_iterations,
201 					 uint8_t num_match_iterations,
202 					 uint8_t delay_per_iteration_us,
203 					 uint8_t delay_before_iterations_us,
204 					 uint32_t status_flags_1_set_all_wait,
205 					 uint32_t status_flags_1_set_any_wait,
206 					 uint32_t status_flags_1_clr_all_wait,
207 					 uint32_t status_flags_1_clr_any_wait);
208 
209 /**
210  * System Low Power Operations
211  *
212  * - ti_sci_enter_sleep - Command to initiate system transition into suspend.
213  *		@proc_id: Processor ID.
214  *		@mode: Low power mode to enter.
215  *		@core_resume_addr: Address that core should be resumed from
216  *				   after low power transition.
217  *
218  * NOTE: for all these functions, the following are generic in nature:
219  * Returns 0 for successful request, else returns corresponding error message.
220  */
221 int ti_sci_enter_sleep(uint8_t proc_id,
222 		       uint8_t mode,
223 		       uint64_t core_resume_addr);
224 
225 /**
226  * ti_sci_init() - Basic initialization
227  *
228  * Return: 0 if all goes good, else appropriate error message.
229  */
230 int ti_sci_init(void);
231 
232 #endif /* TI_SCI_H */
233