1 /*
2 * Copyright 2022 Intel Corporation
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 */
6
7 #ifndef ZEPHYR_INCLUDE_DRIVERS_I3C_CCC_H_
8 #define ZEPHYR_INCLUDE_DRIVERS_I3C_CCC_H_
9
10 /**
11 * @brief I3C Common Command Codes
12 * @defgroup i3c_ccc I3C Common Command Codes
13 * @ingroup i3c_interface
14 * @{
15 */
16
17 #include <zephyr/types.h>
18 #include <zephyr/device.h>
19 #include <zephyr/toolchain.h>
20 #include <zephyr/sys/util.h>
21
22 #ifdef __cplusplus
23 extern "C" {
24 #endif
25
26 /** Maximum CCC ID for broadcast */
27 #define I3C_CCC_BROADCAST_MAX_ID 0x7FU
28
29 /**
30 * Enable Events Command
31 *
32 * @param broadcast True if broadcast, false if direct.
33 */
34 #define I3C_CCC_ENEC(broadcast) ((broadcast) ? 0x00U : 0x80U)
35
36 /**
37 * Disable Events Command
38 *
39 * @param broadcast True if broadcast, false if direct.
40 */
41 #define I3C_CCC_DISEC(broadcast) ((broadcast) ? 0x01U : 0x81U)
42
43 /**
44 * Enter Activity State
45 *
46 * @param as Desired activity state
47 * @param broadcast True if broadcast, false if direct.
48 */
49 #define I3C_CCC_ENTAS(as, broadcast) (((broadcast) ? 0x02U : 0x82U) + (as))
50
51 /**
52 * Enter Activity State 0
53 *
54 * @param broadcast True if broadcast, false if direct.
55 */
56 #define I3C_CCC_ENTAS0(broadcast) I3C_CCC_ENTAS(0, broadcast)
57
58 /**
59 * Enter Activity State 1
60 *
61 * @param broadcast True if broadcast, false if direct.
62 */
63 #define I3C_CCC_ENTAS1(broadcast) I3C_CCC_ENTAS(1, broadcast)
64
65 /**
66 * Enter Activity State 2
67 *
68 * @param broadcast True if broadcast, false if direct.
69 */
70 #define I3C_CCC_ENTAS2(broadcast) I3C_CCC_ENTAS(2, broadcast)
71
72 /**
73 * Enter Activity State 3
74 *
75 * @param broadcast True if broadcast, false if direct.
76 */
77 #define I3C_CCC_ENTAS3(broadcast) I3C_CCC_ENTAS(3, broadcast)
78
79 /** Reset Dynamic Address Assignment (Broadcast) */
80 #define I3C_CCC_RSTDAA 0x06U
81
82 /** Enter Dynamic Address Assignment (Broadcast) */
83 #define I3C_CCC_ENTDAA 0x07U
84
85 /** Define List of Targets (Broadcast) */
86 #define I3C_CCC_DEFTGTS 0x08U
87
88 /**
89 * Set Max Write Length (Broadcast or Direct)
90 *
91 * @param broadcast True if broadcast, false if direct.
92 */
93 #define I3C_CCC_SETMWL(broadcast) ((broadcast) ? 0x09U : 0x89U)
94
95 /**
96 * Set Max Read Length (Broadcast or Direct)
97 *
98 * @param broadcast True if broadcast, false if direct.
99 */
100 #define I3C_CCC_SETMRL(broadcast) ((broadcast) ? 0x0AU : 0x8AU)
101
102 /** Enter Test Mode (Broadcast) */
103 #define I3C_CCC_ENTTM 0x0BU
104
105 /** Set Bus Context (Broadcast) */
106 #define I3C_CCC_SETBUSCON 0x0CU
107
108 /**
109 * Data Transfer Ending Procedure Control
110 *
111 * @param broadcast True if broadcast, false if direct.
112 */
113 #define I3C_CCC_ENDXFER(broadcast) ((broadcast) ? 0x12U : 0x92U)
114
115 /** Enter HDR Mode (HDR-DDR) (Broadcast) */
116 #define I3C_CCC_ENTHDR(x) (0x20U + (x))
117
118 /** Enter HDR Mode 0 (HDR-DDR) (Broadcast) */
119 #define I3C_CCC_ENTHDR0 0x20U
120
121 /** Enter HDR Mode 1 (HDR-TSP) (Broadcast) */
122 #define I3C_CCC_ENTHDR1 0x21U
123
124 /** Enter HDR Mode 2 (HDR-TSL) (Broadcast) */
125 #define I3C_CCC_ENTHDR2 0x22U
126
127 /** Enter HDR Mode 3 (HDR-BT) (Broadcast) */
128 #define I3C_CCC_ENTHDR3 0x23U
129
130 /** Enter HDR Mode 4 (Broadcast) */
131 #define I3C_CCC_ENTHDR4 0x24U
132
133 /** Enter HDR Mode 5 (Broadcast) */
134 #define I3C_CCC_ENTHDR5 0x25U
135
136 /** Enter HDR Mode 6 (Broadcast) */
137 #define I3C_CCC_ENTHDR6 0x26U
138
139 /** Enter HDR Mode 7 (Broadcast) */
140 #define I3C_CCC_ENTHDR7 0x27U
141
142 /**
143 * Exchange Timing Information (Broadcast or Direct)
144 *
145 * @param broadcast True if broadcast, false if direct.
146 */
147 #define I3C_CCC_SETXTIME(broadcast) ((broadcast) ? 0x28U : 0x98U)
148
149 /** Set All Addresses to Static Addresses (Broadcast) */
150 #define I3C_CCC_SETAASA 0x29U
151
152 /**
153 * Target Reset Action
154 *
155 * @param broadcast True if broadcast, false if direct.
156 */
157 #define I3C_CCC_RSTACT(broadcast) ((broadcast) ? 0x2AU : 0x9AU)
158
159 /** Define List of Group Address (Broadcast) */
160 #define I3C_CCC_DEFGRPA 0x2BU
161
162 /**
163 * Reset Group Address
164 *
165 * @param broadcast True if broadcast, false if direct.
166 */
167 #define I3C_CCC_RSTGRPA(broadcast) ((broadcast) ? 0x2CU : 0x9CU)
168
169 /** Multi-Lane Data Transfer Control (Broadcast) */
170 #define I3C_CCC_MLANE(broadcast) ((broadcast) ? 0x2DU : 0x9DU)
171
172 /**
173 * Vendor/Standard Extension
174 *
175 * @param broadcast True if broadcast, false if direct.
176 * @param id Extension ID.
177 */
178 #define I3C_CCC_VENDOR(broadcast, id) ((id) + ((broadcast) ? 0x61U : 0xE0U))
179
180 /** Set Dynamic Address from Static Address (Direct) */
181 #define I3C_CCC_SETDASA 0x87U
182
183 /** Set New Dynamic Address (Direct) */
184 #define I3C_CCC_SETNEWDA 0x88U
185
186 /** Get Max Write Length (Direct) */
187 #define I3C_CCC_GETMWL 0x8BU
188
189 /** Get Max Read Length (Direct) */
190 #define I3C_CCC_GETMRL 0x8CU
191
192 /** Get Provisioned ID (Direct) */
193 #define I3C_CCC_GETPID 0x8DU
194
195 /** Get Bus Characteristics Register (Direct) */
196 #define I3C_CCC_GETBCR 0x8EU
197
198 /** Get Device Characteristics Register (Direct) */
199 #define I3C_CCC_GETDCR 0x8FU
200
201 /** Get Device Status (Direct) */
202 #define I3C_CCC_GETSTATUS 0x90U
203
204 /** Get Accept Controller Role (Direct) */
205 #define I3C_CCC_GETACCCR 0x91U
206
207 /** Set Bridge Targets (Direct) */
208 #define I3C_CCC_SETBRGTGT 0x93U
209
210 /** Get Max Data Speed (Direct) */
211 #define I3C_CCC_GETMXDS 0x94U
212
213 /** Get Optional Feature Capabilities (Direct) */
214 #define I3C_CCC_GETCAPS 0x95U
215
216 /** Set Route (Direct) */
217 #define I3C_CCC_SETROUTE 0x96U
218
219 /** Device to Device(s) Tunneling Control (Direct) */
220 #define I3C_CCC_D2DXFER 0x97U
221
222 /** Get Exchange Timing Information (Direct) */
223 #define I3C_CCC_GETXTIME 0x99U
224
225 /** Set Group Address (Direct) */
226 #define I3C_CCC_SETGRPA 0x9BU
227
228 struct i3c_device_desc;
229
230 /**
231 * @brief Payload structure for Direct CCC to one target.
232 */
233 struct i3c_ccc_target_payload {
234 /** Target address */
235 uint8_t addr;
236
237 /** @c 0 for Write, @c 1 for Read */
238 uint8_t rnw:1;
239
240 /**
241 * - For Write CCC, pointer to the byte array of data
242 * to be sent, which may contain the Sub-Command Byte
243 * and additional data.
244 * - For Read CCC, pointer to the byte buffer for data
245 * to be read into.
246 */
247 uint8_t *data;
248
249 /** Length in bytes for @p data. */
250 size_t data_len;
251 };
252
253 /**
254 * @brief Payload structure for one CCC transaction.
255 */
256 struct i3c_ccc_payload {
257 struct {
258 /**
259 * The CCC ID (@c I3C_CCC_*).
260 */
261 uint8_t id;
262
263 /**
264 * Pointer to byte array of data for this CCC.
265 *
266 * This is the bytes following the CCC command in CCC frame.
267 * Set to @c NULL if no associated data.
268 */
269 uint8_t *data;
270
271 /** Length in bytes for optional data array. */
272 size_t data_len;
273 } ccc;
274
275 struct {
276 /**
277 * Array of struct i3c_ccc_target_payload.
278 *
279 * Each element describes the target and associated
280 * payloads for this CCC.
281 *
282 * Use with Direct CCC.
283 */
284 struct i3c_ccc_target_payload *payloads;
285
286 /** Number of targets */
287 size_t num_targets;
288 } targets;
289 };
290
291 /**
292 * @brief Payload for ENEC/DISEC CCC (Target Events Command).
293 */
294 struct i3c_ccc_events {
295 /**
296 * Event byte:
297 * - Bit[0]: ENINT/DISINT:
298 * - Target Interrupt Requests
299 * - Bit[1]: ENCR/DISCR:
300 * - Controller Role Requests
301 * - Bit[3]: ENHJ/DISHJ:
302 * - Hot-Join Event
303 */
304 uint8_t events;
305 } __packed;
306
307 /* For Enable Events */
308 #define I3C_CCC_ENEC_EVT_ENINTR BIT(0)
309 #define I3C_CCC_ENEC_EVT_ENCR BIT(1)
310 #define I3C_CCC_ENEC_EVT_ENHJ BIT(3)
311
312 #define I3C_CCC_ENEC_EVT_ALL \
313 (I3C_CCC_ENEC_EVT_ENINTR | I3C_CCC_ENEC_EVT_ENCR | I3C_CCC_ENEC_EVT_ENHJ)
314
315 /* For Disable Events */
316 #define I3C_CCC_DISEC_EVT_DISINTR BIT(0)
317 #define I3C_CCC_DISEC_EVT_DISCR BIT(1)
318 #define I3C_CCC_DISEC_EVT_DISHJ BIT(3)
319
320 #define I3C_CCC_DISEC_EVT_ALL \
321 (I3C_CCC_DISEC_EVT_DISINTR | I3C_CCC_DISEC_EVT_DISCR | I3C_CCC_DISEC_EVT_DISHJ)
322
323 /*
324 * Events for both enabling and disabling since
325 * they have the same bits.
326 */
327 #define I3C_CCC_EVT_INTR BIT(0)
328 #define I3C_CCC_EVT_CR BIT(1)
329 #define I3C_CCC_EVT_HJ BIT(3)
330
331 #define I3C_CCC_EVT_ALL \
332 (I3C_CCC_EVT_INTR | I3C_CCC_EVT_CR | I3C_CCC_EVT_HJ)
333
334 /**
335 * @brief Payload for SETMWL/GETMWL CCC (Set/Get Maximum Write Length).
336 *
337 * @note For drivers and help functions, the raw data coming
338 * back from target device is in big endian. This needs to be
339 * translated back to CPU endianness before passing back to
340 * function caller.
341 */
342 struct i3c_ccc_mwl {
343 /** Maximum Write Length */
344 uint16_t len;
345 } __packed;
346
347 /**
348 * @brief Payload for SETMRL/GETMRL CCC (Set/Get Maximum Read Length).
349 *
350 * @note For drivers and help functions, the raw data coming
351 * back from target device is in big endian. This needs to be
352 * translated back to CPU endianness before passing back to
353 * function caller.
354 */
355 struct i3c_ccc_mrl {
356 /** Maximum Read Length */
357 uint16_t len;
358
359 /** Optional IBI Payload Size */
360 uint8_t ibi_len;
361 } __packed;
362
363 /**
364 * @brief The active controller part of payload for DEFTGTS CCC.
365 *
366 * This is used by DEFTGTS (Define List of Targets) CCC to describe
367 * the active controller on the I3C bus.
368 */
369 struct i3c_ccc_deftgts_active_controller {
370 /** Dynamic Address of Active Controller */
371 uint8_t addr;
372
373 /** Device Characteristic Register of Active Controller */
374 uint8_t dcr;
375
376 /** Bus Characteristic Register of Active Controller */
377 uint8_t bcr;
378
379 /** Static Address of Active Controller */
380 uint8_t static_addr;
381 };
382
383 /**
384 * @brief The target device part of payload for DEFTGTS CCC.
385 *
386 * This is used by DEFTGTS (Define List of Targets) CCC to describe
387 * the existing target devices on the I3C bus.
388 */
389 struct i3c_ccc_deftgts_target {
390 /** Dynamic Address of a target device, or a group address */
391 uint8_t addr;
392
393 union {
394 /**
395 * Device Characteristic Register of a I3C target device
396 * or a group.
397 */
398 uint8_t dcr;
399
400 /** Legacy Virtual Register for legacy I2C device. */
401 uint8_t lvr;
402 };
403
404 /** Bus Characteristic Register of a target device or a group */
405 uint8_t bcr;
406
407 /** Static Address of a target device or a group */
408 uint8_t static_addr;
409 };
410
411 /**
412 * @brief Payload for DEFTGTS CCC (Define List of Targets).
413 *
414 * @note @p i3c_ccc_deftgts_target is an array of targets, where
415 * the number of elements is dependent on the number of I3C targets
416 * on the bus. Please have enough space for both read and write of
417 * this CCC.
418 */
419 struct i3c_ccc_deftgts {
420 /** Data describing the active controller */
421 struct i3c_ccc_deftgts_active_controller active_controller;
422
423 /** Data describing the target(s) on the bus */
424 struct i3c_ccc_deftgts_target targets[];
425 } __packed;
426
427 /**
428 * @brief Payload for a single device address.
429 *
430 * This is used for:
431 * - SETDASA (Set Dynamic Address from Static Address)
432 * - SETNEWDA (Set New Dynamic Address)
433 * - SETGRPA (Set Group Address)
434 * - GETACCCR (Get Accept Controller Role)
435 *
436 * Note that the target address is encoded within
437 * struct i3c_ccc_target_payload instead of being encoded in
438 * this payload.
439 */
440 struct i3c_ccc_address {
441 /**
442 * - For SETDASA, Static Address to be assigned as
443 * Dynamic Address.
444 * - For SETNEWDA, new Dynamic Address to be assigned.
445 * - For SETGRPA, new Group Address to be set.
446 * - For GETACCCR, the correct address of Secondary
447 * Controller.
448 *
449 * @note For SETDATA, SETNEWDA and SETGRAP,
450 * the address is left-shift by 1, and bit[0] is always 0.
451 *
452 * @note Fpr SET GETACCCR, the address is left-shift by 1,
453 * and bit[0] is the calculated odd parity bit.
454 */
455 uint8_t addr;
456 } __packed;
457
458 /**
459 * @brief Payload for GETPID CCC (Get Provisioned ID).
460 */
461 struct i3c_ccc_getpid {
462 /**
463 * 48-bit Provisioned ID.
464 *
465 * @note Data is big-endian where first byte is MSB.
466 */
467 uint8_t pid[6];
468 } __packed;
469
470 /**
471 * @brief Payload for GETBCR CCC (Get Bus Characteristics Register).
472 */
473 struct i3c_ccc_getbcr {
474 /** Bus Characteristics Register */
475 uint8_t bcr;
476 } __packed;
477
478 /**
479 * @brief Payload for GETDCR CCC (Get Device Characteristics Register).
480 */
481 struct i3c_ccc_getdcr {
482 /** Device Characteristics Register */
483 uint8_t dcr;
484 } __packed;
485
486
487 /**
488 * @brief Indicate which format of GETSTATUS to use.
489 */
490 enum i3c_ccc_getstatus_fmt {
491 GETSTATUS_FORMAT_1,
492 GETSTATUS_FORMAT_2,
493 };
494
495 enum i3c_ccc_getstatus_defbyte {
496 GETSTATUS_FORMAT_2_TGTSTAT = 0x00U,
497 GETSTATUS_FORMAT_2_PRECR = 0x91U,
498
499 GETSTATUS_FORMAT_2_INVALID = 0x100U
500 };
501
502 /**
503 * @brief Payload for GETSTATUS CCC (Get Device Status).
504 */
505 union i3c_ccc_getstatus {
506 struct {
507 /**
508 * Device Status
509 * - Bit[15:8]: Reserved.
510 * - Bit[7:6]: Activity Mode.
511 * - Bit[5]: Protocol Error.
512 * - Bit[4]: Reserved.
513 * - Bit[3:0]: Number of Pending Interrupts.
514 *
515 * @note For drivers and help functions, the raw data coming
516 * back from target device is in big endian. This needs to be
517 * translated back to CPU endianness before passing back to
518 * function caller.
519 */
520 uint16_t status;
521 } fmt1;
522
523 union {
524 /**
525 * Defining Byte 0x00: TGTSTAT
526 *
527 * @see i3c_ccc_getstatus::fmt1::status
528 */
529 uint16_t tgtstat;
530
531 /**
532 * Defining Byte 0x91: PRECR
533 * - Bit[15:8]: Vendor Reserved
534 * - Bit[7:2]: Reserved
535 * - Bit[1]: Handoff Delay NACK
536 * - Bit[0]: Deep Sleep Detected
537 *
538 * @note For drivers and help functions, the raw data coming
539 * back from target device is in big endian. This needs to be
540 * translated back to CPU endianness before passing back to
541 * function caller.
542 */
543 uint16_t precr;
544
545 uint16_t raw_u16;
546 } fmt2;
547 } __packed;
548
549 #define I3C_CCC_GETSTATUS_PROTOCOL_ERR BIT(5)
550
551 #define I3C_CCC_GETSTATUS_ACTIVITY_MODE_SHIFT 6
552
553 #define I3C_CCC_GETSTATUS_ACTIVITY_MODE_MASK \
554 (0x03U << I3C_CCC_GETSTATUS_ACTIVITY_MODE_SHIFT)
555
556 #define I3C_CCC_GETSTATUS_ACTIVITY_MODE(status) \
557 (((status) & I3C_CCC_GETSTATUS_ACTIVITY_MODE_MASK) \
558 >> I3C_CCC_GETSTATUS_ACTIVITY_MODE_SHIFT)
559
560 #define I3C_CCC_GETSTATUS_NUM_INT_SHIFT 0
561
562 #define I3C_CCC_GETSTATUS_NUM_INT_MASK \
563 (0x0FU << I3C_CCC_GETSTATUS_NUM_INT_SHIFT)
564
565 #define I3C_CCC_GETSTATUS_NUM_INT(status) \
566 (((status) & I3C_CCC_GETSTATUS_NUM_INT_MASK) \
567 >> I3C_CCC_GETSTATUS_NUM_INT_SHIFT)
568
569 #define I3C_CCC_GETSTATUS_PRECR_DEEP_SLEEP_DETECTED BIT(0)
570
571 #define I3C_CCC_GETSTATUS_PRECR_HANDOFF_DELAY_NACK BIT(1)
572
573 /**
574 * @brief One Bridged Target for SETBRGTGT payload.
575 */
576 struct i3c_ccc_setbrgtgt_tgt {
577 /**
578 * Dynamic address of the bridged target.
579 *
580 * @note The address is left-shift by 1, and bit[0]
581 * is always 0.
582 */
583 uint8_t addr;
584
585 /**
586 * 16-bit ID for the bridged target.
587 *
588 * @note For drivers and help functions, the raw data coming
589 * back from target device is in big endian. This needs to be
590 * translated back to CPU endianness before passing back to
591 * function caller.
592 */
593 uint16_t id;
594 } __packed;
595
596 /**
597 * @brief Payload for SETBRGTGT CCC (Set Bridge Targets).
598 *
599 * Note that the bridge target address is encoded within
600 * struct i3c_ccc_target_payload instead of being encoded in
601 * this payload.
602 */
603 struct i3c_ccc_setbrgtgt {
604 /** Number of bridged targets */
605 uint8_t count;
606
607 /** Array of bridged targets */
608 struct i3c_ccc_setbrgtgt_tgt targets[];
609 } __packed;
610
611 /**
612 * @brief Payload for GETMXDS CCC (Get Max Data Speed).
613 *
614 * @note This is only for GETMXDS Format 1 and Format 2.
615 */
616 union i3c_ccc_getmxds {
617 struct {
618 /** maxWr */
619 uint8_t maxwr;
620
621 /** maxRd */
622 uint8_t maxrd;
623 } fmt1;
624
625 struct {
626 /** maxWr */
627 uint8_t maxwr;
628
629 /** maxRd */
630 uint8_t maxrd;
631
632 /**
633 * Maximum Read Turnaround Time in microsecond.
634 *
635 * This is in little-endian where first byte is LSB.
636 */
637 uint8_t maxrdturn[3];
638 } fmt2;
639
640 struct {
641 /**
642 * Defining Byte 0x00: WRRDTURN
643 *
644 * @see i3c_ccc_getmxds::fmt2
645 */
646 uint8_t wrrdturn;
647
648 /**
649 * Defining Byte 0x91: CRHDLY
650 * - Bit[2]: Set Bus Actibity State
651 * - Bit[1:0]: Controller Handoff Activity State
652 */
653 uint8_t crhdly1;
654 } fmt3;
655 } __packed;
656
657 #define I3C_CCC_GETMXDS_MAX_SDR_FSCL_MAX 0
658 #define I3C_CCC_GETMXDS_MAX_SDR_FSCL_8MHZ 1
659 #define I3C_CCC_GETMXDS_MAX_SDR_FSCL_6MHZ 2
660 #define I3C_CCC_GETMXDS_MAX_SDR_FSCL_4MHZ 3
661 #define I3C_CCC_GETMXDS_MAX_SDR_FSCL_2MHZ 4
662
663 #define I3C_CCC_GETMXDS_TSCO_8NS 0
664 #define I3C_CCC_GETMXDS_TSCO_9NS 1
665 #define I3C_CCC_GETMXDS_TSCO_10NS 2
666 #define I3C_CCC_GETMXDS_TSCO_11NS 3
667 #define I3C_CCC_GETMXDS_TSCO_12NS 4
668 #define I3C_CCC_GETMXDS_TSCO_GT_12NS 7
669
670 #define I3C_CCC_GETMXDS_MAXWR_DEFINING_BYTE_SUPPORT BIT(3)
671
672 #define I3C_CCC_GETMXDS_MAXWR_MAX_SDR_FSCL_SHIFT 0
673
674 #define I3C_CCC_GETMXDS_MAXWR_MAX_SDR_FSCL_MASK \
675 (0x07U << I3C_CCC_GET_MXDS_MAXWR_MAX_SDR_FSCL_SHIFT)
676
677 #define I3C_CCC_GETMXDS_MAXWR_MAX_SDR_FSCL(maxwr) \
678 (((maxwr) & \
679 I3C_CCC_GETMXDS_MAXWR_MAX_SDR_FSCL_MASK) \
680 >> I3C_CCC_GETMXDS_MAXWR_MAX_SDR_FSCL_SHIFT)
681
682 #define I3C_CCC_GETMXDS_MAXRD_W2R_PERMITS_STOP_BETWEEN BIT(6)
683
684 #define I3C_CCC_GETMXDS_MAXRD_TSCO_SHIFT 3
685
686 #define I3C_CCC_GETMXDS_MAXRD_TSCO_MASK \
687 (0x07U << I3C_CCC_GETMXDS_MAXRD_TSCO_SHIFT)
688
689 #define I3C_CCC_GETMXDS_MAXRD_TSCO(maxrd) \
690 (((maxrd) & I3C_CCC_GETMXDS_MAXRD_TSCO_MASK) \
691 >> I3C_CCC_GETMXDS_MAXRD_TSCO_SHIFT)
692
693 #define I3C_CCC_GETMXDS_MAXRD_MAX_SDR_FSCL_SHIFT 0
694
695 #define I3C_CCC_GETMXDS_MAXRD_MAX_SDR_FSCL_MASK \
696 (0x07U << I3C_CCC_GET_MXDS_MAXRD_MAX_SDR_FSCL_SHIFT)
697
698 #define I3C_CCC_GETMXDS_MAXRD_MAX_SDR_FSCL(maxrd) \
699 (((maxrd) & \
700 I3C_CCC_GETMXDS_MAXRD_MAX_SDR_FSCL_MASK) \
701 >> I3C_CCC_GETMXDS_MAXRD_MAX_SDR_FSCL_SHIFT)
702
703 #define I3C_CCC_GETMXDS_CRDHLY1_SET_BUS_ACT_STATE BIT(2)
704
705 #define I3C_CCC_GETMXDS_CRDHLY1_CTRL_HANDOFF_ACT_STATE_SHIFT 0
706
707 #define I3C_CCC_GETMXDS_CRDHLY1_CTRL_HANDOFF_ACT_STATE_MASK \
708 (0x03U << I3C_CCC_GETMXDS_CRDHLY1_SET_BUS_ACT_STATE_SHIFT)
709
710 #define I3C_CCC_GETMXDS_CRDHLY1_CTRL_HANDOFF_ACT_STATE(crhdly1) \
711 (((crhdly1) & \
712 I3C_CCC_GETMXDS_CRDHLY1_SET_BUS_ACT_STATE_MASK) \
713 >> I3C_CCC_GETMXDS_CRDHLY1_SET_BUS_ACT_STATE_SHIFT)
714
715 /**
716 * @brief Payload for GETCAPS CCC (Get Optional Feature Capabilities).
717 *
718 * @note Only support GETCAPS Format 1.
719 */
720 struct i3c_ccc_getcaps {
721 /**
722 * GETCAP[1-4] bytes.
723 */
724 uint8_t getcaps[4];
725 } __packed;
726
727 #define I3C_CCC_GETCAPS1_HDR_DDR BIT(0)
728 #define I3C_CCC_GETCAPS1_HDR_BT BIT(3)
729
730 #define I3C_CCC_GETCAPS1_HDR_MODE(x) BIT(x)
731 #define I3C_CCC_GETCAPS1_HDR_MODE0 BIT(0)
732 #define I3C_CCC_GETCAPS1_HDR_MODE1 BIT(1)
733 #define I3C_CCC_GETCAPS1_HDR_MODE2 BIT(2)
734 #define I3C_CCC_GETCAPS1_HDR_MODE3 BIT(3)
735 #define I3C_CCC_GETCAPS1_HDR_MODE4 BIT(4)
736 #define I3C_CCC_GETCAPS1_HDR_MODE5 BIT(5)
737 #define I3C_CCC_GETCAPS1_HDR_MODE6 BIT(6)
738 #define I3C_CCC_GETCAPS1_HDR_MODE7 BIT(7)
739
740 #define I3C_CCC_GETCAPS2_HDRDDR_WRITE_ABORT BIT(6)
741 #define I3C_CCC_GETCAPS2_HDRDDR_ABORT_CRC BIT(7)
742
743 #define I3C_CCC_GETCAPS2_GRPADDR_CAP_SHIFT 4
744 #define I3C_CCC_GETCAPS2_GRPADDR_CAP_MASK \
745 (0x03U << I3C_CCC_GETCAPS2_GRPADDR_CAP_SHIFT)
746 #define I3C_CCC_GETCAPS2_GRPADDR_CAP(getcaps2) \
747 (((getcaps2) & \
748 I3C_CCC_GETCAPS2_GRPADDR_CAP_MASK) \
749 >> I3C_CCC_GETCAPS_GRPADDR_CAP_SHIFT)
750
751 #define I3C_CCC_GETCAPS2_SPEC_VER_SHIFT 0
752 #define I3C_CCC_GETCAPS2_SPEC_VER_MASK \
753 (0x0FU << I3C_CCC_GETCAPS2_SPEC_VER_SHIFT)
754 #define I3C_CCC_GETCAPS2_SPEC_VER(getcaps2) \
755 (((getcaps2) & \
756 I3C_CCC_GETCAPS2_SPEC_VER_MASK) \
757 >> I3C_CCC_GETCAPS_SPEC_VER_SHIFT)
758
759 #define I3C_CCC_GETCAPS3_MLAME_SUPPORT BIT(0)
760 #define I3C_CCC_GETCAPS3_D2DXFER_SUPPORT BIT(1)
761 #define I3C_CCC_GETCAPS3_D3DXFER_IBI_CAPABLE BIT(2)
762 #define I3C_CCC_GETCAPS3_GETCAPS_DEFINING_BYTE_SUPPORT BIT(3)
763 #define I3C_CCC_GETCAPS3_GETSTATUS_DEFINING_BYTE_SUPPORT BIT(4)
764 #define I3C_CCC_GETCAPS3_HDRBT_CRC32_SUPPORT BIT(5)
765 #define I3C_CCC_GETCAPS3_IBI_MDR_PENDING_READ_NOTIFICATION BIT(6)
766
767 enum i3c_ccc_rstact_defining_byte {
768 I3C_CCC_RSTACT_NO_RESET = 0x00U,
769 I3C_CCC_RSTACT_PERIPHERAL_ONLY = 0x01U,
770 I3C_CCC_RSTACT_RESET_WHOLE_TARGET = 0x02U,
771 I3C_CCC_RSTACT_DEBUG_NETWORK_ADAPTER = 0x03U,
772 I3C_CCC_RSTACT_VIRTUAL_TARGET_DETECT = 0x04U,
773 };
774
775 /**
776 * @brief Test if I3C CCC payload is for broadcast.
777 *
778 * This tests if the CCC payload is for broadcast.
779 *
780 * @param[in] payload Pointer to the CCC payload.
781 *
782 * @retval true if payload target is broadcast
783 * @retval false if payload target is direct
784 */
i3c_ccc_is_payload_broadcast(const struct i3c_ccc_payload * payload)785 static inline bool i3c_ccc_is_payload_broadcast(const struct i3c_ccc_payload *payload)
786 {
787 return (payload->ccc.id <= I3C_CCC_BROADCAST_MAX_ID);
788 }
789
790 /**
791 * @brief Get BCR from a target
792 *
793 * Helper function to get BCR (Bus Characteristic Register) from
794 * target device.
795 *
796 * @param[in] target Pointer to the target device descriptor.
797 * @param[out] bcr Pointer to the BCR payload structure.
798 *
799 * @return @see i3c_do_ccc
800 */
801 int i3c_ccc_do_getbcr(struct i3c_device_desc *target,
802 struct i3c_ccc_getbcr *bcr);
803
804 /**
805 * @brief Get DCR from a target
806 *
807 * Helper function to get DCR (Device Characteristic Register) from
808 * target device.
809 *
810 * @param[in] target Pointer to the target device descriptor.
811 * @param[out] dcr Pointer to the DCR payload structure.
812 *
813 * @return @see i3c_do_ccc
814 */
815 int i3c_ccc_do_getdcr(struct i3c_device_desc *target,
816 struct i3c_ccc_getdcr *dcr);
817
818 /**
819 * @brief Get PID from a target
820 *
821 * Helper function to get PID (Provisioned ID) from
822 * target device.
823 *
824 * @param[in] target Pointer to the target device descriptor.
825 * @param[out] pid Pointer to the PID payload structure.
826 *
827 * @return @see i3c_do_ccc
828 */
829 int i3c_ccc_do_getpid(struct i3c_device_desc *target,
830 struct i3c_ccc_getpid *pid);
831
832 /**
833 * @brief Broadcast RSTACT to reset I3C Peripheral.
834 *
835 * Helper function to broadcast Target Reset Action (RSTACT) to
836 * all connected targets to Reset the I3C Peripheral Only (0x01).
837 *
838 * @param[in] controller Pointer to the controller device driver instance.
839 * @param[in] action What reset action to perform.
840 *
841 * @return @see i3c_do_ccc
842 */
843 int i3c_ccc_do_rstact_all(const struct device *controller,
844 enum i3c_ccc_rstact_defining_byte action);
845
846 /**
847 * @brief Broadcast RSTDAA to reset dynamic addresses for all targets.
848 *
849 * Helper function to reset dynamic addresses of all connected targets.
850 *
851 * @param[in] controller Pointer to the controller device driver instance.
852 *
853 * @return @see i3c_do_ccc
854 */
855 int i3c_ccc_do_rstdaa_all(const struct device *controller);
856
857 /**
858 * @brief Set Dynamic Address from Static Address for a target
859 *
860 * Helper function to do SETDASA (Set Dynamic Address from Static Address)
861 * for a particular target.
862 *
863 * Note this does not update @p target with the new dynamic address.
864 *
865 * @param[in] target Pointer to the target device descriptor where
866 * the device is configured with a static address.
867 *
868 * @return @see i3c_do_ccc
869 */
870 int i3c_ccc_do_setdasa(const struct i3c_device_desc *target);
871
872 /**
873 * @brief Set New Dynamic Address for a target
874 *
875 * Helper function to do SETNEWDA(Set New Dynamic Address) for a particular target.
876 *
877 * Note this does not update @p target with the new dynamic address.
878 *
879 * @param[in] target Pointer to the target device descriptor where
880 * the device is configured with a static address.
881 * @param[in] new_da Pointer to the new_da struct.
882 *
883 * @return @see i3c_do_ccc
884 */
885 int i3c_ccc_do_setnewda(const struct i3c_device_desc *target,
886 struct i3c_ccc_address new_da);
887
888 /**
889 * @brief Broadcast ENEC/DISEC to enable/disable target events.
890 *
891 * Helper function to broadcast Target Events Command to enable or
892 * disable target events (ENEC/DISEC).
893 *
894 * @param[in] controller Pointer to the controller device driver instance.
895 * @param[in] enable ENEC if true, DISEC if false.
896 * @param[in] events Pointer to the event struct.
897 *
898 * @return @see i3c_do_ccc
899 */
900 int i3c_ccc_do_events_all_set(const struct device *controller,
901 bool enable, struct i3c_ccc_events *events);
902
903 /**
904 * @brief Direct CCC ENEC/DISEC to enable/disable target events.
905 *
906 * Helper function to send Target Events Command to enable or
907 * disable target events (ENEC/DISEC) on a single target.
908 *
909 * @param[in] target Pointer to the target device descriptor.
910 * @param[in] enable ENEC if true, DISEC if false.
911 * @param[in] events Pointer to the event struct.
912 *
913 * @return @see i3c_do_ccc
914 */
915 int i3c_ccc_do_events_set(struct i3c_device_desc *target,
916 bool enable, struct i3c_ccc_events *events);
917
918 /**
919 * @brief Broadcast SETMWL to Set Maximum Write Length.
920 *
921 * Helper function to do SETMWL (Set Maximum Write Length) to
922 * all connected targets.
923 *
924 * @param[in] controller Pointer to the controller device driver instance.
925 * @param[in] mwl Pointer to SETMWL payload.
926 *
927 * @return @see i3c_do_ccc
928 */
929 int i3c_ccc_do_setmwl_all(const struct device *controller,
930 const struct i3c_ccc_mwl *mwl);
931
932 /**
933 * @brief Single target SETMWL to Set Maximum Write Length.
934 *
935 * Helper function to do SETMWL (Set Maximum Write Length) to
936 * one target.
937 *
938 * @param[in] target Pointer to the target device descriptor.
939 * @param[in] mwl Pointer to SETMWL payload.
940 *
941 * @return @see i3c_do_ccc
942 */
943 int i3c_ccc_do_setmwl(const struct i3c_device_desc *target,
944 const struct i3c_ccc_mwl *mwl);
945
946 /**
947 * @brief Single target GETMWL to Get Maximum Write Length.
948 *
949 * Helper function to do GETMWL (Get Maximum Write Length) of
950 * one target.
951 *
952 * @param[in] target Pointer to the target device descriptor.
953 * @param[out] mwl Pointer to GETMWL payload.
954 *
955 * @return @see i3c_do_ccc
956 */
957 int i3c_ccc_do_getmwl(const struct i3c_device_desc *target,
958 struct i3c_ccc_mwl *mwl);
959
960 /**
961 * @brief Broadcast SETMRL to Set Maximum Read Length.
962 *
963 * Helper function to do SETMRL (Set Maximum Read Length) to
964 * all connected targets.
965 *
966 * @param[in] controller Pointer to the controller device driver instance.
967 * @param[in] mrl Pointer to SETMRL payload.
968 * @param[in] has_ibi_size True if also sending the optional IBI payload
969 * size. False if not sending.
970 *
971 * @return @see i3c_do_ccc
972 */
973 int i3c_ccc_do_setmrl_all(const struct device *controller,
974 const struct i3c_ccc_mrl *mrl,
975 bool has_ibi_size);
976
977 /**
978 * @brief Single target SETMRL to Set Maximum Read Length.
979 *
980 * Helper function to do SETMRL (Set Maximum Read Length) to
981 * one target.
982 *
983 * Note this uses the BCR of the target to determine whether
984 * to send the optional IBI payload size.
985 *
986 * @param[in] target Pointer to the target device descriptor.
987 * @param[in] mrl Pointer to SETMRL payload.
988 *
989 * @return @see i3c_do_ccc
990 */
991 int i3c_ccc_do_setmrl(const struct i3c_device_desc *target,
992 const struct i3c_ccc_mrl *mrl);
993
994 /**
995 * @brief Single target GETMRL to Get Maximum Read Length.
996 *
997 * Helper function to do GETMRL (Get Maximum Read Length) of
998 * one target.
999 *
1000 * Note this uses the BCR of the target to determine whether
1001 * to send the optional IBI payload size.
1002 *
1003 * @param[in] target Pointer to the target device descriptor.
1004 * @param[out] mrl Pointer to GETMRL payload.
1005 *
1006 * @return @see i3c_do_ccc
1007 */
1008 int i3c_ccc_do_getmrl(const struct i3c_device_desc *target,
1009 struct i3c_ccc_mrl *mrl);
1010
1011 /**
1012 * @brief Single target GETSTATUS to Get Target Status.
1013 *
1014 * Helper function to do GETSTATUS (Get Target Status) of
1015 * one target.
1016 *
1017 * Note this uses the BCR of the target to determine whether
1018 * to send the optional IBI payload size.
1019 *
1020 * @param[in] target Pointer to the target device descriptor.
1021 * @param[out] status Pointer to GETSTATUS payload.
1022 * @param[in] fmt Which GETSTATUS to use.
1023 * @param[in] defbyte Defining Byte if using format 2.
1024 *
1025 * @return @see i3c_do_ccc
1026 */
1027 int i3c_ccc_do_getstatus(const struct i3c_device_desc *target,
1028 union i3c_ccc_getstatus *status,
1029 enum i3c_ccc_getstatus_fmt fmt,
1030 enum i3c_ccc_getstatus_defbyte defbyte);
1031
1032 /**
1033 * @brief Single target GETSTATUS to Get Target Status (Format 1).
1034 *
1035 * Helper function to do GETSTATUS (Get Target Status, format 1) of
1036 * one target.
1037 *
1038 * @param[in] target Pointer to the target device descriptor.
1039 * @param[out] status Pointer to GETSTATUS payload.
1040 *
1041 * @return @see i3c_do_ccc
1042 */
i3c_ccc_do_getstatus_fmt1(const struct i3c_device_desc * target,union i3c_ccc_getstatus * status)1043 static inline int i3c_ccc_do_getstatus_fmt1(const struct i3c_device_desc *target,
1044 union i3c_ccc_getstatus *status)
1045 {
1046 return i3c_ccc_do_getstatus(target, status,
1047 GETSTATUS_FORMAT_1,
1048 GETSTATUS_FORMAT_2_INVALID);
1049 }
1050
1051 /**
1052 * @brief Single target GETSTATUS to Get Target Status (Format 2).
1053 *
1054 * Helper function to do GETSTATUS (Get Target Status, format 2) of
1055 * one target.
1056 *
1057 * @param[in] target Pointer to the target device descriptor.
1058 * @param[out] status Pointer to GETSTATUS payload.
1059 * @param[in] defbyte Defining Byte for GETSTATUS format 2.
1060 *
1061 * @return @see i3c_do_ccc
1062 */
i3c_ccc_do_getstatus_fmt2(const struct i3c_device_desc * target,union i3c_ccc_getstatus * status,enum i3c_ccc_getstatus_defbyte defbyte)1063 static inline int i3c_ccc_do_getstatus_fmt2(const struct i3c_device_desc *target,
1064 union i3c_ccc_getstatus *status,
1065 enum i3c_ccc_getstatus_defbyte defbyte)
1066 {
1067 return i3c_ccc_do_getstatus(target, status,
1068 GETSTATUS_FORMAT_2, defbyte);
1069 }
1070
1071
1072 #ifdef __cplusplus
1073 }
1074 #endif
1075
1076 /**
1077 * @}
1078 */
1079
1080 #endif /* ZEPHYR_INCLUDE_DRIVERS_I3C_CCC_H_ */
1081
