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