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 * SDR Error Type
265 *
266 * Error from I3C Specification v1.1.1 section 5.1.10.2. It is expected
267 * for the driver to write to this.
268 */
269 enum i3c_sdr_controller_error_types err;
270 };
271
272 /**
273 * @brief Payload structure for one CCC transaction.
274 */
275 struct i3c_ccc_payload {
276 struct {
277 /**
278 * The CCC ID (@c I3C_CCC_*).
279 */
280 uint8_t id;
281
282 /**
283 * Pointer to byte array of data for this CCC.
284 *
285 * This is the bytes following the CCC command in CCC frame.
286 * Set to @c NULL if no associated data.
287 */
288 uint8_t *data;
289
290 /** Length in bytes for optional data array. */
291 size_t data_len;
292
293 /**
294 * Total number of bytes transferred
295 *
296 * A Controller can abort a transfer before the length of the buffer.
297 * It is expected for the driver to write to this after the transfer.
298 */
299 size_t num_xfer;
300
301 /**
302 * SDR Error Type
303 *
304 * Error from I3C Specification v1.1.1 section 5.1.10.2. It is expected
305 * for the driver to write to this.
306 */
307 enum i3c_sdr_controller_error_types err;
308 } ccc;
309
310 struct {
311 /**
312 * Array of struct i3c_ccc_target_payload.
313 *
314 * Each element describes the target and associated
315 * payloads for this CCC.
316 *
317 * Use with Direct CCC.
318 */
319 struct i3c_ccc_target_payload *payloads;
320
321 /** Number of targets */
322 size_t num_targets;
323 } targets;
324 };
325
326 /**
327 * @brief Payload for ENEC/DISEC CCC (Target Events Command).
328 */
329 struct i3c_ccc_events {
330 /**
331 * Event byte:
332 * - Bit[0]: ENINT/DISINT:
333 * - Target Interrupt Requests
334 * - Bit[1]: ENCR/DISCR:
335 * - Controller Role Requests
336 * - Bit[3]: ENHJ/DISHJ:
337 * - Hot-Join Event
338 */
339 uint8_t events;
340 } __packed;
341
342 /** Enable Events (ENEC) - Target Interrupt Requests. */
343 #define I3C_CCC_ENEC_EVT_ENINTR BIT(0)
344
345 /** Enable Events (ENEC) - Controller Role Requests. */
346 #define I3C_CCC_ENEC_EVT_ENCR BIT(1)
347
348 /** Enable Events (ENEC) - Hot-Join Event. */
349 #define I3C_CCC_ENEC_EVT_ENHJ BIT(3)
350
351 #define I3C_CCC_ENEC_EVT_ALL \
352 (I3C_CCC_ENEC_EVT_ENINTR | I3C_CCC_ENEC_EVT_ENCR | I3C_CCC_ENEC_EVT_ENHJ)
353
354 /** Disable Events (DISEC) - Target Interrupt Requests. */
355 #define I3C_CCC_DISEC_EVT_DISINTR BIT(0)
356
357 /** Disable Events (DISEC) - Controller Role Requests. */
358 #define I3C_CCC_DISEC_EVT_DISCR BIT(1)
359
360 /** Disable Events (DISEC) - Hot-Join Event. */
361 #define I3C_CCC_DISEC_EVT_DISHJ BIT(3)
362
363 #define I3C_CCC_DISEC_EVT_ALL \
364 (I3C_CCC_DISEC_EVT_DISINTR | I3C_CCC_DISEC_EVT_DISCR | I3C_CCC_DISEC_EVT_DISHJ)
365
366 /*
367 * Events for both enabling and disabling since
368 * they have the same bits.
369 */
370
371 /** Events - Target Interrupt Requests. */
372 #define I3C_CCC_EVT_INTR BIT(0)
373
374 /** Events - Controller Role Requests. */
375 #define I3C_CCC_EVT_CR BIT(1)
376
377 /** Events - Hot-Join Event. */
378 #define I3C_CCC_EVT_HJ BIT(3)
379
380 /** Bitmask for all events. */
381 #define I3C_CCC_EVT_ALL \
382 (I3C_CCC_EVT_INTR | I3C_CCC_EVT_CR | I3C_CCC_EVT_HJ)
383
384 /**
385 * @brief Payload for SETMWL/GETMWL CCC (Set/Get Maximum Write Length).
386 *
387 * @note For drivers and help functions, the raw data coming
388 * back from target device is in big endian. This needs to be
389 * translated back to CPU endianness before passing back to
390 * function caller.
391 */
392 struct i3c_ccc_mwl {
393 /** Maximum Write Length */
394 uint16_t len;
395 } __packed;
396
397 /**
398 * @brief Payload for SETMRL/GETMRL CCC (Set/Get Maximum Read Length).
399 *
400 * @note For drivers and help functions, the raw data coming
401 * back from target device is in big endian. This needs to be
402 * translated back to CPU endianness before passing back to
403 * function caller.
404 */
405 struct i3c_ccc_mrl {
406 /** Maximum Read Length */
407 uint16_t len;
408
409 /** Optional IBI Payload Size */
410 uint8_t ibi_len;
411 } __packed;
412
413 /**
414 * @brief The active controller part of payload for DEFTGTS CCC.
415 *
416 * This is used by DEFTGTS (Define List of Targets) CCC to describe
417 * the active controller on the I3C bus.
418 */
419 struct i3c_ccc_deftgts_active_controller {
420 /** Dynamic Address of Active Controller */
421 uint8_t addr;
422
423 /** Device Characteristic Register of Active Controller */
424 uint8_t dcr;
425
426 /** Bus Characteristic Register of Active Controller */
427 uint8_t bcr;
428
429 /** Static Address of Active Controller */
430 uint8_t static_addr;
431 };
432
433 /**
434 * @brief The target device part of payload for DEFTGTS CCC.
435 *
436 * This is used by DEFTGTS (Define List of Targets) CCC to describe
437 * the existing target devices on the I3C bus.
438 */
439 struct i3c_ccc_deftgts_target {
440 /** Dynamic Address of a target device, or a group address */
441 uint8_t addr;
442
443 union {
444 /**
445 * Device Characteristic Register of a I3C target device
446 * or a group.
447 */
448 uint8_t dcr;
449
450 /** Legacy Virtual Register for legacy I2C device. */
451 uint8_t lvr;
452 };
453
454 /** Bus Characteristic Register of a target device or a group */
455 uint8_t bcr;
456
457 /** Static Address of a target device or a group */
458 uint8_t static_addr;
459 };
460
461 /**
462 * @brief Payload for DEFTGTS CCC (Define List of Targets).
463 *
464 * @note @p i3c_ccc_deftgts_target is an array of targets, where
465 * the number of elements is dependent on the number of I3C targets
466 * on the bus. Please have enough space for both read and write of
467 * this CCC.
468 */
469 struct i3c_ccc_deftgts {
470 /** Number of Targets (and Groups) present on the I3C Bus */
471 uint8_t count;
472
473 /** Data describing the active controller */
474 struct i3c_ccc_deftgts_active_controller active_controller;
475
476 /** Data describing the target(s) on the bus */
477 struct i3c_ccc_deftgts_target targets[];
478 } __packed;
479
480 /**
481 * @brief Defining byte values for ENTTM.
482 */
483 enum i3c_ccc_enttm_defbyte {
484 /** Remove all I3C Devices from Test Mode */
485 ENTTM_EXIT_TEST_MODE = 0x00U,
486
487 /** Indicates that I3C Devices shall return a random 32-bit value
488 * in the PID during the Dynamic Address Assignment procedure
489 */
490 ENTTM_VENDOR_TEST_MODE = 0x01U,
491 };
492
493 /**
494 * @brief Payload for a single device address.
495 *
496 * This is used for:
497 * - SETDASA (Set Dynamic Address from Static Address)
498 * - SETNEWDA (Set New Dynamic Address)
499 * - SETGRPA (Set Group Address)
500 * - GETACCCR (Get Accept Controller Role)
501 *
502 * Note that the target address is encoded within
503 * struct i3c_ccc_target_payload instead of being encoded in
504 * this payload.
505 */
506 struct i3c_ccc_address {
507 /**
508 * - For SETDASA, Static Address to be assigned as
509 * Dynamic Address.
510 * - For SETNEWDA, new Dynamic Address to be assigned.
511 * - For SETGRPA, new Group Address to be set.
512 * - For GETACCCR, the correct address of Secondary
513 * Controller.
514 *
515 * @note For SETDATA, SETNEWDA and SETGRPA,
516 * the address is left-shift by 1, and bit[0] is always 0.
517 *
518 * @note For SET GETACCCR, the address is left-shift by 1,
519 * and bit[0] is the calculated odd parity bit.
520 */
521 uint8_t addr;
522 } __packed;
523
524 /**
525 * @brief Payload for GETPID CCC (Get Provisioned ID).
526 */
527 struct i3c_ccc_getpid {
528 /**
529 * 48-bit Provisioned ID.
530 *
531 * @note Data is big-endian where first byte is MSB.
532 */
533 uint8_t pid[6];
534 } __packed;
535
536 /**
537 * @brief Payload for GETBCR CCC (Get Bus Characteristics Register).
538 */
539 struct i3c_ccc_getbcr {
540 /** Bus Characteristics Register */
541 uint8_t bcr;
542 } __packed;
543
544 /**
545 * @brief Payload for GETDCR CCC (Get Device Characteristics Register).
546 */
547 struct i3c_ccc_getdcr {
548 /** Device Characteristics Register */
549 uint8_t dcr;
550 } __packed;
551
552
553 /**
554 * @brief Indicate which format of GETSTATUS to use.
555 */
556 enum i3c_ccc_getstatus_fmt {
557 /** GETSTATUS Format 1 */
558 GETSTATUS_FORMAT_1,
559
560 /** GETSTATUS Format 2 */
561 GETSTATUS_FORMAT_2,
562 };
563
564 /**
565 * @brief Defining byte values for GETSTATUS Format 2.
566 */
567 enum i3c_ccc_getstatus_defbyte {
568 /** Target status. */
569 GETSTATUS_FORMAT_2_TGTSTAT = 0x00U,
570
571 /** PRECR - Alternate status format describing Controller-capable device. */
572 GETSTATUS_FORMAT_2_PRECR = 0x91U,
573
574 /** Invalid defining byte. */
575 GETSTATUS_FORMAT_2_INVALID = 0x100U
576 };
577
578 /**
579 * @brief Payload for GETSTATUS CCC (Get Device Status).
580 */
581 union i3c_ccc_getstatus {
582 struct {
583 /**
584 * Device Status
585 * - Bit[15:8]: Reserved.
586 * - Bit[7:6]: Activity Mode.
587 * - Bit[5]: Protocol Error.
588 * - Bit[4]: Reserved.
589 * - Bit[3:0]: Number of Pending Interrupts.
590 *
591 * @note For drivers and help functions, the raw data coming
592 * back from target device is in big endian. This needs to be
593 * translated back to CPU endianness before passing back to
594 * function caller.
595 */
596 uint16_t status;
597 } fmt1;
598
599 union {
600 /**
601 * Defining Byte 0x00: TGTSTAT
602 *
603 * @see i3c_ccc_getstatus::fmt1::status
604 */
605 uint16_t tgtstat;
606
607 /**
608 * Defining Byte 0x91: PRECR
609 * - Bit[15:8]: Vendor Reserved
610 * - Bit[7:2]: Reserved
611 * - Bit[1]: Handoff Delay NACK
612 * - Bit[0]: Deep Sleep Detected
613 *
614 * @note For drivers and help functions, the raw data coming
615 * back from target device is in big endian. This needs to be
616 * translated back to CPU endianness before passing back to
617 * function caller.
618 */
619 uint16_t precr;
620
621 uint16_t raw_u16;
622 } fmt2;
623 } __packed;
624
625 /** GETSTATUS Format 1 - Protocol Error bit. */
626 #define I3C_CCC_GETSTATUS_PROTOCOL_ERR BIT(5)
627
628 /** GETSTATUS Format 1 - Activity Mode bitmask. */
629 #define I3C_CCC_GETSTATUS_ACTIVITY_MODE_MASK GENMASK(7U, 6U)
630
631 /**
632 * @brief GETSTATUS Format 1 - Activity Mode
633 *
634 * Obtain Activity Mode from GETSTATUS Format 1 value obtained via
635 * GETSTATUS.
636 *
637 * @param status GETSTATUS Format 1 value
638 */
639 #define I3C_CCC_GETSTATUS_ACTIVITY_MODE(status) \
640 FIELD_GET(I3C_CCC_GETSTATUS_ACTIVITY_MODE_MASK, (status))
641
642 /** GETSTATUS Format 1 - Activity Mode Unable to participate in Controller Handoff */
643 #define I3C_CCC_GETSTATUS_ACTIVITY_MODE_NCH 0x3
644
645 /** GETSTATUS Format 1 - Number of Pending Interrupts bitmask. */
646 #define I3C_CCC_GETSTATUS_NUM_INT_MASK GENMASK(3U, 0U)
647
648 /**
649 * @brief GETSTATUS Format 1 - Number of Pending Interrupts
650 *
651 * Obtain Number of Pending Interrupts from GETSTATUS Format 1 value
652 * obtained via GETSTATUS.
653 *
654 * @param status GETSTATUS Format 1 value
655 */
656 #define I3C_CCC_GETSTATUS_NUM_INT(status) \
657 FIELD_GET(I3C_CCC_GETSTATUS_NUM_INT_MASK, (status))
658
659 /** GETSTATUS Format 2 - PERCR - Deep Sleep Detected bit. */
660 #define I3C_CCC_GETSTATUS_PRECR_DEEP_SLEEP_DETECTED BIT(0)
661
662 /** GETSTATUS Format 2 - PERCR - Handoff Delay NACK. */
663 #define I3C_CCC_GETSTATUS_PRECR_HANDOFF_DELAY_NACK BIT(1)
664
665 /**
666 * @brief One Bridged Target for SETBRGTGT payload.
667 */
668 struct i3c_ccc_setbrgtgt_tgt {
669 /**
670 * Dynamic address of the bridged target.
671 *
672 * @note The address is left-shift by 1, and bit[0]
673 * is always 0.
674 */
675 uint8_t addr;
676
677 /**
678 * 16-bit ID for the bridged target.
679 *
680 * @note For drivers and help functions, the raw data coming
681 * back from target device is in big endian. This needs to be
682 * translated back to CPU endianness before passing back to
683 * function caller.
684 */
685 uint16_t id;
686 } __packed;
687
688 /**
689 * @brief Payload for SETBRGTGT CCC (Set Bridge Targets).
690 *
691 * Note that the bridge target address is encoded within
692 * struct i3c_ccc_target_payload instead of being encoded in
693 * this payload.
694 */
695 struct i3c_ccc_setbrgtgt {
696 /** Number of bridged targets */
697 uint8_t count;
698
699 /** Array of bridged targets */
700 struct i3c_ccc_setbrgtgt_tgt targets[];
701 } __packed;
702
703 /**
704 * @brief Indicate which format of getmxds to use.
705 */
706 enum i3c_ccc_getmxds_fmt {
707 /** GETMXDS Format 1 */
708 GETMXDS_FORMAT_1,
709
710 /** GETMXDS Format 2 */
711 GETMXDS_FORMAT_2,
712
713 /** GETMXDS Format 3 */
714 GETMXDS_FORMAT_3,
715 };
716
717 /**
718 * @brief Enum for I3C Get Max Data Speed (GETMXDS) Format 3 Defining Byte Values.
719 */
720 enum i3c_ccc_getmxds_defbyte {
721 /** Standard Target Write/Read speed parameters, and optional Maximum Read Turnaround Time
722 */
723 GETMXDS_FORMAT_3_WRRDTURN = 0x00U,
724
725 /** Delay parameters for a Controller-capable Device, and it's expected Activity State
726 * during a Controller Handoff
727 */
728 GETMXDS_FORMAT_3_CRHDLY = 0x91U,
729
730 /** Invalid defining byte. */
731 GETMXDS_FORMAT_3_INVALID = 0x100,
732 };
733
734
735 /**
736 * @brief Payload for GETMXDS CCC (Get Max Data Speed).
737 */
738 union i3c_ccc_getmxds {
739 struct {
740 /** maxWr */
741 uint8_t maxwr;
742
743 /** maxRd */
744 uint8_t maxrd;
745 } fmt1;
746
747 struct {
748 /** maxWr */
749 uint8_t maxwr;
750
751 /** maxRd */
752 uint8_t maxrd;
753
754 /**
755 * Maximum Read Turnaround Time in microsecond.
756 *
757 * This is in little-endian where first byte is LSB.
758 */
759 uint8_t maxrdturn[3];
760 } fmt2;
761
762 struct {
763 /**
764 * Defining Byte 0x00: WRRDTURN
765 *
766 * @see i3c_ccc_getmxds::fmt2
767 */
768 uint8_t wrrdturn[5];
769
770 /**
771 * Defining Byte 0x91: CRHDLY
772 * - Bit[2]: Set Bus Activity State
773 * - Bit[1:0]: Controller Handoff Activity State
774 */
775 uint8_t crhdly1;
776 } fmt3;
777 } __packed;
778
779 /** Get Max Data Speed (GETMXDS) - Default Max Sustained Data Rate. */
780 #define I3C_CCC_GETMXDS_MAX_SDR_FSCL_MAX 0
781
782 /** Get Max Data Speed (GETMXDS) - 8MHz Max Sustained Data Rate. */
783 #define I3C_CCC_GETMXDS_MAX_SDR_FSCL_8MHZ 1
784
785 /** Get Max Data Speed (GETMXDS) - 6MHz Max Sustained Data Rate. */
786 #define I3C_CCC_GETMXDS_MAX_SDR_FSCL_6MHZ 2
787
788 /** Get Max Data Speed (GETMXDS) - 4MHz Max Sustained Data Rate. */
789 #define I3C_CCC_GETMXDS_MAX_SDR_FSCL_4MHZ 3
790
791 /** Get Max Data Speed (GETMXDS) - 2MHz Max Sustained Data Rate. */
792 #define I3C_CCC_GETMXDS_MAX_SDR_FSCL_2MHZ 4
793
794 /** Get Max Data Speed (GETMXDS) - Clock to Data Turnaround <= 8ns. */
795 #define I3C_CCC_GETMXDS_TSCO_8NS 0
796
797 /** Get Max Data Speed (GETMXDS) - Clock to Data Turnaround <= 9ns. */
798 #define I3C_CCC_GETMXDS_TSCO_9NS 1
799
800 /** Get Max Data Speed (GETMXDS) - Clock to Data Turnaround <= 10ns. */
801 #define I3C_CCC_GETMXDS_TSCO_10NS 2
802
803 /** Get Max Data Speed (GETMXDS) - Clock to Data Turnaround <= 11ns. */
804 #define I3C_CCC_GETMXDS_TSCO_11NS 3
805
806 /** Get Max Data Speed (GETMXDS) - Clock to Data Turnaround <= 12ns. */
807 #define I3C_CCC_GETMXDS_TSCO_12NS 4
808
809 /** Get Max Data Speed (GETMXDS) - Clock to Data Turnaround > 12ns. */
810 #define I3C_CCC_GETMXDS_TSCO_GT_12NS 7
811
812 /** Get Max Data Speed (GETMXDS) - maxWr - Optional Defining Byte Support. */
813 #define I3C_CCC_GETMXDS_MAXWR_DEFINING_BYTE_SUPPORT BIT(3)
814
815 /** Get Max Data Speed (GETMXDS) - Max Sustained Data Rate bitmask. */
816 #define I3C_CCC_GETMXDS_MAXWR_MAX_SDR_FSCL_MASK GENMASK(2U, 0U)
817
818 /**
819 * @brief Get Max Data Speed (GETMXDS) - maxWr - Max Sustained Data Rate
820 *
821 * Obtain Max Sustained Data Rate value from GETMXDS maxWr value
822 * obtained via GETMXDS.
823 *
824 * @param maxwr GETMXDS maxWr value.
825 */
826 #define I3C_CCC_GETMXDS_MAXWR_MAX_SDR_FSCL(maxwr) \
827 FIELD_GET(I3C_CCC_GETMXDS_MAXWR_MAX_SDR_FSCL_MASK, (maxwr))
828
829 /** Get Max Data Speed (GETMXDS) - maxRd - Write-to-Read Permits Stop Between. */
830 #define I3C_CCC_GETMXDS_MAXRD_W2R_PERMITS_STOP_BETWEEN BIT(6)
831
832 /** Get Max Data Speed (GETMXDS) - maxRd - Clock to Data Turnaround bitmask. */
833 #define I3C_CCC_GETMXDS_MAXRD_TSCO_MASK GENMASK(5U, 3U)
834
835 /**
836 * @brief Get Max Data Speed (GETMXDS) - maxRd - Clock to Data Turnaround
837 *
838 * Obtain Clock to Data Turnaround value from GETMXDS maxRd value
839 * obtained via GETMXDS.
840 *
841 * @param maxrd GETMXDS maxRd value.
842 */
843 #define I3C_CCC_GETMXDS_MAXRD_TSCO(maxrd) \
844 FIELD_GET(I3C_CCC_GETMXDS_MAXRD_TSCO_MASK, (maxrd))
845
846 /** Get Max Data Speed (GETMXDS) - maxRd - Max Sustained Data Rate bitmask. */
847 #define I3C_CCC_GETMXDS_MAXRD_MAX_SDR_FSCL_MASK GENMASK(2U, 0U)
848
849 /**
850 * @brief Get Max Data Speed (GETMXDS) - maxRd - Max Sustained Data Rate
851 *
852 * Obtain Max Sustained Data Rate value from GETMXDS maxRd value
853 * obtained via GETMXDS.
854 *
855 * @param maxrd GETMXDS maxRd value.
856 */
857 #define I3C_CCC_GETMXDS_MAXRD_MAX_SDR_FSCL(maxrd) \
858 FIELD_GET(I3C_CCC_GETMXDS_MAXRD_MAX_SDR_FSCL_MASK, (maxrd))
859
860 /** Get Max Data Speed (GETMXDS) - CRDHLY1 - Set Bus Activity State bit shift value. */
861 #define I3C_CCC_GETMXDS_CRDHLY1_SET_BUS_ACT_STATE BIT(2)
862
863 /** Get Max Data Speed (GETMXDS) - CRDHLY1 - Controller Handoff Activity State bitmask. */
864 #define I3C_CCC_GETMXDS_CRDHLY1_CTRL_HANDOFF_ACT_STATE_MASK GENMASK(1U, 0U)
865
866 /**
867 * @brief Get Max Data Speed (GETMXDS) - CRDHLY1 - Controller Handoff Activity State
868 *
869 * Obtain Controller Handoff Activity State value from GETMXDS value
870 * obtained via GETMXDS.
871 *
872 * @param crhdly1 GETMXDS value.
873 */
874 #define I3C_CCC_GETMXDS_CRDHLY1_CTRL_HANDOFF_ACT_STATE(crhdly1) \
875 FIELD_GET(I3C_CCC_GETMXDS_CRDHLY1_CTRL_HANDOFF_ACT_STATE_MASK, (crhdly1))
876
877 /**
878 * @brief Indicate which format of GETCAPS to use.
879 */
880 enum i3c_ccc_getcaps_fmt {
881 /** GETCAPS Format 1 */
882 GETCAPS_FORMAT_1,
883
884 /** GETCAPS Format 2 */
885 GETCAPS_FORMAT_2,
886 };
887
888 /**
889 * @brief Enum for I3C Get Capabilities (GETCAPS) Format 2 Defining Byte Values.
890 */
891 enum i3c_ccc_getcaps_defbyte {
892 /** Standard Target capabilities and features. */
893 GETCAPS_FORMAT_2_TGTCAPS = 0x00U,
894
895 /** Fixed 32b test pattern. */
896 GETCAPS_FORMAT_2_TESTPAT = 0x5AU,
897
898 /** Controller handoff capabilities and features. */
899 GETCAPS_FORMAT_2_CRCAPS = 0x91U,
900
901 /** Virtual Target capabilities and features. */
902 GETCAPS_FORMAT_2_VTCAPS = 0x93U,
903
904 /** Debug-capable Device capabilities and features. */
905 GETCAPS_FORMAT_2_DBGCAPS = 0xD7U,
906
907 /** Invalid defining byte. */
908 GETCAPS_FORMAT_2_INVALID = 0x100,
909 };
910
911 /**
912 * @brief Payload for GETCAPS CCC (Get Optional Feature Capabilities).
913 *
914 * @note Only supports GETCAPS Format 1 and Format 2. In I3C v1.0 this was
915 * GETHDRCAP which only returned a single byte which is the same as the
916 * GETCAPS1 byte.
917 */
918 union i3c_ccc_getcaps {
919 union {
920 /**
921 * I3C v1.0 HDR Capabilities
922 * - Bit[0]: HDR-DDR
923 * - Bit[1]: HDR-TSP
924 * - Bit[2]: HDR-TSL
925 * - Bit[7:3]: Reserved
926 */
927 uint8_t gethdrcap;
928
929 /**
930 * I3C v1.1+ Device Capabilities
931 * Byte 1 GETCAPS1
932 * - Bit[0]: HDR-DDR
933 * - Bit[1]: HDR-TSP
934 * - Bit[2]: HDR-TSL
935 * - Bit[3]: HDR-BT
936 * - Bit[7:4]: Reserved
937 * Byte 2 GETCAPS2
938 * - Bit[3:0]: I3C 1.x Specification Version
939 * - Bit[5:4]: Group Address Capabilities
940 * - Bit[6]: HDR-DDR Write Abort
941 * - Bit[7]: HDR-DDR Abort CRC
942 * Byte 3 GETCAPS3
943 * - Bit[0]: Multi-Lane (ML) Data Transfer Support
944 * - Bit[1]: Device to Device Transfer (D2DXFER) Support
945 * - Bit[2]: Device to Device Transfer (D2DXFER) IBI Capable
946 * - Bit[3]: Defining Byte Support in GETCAPS
947 * - Bit[4]: Defining Byte Support in GETSTATUS
948 * - Bit[5]: HDR-BT CRC-32 Support
949 * - Bit[6]: IBI MDB Support for Pending Read Notification
950 * - Bit[7]: Reserved
951 * Byte 4 GETCAPS4
952 * - Bit[7:0]: Reserved
953 */
954 uint8_t getcaps[4];
955 } fmt1;
956
957 union {
958 /**
959 * Defining Byte 0x00: TGTCAPS
960 *
961 * @see i3c_ccc_getcaps::fmt1::getcaps
962 */
963 uint8_t tgtcaps[4];
964
965 /**
966 * Defining Byte 0x5A: TESTPAT
967 *
968 * @note should always be 0xA55AA55A in big endian
969 */
970 uint32_t testpat;
971
972 /**
973 * Defining Byte 0x91: CRCAPS
974 * Byte 1 CRCAPS1
975 * - Bit[0]: Hot-Join Support
976 * - Bit[1]: Group Management Support
977 * - Bit[2]: Multi-Lane Support
978 * Byte 2 CRCAPS2
979 * - Bit[0]: In-Band Interrupt Support
980 * - Bit[1]: Controller Pass-Back
981 * - Bit[2]: Deep Sleep Capable
982 * - Bit[3]: Delayed Controller Handoff
983 */
984 uint8_t crcaps[2];
985
986 /**
987 * Defining Byte 0x93: VTCAPS
988 * Byte 1 VTCAPS1
989 * - Bit[2:0]: Virtual Target Type
990 * - Bit[4]: Side Effects
991 * - Bit[5]: Shared Peripheral Detect
992 * Byte 2 VTCAPS2
993 * - Bit[1:0]: Interrupt Requests
994 * - Bit[2]: Address Remapping
995 * - Bit[4:3]: Bus Context and Conditions
996 */
997 uint8_t vtcaps[2];
998 } fmt2;
999 } __packed;
1000
1001 /** Get Optional Feature Capabilities Byte 1 (GETCAPS) Format 1 - HDR-DDR mode bit. */
1002 #define I3C_CCC_GETCAPS1_HDR_DDR BIT(0)
1003
1004 /** Get Optional Feature Capabilities Byte 1 (GETCAPS) Format 1 - HDR-TSP mode bit. */
1005 #define I3C_CCC_GETCAPS1_HDR_TSP BIT(1)
1006
1007 /** Get Optional Feature Capabilities Byte 1 (GETCAPS) Format 1 - HDR-TSL mode bit. */
1008 #define I3C_CCC_GETCAPS1_HDR_TSL BIT(2)
1009
1010 /** Get Optional Feature Capabilities Byte 1 (GETCAPS) Format 1 - HDR-BT mode bit. */
1011 #define I3C_CCC_GETCAPS1_HDR_BT BIT(3)
1012
1013 /**
1014 * @brief Get Optional Feature Capabilities Byte 1 (GETCAPS) - HDR Mode
1015 *
1016 * Get the bit corresponding to HDR mode.
1017 *
1018 * @param x HDR mode
1019 */
1020 #define I3C_CCC_GETCAPS1_HDR_MODE(x) BIT(x)
1021
1022 /** Get Optional Feature Capabilities Byte 1 (GETCAPS) Format 1 - HDR Mode 0. */
1023 #define I3C_CCC_GETCAPS1_HDR_MODE0 BIT(0)
1024
1025 /** Get Optional Feature Capabilities Byte 1 (GETCAPS) Format 1 - HDR Mode 1. */
1026 #define I3C_CCC_GETCAPS1_HDR_MODE1 BIT(1)
1027
1028 /** Get Optional Feature Capabilities Byte 1 (GETCAPS) Format 1 - HDR Mode 2. */
1029 #define I3C_CCC_GETCAPS1_HDR_MODE2 BIT(2)
1030
1031 /** Get Optional Feature Capabilities Byte 1 (GETCAPS) Format 1 - HDR Mode 3. */
1032 #define I3C_CCC_GETCAPS1_HDR_MODE3 BIT(3)
1033
1034 /** Get Optional Feature Capabilities Byte 1 (GETCAPS) Format 1 - HDR Mode 4. */
1035 #define I3C_CCC_GETCAPS1_HDR_MODE4 BIT(4)
1036
1037 /** Get Optional Feature Capabilities Byte 1 (GETCAPS) Format 1 - HDR Mode 5. */
1038 #define I3C_CCC_GETCAPS1_HDR_MODE5 BIT(5)
1039
1040 /** Get Optional Feature Capabilities Byte 1 (GETCAPS) Format 1 - HDR Mode 6. */
1041 #define I3C_CCC_GETCAPS1_HDR_MODE6 BIT(6)
1042
1043 /** Get Optional Feature Capabilities Byte 1 (GETCAPS) Format 1 - HDR Mode 7. */
1044 #define I3C_CCC_GETCAPS1_HDR_MODE7 BIT(7)
1045
1046 /** Get Optional Feature Capabilities Byte 2 (GETCAPS) Format 1 - HDR-DDR Write Abort bit. */
1047 #define I3C_CCC_GETCAPS2_HDRDDR_WRITE_ABORT BIT(6)
1048
1049 /** Get Optional Feature Capabilities Byte 2 (GETCAPS) Format 1 - HDR-DDR Abort CRC bit. */
1050 #define I3C_CCC_GETCAPS2_HDRDDR_ABORT_CRC BIT(7)
1051
1052 /**
1053 * @brief Get Optional Feature Capabilities Byte 2 (GETCAPS) Format 1 -
1054 * Group Address Capabilities bitmask.
1055 */
1056 #define I3C_CCC_GETCAPS2_GRPADDR_CAP_MASK GENMASK(5U, 4U)
1057
1058 /**
1059 * @brief Get Optional Feature Capabilities Byte 2 (GETCAPS) Format 1 - Group Address Capabilities.
1060 *
1061 * Obtain Group Address Capabilities value from GETCAPS Format 1 value
1062 * obtained via GETCAPS.
1063 *
1064 * @param getcaps2 GETCAPS2 value.
1065 */
1066 #define I3C_CCC_GETCAPS2_GRPADDR_CAP(getcaps2) \
1067 FIELD_GET(I3C_CCC_GETCAPS2_GRPADDR_CAP_MASK, (getcaps2))
1068
1069 /**
1070 * @brief Get Optional Feature Capabilities Byte 2 (GETCAPS) Format 1 -
1071 * I3C 1.x Specification Version bitmask.
1072 */
1073 #define I3C_CCC_GETCAPS2_SPEC_VER_MASK GENMASK(3U, 0U)
1074
1075 /**
1076 * @brief Get Optional Feature Capabilities Byte 2 (GETCAPS) Format 1 -
1077 * I3C 1.x Specification Version.
1078 *
1079 * Obtain I3C 1.x Specification Version value from GETCAPS Format 1 value
1080 * obtained via GETCAPS.
1081 *
1082 * @param getcaps2 GETCAPS2 value.
1083 */
1084 #define I3C_CCC_GETCAPS2_SPEC_VER(getcaps2) \
1085 FIELD_GET(I3C_CCC_GETCAPS2_SPEC_VER_MASK, (getcaps2))
1086
1087 /**
1088 * @brief Get Optional Feature Capabilities Byte 3 (GETCAPS) Format 1 -
1089 * Multi-Lane Data Transfer Support bit.
1090 */
1091 #define I3C_CCC_GETCAPS3_MLANE_SUPPORT BIT(0)
1092
1093 /**
1094 * @brief Get Optional Feature Capabilities Byte 3 (GETCAPS) Format 1 -
1095 * Device to Device Transfer (D2DXFER) Support bit.
1096 */
1097 #define I3C_CCC_GETCAPS3_D2DXFER_SUPPORT BIT(1)
1098
1099 /**
1100 * @brief Get Optional Feature Capabilities Byte 3 (GETCAPS) Format 1 -
1101 * Device to Device Transfer (D2DXFER) IBI Capable bit.
1102 */
1103 #define I3C_CCC_GETCAPS3_D2DXFER_IBI_CAPABLE BIT(2)
1104
1105 /**
1106 * @brief Get Optional Feature Capabilities Byte 3 (GETCAPS) Format 1 -
1107 * Defining Byte Support in GETCAPS bit.
1108 */
1109 #define I3C_CCC_GETCAPS3_GETCAPS_DEFINING_BYTE_SUPPORT BIT(3)
1110
1111 /**
1112 * @brief Get Optional Feature Capabilities Byte 3 (GETCAPS) Format 1 -
1113 * Defining Byte Support in GETSTATUS bit.
1114 */
1115 #define I3C_CCC_GETCAPS3_GETSTATUS_DEFINING_BYTE_SUPPORT BIT(4)
1116
1117 /**
1118 * @brief Get Optional Feature Capabilities Byte 3 (GETCAPS) Format 1 -
1119 * HDR-BT CRC-32 Support bit.
1120 */
1121 #define I3C_CCC_GETCAPS3_HDRBT_CRC32_SUPPORT BIT(5)
1122
1123 /**
1124 * @brief Get Optional Feature Capabilities Byte 3 (GETCAPS) Format 1 -
1125 * IBI MDB Support for Pending Read Notification bit.
1126 */
1127 #define I3C_CCC_GETCAPS3_IBI_MDR_PENDING_READ_NOTIFICATION BIT(6)
1128
1129 /**
1130 * @brief Get Fixed Test Pattern (GETCAPS) Format 2 -
1131 * Fixed Test Pattern Byte 1.
1132 */
1133 #define I3C_CCC_GETCAPS_TESTPAT1 0xA5
1134
1135 /**
1136 * @brief Get Fixed Test Pattern (GETCAPS) Format 2 -
1137 * Fixed Test Pattern Byte 2.
1138 */
1139 #define I3C_CCC_GETCAPS_TESTPAT2 0x5A
1140
1141 /**
1142 * @brief Get Fixed Test Pattern (GETCAPS) Format 2 -
1143 * Fixed Test Pattern Byte 3.
1144 */
1145 #define I3C_CCC_GETCAPS_TESTPAT3 0xA5
1146
1147 /**
1148 * @brief Get Fixed Test Pattern (GETCAPS) Format 2 -
1149 * Fixed Test Pattern Byte 4.
1150 */
1151 #define I3C_CCC_GETCAPS_TESTPAT4 0x5A
1152
1153 /**
1154 * @brief Get Fixed Test Pattern (GETCAPS) Format 2 -
1155 * Fixed Test Pattern Word in Big Endian.
1156 */
1157 #define I3C_CCC_GETCAPS_TESTPAT 0xA55AA55A
1158
1159 /**
1160 * @brief Get Controller Handoff Capabilities Byte 1 (GETCAPS) Format 2 -
1161 * Hot-Join Support.
1162 */
1163 #define I3C_CCC_GETCAPS_CRCAPS1_HJ_SUPPORT BIT(0)
1164
1165 /**
1166 * @brief Get Controller Handoff Capabilities Byte 1 (GETCAPS) Format 2 -
1167 * Group Management Support.
1168 */
1169 #define I3C_CCC_GETCAPS_CRCAPS1_GRP_MANAGEMENT_SUPPORT BIT(1)
1170
1171 /**
1172 * @brief Get Controller Handoff Capabilities Byte 1 (GETCAPS) Format 2 -
1173 * Multi-Lane Support.
1174 */
1175 #define I3C_CCC_GETCAPS_CRCAPS1_ML_SUPPORT BIT(2)
1176
1177 /**
1178 * @brief Get Controller Handoff Capabilities Byte 2 (GETCAPS) Format 2 -
1179 * In-Band Interrupt Support.
1180 */
1181 #define I3C_CCC_GETCAPS_CRCAPS2_IBI_TIR_SUPPORT BIT(0)
1182
1183 /**
1184 * @brief Get Controller Handoff Capabilities Byte 2 (GETCAPS) Format 2 -
1185 * Controller Pass-Back.
1186 */
1187 #define I3C_CCC_GETCAPS_CRCAPS2_CONTROLLER_PASSBACK BIT(1)
1188
1189 /**
1190 * @brief Get Controller Handoff Capabilities Byte 2 (GETCAPS) Format 2 -
1191 * Deep Sleep Capable.
1192 */
1193 #define I3C_CCC_GETCAPS_CRCAPS2_DEEP_SLEEP_CAPABLE BIT(2)
1194
1195 /**
1196 * @brief Get Controller Handoff Capabilities Byte 2 (GETCAPS) Format 2 -
1197 * Deep Sleep Capable.
1198 */
1199 #define I3C_CCC_GETCAPS_CRCAPS2_DELAYED_CONTROLLER_HANDOFF BIT(3)
1200
1201 /** Get Capabilities (GETCAPS) - VTCAP1 - Virtual Target Type bitmask. */
1202 #define I3C_CCC_GETCAPS_VTCAP1_VITRUAL_TARGET_TYPE_MASK GENMASK(2U, 0U)
1203
1204 /**
1205 * @brief Get Capabilities (GETCAPS) - VTCAP1 - Virtual Target Type
1206 *
1207 * Obtain Virtual Target Type value from VTCAP1 value
1208 * obtained via GETCAPS format 2 VTCAP def byte.
1209 *
1210 * @param vtcap1 VTCAP1 value.
1211 */
1212 #define I3C_CCC_GETCAPS_VTCAP1_VITRUAL_TARGET_TYPE(vtcap1) \
1213 FIELD_GET(I3C_CCC_GETCAPS_VTCAP1_VITRUAL_TARGET_TYPE_MASK, (vtcap1))
1214
1215 /**
1216 * @brief Get Virtual Target Capabilities Byte 1 (GETCAPS) Format 2 -
1217 * Side Effects.
1218 */
1219 #define I3C_CCC_GETCAPS_VTCAP1_SIDE_EFFECTS BIT(4)
1220
1221 /**
1222 * @brief Get Virtual Target Capabilities Byte 1 (GETCAPS) Format 2 -
1223 * Shared Peripheral Detect.
1224 */
1225 #define I3C_CCC_GETCAPS_VTCAP1_SHARED_PERIPH_DETECT BIT(5)
1226
1227 /** Get Capabilities (GETCAPS) - VTCAP2 - Interrupt Requests bitmask. */
1228 #define I3C_CCC_GETCAPS_VTCAP2_INTERRUPT_REQUESTS_MASK GENMASK(1U, 0U)
1229
1230 /**
1231 * @brief Get Capabilities (GETCAPS) - VTCAP2 - Interrupt Requests
1232 *
1233 * Obtain Interrupt Requests value from VTCAP2 value
1234 * obtained via GETCAPS format 2 VTCAP def byte.
1235 *
1236 * @param vtcap2 VTCAP2 value.
1237 */
1238 #define I3C_CCC_GETCAPS_VTCAP2_INTERRUPT_REQUESTS(vtcap2) \
1239 FIELD_GET(I3C_CCC_GETCAPS_VTCAP2_INTERRUPT_REQUESTS_MASK, (vtcap2))
1240
1241 /**
1242 * @brief Get Virtual Target Capabilities Byte 2 (GETCAPS) Format 2 -
1243 * Address Remapping.
1244 */
1245 #define I3C_CCC_GETCAPS_VTCAP2_ADDRESS_REMAPPING BIT(2)
1246
1247 /** Get Capabilities (GETCAPS) - VTCAP2 - Bus Context and Condition bitmask. */
1248 #define I3C_CCC_GETCAPS_VTCAP2_BUS_CONTEXT_AND_COND_MASK GENMASK(4U, 3U)
1249
1250 /**
1251 * @brief Get Capabilities (GETCAPS) - VTCAP2 - Bus Context and Condition
1252 *
1253 * Obtain Bus Context and Condition value from VTCAP2 value
1254 * obtained via GETCAPS format 2 VTCAP def byte.
1255 *
1256 * @param vtcap2 VTCAP2 value.
1257 */
1258 #define I3C_CCC_GETCAPS_VTCAP2_BUS_CONTEXT_AND_COND(vtcap2) \
1259 FIELD_GET(I3C_CCC_GETCAPS_VTCAP2_BUS_CONTEXT_AND_COND_MASK, (vtcap2))
1260
1261 /**
1262 * @brief Enum for I3C Reset Action (RSTACT) Defining Byte Values.
1263 */
1264 enum i3c_ccc_rstact_defining_byte {
1265 /** No Reset on Target Reset Pattern. */
1266 I3C_CCC_RSTACT_NO_RESET = 0x00U,
1267
1268 /** Reset the I3C Peripheral Only. */
1269 I3C_CCC_RSTACT_PERIPHERAL_ONLY = 0x01U,
1270
1271 /** Reset the Whole Target. */
1272 I3C_CCC_RSTACT_RESET_WHOLE_TARGET = 0x02U,
1273
1274 /** Debug Network Adapter Reset. */
1275 I3C_CCC_RSTACT_DEBUG_NETWORK_ADAPTER = 0x03U,
1276
1277 /** Virtual Target Detect. */
1278 I3C_CCC_RSTACT_VIRTUAL_TARGET_DETECT = 0x04U,
1279
1280 /** Return Time to Reset Peripheral */
1281 I3C_CCC_RSTACT_RETURN_TIME_TO_RESET_PERIPHERAL = 0x81U,
1282
1283 /** Return Time to Reset Whole Target */
1284 I3C_CCC_RSTACT_RETURN_TIME_TO_WHOLE_TARGET = 0x82U,
1285
1286 /** Return Time for Debug Network Adapter Reset */
1287 I3C_CCC_RSTACT_RETURN_TIME_FOR_DEBUG_NETWORK_ADAPTER_RESET = 0x83U,
1288
1289 /** Return Virtual Target Indication */
1290 I3C_CCC_RSTACT_RETURN_VIRTUAL_TARGET_INDICATION = 0x84U,
1291 };
1292
1293 /**
1294 * @name Set Bus Context MIPI I3C Specification v1.Y Minor Version (SETBUSCON)
1295 * @anchor I3C_CCC_SETBUSCON_I3C_SPEC
1296 *
1297 * - CONTEXT[7:6]: 2'b00
1298 *
1299 * - CONTEXT[5]: I3C Specification Editorial Revision (within Minor Version)
1300 * - 0: Version 1.Y.0
1301 * - 1: Version 1.Y.1 or greater
1302 *
1303 * - CONTEXT[4]: I3C Specification Family
1304 * - 0: MIPI I3C Specification
1305 * - 1: MIPI I3C Basic Specification
1306 *
1307 * - CONTEXT[3:0]: I3C Specification Minor Version (v1.Y)
1308 * - 0: Illegal, do not use (see Note below)
1309 * (It would encode v1.0, but SETBUSCON was not available in I3C Basic v1.0)
1310 * - 1-15: Version 1.1 - Version 1.15
1311 *
1312 * Examples: Bit[5] Bit[4] Bits[3:0]
1313 * I3C Basic v1.1.0: 1’b0 || 1’b1 || 4’b0001 or 8’b00010001
1314 * I3C Basic v1.1.1: 1’b1 || 1’b1 || 4’b0001 or 8’b00110001
1315 * I3C Basic v1.2.0: 1’b0 || 1’b1 || 4’b0010 or 8’b00010010
1316 *
1317 * @{
1318 */
1319
1320 /** I3C Specification Minor Version shift mask */
1321 #define I3C_CCC_SETBUSCON_I3C_SPEC_MINOR_VER_MASK GENMASK(3U, 0U)
1322
1323 /**
1324 * @brief I3C Specification Minor Version (v1.Y)
1325 *
1326 * Set the context bits for SETBUSCON
1327 *
1328 * @param y I3C Specification Minor Version Number
1329 */
1330 #define I3C_CCC_SETBUSCON_I3C_SPEC_MINOR_VER(y) \
1331 FIELD_PREP(I3C_CCC_SETBUSCON_I3C_SPEC_MINOR_VER_MASK, (y))
1332
1333 /** MIPI I3C Specification */
1334 #define I3C_CCC_SETBUSCON_I3C_SPEC_I3C_SPEC 0
1335
1336 /** MIPI I3C Basic Specification */
1337 #define I3C_CCC_SETBUSCON_I3C_SPEC_I3C_BASIC_SPEC BIT(4)
1338
1339 /** Version 1.Y.0 */
1340 #define I3C_CCC_SETBUSCON_I3C_SPEC_I3C_SPEC_EDITORIAL_1_Y_0 0
1341
1342 /** Version 1.Y.1 or greater */
1343 #define I3C_CCC_SETBUSCON_I3C_SPEC_I3C_SPEC_EDITORIAL_1_Y_1 BIT(5)
1344
1345 /** @} */
1346
1347 /**
1348 * @name Set Bus Context Other Standards Organizations (SETBUSCON)
1349 * @anchor I3C_CCC_SETBUSCON_OTHER_STANDARDS
1350 *
1351 * @{
1352 */
1353
1354 /**
1355 * @brief JEDEC Sideband
1356 *
1357 * JEDEC SideBand Bus device, compliant to JESD403 Specification v1.0 or later.
1358 */
1359 #define I3C_CCC_SETBUSCON_OTHER_STANDARDS_JEDEC_SIDEBAND 128
1360
1361 /**
1362 * @brief MCTP
1363 *
1364 * MCTP for system manageability (conforming to the content protocol defined in
1365 * the MCTP I3C Transport Binding Specification, released by DMTF, version 1.0
1366 * or newer)
1367 */
1368 #define I3C_CCC_SETBUSCON_OTHER_STANDARDS_MCTP 129
1369
1370 /**
1371 * @brief ETSI
1372 *
1373 * ETSI for Secure Smart Platform Devices used for mobile networks authentication
1374 * and other ETSI security functions in mobile ecosystem
1375 */
1376 #define I3C_CCC_SETBUSCON_OTHER_STANDARDS_ETSI 130
1377
1378 /** @} */
1379
1380 /**
1381 * @brief Test if I3C CCC payload is for broadcast.
1382 *
1383 * This tests if the CCC payload is for broadcast.
1384 *
1385 * @param[in] payload Pointer to the CCC payload.
1386 *
1387 * @retval true if payload target is broadcast
1388 * @retval false if payload target is direct
1389 */
i3c_ccc_is_payload_broadcast(const struct i3c_ccc_payload * payload)1390 static inline bool i3c_ccc_is_payload_broadcast(const struct i3c_ccc_payload *payload)
1391 {
1392 return (payload->ccc.id <= I3C_CCC_BROADCAST_MAX_ID);
1393 }
1394
1395 /**
1396 * @brief Get BCR from a target
1397 *
1398 * Helper function to get BCR (Bus Characteristic Register) from
1399 * target device.
1400 *
1401 * @param[in] target Pointer to the target device descriptor.
1402 * @param[out] bcr Pointer to the BCR payload structure.
1403 *
1404 * @return @see i3c_do_ccc
1405 */
1406 int i3c_ccc_do_getbcr(struct i3c_device_desc *target,
1407 struct i3c_ccc_getbcr *bcr);
1408
1409 /**
1410 * @brief Get DCR from a target
1411 *
1412 * Helper function to get DCR (Device Characteristic Register) from
1413 * target device.
1414 *
1415 * @param[in] target Pointer to the target device descriptor.
1416 * @param[out] dcr Pointer to the DCR payload structure.
1417 *
1418 * @return @see i3c_do_ccc
1419 */
1420 int i3c_ccc_do_getdcr(struct i3c_device_desc *target,
1421 struct i3c_ccc_getdcr *dcr);
1422
1423 /**
1424 * @brief Get PID from a target
1425 *
1426 * Helper function to get PID (Provisioned ID) from
1427 * target device.
1428 *
1429 * @param[in] target Pointer to the target device descriptor.
1430 * @param[out] pid Pointer to the PID payload structure.
1431 *
1432 * @return @see i3c_do_ccc
1433 */
1434 int i3c_ccc_do_getpid(struct i3c_device_desc *target,
1435 struct i3c_ccc_getpid *pid);
1436
1437 /**
1438 * @brief Broadcast RSTACT to reset I3C Peripheral (Format 1).
1439 *
1440 * Helper function to broadcast Target Reset Action (RSTACT) to
1441 * all connected targets.
1442 *
1443 * @param[in] controller Pointer to the controller device driver instance.
1444 * @param[in] action What reset action to perform.
1445 *
1446 * @return @see i3c_do_ccc
1447 */
1448 int i3c_ccc_do_rstact_all(const struct device *controller,
1449 enum i3c_ccc_rstact_defining_byte action);
1450
1451 /**
1452 * @brief Single target RSTACT to reset I3C Peripheral.
1453 *
1454 * Helper function to do Target Reset Action (RSTACT) to
1455 * one target.
1456 *
1457 * @param[in] target Pointer to the target device descriptor.
1458 * @param[in] action What reset action to perform.
1459 * @param[in] get True if a get, False if set
1460 * @param[out] data Pointer to RSTACT payload received.
1461 *
1462 * @return @see i3c_do_ccc
1463 */
1464 int i3c_ccc_do_rstact(const struct i3c_device_desc *target,
1465 enum i3c_ccc_rstact_defining_byte action,
1466 bool get,
1467 uint8_t *data);
1468
1469 /**
1470 * @brief Single target RSTACT to reset I3C Peripheral (Format 2).
1471 *
1472 * Helper function to do Target Reset Action (RSTACT, format 2) to
1473 * one target. This is a Direct Write.
1474 *
1475 * @param[in] target Pointer to the target device descriptor.
1476 * @param[in] action What reset action to perform.
1477 *
1478 * @return @see i3c_do_ccc
1479 */
i3c_ccc_do_rstact_fmt2(const struct i3c_device_desc * target,enum i3c_ccc_rstact_defining_byte action)1480 static inline int i3c_ccc_do_rstact_fmt2(const struct i3c_device_desc *target,
1481 enum i3c_ccc_rstact_defining_byte action)
1482 {
1483 return i3c_ccc_do_rstact(target, action, false, NULL);
1484 }
1485
1486 /**
1487 * @brief Single target RSTACT to reset I3C Peripheral (Format 3).
1488 *
1489 * Helper function to do Target Reset Action (RSTACT, format 3) to
1490 * one target. This is a Direct Read.
1491 *
1492 * @param[in] target Pointer to the target device descriptor.
1493 * @param[in] action What reset action to perform.
1494 * @param[out] data Pointer to RSTACT payload received.
1495 *
1496 * @return @see i3c_do_ccc
1497 */
i3c_ccc_do_rstact_fmt3(const struct i3c_device_desc * target,enum i3c_ccc_rstact_defining_byte action,uint8_t * data)1498 static inline int i3c_ccc_do_rstact_fmt3(const struct i3c_device_desc *target,
1499 enum i3c_ccc_rstact_defining_byte action,
1500 uint8_t *data)
1501 {
1502 return i3c_ccc_do_rstact(target, action, true, data);
1503 }
1504
1505 /**
1506 * @brief Broadcast RSTDAA to reset dynamic addresses for all targets.
1507 *
1508 * Helper function to reset dynamic addresses of all connected targets.
1509 *
1510 * @param[in] controller Pointer to the controller device driver instance.
1511 *
1512 * @return @see i3c_do_ccc
1513 */
1514 int i3c_ccc_do_rstdaa_all(const struct device *controller);
1515
1516 /**
1517 * @brief Set Dynamic Address from Static Address for a target
1518 *
1519 * Helper function to do SETDASA (Set Dynamic Address from Static Address)
1520 * for a particular target.
1521 *
1522 * Note this does not update @p target with the new dynamic address.
1523 *
1524 * @param[in] target Pointer to the target device descriptor where
1525 * the device is configured with a static address.
1526 * @param[in] da Struct of the Dynamic address
1527 *
1528 * @return @see i3c_do_ccc
1529 */
1530 int i3c_ccc_do_setdasa(const struct i3c_device_desc *target,
1531 struct i3c_ccc_address da);
1532
1533 /**
1534 * @brief Set New Dynamic Address for a target
1535 *
1536 * Helper function to do SETNEWDA(Set New Dynamic Address) for a particular target.
1537 *
1538 * Note this does not update @p target with the new dynamic address.
1539 *
1540 * @param[in] target Pointer to the target device descriptor where
1541 * the device is configured with a static address.
1542 * @param[in] new_da Struct of the Dynamic address
1543 *
1544 * @return @see i3c_do_ccc
1545 */
1546 int i3c_ccc_do_setnewda(const struct i3c_device_desc *target,
1547 struct i3c_ccc_address new_da);
1548
1549 /**
1550 * @brief Broadcast ENEC/DISEC to enable/disable target events.
1551 *
1552 * Helper function to broadcast Target Events Command to enable or
1553 * disable target events (ENEC/DISEC).
1554 *
1555 * @param[in] controller Pointer to the controller device driver instance.
1556 * @param[in] enable ENEC if true, DISEC if false.
1557 * @param[in] events Pointer to the event struct.
1558 *
1559 * @return @see i3c_do_ccc
1560 */
1561 int i3c_ccc_do_events_all_set(const struct device *controller,
1562 bool enable, struct i3c_ccc_events *events);
1563
1564 /**
1565 * @brief Direct CCC ENEC/DISEC to enable/disable target events.
1566 *
1567 * Helper function to send Target Events Command to enable or
1568 * disable target events (ENEC/DISEC) on a single target.
1569 *
1570 * @param[in] target Pointer to the target device descriptor.
1571 * @param[in] enable ENEC if true, DISEC if false.
1572 * @param[in] events Pointer to the event struct.
1573 *
1574 * @return @see i3c_do_ccc
1575 */
1576 int i3c_ccc_do_events_set(struct i3c_device_desc *target,
1577 bool enable, struct i3c_ccc_events *events);
1578
1579 /**
1580 * @brief Direct ENTAS to set the Activity State.
1581 *
1582 * Helper function to broadcast Activity State Command on a single
1583 * target.
1584 *
1585 * @param[in] target Pointer to the target device descriptor.
1586 * @param[in] as Activity State level
1587 *
1588 * @return @see i3c_do_ccc
1589 */
1590 int i3c_ccc_do_entas(const struct i3c_device_desc *target, uint8_t as);
1591
1592 /**
1593 * @brief Direct ENTAS0
1594 *
1595 * Helper function to do ENTAS0 setting the minimum bus activity level to 1us
1596 * on a single target.
1597 *
1598 * @param[in] target Pointer to the target device descriptor.
1599 *
1600 * @return @see i3c_do_ccc
1601 */
i3c_ccc_do_entas0(const struct i3c_device_desc * target)1602 static inline int i3c_ccc_do_entas0(const struct i3c_device_desc *target)
1603 {
1604 return i3c_ccc_do_entas(target, 0);
1605 }
1606
1607 /**
1608 * @brief Direct ENTAS1
1609 *
1610 * Helper function to do ENTAS1 setting the minimum bus activity level to 100us
1611 * on a single target.
1612 *
1613 * @param[in] target Pointer to the target device descriptor.
1614 *
1615 * @return @see i3c_do_ccc
1616 */
i3c_ccc_do_entas1(const struct i3c_device_desc * target)1617 static inline int i3c_ccc_do_entas1(const struct i3c_device_desc *target)
1618 {
1619 return i3c_ccc_do_entas(target, 1);
1620 }
1621
1622 /**
1623 * @brief Direct ENTAS2
1624 *
1625 * Helper function to do ENTAS2 setting the minimum bus activity level to 2ms
1626 * on a single target.
1627 *
1628 * @param[in] target Pointer to the target device descriptor.
1629 *
1630 * @return @see i3c_do_ccc
1631 */
i3c_ccc_do_entas2(const struct i3c_device_desc * target)1632 static inline int i3c_ccc_do_entas2(const struct i3c_device_desc *target)
1633 {
1634 return i3c_ccc_do_entas(target, 2);
1635 }
1636
1637 /**
1638 * @brief Direct ENTAS3
1639 *
1640 * Helper function to do ENTAS3 setting the minimum bus activity level to 50ms
1641 * on a single target.
1642 *
1643 * @param[in] target Pointer to the target device descriptor.
1644 *
1645 * @return @see i3c_do_ccc
1646 */
i3c_ccc_do_entas3(const struct i3c_device_desc * target)1647 static inline int i3c_ccc_do_entas3(const struct i3c_device_desc *target)
1648 {
1649 return i3c_ccc_do_entas(target, 3);
1650 }
1651
1652 /**
1653 * @brief Broadcast ENTAS to set the Activity State.
1654 *
1655 * Helper function to broadcast Activity State Command.
1656 *
1657 * @param[in] controller Pointer to the controller device driver instance.
1658 * @param[in] as Activity State level
1659 *
1660 * @return @see i3c_do_ccc
1661 */
1662 int i3c_ccc_do_entas_all(const struct device *controller, uint8_t as);
1663
1664 /**
1665 * @brief Broadcast ENTAS0
1666 *
1667 * Helper function to do ENTAS0 setting the minimum bus activity level to 1us
1668 *
1669 * @param[in] controller Pointer to the controller device driver instance.
1670 *
1671 * @return @see i3c_do_ccc
1672 */
i3c_ccc_do_entas0_all(const struct device * controller)1673 static inline int i3c_ccc_do_entas0_all(const struct device *controller)
1674 {
1675 return i3c_ccc_do_entas_all(controller, 0);
1676 }
1677
1678 /**
1679 * @brief Broadcast ENTAS1
1680 *
1681 * Helper function to do ENTAS1 setting the minimum bus activity level to 100us
1682 *
1683 * @param[in] controller Pointer to the controller device driver instance.
1684 *
1685 * @return @see i3c_do_ccc
1686 */
i3c_ccc_do_entas1_all(const struct device * controller)1687 static inline int i3c_ccc_do_entas1_all(const struct device *controller)
1688 {
1689 return i3c_ccc_do_entas_all(controller, 1);
1690 }
1691
1692 /**
1693 * @brief Broadcast ENTAS2
1694 *
1695 * Helper function to do ENTAS2 setting the minimum bus activity level to 2ms
1696 *
1697 * @param[in] controller Pointer to the controller device driver instance.
1698 *
1699 * @return @see i3c_do_ccc
1700 */
i3c_ccc_do_entas2_all(const struct device * controller)1701 static inline int i3c_ccc_do_entas2_all(const struct device *controller)
1702 {
1703 return i3c_ccc_do_entas_all(controller, 2);
1704 }
1705
1706 /**
1707 * @brief Broadcast ENTAS3
1708 *
1709 * Helper function to do ENTAS3 setting the minimum bus activity level to 50ms
1710 *
1711 * @param[in] controller Pointer to the controller device driver instance.
1712 *
1713 * @return @see i3c_do_ccc
1714 */
i3c_ccc_do_entas3_all(const struct device * controller)1715 static inline int i3c_ccc_do_entas3_all(const struct device *controller)
1716 {
1717 return i3c_ccc_do_entas_all(controller, 3);
1718 }
1719
1720 /**
1721 * @brief Broadcast SETMWL to Set Maximum Write Length.
1722 *
1723 * Helper function to do SETMWL (Set Maximum Write Length) to
1724 * all connected targets.
1725 *
1726 * @param[in] controller Pointer to the controller device driver instance.
1727 * @param[in] mwl Pointer to SETMWL payload.
1728 *
1729 * @return @see i3c_do_ccc
1730 */
1731 int i3c_ccc_do_setmwl_all(const struct device *controller,
1732 const struct i3c_ccc_mwl *mwl);
1733
1734 /**
1735 * @brief Single target SETMWL to Set Maximum Write Length.
1736 *
1737 * Helper function to do SETMWL (Set Maximum Write Length) to
1738 * one target.
1739 *
1740 * @param[in] target Pointer to the target device descriptor.
1741 * @param[in] mwl Pointer to SETMWL payload.
1742 *
1743 * @return @see i3c_do_ccc
1744 */
1745 int i3c_ccc_do_setmwl(const struct i3c_device_desc *target,
1746 const struct i3c_ccc_mwl *mwl);
1747
1748 /**
1749 * @brief Single target GETMWL to Get Maximum Write Length.
1750 *
1751 * Helper function to do GETMWL (Get Maximum Write Length) of
1752 * one target.
1753 *
1754 * @param[in] target Pointer to the target device descriptor.
1755 * @param[out] mwl Pointer to GETMWL payload.
1756 *
1757 * @return @see i3c_do_ccc
1758 */
1759 int i3c_ccc_do_getmwl(const struct i3c_device_desc *target,
1760 struct i3c_ccc_mwl *mwl);
1761
1762 /**
1763 * @brief Broadcast SETMRL to Set Maximum Read Length.
1764 *
1765 * Helper function to do SETMRL (Set Maximum Read Length) to
1766 * all connected targets.
1767 *
1768 * @param[in] controller Pointer to the controller device driver instance.
1769 * @param[in] mrl Pointer to SETMRL payload.
1770 * @param[in] has_ibi_size True if also sending the optional IBI payload
1771 * size. False if not sending.
1772 *
1773 * @return @see i3c_do_ccc
1774 */
1775 int i3c_ccc_do_setmrl_all(const struct device *controller,
1776 const struct i3c_ccc_mrl *mrl,
1777 bool has_ibi_size);
1778
1779 /**
1780 * @brief Single target SETMRL to Set Maximum Read Length.
1781 *
1782 * Helper function to do SETMRL (Set Maximum Read Length) to
1783 * one target.
1784 *
1785 * Note this uses the BCR of the target to determine whether
1786 * to send the optional IBI payload size.
1787 *
1788 * @param[in] target Pointer to the target device descriptor.
1789 * @param[in] mrl Pointer to SETMRL payload.
1790 *
1791 * @return @see i3c_do_ccc
1792 */
1793 int i3c_ccc_do_setmrl(const struct i3c_device_desc *target,
1794 const struct i3c_ccc_mrl *mrl);
1795
1796 /**
1797 * @brief Single target GETMRL to Get Maximum Read Length.
1798 *
1799 * Helper function to do GETMRL (Get Maximum Read Length) of
1800 * one target.
1801 *
1802 * Note this uses the BCR of the target to determine whether
1803 * to send the optional IBI payload size.
1804 *
1805 * @param[in] target Pointer to the target device descriptor.
1806 * @param[out] mrl Pointer to GETMRL payload.
1807 *
1808 * @return @see i3c_do_ccc
1809 */
1810 int i3c_ccc_do_getmrl(const struct i3c_device_desc *target,
1811 struct i3c_ccc_mrl *mrl);
1812
1813 /**
1814 * @brief Broadcast ENTTM
1815 *
1816 * Helper function to do ENTTM (Enter Test Mode) to all devices
1817 *
1818 * @param[in] controller Pointer to the controller device driver instance.
1819 * @param[in] defbyte Defining Byte for ENTTM.
1820 *
1821 * @return @see i3c_do_ccc
1822 */
1823 int i3c_ccc_do_enttm(const struct device *controller,
1824 enum i3c_ccc_enttm_defbyte defbyte);
1825
1826 /**
1827 * @brief Single target GETSTATUS to Get Target Status.
1828 *
1829 * Helper function to do GETSTATUS (Get Target Status) of
1830 * one target.
1831 *
1832 * Note this uses the BCR of the target to determine whether
1833 * to send the optional IBI payload size.
1834 *
1835 * @param[in] target Pointer to the target device descriptor.
1836 * @param[out] status Pointer to GETSTATUS payload.
1837 * @param[in] fmt Which GETSTATUS to use.
1838 * @param[in] defbyte Defining Byte if using format 2.
1839 *
1840 * @return @see i3c_do_ccc
1841 */
1842 int i3c_ccc_do_getstatus(const struct i3c_device_desc *target,
1843 union i3c_ccc_getstatus *status,
1844 enum i3c_ccc_getstatus_fmt fmt,
1845 enum i3c_ccc_getstatus_defbyte defbyte);
1846
1847 /**
1848 * @brief Single target GETSTATUS to Get Target Status (Format 1).
1849 *
1850 * Helper function to do GETSTATUS (Get Target Status, format 1) of
1851 * one target.
1852 *
1853 * @param[in] target Pointer to the target device descriptor.
1854 * @param[out] status Pointer to GETSTATUS payload.
1855 *
1856 * @return @see i3c_do_ccc
1857 */
i3c_ccc_do_getstatus_fmt1(const struct i3c_device_desc * target,union i3c_ccc_getstatus * status)1858 static inline int i3c_ccc_do_getstatus_fmt1(const struct i3c_device_desc *target,
1859 union i3c_ccc_getstatus *status)
1860 {
1861 return i3c_ccc_do_getstatus(target, status,
1862 GETSTATUS_FORMAT_1,
1863 GETSTATUS_FORMAT_2_INVALID);
1864 }
1865
1866 /**
1867 * @brief Single target GETSTATUS to Get Target Status (Format 2).
1868 *
1869 * Helper function to do GETSTATUS (Get Target Status, format 2) of
1870 * one target.
1871 *
1872 * @param[in] target Pointer to the target device descriptor.
1873 * @param[out] status Pointer to GETSTATUS payload.
1874 * @param[in] defbyte Defining Byte for GETSTATUS format 2.
1875 *
1876 * @return @see i3c_do_ccc
1877 */
i3c_ccc_do_getstatus_fmt2(const struct i3c_device_desc * target,union i3c_ccc_getstatus * status,enum i3c_ccc_getstatus_defbyte defbyte)1878 static inline int i3c_ccc_do_getstatus_fmt2(const struct i3c_device_desc *target,
1879 union i3c_ccc_getstatus *status,
1880 enum i3c_ccc_getstatus_defbyte defbyte)
1881 {
1882 return i3c_ccc_do_getstatus(target, status,
1883 GETSTATUS_FORMAT_2, defbyte);
1884 }
1885
1886 /**
1887 * @brief Single target GETCAPS to Get Target Status.
1888 *
1889 * Helper function to do GETCAPS (Get Capabilities) of
1890 * one target.
1891 *
1892 * This should only be supported if Advanced Capabilities Bit of
1893 * the BCR is set
1894 *
1895 * @param[in] target Pointer to the target device descriptor.
1896 * @param[out] caps Pointer to GETCAPS payload.
1897 * @param[in] fmt Which GETCAPS to use.
1898 * @param[in] defbyte Defining Byte if using format 2.
1899 *
1900 * @return @see i3c_do_ccc
1901 */
1902 int i3c_ccc_do_getcaps(const struct i3c_device_desc *target,
1903 union i3c_ccc_getcaps *caps,
1904 enum i3c_ccc_getcaps_fmt fmt,
1905 enum i3c_ccc_getcaps_defbyte defbyte);
1906
1907 /**
1908 * @brief Single target GETCAPS to Get Capabilities (Format 1).
1909 *
1910 * Helper function to do GETCAPS (Get Capabilities, format 1) of
1911 * one target.
1912 *
1913 * @param[in] target Pointer to the target device descriptor.
1914 * @param[out] caps Pointer to GETCAPS payload.
1915 *
1916 * @return @see i3c_do_ccc
1917 */
i3c_ccc_do_getcaps_fmt1(const struct i3c_device_desc * target,union i3c_ccc_getcaps * caps)1918 static inline int i3c_ccc_do_getcaps_fmt1(const struct i3c_device_desc *target,
1919 union i3c_ccc_getcaps *caps)
1920 {
1921 return i3c_ccc_do_getcaps(target, caps,
1922 GETCAPS_FORMAT_1,
1923 GETCAPS_FORMAT_2_INVALID);
1924 }
1925
1926 /**
1927 * @brief Single target GETCAPS to Get Capabilities (Format 2).
1928 *
1929 * Helper function to do GETCAPS (Get Capabilities, format 2) of
1930 * one target.
1931 *
1932 * @param[in] target Pointer to the target device descriptor.
1933 * @param[out] caps Pointer to GETCAPS payload.
1934 * @param[in] defbyte Defining Byte for GETCAPS format 2.
1935 *
1936 * @return @see i3c_do_ccc
1937 */
i3c_ccc_do_getcaps_fmt2(const struct i3c_device_desc * target,union i3c_ccc_getcaps * caps,enum i3c_ccc_getcaps_defbyte defbyte)1938 static inline int i3c_ccc_do_getcaps_fmt2(const struct i3c_device_desc *target,
1939 union i3c_ccc_getcaps *caps,
1940 enum i3c_ccc_getcaps_defbyte defbyte)
1941 {
1942 return i3c_ccc_do_getcaps(target, caps,
1943 GETCAPS_FORMAT_2, defbyte);
1944 }
1945
1946 /**
1947 * @brief Single target to Set Vendor / Standard Extension CCC
1948 *
1949 * Helper function to set Vendor / Standard Extension CCC of
1950 * one target.
1951 *
1952 * @param[in] target Pointer to the target device descriptor.
1953 * @param[in] id Vendor CCC ID.
1954 * @param[in] payload Pointer to payload.
1955 * @param[in] len Length of payload. 0 if no payload.
1956 *
1957 * @return @see i3c_do_ccc
1958 */
1959 int i3c_ccc_do_setvendor(const struct i3c_device_desc *target,
1960 uint8_t id,
1961 uint8_t *payload,
1962 size_t len);
1963
1964 /**
1965 * @brief Single target to Get Vendor / Standard Extension CCC
1966 *
1967 * Helper function to get Vendor / Standard Extension CCC of
1968 * one target.
1969 *
1970 * @param[in] target Pointer to the target device descriptor.
1971 * @param[in] id Vendor CCC ID.
1972 * @param[out] payload Pointer to payload.
1973 * @param[in] len Maximum Expected Length of the payload
1974 * @param[out] num_xfer Length of the received payload
1975 *
1976 * @return @see i3c_do_ccc
1977 */
1978 int i3c_ccc_do_getvendor(const struct i3c_device_desc *target,
1979 uint8_t id,
1980 uint8_t *payload,
1981 size_t len,
1982 size_t *num_xfer);
1983
1984 /**
1985 * @brief Single target to Get Vendor / Standard Extension CCC
1986 * with a defining byte
1987 *
1988 * Helper function to get Vendor / Standard Extension CCC of
1989 * one target.
1990 *
1991 * @param[in] target Pointer to the target device descriptor.
1992 * @param[in] id Vendor CCC ID.
1993 * @param[in] defbyte Defining Byte
1994 * @param[out] payload Pointer to payload.
1995 * @param[in] len Maximum Expected Length of the payload
1996 * @param[out] num_xfer Length of the received payload
1997 *
1998 * @return @see i3c_do_ccc
1999 */
2000 int i3c_ccc_do_getvendor_defbyte(const struct i3c_device_desc *target,
2001 uint8_t id,
2002 uint8_t defbyte,
2003 uint8_t *payload,
2004 size_t len,
2005 size_t *num_xfer);
2006
2007 /**
2008 * @brief Broadcast Set Vendor / Standard Extension CCC
2009 *
2010 * Helper function to broadcast Vendor / Standard Extension CCC
2011 *
2012 * @param[in] controller Pointer to the controller device driver instance.
2013 * @param[in] id Vendor CCC ID.
2014 * @param[in] payload Pointer to payload.
2015 * @param[in] len Length of payload. 0 if no payload.
2016 *
2017 * @return @see i3c_do_ccc
2018 */
2019 int i3c_ccc_do_setvendor_all(const struct device *controller,
2020 uint8_t id,
2021 uint8_t *payload,
2022 size_t len);
2023
2024 /**
2025 * @brief Broadcast SETAASA to set all target's dynamic address to their
2026 * static address.
2027 *
2028 * Helper function to set dynamic addresses of all connected targets to
2029 * their static address.
2030 *
2031 * @param[in] controller Pointer to the controller device driver instance.
2032 *
2033 * @return @see i3c_do_ccc
2034 */
2035 int i3c_ccc_do_setaasa_all(const struct device *controller);
2036
2037 /**
2038 * @brief Single target GETMXDS to Get Max Data Speed.
2039 *
2040 * Helper function to do GETMXDS (Get Max Data Speed) of
2041 * one target.
2042 *
2043 * This should only be supported if Max Data Speed Limit Bit of
2044 * the BCR is set
2045 *
2046 * @param[in] target Pointer to the target device descriptor.
2047 * @param[out] caps Pointer to GETMXDS payload.
2048 * @param[in] fmt Which GETMXDS to use.
2049 * @param[in] defbyte Defining Byte if using format 3.
2050 *
2051 * @return @see i3c_do_ccc
2052 */
2053 int i3c_ccc_do_getmxds(const struct i3c_device_desc *target,
2054 union i3c_ccc_getmxds *caps,
2055 enum i3c_ccc_getmxds_fmt fmt,
2056 enum i3c_ccc_getmxds_defbyte defbyte);
2057
2058 /**
2059 * @brief Single target GETMXDS to Get Max Data Speed (Format 1).
2060 *
2061 * Helper function to do GETMXDS (Get Max Data Speed, format 1) of
2062 * one target.
2063 *
2064 * @param[in] target Pointer to the target device descriptor.
2065 * @param[out] caps Pointer to GETMXDS payload.
2066 *
2067 * @return @see i3c_do_ccc
2068 */
i3c_ccc_do_getmxds_fmt1(const struct i3c_device_desc * target,union i3c_ccc_getmxds * caps)2069 static inline int i3c_ccc_do_getmxds_fmt1(const struct i3c_device_desc *target,
2070 union i3c_ccc_getmxds *caps)
2071 {
2072 return i3c_ccc_do_getmxds(target, caps,
2073 GETMXDS_FORMAT_1,
2074 GETMXDS_FORMAT_3_INVALID);
2075 }
2076
2077 /**
2078 * @brief Single target GETMXDS to Get Max Data Speed (Format 2).
2079 *
2080 * Helper function to do GETMXDS (Get Max Data Speed, format 2) of
2081 * one target.
2082 *
2083 * @param[in] target Pointer to the target device descriptor.
2084 * @param[out] caps Pointer to GETMXDS payload.
2085 *
2086 * @return @see i3c_do_ccc
2087 */
i3c_ccc_do_getmxds_fmt2(const struct i3c_device_desc * target,union i3c_ccc_getmxds * caps)2088 static inline int i3c_ccc_do_getmxds_fmt2(const struct i3c_device_desc *target,
2089 union i3c_ccc_getmxds *caps)
2090 {
2091 return i3c_ccc_do_getmxds(target, caps,
2092 GETMXDS_FORMAT_2,
2093 GETMXDS_FORMAT_3_INVALID);
2094 }
2095
2096 /**
2097 * @brief Single target GETMXDS to Get Max Data Speed (Format 3).
2098 *
2099 * Helper function to do GETMXDS (Get Max Data Speed, format 3) of
2100 * one target.
2101 *
2102 * @param[in] target Pointer to the target device descriptor.
2103 * @param[out] caps Pointer to GETMXDS payload.
2104 * @param[in] defbyte Defining Byte for GETMXDS format 3.
2105 *
2106 * @return @see i3c_do_ccc
2107 */
i3c_ccc_do_getmxds_fmt3(const struct i3c_device_desc * target,union i3c_ccc_getmxds * caps,enum i3c_ccc_getmxds_defbyte defbyte)2108 static inline int i3c_ccc_do_getmxds_fmt3(const struct i3c_device_desc *target,
2109 union i3c_ccc_getmxds *caps,
2110 enum i3c_ccc_getmxds_defbyte defbyte)
2111 {
2112 return i3c_ccc_do_getmxds(target, caps,
2113 GETMXDS_FORMAT_3, defbyte);
2114 }
2115
2116 /**
2117 * @brief Broadcast DEFTGTS
2118 *
2119 * @param[in] controller Pointer to the controller device driver instance.
2120 * @param[in] deftgts Pointer to the deftgts payload.
2121 *
2122 * @return @see i3c_do_ccc
2123 */
2124 int i3c_ccc_do_deftgts_all(const struct device *controller,
2125 struct i3c_ccc_deftgts *deftgts);
2126
2127 /**
2128 * @brief Broadcast SETBUSCON to set the bus context
2129 *
2130 * Helper function to set the bus context of all connected targets.
2131 *
2132 * @param[in] controller Pointer to the controller device driver instance.
2133 * @param[in] context Pointer to context byte values
2134 * @param[in] length Length of the context buffer
2135 *
2136 * @return @see i3c_do_ccc
2137 */
2138 int i3c_ccc_do_setbuscon(const struct device *controller,
2139 uint8_t *context, uint16_t length);
2140
2141 /**
2142 * @brief Direct GETACCCR for Controller Handoff
2143 *
2144 * Helper function to allow for the Active Controller to pass the
2145 * Controller Role to a Secondary Controller. The returned address
2146 * should match it's dynamic address along with odd parity.
2147 *
2148 * Note it is up to the caller to verify the correct returned address
2149 *
2150 * @param[in] target Pointer to the target device descriptor.
2151 * @param[out] handoff_address Pointer to the address returned by the secondary
2152 * controller.
2153 *
2154 * @return @see i3c_do_ccc
2155 */
2156 int i3c_ccc_do_getacccr(const struct i3c_device_desc *target,
2157 struct i3c_ccc_address *handoff_address);
2158
2159 #ifdef __cplusplus
2160 }
2161 #endif
2162
2163 /**
2164 * @}
2165 */
2166
2167 #endif /* ZEPHYR_INCLUDE_DRIVERS_I3C_CCC_H_ */
2168
