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