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 #define FIXED_5V_100MA_RDO 0x1100280a 49 50 /** 51 * @brief Device Policy Manager requests 52 */ 53 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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_ */ 540
