Line data Source code
1 1 : /*
2 : * Copyright (c) 2025, Texas Instruments
3 : *
4 : * SPDX-License-Identifier: Apache-2.0
5 : */
6 :
7 : /**
8 : * @file
9 : * @brief Public APIs for the TISCI driver
10 : *
11 : */
12 :
13 : #ifndef INCLUDE_ZEPHYR_DRIVERS_TISCI_H_
14 : #define INCLUDE_ZEPHYR_DRIVERS_TISCI_H_
15 :
16 : #include <zephyr/device.h>
17 :
18 0 : #define MAILBOX_MBOX_SIZE 60
19 :
20 : /**
21 : * @struct tisci_version_info
22 : * @brief version information structure
23 : * @param abi_major: Major ABI version. Change here implies risk of backward
24 : * compatibility break.
25 : * @param abi_minor: Minor ABI version. Change here implies new feature addition,
26 : * or compatible change in ABI.
27 : * @param firmware_revision: Firmware revision (not usually used).
28 : * @param firmware_description: Firmware description (not usually used).
29 : */
30 1 : struct tisci_version_info {
31 0 : uint8_t abi_major;
32 0 : uint8_t abi_minor;
33 0 : uint16_t firmware_revision;
34 0 : char firmware_description[32];
35 : };
36 :
37 : /**
38 1 : * @struct tisci_msg_fwl_region_cfg
39 : * @brief Request and Response for firewalls settings
40 : *
41 : * @param fwl_id: Firewall ID in question
42 : * @param region: Region or channel number to set config info
43 : * This field is unused in case of a simple firewall and must be initialized
44 : * to zero. In case of a region based firewall, this field indicates the
45 : * region in question. (index starting from 0) In case of a channel based
46 : * firewall, this field indicates the channel in question (index starting
47 : * from 0)
48 : * @param n_permission_regs: Number of permission registers to set
49 : * @param control: Contents of the firewall CONTROL register to set
50 : * @param permissions: Contents of the firewall PERMISSION register to set
51 : * @param start_address: Contents of the firewall START_ADDRESS register to set
52 : * @param end_address: Contents of the firewall END_ADDRESS register to set
53 : */
54 0 : struct tisci_msg_fwl_region {
55 0 : uint16_t fwl_id;
56 0 : uint16_t region;
57 0 : uint32_t n_permission_regs;
58 0 : uint32_t control;
59 0 : uint32_t permissions[3];
60 0 : uint64_t start_address;
61 0 : uint64_t end_address;
62 : };
63 :
64 : /**
65 : * @brief Request and Response for firewall owner change
66 : * @struct tisci_msg_fwl_owner
67 : * @param fwl_id: Firewall ID in question
68 : * @param region: Region or channel number to set config info
69 : * This field is unused in case of a simple firewall and must be initialized
70 : * to zero. In case of a region based firewall, this field indicates the
71 : * region in question. (index starting from 0) In case of a channel based
72 : * firewall, this field indicates the channel in question (index starting
73 : * from 0)
74 : * @param n_permission_regs: Number of permission registers <= 3
75 : * @param control: Control register value for this region
76 : * @param owner_index: New owner index to change to. Owner indexes are setup in DMSC firmware boot
77 : *configuration data
78 : * @param owner_privid: New owner priv-id, used to lookup owner_index is not known, must be set to
79 : *zero otherwise
80 : * @param owner_permission_bits: New owner permission bits
81 : */
82 1 : struct tisci_msg_fwl_owner {
83 0 : uint16_t fwl_id;
84 0 : uint16_t region;
85 0 : uint8_t owner_index;
86 0 : uint8_t owner_privid;
87 0 : uint16_t owner_permission_bits;
88 : };
89 :
90 : /**
91 : * Configures a Navigator Subsystem UDMAP transmit channel
92 : *
93 : * Configures a Navigator Subsystem UDMAP transmit channel registers.
94 : * See tisci_msg_rm_udmap_tx_ch_cfg_req
95 : */
96 1 : struct tisci_msg_rm_udmap_tx_ch_cfg {
97 0 : uint32_t valid_params;
98 0 : #define TISCI_MSG_VALUE_RM_UDMAP_CH_TX_FILT_EINFO_VALID BIT(9)
99 0 : #define TISCI_MSG_VALUE_RM_UDMAP_CH_TX_FILT_PSWORDS_VALID BIT(10)
100 0 : #define TISCI_MSG_VALUE_RM_UDMAP_CH_TX_SUPR_TDPKT_VALID BIT(11)
101 0 : #define TISCI_MSG_VALUE_RM_UDMAP_CH_TX_CREDIT_COUNT_VALID BIT(12)
102 0 : #define TISCI_MSG_VALUE_RM_UDMAP_CH_TX_FDEPTH_VALID BIT(13)
103 0 : #define TISCI_MSG_VALUE_RM_UDMAP_CH_TX_TDTYPE_VALID BIT(15)
104 0 : #define TISCI_MSG_VALUE_RM_UDMAP_CH_EXTENDED_CH_TYPE_VALID BIT(16)
105 0 : uint16_t nav_id;
106 0 : uint16_t index;
107 0 : uint8_t tx_pause_on_err;
108 0 : uint8_t tx_filt_einfo;
109 0 : uint8_t tx_filt_pswords;
110 0 : uint8_t tx_atype;
111 0 : uint8_t tx_chan_type;
112 0 : uint8_t tx_supr_tdpkt;
113 0 : uint16_t tx_fetch_size;
114 0 : uint8_t tx_credit_count;
115 0 : uint16_t txcq_qnum;
116 0 : uint8_t tx_priority;
117 0 : uint8_t tx_qos;
118 0 : uint8_t tx_orderid;
119 0 : uint16_t fdepth;
120 0 : uint8_t tx_sched_priority;
121 0 : uint8_t tx_burst_size;
122 0 : uint8_t tx_tdtype;
123 0 : uint8_t extended_ch_type;
124 : };
125 :
126 : /**
127 : * Configures a Navigator Subsystem UDMAP receive channel
128 : *
129 : * Configures a Navigator Subsystem UDMAP receive channel registers.
130 : * See tisci_msg_rm_udmap_rx_ch_cfg_req
131 : */
132 1 : struct tisci_msg_rm_udmap_rx_ch_cfg {
133 0 : uint32_t valid_params;
134 0 : #define TISCI_MSG_VALUE_RM_UDMAP_CH_RX_FLOWID_START_VALID BIT(9)
135 0 : #define TISCI_MSG_VALUE_RM_UDMAP_CH_RX_FLOWID_CNT_VALID BIT(10)
136 0 : #define TISCI_MSG_VALUE_RM_UDMAP_CH_RX_IGNORE_SHORT_VALID BIT(11)
137 0 : #define TISCI_MSG_VALUE_RM_UDMAP_CH_RX_IGNORE_LONG_VALID BIT(12)
138 0 : uint16_t nav_id;
139 0 : uint16_t index;
140 0 : uint16_t rx_fetch_size;
141 0 : uint16_t rxcq_qnum;
142 0 : uint8_t rx_priority;
143 0 : uint8_t rx_qos;
144 0 : uint8_t rx_orderid;
145 0 : uint8_t rx_sched_priority;
146 0 : uint16_t flowid_start;
147 0 : uint16_t flowid_cnt;
148 0 : uint8_t rx_pause_on_err;
149 0 : uint8_t rx_atype;
150 0 : uint8_t rx_chan_type;
151 0 : uint8_t rx_ignore_short;
152 0 : uint8_t rx_ignore_long;
153 0 : uint8_t rx_burst_size;
154 : };
155 :
156 0 : #define TISCI_MSG_VALUE_RM_DST_ID_VALID (1u << 0u)
157 0 : #define TISCI_MSG_VALUE_RM_DST_HOST_IRQ_VALID (1u << 1u)
158 0 : #define TISCI_MSG_VALUE_RM_IA_ID_VALID (1u << 2u)
159 0 : #define TISCI_MSG_VALUE_RM_VINT_VALID (1u << 3u)
160 0 : #define TISCI_MSG_VALUE_RM_GLOBAL_EVENT_VALID (1u << 4u)
161 0 : #define TISCI_MSG_VALUE_RM_VINT_STATUS_BIT_INDEX_VALID (1u << 5u)
162 :
163 : /**
164 : * @brief Request to set up an interrupt route.
165 : *
166 : * Configures peripherals within the interrupt subsystem according to the
167 : * valid configuration provided.
168 : *
169 : * @param valid_params Bitfield defining validity of interrupt route set parameters.
170 : * Each bit corresponds to a field's validity.
171 : * @param src_id ID of interrupt source peripheral.
172 : * @param src_index Interrupt source index within source peripheral.
173 : * @param dst_id SoC IR device ID (valid if TISCI_MSG_VALUE_RM_DST_ID_VALID is set).
174 : * @param dst_host_irq SoC IR output index (valid if TISCI_MSG_VALUE_RM_DST_HOST_IRQ_VALID
175 : * is set).
176 : * @param ia_id Device ID of interrupt aggregator (valid if
177 : * TISCI_MSG_VALUE_RM_IA_ID_VALID is set).
178 : * @param vint Virtual interrupt number (valid if TISCI_MSG_VALUE_RM_VINT_VALID is
179 : * set).
180 : * @param global_event Global event mapped to interrupt aggregator (valid if
181 : * TISCI_MSG_VALUE_RM_GLOBAL_EVENT_VALID is set).
182 : * @param vint_status_bit_index Virtual interrupt status bit (valid if
183 : * TISCI_MSG_VALUE_RM_VINT_STATUS_BIT_INDEX_VALID is set).
184 : * @param secondary_host Secondary host value (valid if
185 : * TISCI_MSG_VALUE_RM_SECONDARY_HOST_VALID is set).
186 : */
187 1 : struct tisci_irq_set_req {
188 0 : uint32_t valid_params;
189 0 : uint16_t src_id;
190 0 : uint16_t src_index;
191 0 : uint16_t dst_id;
192 0 : uint16_t dst_host_irq;
193 0 : uint16_t ia_id;
194 0 : uint16_t vint;
195 0 : uint16_t global_event;
196 0 : uint8_t vint_status_bit_index;
197 0 : uint8_t secondary_host;
198 : };
199 :
200 : /**
201 : * @brief Request to release interrupt peripheral resources.
202 : *
203 : * Releases interrupt peripheral resources according to the valid configuration provided.
204 : *
205 : * @param valid_params Bitfield defining validity of interrupt route release parameters.
206 : * Each bit corresponds to a field's validity.
207 : * @param src_id ID of interrupt source peripheral.
208 : * @param src_index Interrupt source index within source peripheral.
209 : * @param dst_id SoC IR device ID (valid if TISCI_MSG_VALUE_RM_DST_ID_VALID is set).
210 : * @param dst_host_irq SoC IR output index (valid if TISCI_MSG_VALUE_RM_DST_HOST_IRQ_VALID
211 : * is set).
212 : * @param ia_id Device ID of interrupt aggregator (valid if
213 : * TISCI_MSG_VALUE_RM_IA_ID_VALID is set).
214 : * @param vint Virtual interrupt number (valid if TISCI_MSG_VALUE_RM_VINT_VALID is
215 : * set).
216 : * @param global_event Global event mapped to interrupt aggregator (valid if
217 : * TISCI_MSG_VALUE_RM_GLOBAL_EVENT_VALID is set).
218 : * @param vint_status_bit_index Virtual interrupt status bit (valid if
219 : * TISCI_MSG_VALUE_RM_VINT_STATUS_BIT_INDEX_VALID is set).
220 : * @param secondary_host Secondary host value (valid if
221 : * TISCI_MSG_VALUE_RM_SECONDARY_HOST_VALID is set).
222 : */
223 :
224 1 : struct tisci_irq_release_req {
225 0 : uint32_t valid_params;
226 0 : uint16_t src_id;
227 0 : uint16_t src_index;
228 0 : uint16_t dst_id;
229 0 : uint16_t dst_host_irq;
230 0 : uint16_t ia_id;
231 0 : uint16_t vint;
232 0 : uint16_t global_event;
233 0 : uint8_t vint_status_bit_index;
234 0 : uint8_t secondary_host;
235 : };
236 :
237 : /* Version/Revision Functions */
238 :
239 : /**
240 : * @brief Get the revision information of the TI SCI firmware
241 : *
242 : * Queries the TI SCI firmware for its version and revision information.
243 : * The retrieved information is stored in the provided @p ver structure.
244 : *
245 : * @param dev Pointer to the TI SCI device
246 : * @param ver Pointer to a structure where the firmware version information will be stored
247 : *
248 : * @return 0 if successful, or a negative error code on failure
249 : */
250 1 : int tisci_cmd_get_revision(const struct device *dev, struct tisci_version_info *ver);
251 :
252 : /* Clock Management Functions */
253 :
254 : /**
255 : * @brief Get the state of a clock
256 : *
257 : * @param dev Pointer to the TI SCI device
258 : * @param dev_id Device identifier for this request
259 : * @param clk_id Clock identifier for the device for this request
260 : * @param programmed_state Pointer to store the requested state of the clock
261 : * @param current_state Pointer to store the current state of the clock
262 : *
263 : * @return 0 if successful, or an error code
264 : */
265 1 : int tisci_cmd_get_clock_state(const struct device *dev, uint32_t dev_id, uint8_t clk_id,
266 : uint8_t *programmed_state, uint8_t *current_state);
267 :
268 : /**
269 : * @brief Set the state of a clock
270 : *
271 : * @param dev Pointer to the TI SCI device
272 : * @param dev_id Device identifier for this request
273 : * @param clk_id Clock identifier for the device for this request
274 : * @param flags Header flags as needed
275 : * @param state State to request for the clock
276 : *
277 : * @return 0 if successful, or an error code
278 : */
279 1 : int tisci_set_clock_state(const struct device *dev, uint32_t dev_id, uint8_t clk_id, uint32_t flags,
280 : uint8_t state);
281 :
282 : /**
283 : * @brief Check if the clock is ON
284 : *
285 : * @param dev Pointer to the TI SCI device
286 : * @param dev_id Device identifier for this request
287 : * @param clk_id Clock identifier for the device for this request
288 : * @param req_state Pointer to store whether the clock is managed and enabled
289 : * @param curr_state Pointer to store whether the clock is ready for operation
290 : *
291 : * @return 0 if successful, or an error code
292 : */
293 1 : int tisci_cmd_clk_is_on(const struct device *dev, uint32_t dev_id, uint8_t clk_id, bool *req_state,
294 : bool *curr_state);
295 :
296 : /**
297 : * @brief Check if the clock is OFF
298 : *
299 : * @param dev Pointer to the TI SCI device
300 : * @param dev_id Device identifier for this request
301 : * @param clk_id Clock identifier for the device for this request
302 : * @param req_state Pointer to store whether the clock is managed and disabled
303 : * @param curr_state Pointer to store whether the clock is NOT ready for operation
304 : *
305 : * @return 0 if successful, or an error code
306 : */
307 1 : int tisci_cmd_clk_is_off(const struct device *dev, uint32_t dev_id, uint8_t clk_id, bool *req_state,
308 : bool *curr_state);
309 :
310 : /**
311 : * @brief Check if the clock is being auto-managed
312 : *
313 : * @param dev Pointer to the TI SCI device
314 : * @param dev_id Device identifier for this request
315 : * @param clk_id Clock identifier for the device for this request
316 : * @param req_state Pointer to store whether the clock is auto-managed
317 : *
318 : * @return 0 if successful, or an error code
319 : */
320 1 : int tisci_cmd_clk_is_auto(const struct device *dev, uint32_t dev_id, uint8_t clk_id,
321 : bool *req_state);
322 :
323 : /**
324 : * @brief Get the current frequency of a clock
325 : *
326 : * @param dev Pointer to the TI SCI device
327 : * @param dev_id Device identifier for this request
328 : * @param clk_id Clock identifier for the device for this request
329 : * @param freq Pointer to store the current frequency in Hz
330 : *
331 : * @return 0 if successful, or an error code
332 : */
333 1 : int tisci_cmd_clk_get_freq(const struct device *dev, uint32_t dev_id, uint8_t clk_id,
334 : uint64_t *freq);
335 :
336 : /**
337 : * @brief Set a frequency for a clock
338 : *
339 : * @param dev Pointer to the TI SCI device
340 : * @param dev_id Device identifier for this request
341 : * @param clk_id Clock identifier for the device for this request
342 : * @param min_freq Minimum allowable frequency in Hz
343 : * @param target_freq Target clock frequency in Hz
344 : * @param max_freq Maximum allowable frequency in Hz
345 : *
346 : * @return 0 if successful, or an error code
347 : */
348 1 : int tisci_cmd_clk_set_freq(const struct device *dev, uint32_t dev_id, uint8_t clk_id,
349 : uint64_t min_freq, uint64_t target_freq, uint64_t max_freq);
350 :
351 : /**
352 : * @brief Get a matching frequency for a clock
353 : *
354 : * Finds a frequency that matches the requested range for a clock.
355 : *
356 : * @param dev Pointer to the TI SCI device
357 : * @param dev_id Device identifier for this request
358 : * @param clk_id Clock identifier for the device for this request
359 : * @param min_freq Minimum allowable frequency in Hz
360 : * @param target_freq Target clock frequency in Hz
361 : * @param max_freq Maximum allowable frequency in Hz
362 : * @param match_freq Pointer to store the matched frequency in Hz
363 : *
364 : * @return 0 if successful, or an error code
365 : */
366 1 : int tisci_cmd_clk_get_match_freq(const struct device *dev, uint32_t dev_id, uint8_t clk_id,
367 : uint64_t min_freq, uint64_t target_freq, uint64_t max_freq,
368 : uint64_t *match_freq);
369 :
370 : /**
371 : * @brief Set the parent clock for a clock
372 : *
373 : * @param dev Pointer to the TI SCI device
374 : * @param dev_id Device identifier for this request
375 : * @param clk_id Clock identifier for the device for this request
376 : * @param parent_id Identifier of the parent clock to set
377 : *
378 : * @return 0 if successful, or an error code
379 : */
380 1 : int tisci_cmd_clk_set_parent(const struct device *dev, uint32_t dev_id, uint8_t clk_id,
381 : uint8_t parent_id);
382 :
383 : /**
384 : * @brief Get the parent clock for a clock
385 : *
386 : * @param dev Pointer to the TI SCI device
387 : * @param dev_id Device identifier for this request
388 : * @param clk_id Clock identifier for the device for this request
389 : * @param parent_id Pointer to store the identifier of the parent clock
390 : *
391 : * @return 0 if successful, or an error code
392 : */
393 1 : int tisci_cmd_clk_get_parent(const struct device *dev, uint32_t dev_id, uint8_t clk_id,
394 : uint8_t *parent_id);
395 :
396 : /**
397 : * @brief Get the number of parent clocks for a clock
398 : *
399 : * @param dev Pointer to the TI SCI device
400 : * @param dev_id Device identifier for this request
401 : * @param clk_id Clock identifier for the device for this request
402 : * @param num_parents Pointer to store the number of parent clocks
403 : *
404 : * @return 0 if successful, or an error code
405 : */
406 1 : int tisci_cmd_clk_get_num_parents(const struct device *dev, uint32_t dev_id, uint8_t clk_id,
407 : uint8_t *num_parents);
408 :
409 : /**
410 : * @brief Get control of a clock from TI SCI
411 : *
412 : * @param dev Pointer to the TI SCI device
413 : * @param dev_id Device identifier for this request
414 : * @param clk_id Clock identifier for the device for this request
415 : * @param needs_ssc 'true' if Spread Spectrum clock is desired, else 'false'
416 : * @param can_change_freq 'true' if frequency change is desired, else 'false'
417 : * @param enable_input_term 'true' if input termination is desired, else 'false'
418 : *
419 : * @return 0 if successful, or an error code
420 : */
421 1 : int tisci_cmd_get_clock(const struct device *dev, uint32_t dev_id, uint8_t clk_id, bool needs_ssc,
422 : bool can_change_freq, bool enable_input_term);
423 :
424 : /**
425 : * @brief Idle a clock that is under control of TI SCI
426 : *
427 : * @param dev Pointer to the TI SCI device
428 : * @param dev_id Device identifier for this request
429 : * @param clk_id Clock identifier for the device for this request
430 : *
431 : * @return 0 if successful, or an error code
432 : */
433 1 : int tisci_cmd_idle_clock(const struct device *dev, uint32_t dev_id, uint8_t clk_id);
434 :
435 : /**
436 : * @brief Release a clock from control back to TI SCI
437 : *
438 : * @param dev Pointer to the TI SCI device
439 : * @param dev_id Device identifier for this request
440 : * @param clk_id Clock identifier for the device for this request
441 : *
442 : * @return 0 if successful, or an error code
443 : */
444 1 : int tisci_cmd_put_clock(const struct device *dev, uint32_t dev_id, uint8_t clk_id);
445 :
446 : /* Device Management Functions */
447 :
448 : /**
449 : * @brief Set the state of a device
450 : *
451 : * @param dev Pointer to the TI SCI device
452 : * @param dev_id Device identifier for this request
453 : * @param flags Flags to set for the device
454 : * @param state State to move the device to:
455 : * - 0: Device is off
456 : * - 1: Device is on
457 : * - 2: Device is in retention
458 : * - 3: Device is in reset
459 : *
460 : * @return 0 if successful, or an error code
461 : */
462 1 : int tisci_set_device_state(const struct device *dev, uint32_t dev_id, uint32_t flags,
463 : uint8_t state);
464 :
465 : /**
466 : * @brief Set the state of a device without waiting for a response
467 : *
468 : * @param dev Pointer to the TI SCI device
469 : * @param dev_id Device identifier for this request
470 : * @param flags Flags to set for the device
471 : * @param state State to move the device to:
472 : * - 0: Device is off
473 : * - 1: Device is on
474 : * - 2: Device is in retention
475 : * - 3: Device is in reset
476 : *
477 : * @return 0 if successful, or an error code
478 : */
479 1 : int tisci_set_device_state_no_wait(const struct device *dev, uint32_t dev_id, uint32_t flags,
480 : uint8_t state);
481 :
482 : /**
483 : * @brief Get the state of a device
484 : *
485 : * @param dev Pointer to the TI SCI device
486 : * @param dev_id Device identifier for this request
487 : * @param clcnt Pointer to store the Context Loss Count
488 : * @param resets Pointer to store the reset count
489 : * @param p_state Pointer to store the programmed state
490 : * @param c_state Pointer to store the current state
491 : *
492 : * @return 0 if successful, or an error code
493 : */
494 1 : int tisci_get_device_state(const struct device *dev, uint32_t dev_id, uint32_t *clcnt,
495 : uint32_t *resets, uint8_t *p_state, uint8_t *c_state);
496 :
497 : /**
498 : * @brief Request exclusive access to a device managed by TISCI
499 : *
500 : * @param dev Pointer to the TI SCI device
501 : * @param dev_id Device identifier for this request
502 : *
503 : * @return 0 if successful, or an error code
504 : */
505 1 : int tisci_cmd_get_device(const struct device *dev, uint32_t dev_id);
506 0 : int tisci_cmd_get_device_exclusive(const struct device *dev, uint32_t dev_id);
507 :
508 : /**
509 : * @brief Command to idle a device managed by TISCI
510 : *
511 : * @param dev Pointer to the TI SCI device
512 : * @param dev_id Device identifier for this request
513 : *
514 : * @return 0 if successful, or an error code
515 : */
516 1 : int tisci_cmd_idle_device(const struct device *dev, uint32_t dev_id);
517 0 : int tisci_cmd_idle_device_exclusive(const struct device *dev, uint32_t dev_id);
518 :
519 : /**
520 : * @brief Command to release a device managed by TISCI
521 : *
522 : * @param dev Pointer to the TI SCI device
523 : * @param dev_id Device identifier for this request
524 : *
525 : * @return 0 if successful, or an error code
526 : */
527 1 : int tisci_cmd_put_device(const struct device *dev, uint32_t dev_id);
528 :
529 : /**
530 : * @brief Check if a device ID is valid
531 : *
532 : * @param dev Pointer to the TI SCI device
533 : * @param dev_id Device identifier for this request
534 : *
535 : * @return 0 if the device ID is valid, or an error code
536 : */
537 1 : int tisci_cmd_dev_is_valid(const struct device *dev, uint32_t dev_id);
538 :
539 : /**
540 : * @brief Get the context loss counter for a device
541 : *
542 : * @param dev Pointer to the TI SCI device
543 : * @param dev_id Device identifier for this request
544 : * @param count Pointer to store the context loss counter
545 : *
546 : * @return 0 if successful, or an error code
547 : */
548 1 : int tisci_cmd_dev_get_clcnt(const struct device *dev, uint32_t dev_id, uint32_t *count);
549 :
550 : /**
551 : * @brief Check if the device is requested to be idle
552 : *
553 : * @param dev Pointer to the TI SCI device
554 : * @param dev_id Device identifier for this request
555 : * @param r_state Pointer to store the result (true if requested to be idle)
556 : *
557 : * @return 0 if successful, or an error code
558 : */
559 1 : int tisci_cmd_dev_is_idle(const struct device *dev, uint32_t dev_id, bool *r_state);
560 :
561 : /**
562 : * @brief Check if the device is requested to be stopped
563 : *
564 : * @param dev Pointer to the TI SCI device
565 : * @param dev_id Device identifier for this request
566 : * @param r_state Pointer to store the result (true if requested to be stopped)
567 : * @param curr_state Pointer to store the result (true if currently stopped)
568 : *
569 : * @return 0 if successful, or an error code
570 : */
571 1 : int tisci_cmd_dev_is_stop(const struct device *dev, uint32_t dev_id, bool *r_state,
572 : bool *curr_state);
573 :
574 : /**
575 : * @brief Check if the device is requested to be ON
576 : *
577 : * @param dev Pointer to the TI SCI device
578 : * @param dev_id Device identifier for this request
579 : * @param r_state Pointer to store the result (true if requested to be ON)
580 : * @param curr_state Pointer to store the result (true if currently ON and active)
581 : *
582 : * @return 0 if successful, or an error code
583 : */
584 1 : int tisci_cmd_dev_is_on(const struct device *dev, uint32_t dev_id, bool *r_state, bool *curr_state);
585 :
586 : /**
587 : * @brief Check if the device is currently transitioning
588 : *
589 : * @param dev Pointer to the TI SCI device
590 : * @param dev_id Device identifier for this request
591 : * @param curr_state Pointer to store the result (true if currently transitioning)
592 : *
593 : * @return 0 if successful, or an error code
594 : */
595 1 : int tisci_cmd_dev_is_trans(const struct device *dev, uint32_t dev_id, bool *curr_state);
596 :
597 : /**
598 : * @brief Set resets for a device managed by TISCI
599 : *
600 : * @param dev Pointer to the TI SCI device
601 : * @param dev_id Device identifier for this request
602 : * @param reset_state Device-specific reset bit field
603 : *
604 : * @return 0 if successful, or an error code
605 : */
606 1 : int tisci_cmd_set_device_resets(const struct device *dev, uint32_t dev_id, uint32_t reset_state);
607 :
608 : /**
609 : * @brief Get reset state for a device managed by TISCI
610 : *
611 : * @param dev Pointer to the TI SCI device
612 : * @param dev_id Device identifier for this request
613 : * @param reset_state Pointer to store the reset state
614 : *
615 : * @return 0 if successful, or an error code
616 : */
617 1 : int tisci_cmd_get_device_resets(const struct device *dev, uint32_t dev_id, uint32_t *reset_state);
618 :
619 : /* Resource Management Functions */
620 :
621 : /**
622 : * @brief Get a range of resources assigned to a host
623 : *
624 : * @param dev Pointer to the TI SCI device
625 : * @param dev_id TISCI device ID
626 : * @param subtype Resource assignment subtype being requested
627 : * @param s_host Host processor ID to which the resources are allocated
628 : * @param range_start Pointer to store the start index of the resource range
629 : * @param range_num Pointer to store the number of resources in the range
630 : *
631 : * @return 0 if successful, or an error code
632 : */
633 1 : int tisci_get_resource_range(const struct device *dev, uint32_t dev_id, uint8_t subtype,
634 : uint8_t s_host, uint16_t *range_start, uint16_t *range_num);
635 :
636 : /**
637 : * @brief Get a range of resources assigned to the host
638 : *
639 : * @param dev Pointer to the TI SCI device
640 : * @param dev_id TISCI device ID
641 : * @param subtype Resource assignment subtype being requested
642 : * @param range_start Pointer to store the start index of the resource range
643 : * @param range_num Pointer to store the number of resources in the range
644 : *
645 : * @return 0 if successful, or an error code
646 : */
647 1 : int tisci_cmd_get_resource_range(const struct device *dev, uint32_t dev_id, uint8_t subtype,
648 : uint16_t *range_start, uint16_t *range_num);
649 :
650 : /**
651 : * @brief Get a range of resources assigned to a specified host
652 : *
653 : * @param dev Pointer to the TI SCI device
654 : * @param dev_id TISCI device ID
655 : * @param subtype Resource assignment subtype being requested
656 : * @param s_host Host processor ID to which the resources are allocated
657 : * @param range_start Pointer to store the start index of the resource range
658 : * @param range_num Pointer to store the number of resources in the range
659 : *
660 : * @return 0 if successful, or an error code
661 : */
662 1 : int tisci_cmd_get_resource_range_from_shost(const struct device *dev, uint32_t dev_id,
663 : uint8_t subtype, uint8_t s_host, uint16_t *range_start,
664 : uint16_t *range_num);
665 :
666 : /* Processor Management Functions */
667 :
668 : /**
669 : * @brief Command to request a physical processor control
670 : *
671 : * @param dev Pointer to the TI SCI device
672 : * @param proc_id Processor ID this request is for
673 : *
674 : * @return 0 if successful, or an error code
675 : */
676 1 : int tisci_cmd_proc_request(const struct device *dev, uint8_t proc_id);
677 :
678 : /**
679 : * @brief Command to release a physical processor control
680 : *
681 : * @param dev Pointer to the TI SCI device
682 : * @param proc_id Processor ID this request is for
683 : *
684 : * @return 0 if successful, or an error code
685 : */
686 1 : int tisci_cmd_proc_release(const struct device *dev, uint8_t proc_id);
687 :
688 : /**
689 : * @brief Command to handover a physical processor control to a host
690 : * in the processor's access control list
691 : *
692 : * @param dev Pointer to the TI SCI device
693 : * @param proc_id Processor ID this request is for
694 : * @param host_id Host ID to get the control of the processor
695 : *
696 : * @return 0 if successful, or an error code
697 : */
698 1 : int tisci_cmd_proc_handover(const struct device *dev, uint8_t proc_id, uint8_t host_id);
699 :
700 : /**
701 : * @brief Command to set the processor boot configuration flags
702 : *
703 : * @param dev Pointer to the TI SCI device
704 : * @param proc_id Processor ID this request is for
705 : * @param bootvector Boot vector address
706 : * @param config_flags_set Configuration flags to be set
707 : * @param config_flags_clear Configuration flags to be cleared
708 : *
709 : * @return 0 if successful, or an error code
710 : */
711 1 : int tisci_cmd_set_proc_boot_cfg(const struct device *dev, uint8_t proc_id, uint64_t bootvector,
712 : uint32_t config_flags_set, uint32_t config_flags_clear);
713 :
714 : /**
715 : * @brief Command to set the processor boot control flags
716 : *
717 : * @param dev Pointer to the TI SCI device
718 : * @param proc_id Processor ID this request is for
719 : * @param control_flags_set Control flags to be set
720 : * @param control_flags_clear Control flags to be cleared
721 : *
722 : * @return 0 if successful, or an error code
723 : */
724 1 : int tisci_cmd_set_proc_boot_ctrl(const struct device *dev, uint8_t proc_id,
725 : uint32_t control_flags_set, uint32_t control_flags_clear);
726 :
727 : /**
728 : * @brief Command to authenticate and load the image, then set the processor configuration flags
729 : *
730 : * @param dev Pointer to the TI SCI device
731 : * @param image_addr Pointer to the memory address of the payload image and certificate
732 : * @param image_size Pointer to the size of the image after authentication
733 : *
734 : * @return 0 if successful, or an error code
735 : */
736 1 : int tisci_cmd_proc_auth_boot_image(const struct device *dev, uint64_t *image_addr,
737 : uint32_t *image_size);
738 :
739 : /**
740 : * @brief Command to get the processor boot status
741 : *
742 : * @param dev Pointer to the TI SCI device
743 : * @param proc_id Processor ID this request is for
744 : * @param bv Pointer to store the boot vector
745 : * @param cfg_flags Pointer to store the configuration flags
746 : * @param ctrl_flags Pointer to store the control flags
747 : * @param sts_flags Pointer to store the status flags
748 : *
749 : * @return 0 if successful, or an error code
750 : */
751 1 : int tisci_cmd_get_proc_boot_status(const struct device *dev, uint8_t proc_id, uint64_t *bv,
752 : uint32_t *cfg_flags, uint32_t *ctrl_flags, uint32_t *sts_flags);
753 :
754 : /**
755 : * @brief Helper function to wait for a processor boot status without requesting or waiting for a
756 : * response
757 : *
758 : * @param dev Pointer to the TI SCI device
759 : * @param proc_id Processor ID this request is for
760 : * @param num_wait_iterations Total number of iterations to check before timeout
761 : * @param num_match_iterations Number of consecutive matches required to confirm status
762 : * @param delay_per_iteration_us Delay in microseconds between each status check
763 : * @param delay_before_iterations_us Delay in microseconds before the first status check
764 : * @param status_flags_1_set_all_wait Flags that must all be set to 1
765 : * @param status_flags_1_set_any_wait Flags where at least one must be set to 1
766 : * @param status_flags_1_clr_all_wait Flags that must all be cleared to 0
767 : * @param status_flags_1_clr_any_wait Flags where at least one must be cleared to 0
768 : *
769 : * @return 0 if successful, or an error code
770 : */
771 1 : int tisci_proc_wait_boot_status_no_wait(const struct device *dev, uint8_t proc_id,
772 : uint8_t num_wait_iterations, uint8_t num_match_iterations,
773 : uint8_t delay_per_iteration_us,
774 : uint8_t delay_before_iterations_us,
775 : uint32_t status_flags_1_set_all_wait,
776 : uint32_t status_flags_1_set_any_wait,
777 : uint32_t status_flags_1_clr_all_wait,
778 : uint32_t status_flags_1_clr_any_wait);
779 :
780 : /**
781 : * @brief Command to shutdown a core without requesting or waiting for a response
782 : *
783 : * @param dev Pointer to the TI SCI device
784 : * @param proc_id Processor ID this request is for
785 : *
786 : * @return 0 if successful, or an error code
787 : */
788 1 : int tisci_cmd_proc_shutdown_no_wait(const struct device *dev, uint8_t proc_id);
789 :
790 : /* Board Configuration Functions */
791 :
792 : /**
793 : * @brief Set board configuration using a specified message type
794 : *
795 : * Sends a board configuration message to the TI SCI firmware with configuration
796 : * data from a specified memory location.
797 : *
798 : * @param dev Pointer to the TI SCI device
799 : * @param msg_type TISCI message type for board configuration
800 : * @param addr Physical address of board configuration data
801 : * @param size Size of board configuration data in bytes
802 : *
803 : * @return 0 if successful, or an error code
804 : */
805 1 : int cmd_set_board_config_using_msg(const struct device *dev, uint16_t msg_type, uint64_t addr,
806 : uint32_t size);
807 :
808 : /* Ring Configuration Function */
809 :
810 : /**
811 : * @brief Configure a RA ring
812 : *
813 : * @param dev Pointer to the TI SCI device
814 : * @param valid_params Bitfield defining validity of ring configuration parameters
815 : * @param nav_id Device ID of Navigator Subsystem from which the ring is allocated
816 : * @param index Ring index
817 : * @param addr_lo The ring base address low 32 bits
818 : * @param addr_hi The ring base address high 32 bits
819 : * @param count Number of ring elements
820 : * @param mode The mode of the ring
821 : * @param size The ring element size
822 : * @param order_id Specifies the ring's bus order ID
823 : *
824 : * @return 0 if successful, or an error code
825 : */
826 1 : int tisci_cmd_ring_config(const struct device *dev, uint32_t valid_params, uint16_t nav_id,
827 : uint16_t index, uint32_t addr_lo, uint32_t addr_hi, uint32_t count,
828 : uint8_t mode, uint8_t size, uint8_t order_id);
829 :
830 : /* System Control Functions */
831 :
832 : /**
833 : * @brief Request a system reset
834 : *
835 : * Commands the TI SCI firmware to perform a system reset.
836 : *
837 : * @param dev Pointer to the TI SCI device
838 : *
839 : * @return 0 if successful, or an error code
840 : */
841 1 : int tisci_cmd_sys_reset(const struct device *dev);
842 :
843 : /* Memory Management Functions */
844 :
845 : /**
846 : * @brief Query the available MSMC memory range
847 : *
848 : * Queries the TI SCI firmware for the currently available MSMC (Multi-Standard
849 : * Shared Memory Controller) memory range.
850 : *
851 : * @param dev Pointer to the TI SCI device
852 : * @param msmc_start Pointer to store the MSMC start address
853 : * @param msmc_end Pointer to store the MSMC end address
854 : *
855 : * @return 0 if successful, or an error code
856 : */
857 1 : int tisci_cmd_query_msmc(const struct device *dev, uint64_t *msmc_start, uint64_t *msmc_end);
858 :
859 : /* Firewall Management Functions */
860 :
861 : /**
862 : * @brief Configure a firewall region
863 : *
864 : * Sets up a firewall region with the specified configuration parameters
865 : * including permissions, addresses, and control settings.
866 : *
867 : * @param dev Pointer to the TI SCI device
868 : * @param region Pointer to the firewall region configuration parameters
869 : *
870 : * @return 0 if successful, or an error code
871 : */
872 1 : int tisci_cmd_set_fwl_region(const struct device *dev, const struct tisci_msg_fwl_region *region);
873 :
874 : /* INCLUDE_ZEPHYR_DRIVERS_TISCI_H_ */
875 :
876 : /* Firewall Management Functions */
877 : /* ... previous firewall functions ... */
878 :
879 : /**
880 : * @brief Get firewall region configuration
881 : *
882 : * Retrieves the configuration of a firewall region including permissions,
883 : * addresses, and control settings.
884 : *
885 : * @param dev Pointer to the TI SCI device
886 : * @param region Pointer to store the firewall region configuration.
887 : * The fwl_id, region, and n_permission_regs fields must be
888 : * set before calling this function.
889 : *
890 : * @return 0 if successful, or an error code
891 : */
892 1 : int tisci_cmd_get_fwl_region(const struct device *dev, struct tisci_msg_fwl_region *region);
893 :
894 : /* Firewall Management Functions */
895 : /* ... previous firewall functions ... */
896 :
897 : /**
898 : * @brief Change firewall region owner
899 : *
900 : * Changes the ownership of a firewall region and retrieves updated
901 : * ownership information.
902 : *
903 : * @param dev Pointer to the TI SCI device
904 : * @param owner Pointer to firewall owner configuration.
905 : * On input: contains fwl_id, region, and owner_index
906 : * On output: contains updated ownership information
907 : *
908 : * @return 0 if successful, or an error code
909 : */
910 1 : int tisci_cmd_change_fwl_owner(const struct device *dev, struct tisci_msg_fwl_owner *owner);
911 :
912 : /* UDMAP Management Functions */
913 :
914 : /**
915 : * @brief Configure a UDMAP transmit channel
916 : *
917 : * Configures the non-real-time registers of a Navigator Subsystem UDMAP
918 : * transmit channel.
919 : *
920 : * @param dev Pointer to the TI SCI device
921 : * @param params Pointer to the transmit channel configuration parameters
922 : *
923 : * @return 0 if successful, or an error code
924 : */
925 1 : int tisci_cmd_rm_udmap_tx_ch_cfg(const struct device *dev,
926 : const struct tisci_msg_rm_udmap_tx_ch_cfg *params);
927 :
928 : /**
929 : * @brief Configure a UDMAP receive channel
930 : *
931 : * Configures the non-real-time registers of a Navigator Subsystem UDMAP
932 : * receive channel.
933 : *
934 : * @param dev Pointer to the TI SCI device
935 : * @param params Pointer to the receive channel configuration parameters
936 : *
937 : * @return 0 if successful, or an error code
938 : */
939 1 : int tisci_cmd_rm_udmap_rx_ch_cfg(const struct device *dev,
940 : const struct tisci_msg_rm_udmap_rx_ch_cfg *params);
941 :
942 : /* PSI-L Management Functions */
943 :
944 : /**
945 : * @brief Pair PSI-L source thread to destination thread
946 : *
947 : * Pairs a PSI-L source thread to a destination thread in the
948 : * Navigator Subsystem.
949 : *
950 : * @param dev Pointer to the TI SCI device
951 : * @param nav_id Navigator Subsystem device ID
952 : * @param src_thread Source thread ID
953 : * @param dst_thread Destination thread ID
954 : *
955 : * @return 0 if successful, or an error code
956 : */
957 1 : int tisci_cmd_rm_psil_pair(const struct device *dev, uint32_t nav_id, uint32_t src_thread,
958 : uint32_t dst_thread);
959 :
960 : /**
961 : * @brief Unpair PSI-L source thread from destination thread
962 : *
963 : * Unpairs a PSI-L source thread from a destination thread in the
964 : * Navigator Subsystem.
965 : *
966 : * @param dev Pointer to the TI SCI device
967 : * @param nav_id Navigator Subsystem device ID
968 : * @param src_thread Source thread ID
969 : * @param dst_thread Destination thread ID
970 : *
971 : * @return 0 if successful, or an error code
972 : */
973 1 : int tisci_cmd_rm_psil_unpair(const struct device *dev, uint32_t nav_id, uint32_t src_thread,
974 : uint32_t dst_thread);
975 :
976 : /**
977 : * @brief Set a Navigator Subsystem IRQ
978 : *
979 : * Sets up an interrupt route in the Navigator Subsystem using the provided request structure.
980 : *
981 : * @param dev Pointer to the TI SCI device
982 : * @param req Pointer to the IRQ set request structure
983 : *
984 : * @return 0 if successful, or an error code
985 : */
986 1 : int tisci_cmd_rm_irq_set(const struct device *dev, struct tisci_irq_set_req *req);
987 :
988 : /**
989 : * @brief Release a Navigator Subsystem IRQ
990 : *
991 : * Releases an interrupt route in the Navigator Subsystem using the provided request structure.
992 : *
993 : * @param dev Pointer to the TI SCI device
994 : * @param req Pointer to the IRQ release request structure
995 : *
996 : * @return 0 if successful, or an error code
997 : */
998 1 : int tisci_cmd_rm_irq_release(const struct device *dev, struct tisci_irq_release_req *req);
999 : #endif
|
