1 /*
2 * Copyright (C) 2017-2019 Texas Instruments Incorporated
3 *
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions
6 * are met:
7 *
8 * Redistributions of source code must retain the above copyright
9 * notice, this list of conditions and the following disclaimer.
10 *
11 * Redistributions in binary form must reproduce the above copyright
12 * notice, this list of conditions and the following disclaimer in the
13 * documentation and/or other materials provided with the
14 * distribution.
15 *
16 * Neither the name of Texas Instruments Incorporated nor the names of
17 * its contributors may be used to endorse or promote products derived
18 * from this software without specific prior written permission.
19 *
20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
21 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
22 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
23 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
24 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
25 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
26 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
27 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
28 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
30 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 *
32 */
33 /**
34 * \ingroup TISCI
35 * \defgroup tisci_pm_clock TISCI Power Management Clock
36 *
37 * DMSC controls the power management, security and resource management
38 * of the device.
39 *
40 *
41 * @{
42 */
43 /**
44 * \file tisci_pm_clock.h
45 *
46 * \brief This file contains:
47 *
48 * WARNING!!: Autogenerated file from SYSFW. DO NOT MODIFY!!
49 * System Firmware
50 *
51 * Cortex-M3 (CM3) firmware for power management
52 *
53 */
54 #ifndef TISCI_PM_TISCI_CLOCK_H
55 #define TISCI_PM_TISCI_CLOCK_H
57 #include <stdint.h>
58 #include <stddef.h>
59 #include <stdbool.h>
60 #include <ti/drv/sciclient/include/tisci/tisci_protocol.h>
62 /**
63 * \anchor Sciclient_PmSetClockMsgState
64 * \name Clock SW state Macros
65 * @{
66 * Macros used by setClock API
67 */
68 /**
69 * The IP does not require this clock, it can be disabled, regardless of the
70 * state of the device
71 */
72 #define TISCI_MSG_VALUE_CLOCK_SW_STATE_UNREQ 0
74 /**
75 * Allow the system controller to automatically manage the state of this clock.
76 * If the device is enabled, then the clock is enabled. If the device is set to
77 * off or retention, then the clock is internally set as not being required
78 * by the device. This is the default state.
79 */
80 #define TISCI_MSG_VALUE_CLOCK_SW_STATE_AUTO 1
82 /** Configure the clock to be enabled, regardless of the state of the device. */
83 #define TISCI_MSG_VALUE_CLOCK_SW_STATE_REQ 2
84 /* @} */
86 /**
87 * \anchor Sciclient_PmGetClockMsgState
88 * \name Clock HW state Macros
89 * @{
90 * Macros of values returned by getClock API
91 */
92 /** Indicate hardware state of the clock is that it is not running. */
93 #define TISCI_MSG_VALUE_CLOCK_HW_STATE_NOT_READY 0
95 /** Indicate hardware state of the clock is that it is running. */
96 #define TISCI_MSG_VALUE_CLOCK_HW_STATE_READY 1
97 /* @} */
99 /**
100 * \anchor Sciclient_PmSetClockMsgFlag
101 * \name SetClock Message Flags
102 * @{
103 * Flags used in SetClock API to alter the clock state
104 */
105 /** Allow this clock to be modified via spread spectrum clocking. */
106 #define TISCI_MSG_FLAG_CLOCK_ALLOW_SSC TISCI_BIT(8)
108 /**
109 * Allow this clock's frequency to be changed while it is running
110 * so long as it is within the min/max limits.
111 */
112 #define TISCI_MSG_FLAG_CLOCK_ALLOW_FREQ_CHANGE TISCI_BIT(9)
114 /**
115 * Enable input termination, this is only applicable to clock inputs
116 * on the SoC pseudo-device, TISCI_BOARD0.
117 */
118 #define TISCI_MSG_FLAG_CLOCK_INPUT_TERM TISCI_BIT(10)
120 /** Indicate that SSC is active for this clock. */
121 #define TISCI_MSG_FLAG_CLOCK_SSC_ACTIVE TISCI_BIT(11)
122 /* @} */
125 /**
126 * \brief Mark a clock as required/not required.
127 *
128 * Indicate that the selected clock is currently required/not required by
129 * the IP.
130 *
131 * Certain flags can be set in the message header for device clocks:
132 * TISCI_MSG_FLAG_CLOCK_ALLOW_SSC, TISCI_MSG_FLAG_CLOCK_ALLOW_FREQ_CHANGE,
133 * TISCI_MSG_FLAG_CLOCK_INPUT_TERM.
134 *
135 *
136 * \param device
137 * The device ID that the clock is connected to.
138 *
139 * \param clk
140 * Each device has its own set of clock inputs. This indexes which clock
141 * input to modify.
142 *
143 * If the clock index is 255 or greater, this field should be set to 255
144 * and the full value placed in the clk32 field. This is kept for backwards
145 * compatibility with older firmwares.
146 *
147 * \param clk32
148 * Stores the actual clock index if clk field is set to 255. This field is
149 * ignored otherwise. This field can hold the full range of possible clock
150 * indexes, but for compatibility with older firmwares should only be used
151 * when the index is 255 or greater.
152 *
153 * \param state
154 * The desired state of the clock, TISCI_MSG_VALUE_CLOCK_SW_STATE_REQ if the clock is
155 * currently required by the IP and TISCI_MSG_VALUE_CLOCK_SW_STATE_UNREQ if it is
156 * not. TISCI_MSG_VALUE_CLOCK_SW_STATE_AUTO enables the clock when the IP is set
157 * to enabled and disables it when the IP is set to disabled. This is the
158 * default state.
159 */
160 struct tisci_msg_set_clock_req {
161 uint32_t device;
162 uint8_t clk;
163 uint8_t state;
164 uint32_t clk32;
165 } __attribute__((__packed__));
167 /**
168 * \brief Empty response for TISCI_MSG_SET_CLOCK
169 *
170 * Although this message is essentially empty and contains only a header
171 * a full data structure is created for consistency in implementation.
172 *
173 */
174 struct tisci_msg_set_clock_resp {
175 } __attribute__((__packed__));
177 /**
178 * \brief Get the current state of a clock
179 *
180 *
181 * \param device
182 * The device ID that the clock is connected to.
183 *
184 * \param clk
185 * Each device has its own set of clock inputs. This indexes which clock
186 * input to get.
187 *
188 * If the clock index is 255 or greater, this field should be set to 255
189 * and the full value placed in the clk32 field. This is kept for backwards
190 * compatibility with older firmwares.
191 *
192 * \param clk32
193 * Stores the actual clock index if clk field is set to 255. This field is
194 * ignored otherwise. This field can hold the full range of possible clock
195 * indexes, but for compatibility with older firmwares should only be used
196 * when the index is 255 or greater.
197 */
198 struct tisci_msg_get_clock_req {
199 uint32_t device;
200 uint8_t clk;
201 uint32_t clk32;
202 } __attribute__((__packed__));
204 /**
205 * \brief Clock state response.
206 *
207 *
208 * \param programmed_state
209 * The programmed state as set by the set message.
210 *
211 * \param current_state
212 * The actual state of the clock. If it is desired that a clock be on, it
213 * is usually better to send a set message with a flag indicating that
214 * an ack be sent when the message is processed rather than attempting
215 * to poll this state.
216 */
217 struct tisci_msg_get_clock_resp {
218 uint8_t programmed_state;
219 uint8_t current_state;
220 } __attribute__((__packed__));
222 /**
223 * \brief Set the clock parent
224 *
225 * Many IPs have a mux external to the IP that can select among different
226 * clock sources. The clock must be disabled (TISCI_MSG_VALUE_CLOCK_SW_STATE_UNREQ)
227 * for this message to succeed. If a set frequency command is not issued
228 * before the clock is enabled again, then the execution of the enable
229 * command will attempt to set the new parent to the old parent's
230 * frequency. If this fails, then the enable will fail.
231 *
232 * Muxes that provide clocks to multiple devices are not currently
233 * configurable via this API.
234 *
235 *
236 * \param device
237 * The device ID that the clock is connected to.
238 *
239 * \param clk
240 * Each device has its own set of clock inputs. This indexes which clock
241 * input to modify.
242 *
243 * If the clock index is 255 or greater, this field should be set to 255
244 * and the full value placed in the clk32 field. This is kept for backwards
245 * compatibility with older firmwares.
246 *
247 * \param clk32
248 * Stores the actual clock index if clk field is set to 255. This field is
249 * ignored otherwise. This field can hold the full range of possible clock
250 * indexes, but for compatibility with older firmwares should only be used
251 * when the index is 255 or greater.
252 *
253 * \param parent
254 * The new clock parent is selectable by an index via this parameter.
255 *
256 * If the parent clock index is 255 or greater, this field should be set to
257 * 255 and the full value placed in the parent32 field. This is kept for
258 * backwards compatibility with older firmwares.
259 *
260 * \param parent32
261 * Stores the actual parent clock index if parent field is set to 255. This
262 * field is ignored otherwise. This field can hold the full range of possible
263 * parent clock indexes, but for compatibility with older firmwares should
264 * only be used when the index is 255 or greater.
265 */
266 struct tisci_msg_set_clock_parent_req {
267 uint32_t device;
268 uint8_t clk;
269 uint8_t parent;
270 uint32_t clk32;
271 uint32_t parent32;
272 } __attribute__((__packed__));
274 /**
275 * \brief Empty response for TISCI_MSG_SET_CLOCK_PARENT
276 *
277 * Although this message is essentially empty and contains only a header
278 * a full data structure is created for consistency in implementation.
279 *
280 */
281 struct tisci_msg_set_clock_parent_resp {
282 } __attribute__((__packed__));
284 /**
285 * \brief Return the current clock parent
286 *
287 * If the hardware value indicating the current clock parent contains a
288 * reserved value, a NAK is returned for this message. Once a valid parent
289 * is programmed via a successful SET_CLOCK_PARENT call, calls to
290 * GET_CLOCK_PARENT will succeed.
291 *
292 *
293 * \param device
294 * The device ID that the clock is connected to.
295 *
296 * \param clk
297 * Each device has its own set of clock inputs. This indexes which clock
298 * input to get.
299 *
300 * If the clock index is 255 or greater, this field should be set to 255
301 * and the full value placed in the clk32 field. This is kept for backwards
302 * compatibility with older firmwares.
303 *
304 * \param clk32
305 * Stores the actual clock index if clk field is set to 255. This field is
306 * ignored otherwise. This field can hold the full range of possible clock
307 * indexes, but for compatibility with older firmwares should only be used
308 * when the index is 255 or greater.
309 */
310 struct tisci_msg_get_clock_parent_req {
311 uint32_t device;
312 uint8_t clk;
313 uint32_t clk32;
314 } __attribute__((__packed__));
316 /**
317 * \brief Clock parent response
318 *
319 *
320 * \param parent
321 * The current clock parent.
322 *
323 * If the parent clock index is 255 or greater, this field will be
324 * set to 255 and the full value placed in the parent32 field. This is
325 * for backwards compatibility with older firmwares.
326 *
327 * \param parent32
328 * Parent Clock index if 255 or greater and parent field is set
329 * to 255. This field will contain 0xFFFFFFFF otherwise.
330 */
331 struct tisci_msg_get_clock_parent_resp {
332 uint8_t parent;
333 uint32_t parent32;
334 } __attribute__((__packed__));
336 /**
337 * \brief Return the number of possible parents for a clock
338 *
339 *
340 * \param device
341 * The device ID that the clock is connected to.
342 *
343 * \param clk
344 * Each device has its own set of clock inputs. This indexes which clock
345 * input to query.
346 *
347 * If the clock index is 255 or greater, this field should be set to 255
348 * and the full value placed in the clk32 field. This is kept for backwards
349 * compatibility with older firmwares.
350 *
351 * \param clk32
352 * Stores the actual clock index if clk field is set to 255. This field is
353 * ignored otherwise. This field can hold the full range of possible clock
354 * indexes, but for compatibility with older firmwares should only be used
355 * when the index is 255 or greater.
356 */
357 struct tisci_msg_get_num_clock_parents_req {
358 uint32_t device;
359 uint8_t clk;
360 uint32_t clk32;
361 } __attribute__((__packed__));
363 /**
364 * \brief Num clock parents response
365 *
366 *
367 * \param num_parents
368 * The number of clock parents.
369 *
370 * If the number of clock parents is 255 or greater, this field will
371 * be set to 255 and the full value placed in the num_parentint32_t field.
372 * This is for backwards compatibility with older firmwares.
373 *
374 * \param num_parentint32_t
375 * Number of clock parents if 255 or greater and num_parents field
376 * is set to 255. This field will contain 0xFFFFFFFF otherwise.
377 */
378 struct tisci_msg_get_num_clock_parents_resp {
379 uint8_t num_parents;
380 uint32_t num_parentint32_t;
381 } __attribute__((__packed__));
383 /**
384 * \brief Set the desired frequency for a clock.
385 *
386 * This set the desired frequency for a clock within an allowable
387 * range. This message will fail on an enabled clock unless
388 * TISCI_MSG_FLAG_CLOCK_ALLOW_FREQ_CHANGE is set for the clock. Additionally,
389 * if other clocks have their frequency modified due to this message,
390 * they also must have the TISCI_MSG_FLAG_CLOCK_ALLOW_FREQ_CHANGE or be
391 * disabled.
392 *
393 * Calling set frequency on a clock input to the SoC psuedo-device will
394 * inform the PMMC of that clock's frequency. Setting a frequency of
395 * zero will indicate the clock is disabled.
396 *
397 * Calling set frequency on clock outputs from the SoC pseudo-device will
398 * function similarly to setting the clock frequency on a device.
399 *
400 *
401 * \param device
402 * The device ID that the clock is connected to.
403 *
404 * \param min_freq_hz
405 * The minimum allowable frequency in Hz. This is the minimum allowable
406 * programmed frequency and does not account for clock tolerances and jitter.
407 *
408 * \param target_freq_hz
409 * The target clock frequency. The clock will be programmed at a rate as
410 * close to this target frequency as possible.
411 *
412 * \param max_freq_hz
413 * The maximum allowable frequency in Hz. This is the maximum allowable
414 * programmed frequency and does not account for clock tolerances and jitter.
415 * The firmware will actually accept any frequency up to but not including
416 * max + 1.
417 *
418 * \param clk
419 * Each device has its own set of clock inputs. This indexes which clock
420 * input to modify.
421 *
422 * If the clock index is 255 or greater, this field should be set to 255
423 * and the full value placed in the clk32 field. This is kept for backwards
424 * compatibility with older firmwares.
425 *
426 * \param clk32
427 * Stores the actual clock index if clk field is set to 255. This field is
428 * ignored otherwise. This field can hold the full range of possible clock
429 * indexes, but for compatibility with older firmwares should only be used
430 * when the index is 255 or greater.
431 */
432 struct tisci_msg_set_freq_req {
433 uint32_t device;
434 uint64_t min_freq_hz;
435 uint64_t target_freq_hz;
436 uint64_t max_freq_hz;
437 uint8_t clk;
438 uint32_t clk32;
439 } __attribute__((__packed__));
441 /**
442 * \brief Empty response for TISCI_MSG_SET_FREQ
443 *
444 * Although this message is essentially empty and contains only a header
445 * a full data structure is created for consistency in implementation.
446 *
447 */
448 struct tisci_msg_set_freq_resp {
449 } __attribute__((__packed__));
451 /**
452 * \brief Determine the result of a hypothetical set frequency operation.
453 *
454 * This allows the OS to determine what rate would be set given a set
455 * of parameters. A nack will be received if a frequency is not available
456 * in the given range.
457 *
458 *
459 * \param device
460 * The device ID that the clock is connected to.
461 *
462 * \param min_freq_hz
463 * The minimum allowable frequency in Hz. This is the minimum allowable
464 * programmed frequency and does not account for clock tolerances and jitter.
465 *
466 * \param target_freq_hz
467 * The target clock frequency. A frequency will be found as close to the
468 * target frequency as possible.
469 *
470 * \param max_freq_hz
471 * The maximum allowable frequency in Hz. This is the maximum allowable
472 * programmed frequency and does not account for clock tolerances and jitter.
473 * The firmware will actually accept any frequency up to but not including
474 * max + 1.
475 *
476 * \param clk
477 * Each device has its own set of clock inputs. This indexes which clock
478 * input to query.
479 *
480 * If the clock index is 255 or greater, this field should be set to 255
481 * and the full value placed in the clk32 field. This is kept for backwards
482 * compatibility with older firmwares.
483 *
484 * \param clk32
485 * Stores the actual clock index if clk field is set to 255. This field is
486 * ignored otherwise. This field can hold the full range of possible clock
487 * indexes, but for compatibility with older firmwares should only be used
488 * when the index is 255 or greater.
489 */
490 struct tisci_msg_query_freq_req {
491 uint32_t device;
492 uint64_t min_freq_hz;
493 uint64_t target_freq_hz;
494 uint64_t max_freq_hz;
495 uint8_t clk;
496 uint32_t clk32;
497 } __attribute__((__packed__));
499 /**
500 * \brief Result of a query operation
501 *
502 *
503 * \param freq_hz
504 * The frequency in Hz that the hardware would set for the given parameters.
505 */
506 struct tisci_msg_query_freq_resp {
507 uint64_t freq_hz;
508 } __attribute__((__packed__));
510 /**
511 * \brief Get the current frequency of a device's clock
512 *
513 * This message will only succeed if the clock is currently enabled, otherwise
514 * it returns nack.
515 *
516 *
517 * \param device
518 * The device ID that the clock is connected to.
519 *
520 * \param clk
521 * Each device has its own set of clock inputs. This indexes which clock
522 * input to query.
523 *
524 * If the clock index is 255 or greater, this field should be set to 255
525 * and the full value placed in the clk32 field. This is kept for backwards
526 * compatibility with older firmwares.
527 *
528 * \param clk32
529 * Stores the actual clock index if clk field is set to 255. This field is
530 * ignored otherwise. This field can hold the full range of possible clock
531 * indexes, but for compatibility with older firmwares should only be used
532 * when the index is 255 or greater.
533 */
534 struct tisci_msg_get_freq_req {
535 uint32_t device;
536 uint8_t clk;
537 uint32_t clk32;
538 } __attribute__((__packed__));
540 /**
541 * \brief Result of get frequency request
542 *
543 *
544 * \param freq_hz
545 * The current frequency in Hz.
546 */
547 struct tisci_msg_get_freq_resp {
548 uint64_t freq_hz;
549 } __attribute__((__packed__));
551 #endif /* TISCI_PM_TISCI_CLOCK_H */
553 /* @} */