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 * @brief Set pointer to Device Policy Manager (DPM) data 355 * 356 * @param dev Runtime device structure 357 * @param dpm_data pointer to dpm data 358 */ 359 void usbc_set_dpm_data(const struct device *dev, void *dpm_data); 360 361 /** 362 * @brief Get pointer to Device Policy Manager (DPM) data 363 * 364 * @param dev Runtime device structure 365 * 366 * @retval pointer to dpm data that was set with usbc_set_dpm_data 367 * @retval NULL if dpm data was not set 368 */ 369 void *usbc_get_dpm_data(const struct device *dev); 370 371 /** 372 * @brief Set the callback used to set VCONN control 373 * 374 * @param dev Runtime device structure 375 * @param cb VCONN control callback 376 */ 377 void usbc_set_vconn_control_cb(const struct device *dev, const tcpc_vconn_control_cb_t cb); 378 379 /** 380 * @brief Set the callback used to discharge VCONN 381 * 382 * @param dev Runtime device structure 383 * @param cb VCONN discharge callback 384 */ 385 void usbc_set_vconn_discharge_cb(const struct device *dev, const tcpc_vconn_discharge_cb_t cb); 386 387 /** 388 * @brief Set the callback used to check a policy 389 * 390 * @param dev Runtime device structure 391 * @param cb callback 392 */ 393 void usbc_set_policy_cb_check(const struct device *dev, const policy_cb_check_t cb); 394 395 /** 396 * @brief Set the callback used to notify Device Policy Manager of a 397 * policy change 398 * 399 * @param dev Runtime device structure 400 * @param cb callback 401 */ 402 void usbc_set_policy_cb_notify(const struct device *dev, const policy_cb_notify_t cb); 403 404 /** 405 * @brief Set the callback used to notify Device Policy Manager of WAIT 406 * message reception 407 * 408 * @param dev Runtime device structure 409 * @param cb callback 410 */ 411 void usbc_set_policy_cb_wait_notify(const struct device *dev, const policy_cb_wait_notify_t cb); 412 413 /** 414 * @brief Set the callback used to get the Sink Capabilities 415 * 416 * @param dev Runtime device structure 417 * @param cb callback 418 */ 419 void usbc_set_policy_cb_get_snk_cap(const struct device *dev, const policy_cb_get_snk_cap_t cb); 420 421 /** 422 * @brief Set the callback used to store the received Port Partner's 423 * Source Capabilities 424 * 425 * @param dev Runtime device structure 426 * @param cb callback 427 */ 428 void usbc_set_policy_cb_set_src_cap(const struct device *dev, const policy_cb_set_src_cap_t cb); 429 430 /** 431 * @brief Set the callback used to get the Request Data Object (RDO) 432 * 433 * @param dev Runtime device structure 434 * @param cb callback 435 */ 436 void usbc_set_policy_cb_get_rdo(const struct device *dev, const policy_cb_get_rdo_t cb); 437 438 /** 439 * @brief Set the callback used to check if the sink power supply is at 440 * the default level 441 * 442 * @param dev Runtime device structure 443 * @param cb callback 444 */ 445 void usbc_set_policy_cb_is_snk_at_default(const struct device *dev, 446 const policy_cb_is_snk_at_default_t cb); 447 448 /** 449 * @brief Set the callback used to get the Rp value that should be placed on 450 * the CC lines 451 * 452 * @param dev USB-C Connector Instance 453 * @param cb callback 454 */ 455 void usbc_set_policy_cb_get_src_rp(const struct device *dev, const policy_cb_get_src_rp_t cb); 456 457 /** 458 * @brief Set the callback used to enable VBUS 459 * 460 * @param dev USB-C Connector Instance 461 * @param cb callback 462 */ 463 void usbc_set_policy_cb_src_en(const struct device *dev, const policy_cb_src_en_t cb); 464 465 /** 466 * @brief Set the callback used to get the Source Capabilities 467 * from the Device Policy Manager 468 * 469 * @param dev USB-C Connector Instance 470 * @param cb callback 471 */ 472 void usbc_set_policy_cb_get_src_caps(const struct device *dev, const policy_cb_get_src_caps_t cb); 473 474 /** 475 * @brief Set the callback used to check if Sink request is valid 476 * 477 * @param dev USB-C Connector Instance 478 * @param cb callback 479 */ 480 void usbc_set_policy_cb_check_sink_request(const struct device *dev, 481 const policy_cb_check_sink_request_t cb); 482 483 /** 484 * @brief Set the callback used to check if Source Power Supply is ready 485 * 486 * @param dev USB-C Connector Instance 487 * @param cb callback 488 */ 489 void usbc_set_policy_cb_is_ps_ready(const struct device *dev, 490 const policy_cb_is_ps_ready_t cb); 491 492 /** 493 * @brief Set the callback to check if present Contract is still valid 494 * 495 * @param dev USB-C Connector Instance 496 * @param cb callback 497 */ 498 void usbc_set_policy_cb_present_contract_is_valid(const struct device *dev, 499 const policy_cb_present_contract_is_valid_t cb); 500 501 /** 502 * @brief Set the callback used to request that a different set of Source Caps 503 * be sent to the Sink 504 * 505 * @param dev USB-C Connector Instance 506 * @param cb callback 507 */ 508 void usbc_set_policy_cb_change_src_caps(const struct device *dev, 509 const policy_cb_change_src_caps_t cb); 510 511 /** 512 * @brief Set the callback used to store the Capabilities received from a Sink Port Partner 513 * 514 * @param dev USB-C Connector Instance 515 * @param cb callback 516 */ 517 void usbc_set_policy_cb_set_port_partner_snk_cap(const struct device *dev, 518 const policy_cb_set_port_partner_snk_cap_t cb); 519 520 /** 521 * @} 522 */ 523 524 #ifdef __cplusplus 525 } 526 #endif 527 528 #endif /* ZEPHYR_INCLUDE_USBC_H_ */ 529
