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