1 /* 2 * Copyright (c) 2022 The Chromium OS Authors 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 #ifndef ZEPHYR_SUBSYS_USBC_PE_COMMON_INTERNAL_H_ 8 #define ZEPHYR_SUBSYS_USBC_PE_COMMON_INTERNAL_H_ 9 10 #include <zephyr/kernel.h> 11 #include <zephyr/usb_c/usbc.h> 12 #include <zephyr/drivers/usb_c/usbc_pd.h> 13 #include <zephyr/drivers/usb_c/usbc_tc.h> 14 #include <zephyr/smf.h> 15 #include "usbc_timer.h" 16 17 /** 18 * @brief Used in sub-machines for message transmit and receive operation 19 */ 20 enum sm_msg_xmit { 21 /* Wait for a message transmission sub-machine state */ 22 SM_WAIT_FOR_TX, 23 /* Wait for a message reception sub-machine state */ 24 SM_WAIT_FOR_RX, 25 }; 26 27 /** 28 * @brief Used in sub-machines for message source hard reset operation 29 */ 30 enum sm_hard_reset { 31 /* Start the hard-reset sub-machine state */ 32 SM_HARD_RESET_START, 33 /* Wait for hard-reset to complete sub-machine state */ 34 SM_HARD_RESET_WAIT, 35 }; 36 37 /** 38 * @brief Policy Engine Errors 39 */ 40 enum pe_error { 41 /** Transmit error */ 42 ERR_XMIT, 43 }; 44 45 /** 46 * @brief Policy Engine Layer States 47 */ 48 enum usbc_pe_state { 49 /** PE_SNK_Startup */ 50 PE_SNK_STARTUP, 51 /** PE_SNK_Discovery */ 52 PE_SNK_DISCOVERY, 53 /** PE_SNK_Wait_for_Capabilities */ 54 PE_SNK_WAIT_FOR_CAPABILITIES, 55 /** PE_SNK_Evaluate_Capability */ 56 PE_SNK_EVALUATE_CAPABILITY, 57 /** PE_SNK_Select_Capability */ 58 PE_SNK_SELECT_CAPABILITY, 59 /** PE_SNK_Transition_Sink */ 60 PE_SNK_TRANSITION_SINK, 61 /** PE_SNK_Ready */ 62 PE_SNK_READY, 63 /** PE_SNK_Hard_Reset */ 64 PE_SNK_HARD_RESET, 65 /** PE_SNK_Transition_to_default */ 66 PE_SNK_TRANSITION_TO_DEFAULT, 67 /** PE_SNK_Give_Sink_Cap */ 68 PE_SNK_GIVE_SINK_CAP, 69 /** PE_SNK_Get_Source_Cap */ 70 PE_SNK_GET_SOURCE_CAP, 71 72 /** PE_SRC_Startup */ 73 PE_SRC_STARTUP, 74 /** PE_SRC_Discovery */ 75 PE_SRC_DISCOVERY, 76 /** PE_SRC_Send_Capabilities */ 77 PE_SRC_SEND_CAPABILITIES, 78 /** PE_SRC_Negotiate_capability */ 79 PE_SRC_NEGOTIATE_CAPABILITY, 80 /** PE_SRC_Capability_Response */ 81 PE_SRC_CAPABILITY_RESPONSE, 82 /** PE_SRC_Transition_Supply */ 83 PE_SRC_TRANSITION_SUPPLY, 84 /** PE_SRC_Ready */ 85 PE_SRC_READY, 86 /** PE_SRC_Hard_Reset */ 87 PE_SRC_HARD_RESET, 88 /** PE_SRC_Hard_Reset_Received */ 89 PE_SRC_HARD_RESET_RECEIVED, 90 /** PE_SRC_Transition_To_Default */ 91 PE_SRC_TRANSITION_TO_DEFAULT, 92 93 /** PE_SNK_Soft_Reset and PE_SRC_Soft_Reset */ 94 PE_SOFT_RESET, 95 /** PE_SNK_Chunk_Received or PE_SRC_Chunk_Received */ 96 PE_CHUNK_RECEIVED, 97 /**PE_Send_Soft_Reset */ 98 PE_SEND_SOFT_RESET, 99 100 /** PE_Send_Not_Supported */ 101 PE_SEND_NOT_SUPPORTED, 102 /** PE_DRS_Evaluate_Swap */ 103 PE_DRS_EVALUATE_SWAP, 104 /** PE_DRS_Send_Swap */ 105 PE_DRS_SEND_SWAP, 106 /** PE_Get_Sink_Cap */ 107 PE_GET_SINK_CAP, 108 109 /** PE_Suspend. Not part of the PD specification. */ 110 PE_SUSPEND, 111 112 /** 113 * NOTE: The states below should not be called directly. They're used 114 * internally by the state machine. 115 */ 116 117 /** PE_SENDER_RESPONSE_PARENT. Not part of the PD specification. */ 118 PE_SENDER_RESPONSE_PARENT, 119 /** PE_SRC_HARD_RESET_PARENT. Not part of the PD specification. */ 120 PE_SRC_HARD_RESET_PARENT, 121 /** Number of PE States */ 122 PE_STATE_COUNT 123 }; 124 125 /** 126 * @brief Policy Engine Layer Flags 127 */ 128 enum pe_flags { 129 /** Accept message received from port partner */ 130 PE_FLAGS_ACCEPT = 0, 131 /** A message we requested to be sent has been transmitted */ 132 PE_FLAGS_TX_COMPLETE = 1, 133 /** A message sent by a port partner has been received */ 134 PE_FLAGS_MSG_RECEIVED = 2, 135 /** 136 * A hard reset has been requested by the DPM but has not been sent, 137 * not currently used 138 */ 139 PE_FLAGS_HARD_RESET_PENDING = 3, 140 /** An explicit contract is in place with our port partner */ 141 PE_FLAGS_EXPLICIT_CONTRACT = 4, 142 /** 143 * Waiting for Sink Capabailities timed out. Used for retry error 144 * handling 145 */ 146 PE_FLAGS_SNK_WAIT_CAP_TIMEOUT = 5, 147 /** 148 * Flag to note current Atomic Message Sequence (AMS) is interruptible. 149 * If this flag is not set the AMS is non-interruptible. This flag must 150 * be set in the interruptible's message state entry. 151 */ 152 PE_FLAGS_INTERRUPTIBLE_AMS = 6, 153 /** Flag to trigger sending a Data Role Swap */ 154 PE_FLAGS_DR_SWAP_TO_DFP = 7, 155 /** Flag is set when an AMS is initiated by the Device Policy Manager */ 156 PE_FLAGS_DPM_INITIATED_AMS = 8, 157 /** Flag to note message was discarded due to incoming message */ 158 PE_FLAGS_MSG_DISCARDED = 9, 159 /** Flag to trigger sending a soft reset */ 160 PE_FLAGS_SEND_SOFT_RESET = 10, 161 /** 162 * This flag is set when a Wait message is received in response to a 163 * Sink REQUEST 164 */ 165 PE_FLAGS_WAIT_SINK_REQUEST = 11, 166 /** 167 * This flag is set when a Wait message is received in response to a 168 * Data Role Swap 169 */ 170 PE_FLAGS_WAIT_DATA_ROLE_SWAP = 12, 171 /** 172 * This flag is set when a protocol error occurs. 173 */ 174 PE_FLAGS_PROTOCOL_ERROR = 13, 175 /** This flag is set when a transmit error occurs. */ 176 PE_FLAGS_MSG_XMIT_ERROR = 14, 177 178 /* The Port Partner is PD connected */ 179 PE_FLAGS_PD_CONNECTED = 15, 180 /* The Port partner has been PD connected at least once */ 181 PE_FLAGS_HAS_BEEN_PD_CONNECTED = 16, 182 /* A Protocol Error didn't generate a Soft Reset */ 183 PE_FLAGS_PROTOCOL_ERROR_NO_SOFT_RESET = 17, 184 /* This flag is set when the first AMS message is sent */ 185 PE_FLAGS_FIRST_MSG_SENT = 18, 186 /** Number of PE Flags */ 187 PE_FLAGS_COUNT 188 }; 189 190 /** 191 * @brief Policy Engine State Machine Object 192 */ 193 struct policy_engine { 194 /** state machine context */ 195 struct smf_ctx ctx; 196 /** Port device */ 197 const struct device *dev; 198 /** state machine flags */ 199 ATOMIC_DEFINE(flags, PE_FLAGS_COUNT); 200 /** current port power role (SOURCE or SINK) */ 201 enum tc_power_role power_role; 202 /** current port data role (DFP or UFP) */ 203 enum tc_data_role data_role; 204 /** port address where soft resets are sent */ 205 enum pd_packet_type soft_reset_sop; 206 /** DPM request */ 207 enum usbc_policy_request_t dpm_request; 208 /** generic variable used for simple in state statemachines */ 209 uint32_t submachine; 210 #ifdef CONFIG_USBC_CSM_SOURCE_ONLY 211 /** The Sink made a valid request of the Source if true */ 212 bool snk_request_can_be_met; 213 /** Outcome of the Sink request */ 214 enum usbc_snk_req_reply_t snk_request_reply; 215 /** Save Sink Request Object */ 216 uint32_t snk_request; 217 /** Present Contract stores the current Sink Request */ 218 uint32_t present_contract; 219 #endif 220 /* Counters */ 221 222 /** 223 * This counter is used to retry the Hard Reset whenever there is no 224 * response from the remote device. 225 */ 226 uint32_t hard_reset_counter; 227 228 #ifdef CONFIG_USBC_CSM_SOURCE_ONLY 229 /** 230 * This counter tracks the number of times a Source Caps message was 231 * sent. 232 */ 233 uint32_t caps_counter; 234 #endif 235 236 /* Timers */ 237 238 /** tSenderResponse timer */ 239 struct usbc_timer_t pd_t_sender_response; 240 /** tChunkingNotSupported timer */ 241 struct usbc_timer_t pd_t_chunking_not_supported; 242 /** Time to wait before resending message after WAIT reception */ 243 struct usbc_timer_t pd_t_wait_to_resend; 244 245 #ifdef CONFIG_USBC_CSM_SINK_ONLY 246 /** tTypeCSinkWaitCap timer */ 247 struct usbc_timer_t pd_t_typec_sink_wait_cap; 248 /** tPSTransition timer */ 249 struct usbc_timer_t pd_t_ps_transition; 250 /** tSinkRequest timer */ 251 struct usbc_timer_t pd_t_sink_request; 252 #else 253 /** tTypeCSendSourceCap timer */ 254 struct usbc_timer_t pd_t_typec_send_source_cap; 255 /** tNoResponse timer */ 256 struct usbc_timer_t pd_t_no_response; 257 /** tPSHardReset timer */ 258 struct usbc_timer_t pd_t_ps_hard_reset; 259 #endif /* CONFIG_USBC_CSM_SINK_ONLY */ 260 }; 261 262 /** 263 * @brief First message in AMS has been sent 264 * 265 * @param dev Pointer to the device structure for the driver instance 266 */ 267 void pe_first_msg_sent(const struct device *dev); 268 269 /** 270 * @brief Sets a Policy Engine state 271 * 272 * @param dev Pointer to the device structure for the driver instance 273 * @param state next PE State to enter 274 */ 275 void pe_set_state(const struct device *dev, const enum usbc_pe_state state); 276 277 /** 278 * @brief Get the Policy Engine's current state 279 * 280 * @param dev Pointer to the device structure for the driver instance 281 * @retval current PE state 282 */ 283 enum usbc_pe_state pe_get_state(const struct device *dev); 284 285 /** 286 * @brief Get the Policy Engine's previous state 287 * 288 * @param dev Pointer to the device structure for the driver instance 289 * @retval last PE state 290 */ 291 enum usbc_pe_state pe_get_last_state(const struct device *dev); 292 293 /** 294 * @brief Send a soft reset message 295 * 296 * @param dev Pointer to the device structure for the driver instance 297 * @param type SOP* to send soft reset message 298 */ 299 void pe_send_soft_reset(const struct device *dev, const enum pd_packet_type type); 300 301 /** 302 * @brief Send a Power Delivery Data Message 303 * 304 * @param dev Pointer to the device structure for the driver instance 305 * @param type SOP* to send message 306 * @param msg PD data message to send 307 */ 308 void pe_send_data_msg(const struct device *dev, 309 const enum pd_packet_type type, 310 const enum pd_data_msg_type msg); 311 312 /** 313 * @brief Send a Power Delivery Control Message 314 * 315 * @param dev Pointer to the device structure for the driver instance 316 * @param type SOP* to send message 317 * @param msg PD control message to send 318 */ 319 void pe_send_ctrl_msg(const struct device *dev, 320 const enum pd_packet_type type, 321 const enum pd_ctrl_msg_type msg); 322 323 /** 324 * @brief Request desired voltage from source. 325 * 326 * @param dev Pointer to the device structure for the driver instance 327 * @param rdo Request Data Object to send 328 */ 329 void pe_send_request_msg(const struct device *dev, const uint32_t rdo); 330 331 /** 332 * @brief Transitions state after receiving an extended message. 333 * 334 * @param dev Pointer to the device structure for the driver instance 335 */ 336 void extended_message_not_supported(const struct device *dev); 337 338 /** 339 * @brief Check if a specific control message was received 340 * 341 * @param dev Pointer to the device structure for the driver instance 342 * @param header message header containing the message 343 * @param mt message type to check 344 * @retval true if the header contains the message type, else false 345 */ 346 bool received_control_message(const struct device *dev, const union pd_header header, 347 const enum pd_ctrl_msg_type mt); 348 349 /** 350 * @brief Check if a specific data message was received 351 * 352 * @param dev Pointer to the device structure for the driver instance 353 * @param header message header containing the message 354 * @param mt message type to check 355 * @param true if the header contains the message type, else false 356 */ 357 bool received_data_message(const struct device *dev, const union pd_header header, 358 const enum pd_data_msg_type mt); 359 360 /** 361 * @brief Check a DPM policy 362 * 363 * @param dev Pointer to the device structure for the driver instance 364 * @param pc The DPM policy to check 365 * @retval true if the DPM approves the check, else false 366 */ 367 bool policy_check(const struct device *dev, const enum usbc_policy_check_t pc); 368 369 /** 370 * @brief Notify the DPM of a policy change 371 * 372 * @param dev Pointer to the device structure for the driver instance 373 * @param notify The notification to send the DPM 374 */ 375 void policy_notify(const struct device *dev, const enum usbc_policy_notify_t notify); 376 377 /** 378 * @brief Notify the DPM of a WAIT message reception 379 * 380 * @param dev Pointer to the device structure for the driver instance 381 * @param notify Wait message to send to DPM 382 * @retval true if the Policy Engine should wait and try the action again 383 */ 384 bool policy_wait_notify(const struct device *dev, const enum usbc_policy_wait_t notify); 385 386 /** 387 * @brief Send the received source caps to the DPM 388 * 389 * @param dev Pointer to the device structure for the driver instance 390 * @param pdos pointer to pdos to send 391 * @param num_pdos number of pdos to send 392 */ 393 void policy_set_src_cap(const struct device *dev, const uint32_t *pdos, const int num_pdos); 394 395 /** 396 * @brief Check if the sink request can be met by the DPM 397 */ 398 enum usbc_snk_req_reply_t policy_check_sink_request(const struct device *dev, 399 const uint32_t request_msg); 400 401 /** 402 * @brief Check if the Present Contract is still valid. 403 * 404 * @note The contract is considered "invalid" if the previous current/voltage 405 * are no longer available AND the sink fails to make a valid request. 406 */ 407 bool policy_present_contract_is_valid(const struct device *dev, const uint32_t present_contract); 408 409 /** 410 * @brief Get a Request Data Object from the DPM 411 * 412 * @param dev Pointer to the device structure for the driver instance 413 * @retval the RDO from the DPM 414 */ 415 uint32_t policy_get_request_data_object(const struct device *dev); 416 417 /** 418 * @brief Check if the sink is a default level 419 * 420 * @param dev Pointer to the device structure for the driver instance 421 * @retval true if sink is at default value, else false 422 */ 423 bool policy_is_snk_at_default(const struct device *dev); 424 425 /** 426 * @brief Get sink caps from the DPM 427 * 428 * @param dev Pointer to the device structure for the driver instance 429 * @param pdos pointer to pdo sink caps 430 * @param num_pdos number of pdo sink caps 431 */ 432 void policy_get_snk_cap(const struct device *dev, uint32_t **pdos, int *num_pdos); 433 434 /** 435 * @brief Check if Source Power Supply is ready 436 */ 437 bool policy_is_ps_ready(const struct device *dev); 438 439 /** 440 * @brief Informs the Device Policy Manager that the Sink 441 * is unable to use the current Source Caps and should 442 * should enable a different set of Source Caps. True 443 * is returned if new Source Caps are available, else 444 * false. 445 */ 446 bool policy_change_src_caps(const struct device *dev); 447 448 /** 449 * @brief End and atomic messaging sequence 450 */ 451 void pe_dpm_end_ams(const struct device *dev); 452 453 /** 454 * @brief Handle common DPM requests 455 * 456 * @param dev Pointer to the device structure for the driver instance 457 * @retval true if request was handled, else false 458 */ 459 bool common_dpm_requests(const struct device *dev); 460 461 /** 462 * @brief This function must only be called in the subsystem init function. 463 * 464 * @param dev Pointer to the device structure for the driver instance. 465 */ 466 void pe_subsys_init(const struct device *dev); 467 468 /** 469 * @brief Start the Policy Engine Layer state machine. This is only called 470 * from the Type-C state machine. 471 * 472 * @param dev Pointer to the device structure for the driver instance 473 */ 474 void pe_start(const struct device *dev); 475 476 /** 477 * @brief Suspend the Policy Engine Layer state machine. This is only called 478 * from the Type-C state machine. 479 * 480 * @param dev Pointer to the device structure for the driver instance 481 */ 482 void pe_suspend(const struct device *dev); 483 484 /** 485 * @brief Run the Policy Engine Layer state machine. This is called from the 486 * subsystems port stack thread 487 * 488 * @param dev Pointer to the device structure for the driver instance 489 * @param dpm_request Device Policy Manager request 490 */ 491 void pe_run(const struct device *dev, 492 const int32_t dpm_request); 493 494 /** 495 * @brief Query if the Policy Engine is running 496 * 497 * @param dev Pointer to the device structure for the driver instance 498 * 499 * @retval TRUE if the Policy Engine is running 500 * @retval FALSE if the Policy Engine is not running 501 */ 502 bool pe_is_running(const struct device *dev); 503 504 /** 505 * @brief Informs the Policy Engine that a message was successfully sent 506 * 507 * @param dev Pointer to the device structure for the driver instance 508 */ 509 void pe_message_sent(const struct device *dev); 510 511 /** 512 * @brief Informs the Policy Engine of an error. 513 * 514 * @param dev Pointer to the device structure for the driver instance 515 * @param e policy error 516 * @param type port partner address where error was generated 517 */ 518 void pe_report_error(const struct device *dev, 519 const enum pe_error e, 520 const enum pd_packet_type type); 521 522 /** 523 * @brief Informs the Policy Engine that a transmit message was discarded 524 * because of an incoming message. 525 * 526 * @param dev Pointer to the device structure for the driver instance 527 */ 528 void pe_report_discard(const struct device *dev); 529 530 /** 531 * @brief Called by the Protocol Layer to informs the Policy Engine 532 * that a message has been received. 533 * 534 * @param dev Pointer to the device structure for the driver instance 535 */ 536 void pe_message_received(const struct device *dev); 537 538 /** 539 * @brief Informs the Policy Engine that a hard reset was received. 540 * 541 * @param dev Pointer to the device structure for the driver instance 542 */ 543 void pe_got_hard_reset(const struct device *dev); 544 545 /** 546 * @brief Informs the Policy Engine that a soft reset was received. 547 * 548 * @param dev Pointer to the device structure for the driver instance 549 */ 550 void pe_got_soft_reset(const struct device *dev); 551 552 /** 553 * @brief Informs the Policy Engine that a hard reset was sent. 554 * 555 * @param dev Pointer to the device structure for the driver instance 556 */ 557 void pe_hard_reset_sent(const struct device *dev); 558 559 /** 560 * @brief Indicates if an explicit contract is in place 561 * 562 * @param dev Pointer to the device structure for the driver instance 563 * 564 * @retval true if an explicit contract is in place, else false 565 */ 566 bool pe_is_explicit_contract(const struct device *dev); 567 568 /* 569 * @brief Informs the Policy Engine that it should invalidate the 570 * explicit contract. 571 * 572 * @param dev Pointer to the device structure for the driver instance 573 */ 574 void pe_invalidate_explicit_contract(const struct device *dev); 575 576 /** 577 * @brief Return true if the PE is within an atomic messaging sequence 578 * that it initiated with a SOP* port partner. 579 * 580 * @note The PRL layer polls this instead of using AMS_START and AMS_END 581 * notification from the PE that is called out by the spec 582 * 583 * @param dev Pointer to the device structure for the driver instance 584 */ 585 bool pe_dpm_initiated_ams(const struct device *dev); 586 587 /** 588 * @brief Get the current data role 589 * 590 * @param dev Pointer to the device structure for the driver instance 591 * 592 * @retval data role 593 */ 594 enum tc_data_role pe_get_data_role(const struct device *dev); 595 596 /** 597 * @brief Sets the data role and updates the TCPC 598 * 599 * @param dev Pointer to the device structure for the driver instance 600 * @param dr Data Role to be set 601 */ 602 void pe_set_data_role(const struct device *dev, enum tc_data_role dr); 603 604 /** 605 * @brief Get the current power role 606 * 607 * @param dev Pointer to the device structure for the driver instance 608 * 609 * @retval power role 610 */ 611 enum tc_power_role pe_get_power_role(const struct device *dev); 612 613 /** 614 * @brief Get cable plug role 615 * 616 * @param dev Pointer to the device structure for the driver instance 617 * 618 * @retval cable plug role 619 */ 620 enum tc_cable_plug pe_get_cable_plug(const struct device *dev); 621 622 #endif /* ZEPHYR_SUBSYS_USBC_PE_COMMON_INTERNAL_H_ */ 623
