1 /*
2 * Copyright 2022 Intel Corporation
3 * Copyright 2023 Meta Platforms, Inc. and its affiliates
4 *
5 * SPDX-License-Identifier: Apache-2.0
6 */
7
8 #ifndef ZEPHYR_INCLUDE_DRIVERS_I3C_CCC_H_
9 #define ZEPHYR_INCLUDE_DRIVERS_I3C_CCC_H_
10
11 /**
12 * @brief I3C Common Command Codes
13 * @defgroup i3c_ccc I3C Common Command Codes
14 * @ingroup i3c_interface
15 * @{
16 */
17
18 #include <stdint.h>
19
20 #include <zephyr/device.h>
21 #include <zephyr/toolchain.h>
22 #include <zephyr/sys/util.h>
23
24 #ifdef __cplusplus
25 extern "C" {
26 #endif
27
28 /** Maximum CCC ID for broadcast */
29 #define I3C_CCC_BROADCAST_MAX_ID 0x7FU
30
31 /**
32 * Enable Events Command
33 *
34 * @param broadcast True if broadcast, false if direct.
35 */
36 #define I3C_CCC_ENEC(broadcast) ((broadcast) ? 0x00U : 0x80U)
37
38 /**
39 * Disable Events Command
40 *
41 * @param broadcast True if broadcast, false if direct.
42 */
43 #define I3C_CCC_DISEC(broadcast) ((broadcast) ? 0x01U : 0x81U)
44
45 /**
46 * Enter Activity State
47 *
48 * @param as Desired activity state
49 * @param broadcast True if broadcast, false if direct.
50 */
51 #define I3C_CCC_ENTAS(as, broadcast) (((broadcast) ? 0x02U : 0x82U) + (as))
52
53 /**
54 * Enter Activity State 0
55 *
56 * @param broadcast True if broadcast, false if direct.
57 */
58 #define I3C_CCC_ENTAS0(broadcast) I3C_CCC_ENTAS(0, broadcast)
59
60 /**
61 * Enter Activity State 1
62 *
63 * @param broadcast True if broadcast, false if direct.
64 */
65 #define I3C_CCC_ENTAS1(broadcast) I3C_CCC_ENTAS(1, broadcast)
66
67 /**
68 * Enter Activity State 2
69 *
70 * @param broadcast True if broadcast, false if direct.
71 */
72 #define I3C_CCC_ENTAS2(broadcast) I3C_CCC_ENTAS(2, broadcast)
73
74 /**
75 * Enter Activity State 3
76 *
77 * @param broadcast True if broadcast, false if direct.
78 */
79 #define I3C_CCC_ENTAS3(broadcast) I3C_CCC_ENTAS(3, broadcast)
80
81 /** Reset Dynamic Address Assignment (Broadcast) */
82 #define I3C_CCC_RSTDAA 0x06U
83
84 /** Enter Dynamic Address Assignment (Broadcast) */
85 #define I3C_CCC_ENTDAA 0x07U
86
87 /** Define List of Targets (Broadcast) */
88 #define I3C_CCC_DEFTGTS 0x08U
89
90 /**
91 * Set Max Write Length (Broadcast or Direct)
92 *
93 * @param broadcast True if broadcast, false if direct.
94 */
95 #define I3C_CCC_SETMWL(broadcast) ((broadcast) ? 0x09U : 0x89U)
96
97 /**
98 * Set Max Read Length (Broadcast or Direct)
99 *
100 * @param broadcast True if broadcast, false if direct.
101 */
102 #define I3C_CCC_SETMRL(broadcast) ((broadcast) ? 0x0AU : 0x8AU)
103
104 /** Enter Test Mode (Broadcast) */
105 #define I3C_CCC_ENTTM 0x0BU
106
107 /** Set Bus Context (Broadcast) */
108 #define I3C_CCC_SETBUSCON 0x0CU
109
110 /**
111 * Data Transfer Ending Procedure Control
112 *
113 * @param broadcast True if broadcast, false if direct.
114 */
115 #define I3C_CCC_ENDXFER(broadcast) ((broadcast) ? 0x12U : 0x92U)
116
117 /** Enter HDR Mode (HDR-DDR) (Broadcast) */
118 #define I3C_CCC_ENTHDR(x) (0x20U + (x))
119
120 /** Enter HDR Mode 0 (HDR-DDR) (Broadcast) */
121 #define I3C_CCC_ENTHDR0 0x20U
122
123 /** Enter HDR Mode 1 (HDR-TSP) (Broadcast) */
124 #define I3C_CCC_ENTHDR1 0x21U
125
126 /** Enter HDR Mode 2 (HDR-TSL) (Broadcast) */
127 #define I3C_CCC_ENTHDR2 0x22U
128
129 /** Enter HDR Mode 3 (HDR-BT) (Broadcast) */
130 #define I3C_CCC_ENTHDR3 0x23U
131
132 /** Enter HDR Mode 4 (Broadcast) */
133 #define I3C_CCC_ENTHDR4 0x24U
134
135 /** Enter HDR Mode 5 (Broadcast) */
136 #define I3C_CCC_ENTHDR5 0x25U
137
138 /** Enter HDR Mode 6 (Broadcast) */
139 #define I3C_CCC_ENTHDR6 0x26U
140
141 /** Enter HDR Mode 7 (Broadcast) */
142 #define I3C_CCC_ENTHDR7 0x27U
143
144 /**
145 * Exchange Timing Information (Broadcast or Direct)
146 *
147 * @param broadcast True if broadcast, false if direct.
148 */
149 #define I3C_CCC_SETXTIME(broadcast) ((broadcast) ? 0x28U : 0x98U)
150
151 /** Set All Addresses to Static Addresses (Broadcast) */
152 #define I3C_CCC_SETAASA 0x29U
153
154 /**
155 * Target Reset Action
156 *
157 * @param broadcast True if broadcast, false if direct.
158 */
159 #define I3C_CCC_RSTACT(broadcast) ((broadcast) ? 0x2AU : 0x9AU)
160
161 /** Define List of Group Address (Broadcast) */
162 #define I3C_CCC_DEFGRPA 0x2BU
163
164 /**
165 * Reset Group Address
166 *
167 * @param broadcast True if broadcast, false if direct.
168 */
169 #define I3C_CCC_RSTGRPA(broadcast) ((broadcast) ? 0x2CU : 0x9CU)
170
171 /** Multi-Lane Data Transfer Control (Broadcast) */
172 #define I3C_CCC_MLANE(broadcast) ((broadcast) ? 0x2DU : 0x9DU)
173
174 /**
175 * Vendor/Standard Extension
176 *
177 * @param broadcast True if broadcast, false if direct.
178 * @param id Extension ID.
179 */
180 #define I3C_CCC_VENDOR(broadcast, id) ((id) + ((broadcast) ? 0x61U : 0xE0U))
181
182 /** Set Dynamic Address from Static Address (Direct) */
183 #define I3C_CCC_SETDASA 0x87U
184
185 /** Set New Dynamic Address (Direct) */
186 #define I3C_CCC_SETNEWDA 0x88U
187
188 /** Get Max Write Length (Direct) */
189 #define I3C_CCC_GETMWL 0x8BU
190
191 /** Get Max Read Length (Direct) */
192 #define I3C_CCC_GETMRL 0x8CU
193
194 /** Get Provisioned ID (Direct) */
195 #define I3C_CCC_GETPID 0x8DU
196
197 /** Get Bus Characteristics Register (Direct) */
198 #define I3C_CCC_GETBCR 0x8EU
199
200 /** Get Device Characteristics Register (Direct) */
201 #define I3C_CCC_GETDCR 0x8FU
202
203 /** Get Device Status (Direct) */
204 #define I3C_CCC_GETSTATUS 0x90U
205
206 /** Get Accept Controller Role (Direct) */
207 #define I3C_CCC_GETACCCR 0x91U
208
209 /** Set Bridge Targets (Direct) */
210 #define I3C_CCC_SETBRGTGT 0x93U
211
212 /** Get Max Data Speed (Direct) */
213 #define I3C_CCC_GETMXDS 0x94U
214
215 /** Get Optional Feature Capabilities (Direct) */
216 #define I3C_CCC_GETCAPS 0x95U
217
218 /** Set Route (Direct) */
219 #define I3C_CCC_SETROUTE 0x96U
220
221 /** Device to Device(s) Tunneling Control (Direct) */
222 #define I3C_CCC_D2DXFER 0x97U
223
224 /** Get Exchange Timing Information (Direct) */
225 #define I3C_CCC_GETXTIME 0x99U
226
227 /** Set Group Address (Direct) */
228 #define I3C_CCC_SETGRPA 0x9BU
229
230 struct i3c_device_desc;
231
232 /**
233 * @brief Payload structure for Direct CCC to one target.
234 */
235 struct i3c_ccc_target_payload {
236 /** Target address */
237 uint8_t addr;
238
239 /** @c 0 for Write, @c 1 for Read */
240 uint8_t rnw:1;
241
242 /**
243 * - For Write CCC, pointer to the byte array of data
244 * to be sent, which may contain the Sub-Command Byte
245 * and additional data.
246 * - For Read CCC, pointer to the byte buffer for data
247 * to be read into.
248 */
249 uint8_t *data;
250
251 /** Length in bytes for @p data. */
252 size_t data_len;
253
254 /**
255 * Total number of bytes transferred
256 *
257 * A Target can issue an EoD or the Controller can abort a transfer
258 * before the length of the buffer. It is expected for the driver to
259 * write to this after the transfer.
260 */
261 size_t num_xfer;
262 };
263
264 /**
265 * @brief Payload structure for one CCC transaction.
266 */
267 struct i3c_ccc_payload {
268 struct {
269 /**
270 * The CCC ID (@c I3C_CCC_*).
271 */
272 uint8_t id;
273
274 /**
275 * Pointer to byte array of data for this CCC.
276 *
277 * This is the bytes following the CCC command in CCC frame.
278 * Set to @c NULL if no associated data.
279 */
280 uint8_t *data;
281
282 /** Length in bytes for optional data array. */
283 size_t data_len;
284
285 /**
286 * Total number of bytes transferred
287 *
288 * A Controller can abort a transfer before the length of the buffer.
289 * It is expected for the driver to write to this after the transfer.
290 */
291 size_t num_xfer;
292 } ccc;
293
294 struct {
295 /**
296 * Array of struct i3c_ccc_target_payload.
297 *
298 * Each element describes the target and associated
299 * payloads for this CCC.
300 *
301 * Use with Direct CCC.
302 */
303 struct i3c_ccc_target_payload *payloads;
304
305 /** Number of targets */
306 size_t num_targets;
307 } targets;
308 };
309
310 /**
311 * @brief Payload for ENEC/DISEC CCC (Target Events Command).
312 */
313 struct i3c_ccc_events {
314 /**
315 * Event byte:
316 * - Bit[0]: ENINT/DISINT:
317 * - Target Interrupt Requests
318 * - Bit[1]: ENCR/DISCR:
319 * - Controller Role Requests
320 * - Bit[3]: ENHJ/DISHJ:
321 * - Hot-Join Event
322 */
323 uint8_t events;
324 } __packed;
325
326 /** Enable Events (ENEC) - Target Interrupt Requests. */
327 #define I3C_CCC_ENEC_EVT_ENINTR BIT(0)
328
329 /** Enable Events (ENEC) - Controller Role Requests. */
330 #define I3C_CCC_ENEC_EVT_ENCR BIT(1)
331
332 /** Enable Events (ENEC) - Hot-Join Event. */
333 #define I3C_CCC_ENEC_EVT_ENHJ BIT(3)
334
335 #define I3C_CCC_ENEC_EVT_ALL \
336 (I3C_CCC_ENEC_EVT_ENINTR | I3C_CCC_ENEC_EVT_ENCR | I3C_CCC_ENEC_EVT_ENHJ)
337
338 /** Disable Events (DISEC) - Target Interrupt Requests. */
339 #define I3C_CCC_DISEC_EVT_DISINTR BIT(0)
340
341 /** Disable Events (DISEC) - Controller Role Requests. */
342 #define I3C_CCC_DISEC_EVT_DISCR BIT(1)
343
344 /** Disable Events (DISEC) - Hot-Join Event. */
345 #define I3C_CCC_DISEC_EVT_DISHJ BIT(3)
346
347 #define I3C_CCC_DISEC_EVT_ALL \
348 (I3C_CCC_DISEC_EVT_DISINTR | I3C_CCC_DISEC_EVT_DISCR | I3C_CCC_DISEC_EVT_DISHJ)
349
350 /*
351 * Events for both enabling and disabling since
352 * they have the same bits.
353 */
354
355 /** Events - Target Interrupt Requests. */
356 #define I3C_CCC_EVT_INTR BIT(0)
357
358 /** Events - Controller Role Requests. */
359 #define I3C_CCC_EVT_CR BIT(1)
360
361 /** Events - Hot-Join Event. */
362 #define I3C_CCC_EVT_HJ BIT(3)
363
364 /** Bitmask for all events. */
365 #define I3C_CCC_EVT_ALL \
366 (I3C_CCC_EVT_INTR | I3C_CCC_EVT_CR | I3C_CCC_EVT_HJ)
367
368 /**
369 * @brief Payload for SETMWL/GETMWL CCC (Set/Get Maximum Write Length).
370 *
371 * @note For drivers and help functions, the raw data coming
372 * back from target device is in big endian. This needs to be
373 * translated back to CPU endianness before passing back to
374 * function caller.
375 */
376 struct i3c_ccc_mwl {
377 /** Maximum Write Length */
378 uint16_t len;
379 } __packed;
380
381 /**
382 * @brief Payload for SETMRL/GETMRL CCC (Set/Get Maximum Read Length).
383 *
384 * @note For drivers and help functions, the raw data coming
385 * back from target device is in big endian. This needs to be
386 * translated back to CPU endianness before passing back to
387 * function caller.
388 */
389 struct i3c_ccc_mrl {
390 /** Maximum Read Length */
391 uint16_t len;
392
393 /** Optional IBI Payload Size */
394 uint8_t ibi_len;
395 } __packed;
396
397 /**
398 * @brief The active controller part of payload for DEFTGTS CCC.
399 *
400 * This is used by DEFTGTS (Define List of Targets) CCC to describe
401 * the active controller on the I3C bus.
402 */
403 struct i3c_ccc_deftgts_active_controller {
404 /** Dynamic Address of Active Controller */
405 uint8_t addr;
406
407 /** Device Characteristic Register of Active Controller */
408 uint8_t dcr;
409
410 /** Bus Characteristic Register of Active Controller */
411 uint8_t bcr;
412
413 /** Static Address of Active Controller */
414 uint8_t static_addr;
415 };
416
417 /**
418 * @brief The target device part of payload for DEFTGTS CCC.
419 *
420 * This is used by DEFTGTS (Define List of Targets) CCC to describe
421 * the existing target devices on the I3C bus.
422 */
423 struct i3c_ccc_deftgts_target {
424 /** Dynamic Address of a target device, or a group address */
425 uint8_t addr;
426
427 union {
428 /**
429 * Device Characteristic Register of a I3C target device
430 * or a group.
431 */
432 uint8_t dcr;
433
434 /** Legacy Virtual Register for legacy I2C device. */
435 uint8_t lvr;
436 };
437
438 /** Bus Characteristic Register of a target device or a group */
439 uint8_t bcr;
440
441 /** Static Address of a target device or a group */
442 uint8_t static_addr;
443 };
444
445 /**
446 * @brief Payload for DEFTGTS CCC (Define List of Targets).
447 *
448 * @note @p i3c_ccc_deftgts_target is an array of targets, where
449 * the number of elements is dependent on the number of I3C targets
450 * on the bus. Please have enough space for both read and write of
451 * this CCC.
452 */
453 struct i3c_ccc_deftgts {
454 /** Data describing the active controller */
455 struct i3c_ccc_deftgts_active_controller active_controller;
456
457 /** Data describing the target(s) on the bus */
458 struct i3c_ccc_deftgts_target targets[];
459 } __packed;
460
461 /**
462 * @brief Payload for a single device address.
463 *
464 * This is used for:
465 * - SETDASA (Set Dynamic Address from Static Address)
466 * - SETNEWDA (Set New Dynamic Address)
467 * - SETGRPA (Set Group Address)
468 * - GETACCCR (Get Accept Controller Role)
469 *
470 * Note that the target address is encoded within
471 * struct i3c_ccc_target_payload instead of being encoded in
472 * this payload.
473 */
474 struct i3c_ccc_address {
475 /**
476 * - For SETDASA, Static Address to be assigned as
477 * Dynamic Address.
478 * - For SETNEWDA, new Dynamic Address to be assigned.
479 * - For SETGRPA, new Group Address to be set.
480 * - For GETACCCR, the correct address of Secondary
481 * Controller.
482 *
483 * @note For SETDATA, SETNEWDA and SETGRAP,
484 * the address is left-shift by 1, and bit[0] is always 0.
485 *
486 * @note Fpr SET GETACCCR, the address is left-shift by 1,
487 * and bit[0] is the calculated odd parity bit.
488 */
489 uint8_t addr;
490 } __packed;
491
492 /**
493 * @brief Payload for GETPID CCC (Get Provisioned ID).
494 */
495 struct i3c_ccc_getpid {
496 /**
497 * 48-bit Provisioned ID.
498 *
499 * @note Data is big-endian where first byte is MSB.
500 */
501 uint8_t pid[6];
502 } __packed;
503
504 /**
505 * @brief Payload for GETBCR CCC (Get Bus Characteristics Register).
506 */
507 struct i3c_ccc_getbcr {
508 /** Bus Characteristics Register */
509 uint8_t bcr;
510 } __packed;
511
512 /**
513 * @brief Payload for GETDCR CCC (Get Device Characteristics Register).
514 */
515 struct i3c_ccc_getdcr {
516 /** Device Characteristics Register */
517 uint8_t dcr;
518 } __packed;
519
520
521 /**
522 * @brief Indicate which format of GETSTATUS to use.
523 */
524 enum i3c_ccc_getstatus_fmt {
525 /** GETSTATUS Format 1 */
526 GETSTATUS_FORMAT_1,
527
528 /** GETSTATUS Format 2 */
529 GETSTATUS_FORMAT_2,
530 };
531
532 /**
533 * @brief Defining byte values for GETSTATUS Format 2.
534 */
535 enum i3c_ccc_getstatus_defbyte {
536 /** Target status. */
537 GETSTATUS_FORMAT_2_TGTSTAT = 0x00U,
538
539 /** PRECR - Alternate status format describing Controller-capable device. */
540 GETSTATUS_FORMAT_2_PRECR = 0x91U,
541
542 /** Invalid defining byte. */
543 GETSTATUS_FORMAT_2_INVALID = 0x100U
544 };
545
546 /**
547 * @brief Payload for GETSTATUS CCC (Get Device Status).
548 */
549 union i3c_ccc_getstatus {
550 struct {
551 /**
552 * Device Status
553 * - Bit[15:8]: Reserved.
554 * - Bit[7:6]: Activity Mode.
555 * - Bit[5]: Protocol Error.
556 * - Bit[4]: Reserved.
557 * - Bit[3:0]: Number of Pending Interrupts.
558 *
559 * @note For drivers and help functions, the raw data coming
560 * back from target device is in big endian. This needs to be
561 * translated back to CPU endianness before passing back to
562 * function caller.
563 */
564 uint16_t status;
565 } fmt1;
566
567 union {
568 /**
569 * Defining Byte 0x00: TGTSTAT
570 *
571 * @see i3c_ccc_getstatus::fmt1::status
572 */
573 uint16_t tgtstat;
574
575 /**
576 * Defining Byte 0x91: PRECR
577 * - Bit[15:8]: Vendor Reserved
578 * - Bit[7:2]: Reserved
579 * - Bit[1]: Handoff Delay NACK
580 * - Bit[0]: Deep Sleep Detected
581 *
582 * @note For drivers and help functions, the raw data coming
583 * back from target device is in big endian. This needs to be
584 * translated back to CPU endianness before passing back to
585 * function caller.
586 */
587 uint16_t precr;
588
589 uint16_t raw_u16;
590 } fmt2;
591 } __packed;
592
593 /** GETSTATUS Format 1 - Protocol Error bit. */
594 #define I3C_CCC_GETSTATUS_PROTOCOL_ERR BIT(5)
595
596 /** GETSTATUS Format 1 - Activity Mode bitmask. */
597 #define I3C_CCC_GETSTATUS_ACTIVITY_MODE_MASK GENMASK(7U, 6U)
598
599 /**
600 * @brief GETSTATUS Format 1 - Activity Mode
601 *
602 * Obtain Activity Mode from GETSTATUS Format 1 value obtained via
603 * GETSTATUS.
604 *
605 * @param status GETSTATUS Format 1 value
606 */
607 #define I3C_CCC_GETSTATUS_ACTIVITY_MODE(status) \
608 FIELD_GET(I3C_CCC_GETSTATUS_ACTIVITY_MODE_MASK, (status))
609
610 /** GETSTATUS Format 1 - Number of Pending Interrupts bitmask. */
611 #define I3C_CCC_GETSTATUS_NUM_INT_MASK GENMASK(3U, 0U)
612
613 /**
614 * @brief GETSTATUS Format 1 - Number of Pending Interrupts
615 *
616 * Obtain Number of Pending Interrupts from GETSTATUS Format 1 value
617 * obtained via GETSTATUS.
618 *
619 * @param status GETSTATUS Format 1 value
620 */
621 #define I3C_CCC_GETSTATUS_NUM_INT(status) \
622 FIELD_GET(I3C_CCC_GETSTATUS_NUM_INT_MASK, (status))
623
624 /** GETSTATUS Format 2 - PERCR - Deep Sleep Detected bit. */
625 #define I3C_CCC_GETSTATUS_PRECR_DEEP_SLEEP_DETECTED BIT(0)
626
627 /** GETSTATUS Format 2 - PERCR - Handoff Delay NACK. */
628 #define I3C_CCC_GETSTATUS_PRECR_HANDOFF_DELAY_NACK BIT(1)
629
630 /**
631 * @brief One Bridged Target for SETBRGTGT payload.
632 */
633 struct i3c_ccc_setbrgtgt_tgt {
634 /**
635 * Dynamic address of the bridged target.
636 *
637 * @note The address is left-shift by 1, and bit[0]
638 * is always 0.
639 */
640 uint8_t addr;
641
642 /**
643 * 16-bit ID for the bridged target.
644 *
645 * @note For drivers and help functions, the raw data coming
646 * back from target device is in big endian. This needs to be
647 * translated back to CPU endianness before passing back to
648 * function caller.
649 */
650 uint16_t id;
651 } __packed;
652
653 /**
654 * @brief Payload for SETBRGTGT CCC (Set Bridge Targets).
655 *
656 * Note that the bridge target address is encoded within
657 * struct i3c_ccc_target_payload instead of being encoded in
658 * this payload.
659 */
660 struct i3c_ccc_setbrgtgt {
661 /** Number of bridged targets */
662 uint8_t count;
663
664 /** Array of bridged targets */
665 struct i3c_ccc_setbrgtgt_tgt targets[];
666 } __packed;
667
668 /**
669 * @brief Payload for GETMXDS CCC (Get Max Data Speed).
670 *
671 * @note This is only for GETMXDS Format 1 and Format 2.
672 */
673 union i3c_ccc_getmxds {
674 struct {
675 /** maxWr */
676 uint8_t maxwr;
677
678 /** maxRd */
679 uint8_t maxrd;
680 } fmt1;
681
682 struct {
683 /** maxWr */
684 uint8_t maxwr;
685
686 /** maxRd */
687 uint8_t maxrd;
688
689 /**
690 * Maximum Read Turnaround Time in microsecond.
691 *
692 * This is in little-endian where first byte is LSB.
693 */
694 uint8_t maxrdturn[3];
695 } fmt2;
696
697 struct {
698 /**
699 * Defining Byte 0x00: WRRDTURN
700 *
701 * @see i3c_ccc_getmxds::fmt2
702 */
703 uint8_t wrrdturn;
704
705 /**
706 * Defining Byte 0x91: CRHDLY
707 * - Bit[2]: Set Bus Activity State
708 * - Bit[1:0]: Controller Handoff Activity State
709 */
710 uint8_t crhdly1;
711 } fmt3;
712 } __packed;
713
714 /** Get Max Data Speed (GETMXDS) - Default Max Sustained Data Rate. */
715 #define I3C_CCC_GETMXDS_MAX_SDR_FSCL_MAX 0
716
717 /** Get Max Data Speed (GETMXDS) - 8MHz Max Sustained Data Rate. */
718 #define I3C_CCC_GETMXDS_MAX_SDR_FSCL_8MHZ 1
719
720 /** Get Max Data Speed (GETMXDS) - 6MHz Max Sustained Data Rate. */
721 #define I3C_CCC_GETMXDS_MAX_SDR_FSCL_6MHZ 2
722
723 /** Get Max Data Speed (GETMXDS) - 4MHz Max Sustained Data Rate. */
724 #define I3C_CCC_GETMXDS_MAX_SDR_FSCL_4MHZ 3
725
726 /** Get Max Data Speed (GETMXDS) - 2MHz Max Sustained Data Rate. */
727 #define I3C_CCC_GETMXDS_MAX_SDR_FSCL_2MHZ 4
728
729 /** Get Max Data Speed (GETMXDS) - Clock to Data Turnaround <= 8ns. */
730 #define I3C_CCC_GETMXDS_TSCO_8NS 0
731
732 /** Get Max Data Speed (GETMXDS) - Clock to Data Turnaround <= 9ns. */
733 #define I3C_CCC_GETMXDS_TSCO_9NS 1
734
735 /** Get Max Data Speed (GETMXDS) - Clock to Data Turnaround <= 10ns. */
736 #define I3C_CCC_GETMXDS_TSCO_10NS 2
737
738 /** Get Max Data Speed (GETMXDS) - Clock to Data Turnaround <= 11ns. */
739 #define I3C_CCC_GETMXDS_TSCO_11NS 3
740
741 /** Get Max Data Speed (GETMXDS) - Clock to Data Turnaround <= 12ns. */
742 #define I3C_CCC_GETMXDS_TSCO_12NS 4
743
744 /** Get Max Data Speed (GETMXDS) - Clock to Data Turnaround > 12ns. */
745 #define I3C_CCC_GETMXDS_TSCO_GT_12NS 7
746
747 /** Get Max Data Speed (GETMXDS) - maxWr - Optional Defining Byte Support. */
748 #define I3C_CCC_GETMXDS_MAXWR_DEFINING_BYTE_SUPPORT BIT(3)
749
750 /** Get Max Data Speed (GETMXDS) - Max Sustained Data Rate bitmask. */
751 #define I3C_CCC_GETMXDS_MAXWR_MAX_SDR_FSCL_MASK GENMASK(2U, 0U)
752
753 /**
754 * @brief Get Max Data Speed (GETMXDS) - maxWr - Max Sustained Data Rate
755 *
756 * Obtain Max Sustained Data Rate value from GETMXDS maxWr value
757 * obtained via GETMXDS.
758 *
759 * @param maxwr GETMXDS maxWr value.
760 */
761 #define I3C_CCC_GETMXDS_MAXWR_MAX_SDR_FSCL(maxwr) \
762 FIELD_GET(I3C_CCC_GETMXDS_MAXWR_MAX_SDR_FSCL_MASK, (maxwr))
763
764 /** Get Max Data Speed (GETMXDS) - maxRd - Write-to-Read Permits Stop Between. */
765 #define I3C_CCC_GETMXDS_MAXRD_W2R_PERMITS_STOP_BETWEEN BIT(6)
766
767 /** Get Max Data Speed (GETMXDS) - maxRd - Clock to Data Turnaround bitmask. */
768 #define I3C_CCC_GETMXDS_MAXRD_TSCO_MASK GENMASK(5U, 3U)
769
770 /**
771 * @brief Get Max Data Speed (GETMXDS) - maxRd - Clock to Data Turnaround
772 *
773 * Obtain Clock to Data Turnaround value from GETMXDS maxRd value
774 * obtained via GETMXDS.
775 *
776 * @param maxrd GETMXDS maxRd value.
777 */
778 #define I3C_CCC_GETMXDS_MAXRD_TSCO(maxrd) \
779 FIELD_GET(I3C_CCC_GETMXDS_MAXRD_TSCO_MASK, (maxrd))
780
781 /** Get Max Data Speed (GETMXDS) - maxRd - Max Sustained Data Rate bitmask. */
782 #define I3C_CCC_GETMXDS_MAXRD_MAX_SDR_FSCL_MASK GENMASK(2U, 0U)
783
784 /**
785 * @brief Get Max Data Speed (GETMXDS) - maxRd - Max Sustained Data Rate
786 *
787 * Obtain Max Sustained Data Rate value from GETMXDS maxRd value
788 * obtained via GETMXDS.
789 *
790 * @param maxrd GETMXDS maxRd value.
791 */
792 #define I3C_CCC_GETMXDS_MAXRD_MAX_SDR_FSCL(maxrd) \
793 FIELD_GET(I3C_CCC_GETMXDS_MAXRD_MAX_SDR_FSCL_MASK, (maxrd))
794
795 /** Get Max Data Speed (GETMXDS) - CRDHLY1 - Set Bus Activity State bit shift value. */
796 #define I3C_CCC_GETMXDS_CRDHLY1_SET_BUS_ACT_STATE BIT(2)
797
798 /** Get Max Data Speed (GETMXDS) - CRDHLY1 - Controller Handoff Activity State bitmask. */
799 #define I3C_CCC_GETMXDS_CRDHLY1_CTRL_HANDOFF_ACT_STATE_MASK GENMASK(1U, 0U)
800
801 /**
802 * @brief Get Max Data Speed (GETMXDS) - CRDHLY1 - Controller Handoff Activity State
803 *
804 * Obtain Controller Handoff Activity State value from GETMXDS value
805 * obtained via GETMXDS.
806 *
807 * @param crhdly1 GETMXDS value.
808 */
809 #define I3C_CCC_GETMXDS_CRDHLY1_CTRL_HANDOFF_ACT_STATE(crhdly1) \
810 FIELD_GET(I3C_CCC_GETMXDS_CRDHLY1_CTRL_HANDOFF_ACT_STATE_MASK, (chrdly1))
811
812 /**
813 * @brief Indicate which format of GETCAPS to use.
814 */
815 enum i3c_ccc_getcaps_fmt {
816 /** GETCAPS Format 1 */
817 GETCAPS_FORMAT_1,
818
819 /** GETCAPS Format 2 */
820 GETCAPS_FORMAT_2,
821 };
822
823 /**
824 * @brief Enum for I3C Get Capabilities (GETCAPS) Format 2 Defining Byte Values.
825 */
826 enum i3c_ccc_getcaps_defbyte {
827 /** Standard Target capabilities and features. */
828 GETCAPS_FORMAT_2_TGTCAPS = 0x00U,
829
830 /** Fixed 32b test pattern. */
831 GETCAPS_FORMAT_2_TESTPAT = 0x5AU,
832
833 /** Controller handoff capabilities and features. */
834 GETCAPS_FORMAT_2_CRCAPS = 0x91U,
835
836 /** Virtual Target capabilities and features. */
837 GETCAPS_FORMAT_2_VTCAPS = 0x93U,
838
839 /** Debug-capable Device capabilities and features. */
840 GETCAPS_FORMAT_2_DBGCAPS = 0xD7U,
841
842 /** Invalid defining byte. */
843 GETCAPS_FORMAT_2_INVALID = 0x100,
844 };
845
846 /**
847 * @brief Payload for GETCAPS CCC (Get Optional Feature Capabilities).
848 *
849 * @note Only supports GETCAPS Format 1 and Format 2. In I3C v1.0 this was
850 * GETHDRCAP which only returned a single byte which is the same as the
851 * GETCAPS1 byte.
852 */
853 union i3c_ccc_getcaps {
854 union {
855 /**
856 * I3C v1.0 HDR Capabilities
857 * - Bit[0]: HDR-DDR
858 * - Bit[1]: HDR-TSP
859 * - Bit[2]: HDR-TSL
860 * - Bit[7:3]: Reserved
861 */
862 uint8_t gethdrcap;
863
864 /**
865 * I3C v1.1+ Device Capabilities
866 * Byte 1 GETCAPS1
867 * - Bit[0]: HDR-DDR
868 * - Bit[1]: HDR-TSP
869 * - Bit[2]: HDR-TSL
870 * - Bit[3]: HDR-BT
871 * - Bit[7:4]: Reserved
872 * Byte 2 GETCAPS2
873 * - Bit[3:0]: I3C 1.x Specification Version
874 * - Bit[5:4]: Group Address Capabilities
875 * - Bit[6]: HDR-DDR Write Abort
876 * - Bit[7]: HDR-DDR Abort CRC
877 * Byte 3 GETCAPS3
878 * - Bit[0]: Multi-Lane (ML) Data Transfer Support
879 * - Bit[1]: Device to Device Transfer (D2DXFER) Support
880 * - Bit[2]: Device to Device Transfer (D2DXFER) IBI Capable
881 * - Bit[3]: Defining Byte Support in GETCAPS
882 * - Bit[4]: Defining Byte Support in GETSTATUS
883 * - Bit[5]: HDR-BT CRC-32 Support
884 * - Bit[6]: IBI MDB Support for Pending Read Notification
885 * - Bit[7]: Reserved
886 * Byte 4 GETCAPS4
887 * - Bit[7:0]: Reserved
888 */
889 uint8_t getcaps[4];
890 } fmt1;
891
892 union {
893 /**
894 * Defining Byte 0x00: TGTCAPS
895 *
896 * @see i3c_ccc_getcaps::fmt1::getcaps
897 */
898 uint8_t tgtcaps[4];
899
900 /**
901 * Defining Byte 0x5A: TESTPAT
902 *
903 * @note should always be 0xA55AA55A in big endian
904 */
905 uint32_t testpat;
906
907 /**
908 * Defining Byte 0x91: CRCAPS
909 * Byte 1 CRCAPS1
910 * - Bit[0]: Hot-Join Support
911 * - Bit[1]: Group Management Support
912 * - Bit[2]: Multi-Lane Support
913 * Byte 2 CRCAPS2
914 * - Bit[0]: In-Band Interrupt Support
915 * - Bit[1]: Controller Pass-Back
916 * - Bit[2]: Deep Sleep Capable
917 * - Bit[3]: Delayed Controller Handoff
918 */
919 uint8_t crcaps[2];
920
921 /**
922 * Defining Byte 0x93: VTCAPS
923 * Byte 1 VTCAPS1
924 * - Bit[2:0]: Virtual Target Type
925 * - Bit[4]: Side Effects
926 * - Bit[5]: Shared Peripheral Detect
927 * Byte 2 VTCAPS2
928 * - Bit[1:0]: Interrupt Requests
929 * - Bit[2]: Address Remapping
930 * - Bit[4:3]: Bus Context and Conditions
931 */
932 uint8_t vtcaps[2];
933 } fmt2;
934 } __packed;
935
936 /** Get Optional Feature Capabilities Byte 1 (GETCAPS) Format 1 - HDR-DDR mode bit. */
937 #define I3C_CCC_GETCAPS1_HDR_DDR BIT(0)
938
939 /** Get Optional Feature Capabilities Byte 1 (GETCAPS) Format 1 - HDR-TSP mode bit. */
940 #define I3C_CCC_GETCAPS1_HDR_TSP BIT(1)
941
942 /** Get Optional Feature Capabilities Byte 1 (GETCAPS) Format 1 - HDR-TSL mode bit. */
943 #define I3C_CCC_GETCAPS1_HDR_TSL BIT(2)
944
945 /** Get Optional Feature Capabilities Byte 1 (GETCAPS) Format 1 - HDR-BT mode bit. */
946 #define I3C_CCC_GETCAPS1_HDR_BT BIT(3)
947
948 /**
949 * @brief Get Optional Feature Capabilities Byte 1 (GETCAPS) - HDR Mode
950 *
951 * Get the bit corresponding to HDR mode.
952 *
953 * @param x HDR mode
954 */
955 #define I3C_CCC_GETCAPS1_HDR_MODE(x) BIT(x)
956
957 /** Get Optional Feature Capabilities Byte 1 (GETCAPS) Format 1 - HDR Mode 0. */
958 #define I3C_CCC_GETCAPS1_HDR_MODE0 BIT(0)
959
960 /** Get Optional Feature Capabilities Byte 1 (GETCAPS) Format 1 - HDR Mode 1. */
961 #define I3C_CCC_GETCAPS1_HDR_MODE1 BIT(1)
962
963 /** Get Optional Feature Capabilities Byte 1 (GETCAPS) Format 1 - HDR Mode 2. */
964 #define I3C_CCC_GETCAPS1_HDR_MODE2 BIT(2)
965
966 /** Get Optional Feature Capabilities Byte 1 (GETCAPS) Format 1 - HDR Mode 3. */
967 #define I3C_CCC_GETCAPS1_HDR_MODE3 BIT(3)
968
969 /** Get Optional Feature Capabilities Byte 1 (GETCAPS) Format 1 - HDR Mode 4. */
970 #define I3C_CCC_GETCAPS1_HDR_MODE4 BIT(4)
971
972 /** Get Optional Feature Capabilities Byte 1 (GETCAPS) Format 1 - HDR Mode 5. */
973 #define I3C_CCC_GETCAPS1_HDR_MODE5 BIT(5)
974
975 /** Get Optional Feature Capabilities Byte 1 (GETCAPS) Format 1 - HDR Mode 6. */
976 #define I3C_CCC_GETCAPS1_HDR_MODE6 BIT(6)
977
978 /** Get Optional Feature Capabilities Byte 1 (GETCAPS) Format 1 - HDR Mode 7. */
979 #define I3C_CCC_GETCAPS1_HDR_MODE7 BIT(7)
980
981 /** Get Optional Feature Capabilities Byte 2 (GETCAPS) Format 1 - HDR-DDR Write Abort bit. */
982 #define I3C_CCC_GETCAPS2_HDRDDR_WRITE_ABORT BIT(6)
983
984 /** Get Optional Feature Capabilities Byte 2 (GETCAPS) Format 1 - HDR-DDR Abort CRC bit. */
985 #define I3C_CCC_GETCAPS2_HDRDDR_ABORT_CRC BIT(7)
986
987 /**
988 * @brief Get Optional Feature Capabilities Byte 2 (GETCAPS) Format 1 -
989 * Group Address Capabilities bitmask.
990 */
991 #define I3C_CCC_GETCAPS2_GRPADDR_CAP_MASK GENMASK(5U, 4U)
992
993 /**
994 * @brief Get Optional Feature Capabilities Byte 2 (GETCAPS) Format 1 - Group Address Capabilities.
995 *
996 * Obtain Group Address Capabilities value from GETCAPS Format 1 value
997 * obtained via GETCAPS.
998 *
999 * @param getcaps2 GETCAPS2 value.
1000 */
1001 #define I3C_CCC_GETCAPS2_GRPADDR_CAP(getcaps2) \
1002 FIELD_GET(I3C_CCC_GETCAPS2_GRPADDR_CAP_MASK, (getcaps2))
1003
1004 /**
1005 * @brief Get Optional Feature Capabilities Byte 2 (GETCAPS) Format 1 -
1006 * I3C 1.x Specification Version bitmask.
1007 */
1008 #define I3C_CCC_GETCAPS2_SPEC_VER_MASK GENMASK(3U, 0U)
1009
1010 /**
1011 * @brief Get Optional Feature Capabilities Byte 2 (GETCAPS) Format 1 -
1012 * I3C 1.x Specification Version.
1013 *
1014 * Obtain I3C 1.x Specification Version value from GETCAPS Format 1 value
1015 * obtained via GETCAPS.
1016 *
1017 * @param getcaps2 GETCAPS2 value.
1018 */
1019 #define I3C_CCC_GETCAPS2_SPEC_VER(getcaps2) \
1020 FIELD_GET(I3C_CCC_GETCAPS2_SPEC_VER_MASK, (getcaps2))
1021
1022 /**
1023 * @brief Get Optional Feature Capabilities Byte 3 (GETCAPS) Format 1 -
1024 * Multi-Lane Data Transfer Support bit.
1025 */
1026 #define I3C_CCC_GETCAPS3_MLANE_SUPPORT BIT(0)
1027
1028 /**
1029 * @brief Get Optional Feature Capabilities Byte 3 (GETCAPS) Format 1 -
1030 * Device to Device Transfer (D2DXFER) Support bit.
1031 */
1032 #define I3C_CCC_GETCAPS3_D2DXFER_SUPPORT BIT(1)
1033
1034 /**
1035 * @brief Get Optional Feature Capabilities Byte 3 (GETCAPS) Format 1 -
1036 * Device to Device Transfer (D2DXFER) IBI Capable bit.
1037 */
1038 #define I3C_CCC_GETCAPS3_D2DXFER_IBI_CAPABLE BIT(2)
1039
1040 /**
1041 * @brief Get Optional Feature Capabilities Byte 3 (GETCAPS) Format 1 -
1042 * Defining Byte Support in GETCAPS bit.
1043 */
1044 #define I3C_CCC_GETCAPS3_GETCAPS_DEFINING_BYTE_SUPPORT BIT(3)
1045
1046 /**
1047 * @brief Get Optional Feature Capabilities Byte 3 (GETCAPS) Format 1 -
1048 * Defining Byte Support in GETSTATUS bit.
1049 */
1050 #define I3C_CCC_GETCAPS3_GETSTATUS_DEFINING_BYTE_SUPPORT BIT(4)
1051
1052 /**
1053 * @brief Get Optional Feature Capabilities Byte 3 (GETCAPS) Format 1 -
1054 * HDR-BT CRC-32 Support bit.
1055 */
1056 #define I3C_CCC_GETCAPS3_HDRBT_CRC32_SUPPORT BIT(5)
1057
1058 /**
1059 * @brief Get Optional Feature Capabilities Byte 3 (GETCAPS) Format 1 -
1060 * IBI MDB Support for Pending Read Notification bit.
1061 */
1062 #define I3C_CCC_GETCAPS3_IBI_MDR_PENDING_READ_NOTIFICATION BIT(6)
1063
1064 /**
1065 * @brief Get Fixed Test Pattern (GETCAPS) Format 2 -
1066 * Fixed Test Pattern Byte 1.
1067 */
1068 #define I3C_CCC_GETCAPS_TESTPAT1 0xA5
1069
1070 /**
1071 * @brief Get Fixed Test Pattern (GETCAPS) Format 2 -
1072 * Fixed Test Pattern Byte 2.
1073 */
1074 #define I3C_CCC_GETCAPS_TESTPAT2 0x5A
1075
1076 /**
1077 * @brief Get Fixed Test Pattern (GETCAPS) Format 2 -
1078 * Fixed Test Pattern Byte 3.
1079 */
1080 #define I3C_CCC_GETCAPS_TESTPAT3 0xA5
1081
1082 /**
1083 * @brief Get Fixed Test Pattern (GETCAPS) Format 2 -
1084 * Fixed Test Pattern Byte 4.
1085 */
1086 #define I3C_CCC_GETCAPS_TESTPAT4 0x5A
1087
1088 /**
1089 * @brief Get Fixed Test Pattern (GETCAPS) Format 2 -
1090 * Fixed Test Pattern Word in Big Endian.
1091 */
1092 #define I3C_CCC_GETCAPS_TESTPAT 0xA55AA55A
1093
1094 /**
1095 * @brief Get Controller Handoff Capabilities Byte 1 (GETCAPS) Format 2 -
1096 * Hot-Join Support.
1097 */
1098 #define I3C_CCC_GETCAPS_CRCAPS1_HJ_SUPPORT BIT(0)
1099
1100 /**
1101 * @brief Get Controller Handoff Capabilities Byte 1 (GETCAPS) Format 2 -
1102 * Group Management Support.
1103 */
1104 #define I3C_CCC_GETCAPS_CRCAPS1_GRP_MANAGEMENT_SUPPORT BIT(1)
1105
1106 /**
1107 * @brief Get Controller Handoff Capabilities Byte 1 (GETCAPS) Format 2 -
1108 * Multi-Lane Support.
1109 */
1110 #define I3C_CCC_GETCAPS_CRCAPS1_ML_SUPPORT BIT(2)
1111
1112 /**
1113 * @brief Get Controller Handoff Capabilities Byte 2 (GETCAPS) Format 2 -
1114 * In-Band Interrupt Support.
1115 */
1116 #define I3C_CCC_GETCAPS_CRCAPS2_IBI_TIR_SUPPORT BIT(0)
1117
1118 /**
1119 * @brief Get Controller Handoff Capabilities Byte 2 (GETCAPS) Format 2 -
1120 * Controller Pass-Back.
1121 */
1122 #define I3C_CCC_GETCAPS_CRCAPS2_CONTROLLER_PASSBACK BIT(1)
1123
1124 /**
1125 * @brief Get Controller Handoff Capabilities Byte 2 (GETCAPS) Format 2 -
1126 * Deep Sleep Capable.
1127 */
1128 #define I3C_CCC_GETCAPS_CRCAPS2_DEEP_SLEEP_CAPABLE BIT(2)
1129
1130 /**
1131 * @brief Get Controller Handoff Capabilities Byte 2 (GETCAPS) Format 2 -
1132 * Deep Sleep Capable.
1133 */
1134 #define I3C_CCC_GETCAPS_CRCAPS2_DELAYED_CONTROLLER_HANDOFF BIT(3)
1135
1136 /** Get Capabilities (GETCAPS) - VTCAP1 - Virtual Target Type bitmask. */
1137 #define I3C_CCC_GETCAPS_VTCAP1_VITRUAL_TARGET_TYPE_MASK GENMASK(2U, 0U)
1138
1139 /**
1140 * @brief Get Capabilities (GETCAPS) - VTCAP1 - Virtual Target Type
1141 *
1142 * Obtain Virtual Target Type value from VTCAP1 value
1143 * obtained via GETCAPS format 2 VTCAP def byte.
1144 *
1145 * @param vtcap1 VTCAP1 value.
1146 */
1147 #define I3C_CCC_GETCAPS_VTCAP1_VITRUAL_TARGET_TYPE(vtcap1) \
1148 FIELD_GET(I3C_CCC_GETCAPS_VTCAP1_VITRUAL_TARGET_TYPE_MASK, (vtcap1))
1149
1150 /**
1151 * @brief Get Virtual Target Capabilities Byte 1 (GETCAPS) Format 2 -
1152 * Side Effects.
1153 */
1154 #define I3C_CCC_GETCAPS_VTCAP1_SIDE_EFFECTS BIT(4)
1155
1156 /**
1157 * @brief Get Virtual Target Capabilities Byte 1 (GETCAPS) Format 2 -
1158 * Shared Peripheral Detect.
1159 */
1160 #define I3C_CCC_GETCAPS_VTCAP1_SHARED_PERIPH_DETECT BIT(5)
1161
1162 /** Get Capabilities (GETCAPS) - VTCAP2 - Interrupt Requests bitmask. */
1163 #define I3C_CCC_GETCAPS_VTCAP2_INTERRUPT_REQUESTS_MASK GENMASK(1U, 0U)
1164
1165 /**
1166 * @brief Get Capabilities (GETCAPS) - VTCAP2 - Interrupt Requests
1167 *
1168 * Obtain Interrupt Requests value from VTCAP2 value
1169 * obtained via GETCAPS format 2 VTCAP def byte.
1170 *
1171 * @param vtcap2 VTCAP2 value.
1172 */
1173 #define I3C_CCC_GETCAPS_VTCAP2_INTERRUPT_REQUESTS(vtcap2) \
1174 FIELD_GET(I3C_CCC_GETCAPS_VTCAP2_INTERRUPT_REQUESTS_MASK, (vtcap2))
1175
1176 /**
1177 * @brief Get Virtual Target Capabilities Byte 2 (GETCAPS) Format 2 -
1178 * Address Remapping.
1179 */
1180 #define I3C_CCC_GETCAPS_VTCAP2_ADDRESS_REMAPPING BIT(2)
1181
1182 /** Get Capabilities (GETCAPS) - VTCAP2 - Bus Context and Condition bitmask. */
1183 #define I3C_CCC_GETCAPS_VTCAP2_BUS_CONTEXT_AND_COND_MASK GENMASK(4U, 3U)
1184
1185 /**
1186 * @brief Get Capabilities (GETCAPS) - VTCAP2 - Bus Context and Condition
1187 *
1188 * Obtain Bus Context and Condition value from VTCAP2 value
1189 * obtained via GETCAPS format 2 VTCAP def byte.
1190 *
1191 * @param vtcap2 VTCAP2 value.
1192 */
1193 #define I3C_CCC_GETCAPS_VTCAP2_BUS_CONTEXT_AND_COND(vtcap2) \
1194 FIELD_GET(I3C_CCC_GETCAPS_VTCAP2_BUS_CONTEXT_AND_COND_MASK, (vtcap2))
1195
1196 /**
1197 * @brief Enum for I3C Reset Action (RSTACT) Defining Byte Values.
1198 */
1199 enum i3c_ccc_rstact_defining_byte {
1200 /** No Reset on Target Reset Pattern. */
1201 I3C_CCC_RSTACT_NO_RESET = 0x00U,
1202
1203 /** Reset the I3C Peripheral Only. */
1204 I3C_CCC_RSTACT_PERIPHERAL_ONLY = 0x01U,
1205
1206 /** Reset the Whole Target. */
1207 I3C_CCC_RSTACT_RESET_WHOLE_TARGET = 0x02U,
1208
1209 /** Debug Network Adapter Reset. */
1210 I3C_CCC_RSTACT_DEBUG_NETWORK_ADAPTER = 0x03U,
1211
1212 /** Virtual Target Detect. */
1213 I3C_CCC_RSTACT_VIRTUAL_TARGET_DETECT = 0x04U,
1214 };
1215
1216 /**
1217 * @brief Test if I3C CCC payload is for broadcast.
1218 *
1219 * This tests if the CCC payload is for broadcast.
1220 *
1221 * @param[in] payload Pointer to the CCC payload.
1222 *
1223 * @retval true if payload target is broadcast
1224 * @retval false if payload target is direct
1225 */
i3c_ccc_is_payload_broadcast(const struct i3c_ccc_payload * payload)1226 static inline bool i3c_ccc_is_payload_broadcast(const struct i3c_ccc_payload *payload)
1227 {
1228 return (payload->ccc.id <= I3C_CCC_BROADCAST_MAX_ID);
1229 }
1230
1231 /**
1232 * @brief Get BCR from a target
1233 *
1234 * Helper function to get BCR (Bus Characteristic Register) from
1235 * target device.
1236 *
1237 * @param[in] target Pointer to the target device descriptor.
1238 * @param[out] bcr Pointer to the BCR payload structure.
1239 *
1240 * @return @see i3c_do_ccc
1241 */
1242 int i3c_ccc_do_getbcr(struct i3c_device_desc *target,
1243 struct i3c_ccc_getbcr *bcr);
1244
1245 /**
1246 * @brief Get DCR from a target
1247 *
1248 * Helper function to get DCR (Device Characteristic Register) from
1249 * target device.
1250 *
1251 * @param[in] target Pointer to the target device descriptor.
1252 * @param[out] dcr Pointer to the DCR payload structure.
1253 *
1254 * @return @see i3c_do_ccc
1255 */
1256 int i3c_ccc_do_getdcr(struct i3c_device_desc *target,
1257 struct i3c_ccc_getdcr *dcr);
1258
1259 /**
1260 * @brief Get PID from a target
1261 *
1262 * Helper function to get PID (Provisioned ID) from
1263 * target device.
1264 *
1265 * @param[in] target Pointer to the target device descriptor.
1266 * @param[out] pid Pointer to the PID payload structure.
1267 *
1268 * @return @see i3c_do_ccc
1269 */
1270 int i3c_ccc_do_getpid(struct i3c_device_desc *target,
1271 struct i3c_ccc_getpid *pid);
1272
1273 /**
1274 * @brief Broadcast RSTACT to reset I3C Peripheral.
1275 *
1276 * Helper function to broadcast Target Reset Action (RSTACT) to
1277 * all connected targets to Reset the I3C Peripheral Only (0x01).
1278 *
1279 * @param[in] controller Pointer to the controller device driver instance.
1280 * @param[in] action What reset action to perform.
1281 *
1282 * @return @see i3c_do_ccc
1283 */
1284 int i3c_ccc_do_rstact_all(const struct device *controller,
1285 enum i3c_ccc_rstact_defining_byte action);
1286
1287 /**
1288 * @brief Broadcast RSTDAA to reset dynamic addresses for all targets.
1289 *
1290 * Helper function to reset dynamic addresses of all connected targets.
1291 *
1292 * @param[in] controller Pointer to the controller device driver instance.
1293 *
1294 * @return @see i3c_do_ccc
1295 */
1296 int i3c_ccc_do_rstdaa_all(const struct device *controller);
1297
1298 /**
1299 * @brief Set Dynamic Address from Static Address for a target
1300 *
1301 * Helper function to do SETDASA (Set Dynamic Address from Static Address)
1302 * for a particular target.
1303 *
1304 * Note this does not update @p target with the new dynamic address.
1305 *
1306 * @param[in] target Pointer to the target device descriptor where
1307 * the device is configured with a static address.
1308 *
1309 * @return @see i3c_do_ccc
1310 */
1311 int i3c_ccc_do_setdasa(const struct i3c_device_desc *target);
1312
1313 /**
1314 * @brief Set New Dynamic Address for a target
1315 *
1316 * Helper function to do SETNEWDA(Set New Dynamic Address) for a particular target.
1317 *
1318 * Note this does not update @p target with the new dynamic address.
1319 *
1320 * @param[in] target Pointer to the target device descriptor where
1321 * the device is configured with a static address.
1322 * @param[in] new_da Pointer to the new_da struct.
1323 *
1324 * @return @see i3c_do_ccc
1325 */
1326 int i3c_ccc_do_setnewda(const struct i3c_device_desc *target,
1327 struct i3c_ccc_address new_da);
1328
1329 /**
1330 * @brief Broadcast ENEC/DISEC to enable/disable target events.
1331 *
1332 * Helper function to broadcast Target Events Command to enable or
1333 * disable target events (ENEC/DISEC).
1334 *
1335 * @param[in] controller Pointer to the controller device driver instance.
1336 * @param[in] enable ENEC if true, DISEC if false.
1337 * @param[in] events Pointer to the event struct.
1338 *
1339 * @return @see i3c_do_ccc
1340 */
1341 int i3c_ccc_do_events_all_set(const struct device *controller,
1342 bool enable, struct i3c_ccc_events *events);
1343
1344 /**
1345 * @brief Direct CCC ENEC/DISEC to enable/disable target events.
1346 *
1347 * Helper function to send Target Events Command to enable or
1348 * disable target events (ENEC/DISEC) on a single target.
1349 *
1350 * @param[in] target Pointer to the target device descriptor.
1351 * @param[in] enable ENEC if true, DISEC if false.
1352 * @param[in] events Pointer to the event struct.
1353 *
1354 * @return @see i3c_do_ccc
1355 */
1356 int i3c_ccc_do_events_set(struct i3c_device_desc *target,
1357 bool enable, struct i3c_ccc_events *events);
1358
1359 /**
1360 * @brief Broadcast SETMWL to Set Maximum Write Length.
1361 *
1362 * Helper function to do SETMWL (Set Maximum Write Length) to
1363 * all connected targets.
1364 *
1365 * @param[in] controller Pointer to the controller device driver instance.
1366 * @param[in] mwl Pointer to SETMWL payload.
1367 *
1368 * @return @see i3c_do_ccc
1369 */
1370 int i3c_ccc_do_setmwl_all(const struct device *controller,
1371 const struct i3c_ccc_mwl *mwl);
1372
1373 /**
1374 * @brief Single target SETMWL to Set Maximum Write Length.
1375 *
1376 * Helper function to do SETMWL (Set Maximum Write Length) to
1377 * one target.
1378 *
1379 * @param[in] target Pointer to the target device descriptor.
1380 * @param[in] mwl Pointer to SETMWL payload.
1381 *
1382 * @return @see i3c_do_ccc
1383 */
1384 int i3c_ccc_do_setmwl(const struct i3c_device_desc *target,
1385 const struct i3c_ccc_mwl *mwl);
1386
1387 /**
1388 * @brief Single target GETMWL to Get Maximum Write Length.
1389 *
1390 * Helper function to do GETMWL (Get Maximum Write Length) of
1391 * one target.
1392 *
1393 * @param[in] target Pointer to the target device descriptor.
1394 * @param[out] mwl Pointer to GETMWL payload.
1395 *
1396 * @return @see i3c_do_ccc
1397 */
1398 int i3c_ccc_do_getmwl(const struct i3c_device_desc *target,
1399 struct i3c_ccc_mwl *mwl);
1400
1401 /**
1402 * @brief Broadcast SETMRL to Set Maximum Read Length.
1403 *
1404 * Helper function to do SETMRL (Set Maximum Read Length) to
1405 * all connected targets.
1406 *
1407 * @param[in] controller Pointer to the controller device driver instance.
1408 * @param[in] mrl Pointer to SETMRL payload.
1409 * @param[in] has_ibi_size True if also sending the optional IBI payload
1410 * size. False if not sending.
1411 *
1412 * @return @see i3c_do_ccc
1413 */
1414 int i3c_ccc_do_setmrl_all(const struct device *controller,
1415 const struct i3c_ccc_mrl *mrl,
1416 bool has_ibi_size);
1417
1418 /**
1419 * @brief Single target SETMRL to Set Maximum Read Length.
1420 *
1421 * Helper function to do SETMRL (Set Maximum Read Length) to
1422 * one target.
1423 *
1424 * Note this uses the BCR of the target to determine whether
1425 * to send the optional IBI payload size.
1426 *
1427 * @param[in] target Pointer to the target device descriptor.
1428 * @param[in] mrl Pointer to SETMRL payload.
1429 *
1430 * @return @see i3c_do_ccc
1431 */
1432 int i3c_ccc_do_setmrl(const struct i3c_device_desc *target,
1433 const struct i3c_ccc_mrl *mrl);
1434
1435 /**
1436 * @brief Single target GETMRL to Get Maximum Read Length.
1437 *
1438 * Helper function to do GETMRL (Get Maximum Read Length) of
1439 * one target.
1440 *
1441 * Note this uses the BCR of the target to determine whether
1442 * to send the optional IBI payload size.
1443 *
1444 * @param[in] target Pointer to the target device descriptor.
1445 * @param[out] mrl Pointer to GETMRL payload.
1446 *
1447 * @return @see i3c_do_ccc
1448 */
1449 int i3c_ccc_do_getmrl(const struct i3c_device_desc *target,
1450 struct i3c_ccc_mrl *mrl);
1451
1452 /**
1453 * @brief Single target GETSTATUS to Get Target Status.
1454 *
1455 * Helper function to do GETSTATUS (Get Target Status) of
1456 * one target.
1457 *
1458 * Note this uses the BCR of the target to determine whether
1459 * to send the optional IBI payload size.
1460 *
1461 * @param[in] target Pointer to the target device descriptor.
1462 * @param[out] status Pointer to GETSTATUS payload.
1463 * @param[in] fmt Which GETSTATUS to use.
1464 * @param[in] defbyte Defining Byte if using format 2.
1465 *
1466 * @return @see i3c_do_ccc
1467 */
1468 int i3c_ccc_do_getstatus(const struct i3c_device_desc *target,
1469 union i3c_ccc_getstatus *status,
1470 enum i3c_ccc_getstatus_fmt fmt,
1471 enum i3c_ccc_getstatus_defbyte defbyte);
1472
1473 /**
1474 * @brief Single target GETSTATUS to Get Target Status (Format 1).
1475 *
1476 * Helper function to do GETSTATUS (Get Target Status, format 1) of
1477 * one target.
1478 *
1479 * @param[in] target Pointer to the target device descriptor.
1480 * @param[out] status Pointer to GETSTATUS payload.
1481 *
1482 * @return @see i3c_do_ccc
1483 */
i3c_ccc_do_getstatus_fmt1(const struct i3c_device_desc * target,union i3c_ccc_getstatus * status)1484 static inline int i3c_ccc_do_getstatus_fmt1(const struct i3c_device_desc *target,
1485 union i3c_ccc_getstatus *status)
1486 {
1487 return i3c_ccc_do_getstatus(target, status,
1488 GETSTATUS_FORMAT_1,
1489 GETSTATUS_FORMAT_2_INVALID);
1490 }
1491
1492 /**
1493 * @brief Single target GETSTATUS to Get Target Status (Format 2).
1494 *
1495 * Helper function to do GETSTATUS (Get Target Status, format 2) of
1496 * one target.
1497 *
1498 * @param[in] target Pointer to the target device descriptor.
1499 * @param[out] status Pointer to GETSTATUS payload.
1500 * @param[in] defbyte Defining Byte for GETSTATUS format 2.
1501 *
1502 * @return @see i3c_do_ccc
1503 */
i3c_ccc_do_getstatus_fmt2(const struct i3c_device_desc * target,union i3c_ccc_getstatus * status,enum i3c_ccc_getstatus_defbyte defbyte)1504 static inline int i3c_ccc_do_getstatus_fmt2(const struct i3c_device_desc *target,
1505 union i3c_ccc_getstatus *status,
1506 enum i3c_ccc_getstatus_defbyte defbyte)
1507 {
1508 return i3c_ccc_do_getstatus(target, status,
1509 GETSTATUS_FORMAT_2, defbyte);
1510 }
1511
1512 /**
1513 * @brief Single target GETCAPS to Get Target Status.
1514 *
1515 * Helper function to do GETCAPS (Get Capabilities) of
1516 * one target.
1517 *
1518 * This should only be supported if Advanced Capabilities Bit of
1519 * the BCR is set
1520 *
1521 * @param[in] target Pointer to the target device descriptor.
1522 * @param[out] caps Pointer to GETCAPS payload.
1523 * @param[in] fmt Which GETCAPS to use.
1524 * @param[in] defbyte Defining Byte if using format 2.
1525 *
1526 * @return @see i3c_do_ccc
1527 */
1528 int i3c_ccc_do_getcaps(const struct i3c_device_desc *target,
1529 union i3c_ccc_getcaps *caps,
1530 enum i3c_ccc_getcaps_fmt fmt,
1531 enum i3c_ccc_getcaps_defbyte defbyte);
1532
1533 /**
1534 * @brief Single target GETCAPS to Get Capabilities (Format 1).
1535 *
1536 * Helper function to do GETCAPS (Get Capabilities, format 1) of
1537 * one target.
1538 *
1539 * @param[in] target Pointer to the target device descriptor.
1540 * @param[out] caps Pointer to GETCAPS payload.
1541 *
1542 * @return @see i3c_do_ccc
1543 */
i3c_ccc_do_getcaps_fmt1(const struct i3c_device_desc * target,union i3c_ccc_getcaps * caps)1544 static inline int i3c_ccc_do_getcaps_fmt1(const struct i3c_device_desc *target,
1545 union i3c_ccc_getcaps *caps)
1546 {
1547 return i3c_ccc_do_getcaps(target, caps,
1548 GETCAPS_FORMAT_1,
1549 GETCAPS_FORMAT_2_INVALID);
1550 }
1551
1552 /**
1553 * @brief Single target GETCAPS to Get Capabilities (Format 2).
1554 *
1555 * Helper function to do GETCAPS (Get Capabilities, format 2) of
1556 * one target.
1557 *
1558 * @param[in] target Pointer to the target device descriptor.
1559 * @param[out] caps Pointer to GETCAPS payload.
1560 * @param[in] defbyte Defining Byte for GETCAPS format 2.
1561 *
1562 * @return @see i3c_do_ccc
1563 */
i3c_ccc_do_getcaps_fmt2(const struct i3c_device_desc * target,union i3c_ccc_getcaps * caps,enum i3c_ccc_getcaps_defbyte defbyte)1564 static inline int i3c_ccc_do_getcaps_fmt2(const struct i3c_device_desc *target,
1565 union i3c_ccc_getcaps *caps,
1566 enum i3c_ccc_getcaps_defbyte defbyte)
1567 {
1568 return i3c_ccc_do_getcaps(target, caps,
1569 GETCAPS_FORMAT_2, defbyte);
1570 }
1571
1572 #ifdef __cplusplus
1573 }
1574 #endif
1575
1576 /**
1577 * @}
1578 */
1579
1580 #endif /* ZEPHYR_INCLUDE_DRIVERS_I3C_CCC_H_ */
1581
