Line data Source code
1 1 : /*
2 : * Copyright 2022 The Chromium OS Authors
3 : * SPDX-License-Identifier: Apache-2.0
4 : */
5 :
6 : /**
7 : * @file
8 : * @brief USB-C Device APIs
9 : *
10 : * This file contains the USB-C Device APIs.
11 : */
12 :
13 : #ifndef ZEPHYR_INCLUDE_USBC_H_
14 : #define ZEPHYR_INCLUDE_USBC_H_
15 :
16 : #include <zephyr/types.h>
17 : #include <zephyr/device.h>
18 : #include <zephyr/drivers/usb_c/usbc_tcpc.h>
19 : #include <zephyr/drivers/usb_c/usbc_vbus.h>
20 :
21 : #ifdef __cplusplus
22 : extern "C" {
23 : #endif
24 :
25 : /**
26 : * @brief USB-C Device APIs
27 : * @defgroup _usbc_device_api USB-C Device API
28 : * @since 3.3
29 : * @version 0.1.0
30 : * @{
31 : */
32 :
33 : /**
34 : * @brief This Request Data Object (RDO) value can be returned from the
35 : * policy_cb_get_rdo if 5V@100mA with the following
36 : * options are sufficient for the Sink to operate.
37 : *
38 : * The RDO is configured as follows:
39 : * Maximum operating current 100mA
40 : * Operating current 100mA
41 : * Unchunked Extended Messages Not Supported
42 : * No USB Suspend
43 : * Not USB Communications Capable
44 : * No capability mismatch
45 : * Don't giveback
46 : * Object position 1 (5V PDO)
47 : */
48 1 : #define FIXED_5V_100MA_RDO 0x1100280a
49 :
50 : /**
51 : * @brief Device Policy Manager requests
52 : */
53 1 : enum usbc_policy_request_t {
54 : /** No request */
55 : REQUEST_NOP,
56 : /** Request Type-C layer to transition to Disabled State */
57 : REQUEST_TC_DISABLED,
58 : /** Request Type-C layer to transition to Error Recovery State */
59 : REQUEST_TC_ERROR_RECOVERY,
60 : /** End of Type-C requests */
61 : REQUEST_TC_END,
62 :
63 : /** Request Policy Engine layer to perform a Data Role Swap */
64 : REQUEST_PE_DR_SWAP,
65 : /** Request Policy Engine layer to send a hard reset */
66 : REQUEST_PE_HARD_RESET_SEND,
67 : /** Request Policy Engine layer to send a soft reset */
68 : REQUEST_PE_SOFT_RESET_SEND,
69 : /**
70 : * Request Policy Engine layer to get Source Capabilities from
71 : * port partner
72 : */
73 : REQUEST_PE_GET_SRC_CAPS,
74 : /**
75 : * Request Policy Engine to get Sink Capabilities from
76 : * port partner
77 : */
78 : REQUEST_GET_SNK_CAPS,
79 : /**
80 : * Request Policy Engine to request the port partner to source
81 : * minimum power
82 : */
83 : REQUEST_PE_GOTO_MIN,
84 : };
85 :
86 : /**
87 : * @brief Device Policy Manager notifications
88 : */
89 1 : enum usbc_policy_notify_t {
90 : /** Power Delivery Accept message was received */
91 : MSG_ACCEPT_RECEIVED,
92 : /** Power Delivery Reject message was received */
93 : MSG_REJECTED_RECEIVED,
94 : /** Power Delivery discarded the message being transmitted */
95 : MSG_DISCARDED,
96 : /** Power Delivery Not Supported message was received */
97 : MSG_NOT_SUPPORTED_RECEIVED,
98 : /** Data Role has been set to Upstream Facing Port (UFP) */
99 : DATA_ROLE_IS_UFP,
100 : /** Data Role has been set to Downstream Facing Port (DFP) */
101 : DATA_ROLE_IS_DFP,
102 : /** A PD Explicit Contract is in place */
103 : PD_CONNECTED,
104 : /** No PD Explicit Contract is in place */
105 : NOT_PD_CONNECTED,
106 : /** Transition the Power Supply */
107 : TRANSITION_PS,
108 : /** Port partner is not responsive */
109 : PORT_PARTNER_NOT_RESPONSIVE,
110 : /** Protocol Error occurred */
111 : PROTOCOL_ERROR,
112 : /** Transition the Sink to default */
113 : SNK_TRANSITION_TO_DEFAULT,
114 : /** Hard Reset Received */
115 : HARD_RESET_RECEIVED,
116 : /** Sink SubPower state at 0V */
117 : POWER_CHANGE_0A0,
118 : /** Sink SubPower state a 5V / 500mA */
119 : POWER_CHANGE_DEF,
120 : /** Sink SubPower state a 5V / 1.5A */
121 : POWER_CHANGE_1A5,
122 : /** Sink SubPower state a 5V / 3A */
123 : POWER_CHANGE_3A0,
124 : /** Sender Response Timeout */
125 : SENDER_RESPONSE_TIMEOUT,
126 : /** Source Capabilities Received */
127 : SOURCE_CAPABILITIES_RECEIVED,
128 : };
129 :
130 : /**
131 : * @brief Device Policy Manager checks
132 : */
133 1 : enum usbc_policy_check_t {
134 : /** Check if Power Role Swap is allowed */
135 : CHECK_POWER_ROLE_SWAP,
136 : /** Check if Data Role Swap to DFP is allowed */
137 : CHECK_DATA_ROLE_SWAP_TO_DFP,
138 : /** Check if Data Role Swap to UFP is allowed */
139 : CHECK_DATA_ROLE_SWAP_TO_UFP,
140 : /** Check if Sink is at default level */
141 : CHECK_SNK_AT_DEFAULT_LEVEL,
142 : /** Check if should control VCONN */
143 : CHECK_VCONN_CONTROL,
144 : /** Check if Source Power Supply is at default level */
145 : CHECK_SRC_PS_AT_DEFAULT_LEVEL,
146 : };
147 :
148 : /**
149 : * @brief Device Policy Manager Wait message notifications
150 : */
151 1 : enum usbc_policy_wait_t {
152 : /** The port partner is unable to meet the sink request at this time */
153 : WAIT_SINK_REQUEST,
154 : /** The port partner is unable to do a Power Role Swap at this time */
155 : WAIT_POWER_ROLE_SWAP,
156 : /** The port partner is unable to do a Data Role Swap at this time */
157 : WAIT_DATA_ROLE_SWAP,
158 : /** The port partner is unable to do a VCONN Swap at this time */
159 : WAIT_VCONN_SWAP,
160 : };
161 :
162 : /**
163 : * @brief Device Policy Manager's response to a Sink Request
164 : */
165 1 : enum usbc_snk_req_reply_t {
166 : /** The sink port partner's request can be met */
167 : SNK_REQUEST_VALID,
168 : /** The sink port partner's request can not be met */
169 : SNK_REQUEST_REJECT,
170 : /** The sink port partner's request can be met at a later time */
171 : SNK_REQUEST_WAIT,
172 : };
173 :
174 : /** \addtogroup sink_callbacks
175 : * @{
176 : */
177 : /**
178 : * @brief Callback type used to get the Sink Capabilities
179 : *
180 : * @param dev USB-C Connector Instance
181 : * @param pdos pointer where pdos are stored
182 : * @param num_pdos pointer where number of pdos is stored
183 : * @return 0 on success
184 : */
185 1 : typedef int (*policy_cb_get_snk_cap_t)(const struct device *dev, uint32_t **pdos, int *num_pdos);
186 : /**
187 : * @brief Callback type used to report the received Port Partner's
188 : * Source Capabilities
189 : *
190 : * @param dev USB-C Connector Instance
191 : * @param pdos pointer to the partner's source pdos
192 : * @param num_pdos number of source pdos
193 : */
194 1 : typedef void (*policy_cb_set_src_cap_t)(const struct device *dev, const uint32_t *pdos,
195 : const int num_pdos);
196 :
197 : /**
198 : * @brief Callback type used to check a policy
199 : *
200 : * @param dev USB-C Connector Instance
201 : * @param policy_check policy to check
202 : * @return true if policy is currently allowed by the device policy manager
203 : */
204 1 : typedef bool (*policy_cb_check_t)(const struct device *dev,
205 : const enum usbc_policy_check_t policy_check);
206 :
207 : /**
208 : * @brief Callback type used to notify Device Policy Manager of WAIT
209 : * message reception
210 : *
211 : * @param dev USB-C Connector Instance
212 : * @param wait_notify wait notification
213 : * @return return true if the PE should wait and resend the message
214 : */
215 1 : typedef bool (*policy_cb_wait_notify_t)(const struct device *dev,
216 : const enum usbc_policy_wait_t wait_notify);
217 :
218 : /**
219 : * @brief Callback type used to notify Device Policy Manager of a
220 : * policy change
221 : *
222 : * @param dev USB-C Connector Instance
223 : * @param policy_notify policy notification
224 : */
225 1 : typedef void (*policy_cb_notify_t)(const struct device *dev,
226 : const enum usbc_policy_notify_t policy_notify);
227 :
228 : /**
229 : * @brief Callback type used to get the Request Data Object (RDO)
230 : *
231 : * @param dev USB-C Connector Instance
232 : * @return RDO
233 : */
234 1 : typedef uint32_t (*policy_cb_get_rdo_t)(const struct device *dev);
235 :
236 : /**
237 : * @brief Callback type used to check if the sink power supply is at
238 : * the default level
239 : *
240 : * @param dev USB-C Connector Instance
241 : * @return true if power supply is at default level
242 : */
243 1 : typedef bool (*policy_cb_is_snk_at_default_t)(const struct device *dev);
244 :
245 : /** @}*/
246 : /** \addtogroup source_callbacks
247 : * @{
248 : */
249 : /**
250 : * @brief Callback type used to get the Source Capabilities
251 : * from the Device Policy Manager
252 : *
253 : * @param dev USB-C Connector Instance
254 : * @param pdos pointer to source capability pdos
255 : * @param num_pdos pointer to number of source capability pdos
256 : * @return 0 on success
257 : */
258 1 : typedef int (*policy_cb_get_src_caps_t)(const struct device *dev, const uint32_t **pdos,
259 : uint32_t *num_pdos);
260 :
261 : /**
262 : * @brief Callback type used to check if Sink request is valid
263 : *
264 : * @param dev USB-C Connector Instance
265 : * @param request_msg request message to check
266 : * @return sink request reply
267 : */
268 : typedef enum usbc_snk_req_reply_t (*policy_cb_check_sink_request_t)(const struct device *dev,
269 : const uint32_t request_msg);
270 :
271 : /**
272 : * @brief Callback type used to check if Source Power Supply is ready
273 : *
274 : * @param dev USB-C Connector Instance
275 : * @return true if power supply is ready, else false
276 : */
277 1 : typedef bool (*policy_cb_is_ps_ready_t)(const struct device *dev);
278 :
279 : /**
280 : * @brief Callback type used to check if present Contract is still valid
281 : *
282 : * @param dev USB-C Connector Instance
283 : * @param present_contract present contract
284 : * @return true if present contract is still valid
285 : */
286 1 : typedef bool (*policy_cb_present_contract_is_valid_t)(const struct device *dev,
287 : const uint32_t present_contract);
288 :
289 : /**
290 : * @brief Callback type used to request that a different set of Source Caps
291 : * be sent to the Sink
292 : *
293 : * @param dev USB-C Connector Instance
294 : * @return true if a different set of Source Caps is available
295 : */
296 1 : typedef bool (*policy_cb_change_src_caps_t)(const struct device *dev);
297 :
298 : /**
299 : * @brief Callback type used to report the Capabilities received from
300 : * a Sink Port Partner
301 : *
302 : * @param dev USB-C Connector Instance
303 : * @param pdos pointer to sink cap pdos
304 : * @param num_pdos number of sink cap pdos
305 : */
306 1 : typedef void (*policy_cb_set_port_partner_snk_cap_t)(const struct device *dev, const uint32_t *pdos,
307 : const int num_pdos);
308 : /**
309 : * @brief Callback type used to get the Rp value that should be placed on
310 : * the CC lines
311 : *
312 : * @param dev USB-C Connector Instance
313 : * @param rp rp value
314 : * @return 0 on success
315 : */
316 1 : typedef int (*policy_cb_get_src_rp_t)(const struct device *dev, enum tc_rp_value *rp);
317 : /**
318 : * @brief Callback type used to enable VBUS
319 : *
320 : * @param dev USB-C Connector Instance
321 : * @param en true if VBUS should be enabled, else false to disable it
322 : * @return 0 on success
323 : */
324 1 : typedef int (*policy_cb_src_en_t)(const struct device *dev, bool en);
325 : /** @}*/
326 :
327 : /**
328 : * @brief Start the USB-C Subsystem
329 : *
330 : * @param dev Runtime device structure
331 : *
332 : * @retval 0 on success
333 : */
334 1 : int usbc_start(const struct device *dev);
335 :
336 : /**
337 : * @brief Suspend the USB-C Subsystem
338 : *
339 : * @param dev Runtime device structure
340 : *
341 : * @retval 0 on success
342 : */
343 1 : int usbc_suspend(const struct device *dev);
344 :
345 : /**
346 : * @brief Make a request of the USB-C Subsystem
347 : *
348 : * @param dev Runtime device structure
349 : * @param req request
350 : *
351 : * @retval 0 on success
352 : */
353 1 : int usbc_request(const struct device *dev, const enum usbc_policy_request_t req);
354 :
355 : /**
356 : * @internal
357 : * @brief Bypass the next USB-C stack sleep and execute one more iteration of the state machines.
358 : * Used internally to decrease the response time.
359 : *
360 : * @param dev Runtime device structure
361 : */
362 0 : void usbc_bypass_next_sleep(const struct device *dev);
363 :
364 : /**
365 : * @brief Set pointer to Device Policy Manager (DPM) data
366 : *
367 : * @param dev Runtime device structure
368 : * @param dpm_data pointer to dpm data
369 : */
370 1 : void usbc_set_dpm_data(const struct device *dev, void *dpm_data);
371 :
372 : /**
373 : * @brief Get pointer to Device Policy Manager (DPM) data
374 : *
375 : * @param dev Runtime device structure
376 : *
377 : * @retval pointer to dpm data that was set with usbc_set_dpm_data
378 : * @retval NULL if dpm data was not set
379 : */
380 1 : void *usbc_get_dpm_data(const struct device *dev);
381 :
382 : /**
383 : * @brief Set the callback used to set VCONN control
384 : *
385 : * @param dev Runtime device structure
386 : * @param cb VCONN control callback
387 : */
388 1 : void usbc_set_vconn_control_cb(const struct device *dev, const tcpc_vconn_control_cb_t cb);
389 :
390 : /**
391 : * @brief Set the callback used to discharge VCONN
392 : *
393 : * @param dev Runtime device structure
394 : * @param cb VCONN discharge callback
395 : */
396 1 : void usbc_set_vconn_discharge_cb(const struct device *dev, const tcpc_vconn_discharge_cb_t cb);
397 :
398 : /**
399 : * @brief Set the callback used to check a policy
400 : *
401 : * @param dev Runtime device structure
402 : * @param cb callback
403 : */
404 1 : void usbc_set_policy_cb_check(const struct device *dev, const policy_cb_check_t cb);
405 :
406 : /**
407 : * @brief Set the callback used to notify Device Policy Manager of a
408 : * policy change
409 : *
410 : * @param dev Runtime device structure
411 : * @param cb callback
412 : */
413 1 : void usbc_set_policy_cb_notify(const struct device *dev, const policy_cb_notify_t cb);
414 :
415 : /**
416 : * @brief Set the callback used to notify Device Policy Manager of WAIT
417 : * message reception
418 : *
419 : * @param dev Runtime device structure
420 : * @param cb callback
421 : */
422 1 : void usbc_set_policy_cb_wait_notify(const struct device *dev, const policy_cb_wait_notify_t cb);
423 :
424 : /**
425 : * @brief Set the callback used to get the Sink Capabilities
426 : *
427 : * @param dev Runtime device structure
428 : * @param cb callback
429 : */
430 1 : void usbc_set_policy_cb_get_snk_cap(const struct device *dev, const policy_cb_get_snk_cap_t cb);
431 :
432 : /**
433 : * @brief Set the callback used to store the received Port Partner's
434 : * Source Capabilities
435 : *
436 : * @param dev Runtime device structure
437 : * @param cb callback
438 : */
439 1 : void usbc_set_policy_cb_set_src_cap(const struct device *dev, const policy_cb_set_src_cap_t cb);
440 :
441 : /**
442 : * @brief Set the callback used to get the Request Data Object (RDO)
443 : *
444 : * @param dev Runtime device structure
445 : * @param cb callback
446 : */
447 1 : void usbc_set_policy_cb_get_rdo(const struct device *dev, const policy_cb_get_rdo_t cb);
448 :
449 : /**
450 : * @brief Set the callback used to check if the sink power supply is at
451 : * the default level
452 : *
453 : * @param dev Runtime device structure
454 : * @param cb callback
455 : */
456 1 : void usbc_set_policy_cb_is_snk_at_default(const struct device *dev,
457 : const policy_cb_is_snk_at_default_t cb);
458 :
459 : /**
460 : * @brief Set the callback used to get the Rp value that should be placed on
461 : * the CC lines
462 : *
463 : * @param dev USB-C Connector Instance
464 : * @param cb callback
465 : */
466 1 : void usbc_set_policy_cb_get_src_rp(const struct device *dev, const policy_cb_get_src_rp_t cb);
467 :
468 : /**
469 : * @brief Set the callback used to enable VBUS
470 : *
471 : * @param dev USB-C Connector Instance
472 : * @param cb callback
473 : */
474 1 : void usbc_set_policy_cb_src_en(const struct device *dev, const policy_cb_src_en_t cb);
475 :
476 : /**
477 : * @brief Set the callback used to get the Source Capabilities
478 : * from the Device Policy Manager
479 : *
480 : * @param dev USB-C Connector Instance
481 : * @param cb callback
482 : */
483 1 : void usbc_set_policy_cb_get_src_caps(const struct device *dev, const policy_cb_get_src_caps_t cb);
484 :
485 : /**
486 : * @brief Set the callback used to check if Sink request is valid
487 : *
488 : * @param dev USB-C Connector Instance
489 : * @param cb callback
490 : */
491 1 : void usbc_set_policy_cb_check_sink_request(const struct device *dev,
492 : const policy_cb_check_sink_request_t cb);
493 :
494 : /**
495 : * @brief Set the callback used to check if Source Power Supply is ready
496 : *
497 : * @param dev USB-C Connector Instance
498 : * @param cb callback
499 : */
500 1 : void usbc_set_policy_cb_is_ps_ready(const struct device *dev,
501 : const policy_cb_is_ps_ready_t cb);
502 :
503 : /**
504 : * @brief Set the callback to check if present Contract is still valid
505 : *
506 : * @param dev USB-C Connector Instance
507 : * @param cb callback
508 : */
509 1 : void usbc_set_policy_cb_present_contract_is_valid(const struct device *dev,
510 : const policy_cb_present_contract_is_valid_t cb);
511 :
512 : /**
513 : * @brief Set the callback used to request that a different set of Source Caps
514 : * be sent to the Sink
515 : *
516 : * @param dev USB-C Connector Instance
517 : * @param cb callback
518 : */
519 1 : void usbc_set_policy_cb_change_src_caps(const struct device *dev,
520 : const policy_cb_change_src_caps_t cb);
521 :
522 : /**
523 : * @brief Set the callback used to store the Capabilities received from a Sink Port Partner
524 : *
525 : * @param dev USB-C Connector Instance
526 : * @param cb callback
527 : */
528 1 : void usbc_set_policy_cb_set_port_partner_snk_cap(const struct device *dev,
529 : const policy_cb_set_port_partner_snk_cap_t cb);
530 :
531 : /**
532 : * @}
533 : */
534 :
535 : #ifdef __cplusplus
536 : }
537 : #endif
538 :
539 : #endif /* ZEPHYR_INCLUDE_USBC_H_ */
|
