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