3  * SPDX-License-Identifier: Apache-2.0
8  * @brief USBC Type-C Port Controller device APIs
10  * This file contains the USB Type-C Port Controller device APIs.
11  * All Type-C Port Controller device drivers should implement the
19  * @brief USB Type-C Port Controller API
20  * @defgroup usb_type_c_port_controller_api USB Type-C Port Controller API
41 enum tcpc_alert {
59 	/** A high-voltage alarm has occurred */
61 	/** A low-voltage alarm has occurred */
85 enum tcpc_status_reg {
121 typedef int (*tcpc_vconn_control_cb_t)(const struct device *dev, enum tc_cc_polarity pol,
123 typedef int (*tcpc_vconn_discharge_cb_t)(const struct device *dev, enum tc_cc_polarity pol,
126 					enum tcpc_alert alert);
129 	int (*init)(const struct device *dev);
130 	int (*get_cc)(const struct device *dev, enum tc_cc_voltage_state *cc1,
131 		      enum tc_cc_voltage_state *cc2);
132 	int (*select_rp_value)(const struct device *dev, enum tc_rp_value rp);
133 	int (*get_rp_value)(const struct device *dev, enum tc_rp_value *rp);
134 	int (*set_cc)(const struct device *dev, enum tc_cc_pull pull);
137 	int (*vconn_discharge)(const struct device *dev, bool enable);
138 	int (*set_vconn)(const struct device *dev, bool enable);
139 	int (*set_roles)(const struct device *dev, enum tc_power_role power_role,
140 			 enum tc_data_role data_role);
141 	int (*get_rx_pending_msg)(const struct device *dev, struct pd_msg *msg);
142 	int (*set_rx_enable)(const struct device *dev, bool enable);
143 	int (*set_cc_polarity)(const struct device *dev, enum tc_cc_polarity polarity);
144 	int (*transmit_data)(const struct device *dev, struct pd_msg *msg);
145 	int (*dump_std_reg)(const struct device *dev);
146 	void (*alert_handler_cb)(const struct device *dev, void *data, enum tcpc_alert alert);
147 	int (*get_status_register)(const struct device *dev, enum tcpc_status_reg reg,
149 	int (*clear_status_register)(const struct device *dev, enum tcpc_status_reg reg,
151 	int (*mask_status_register)(const struct device *dev, enum tcpc_status_reg reg,
153 	int (*set_debug_accessory)(const struct device *dev, bool enable);
154 	int (*set_debug_detach)(const struct device *dev);
155 	int (*set_drp_toggle)(const struct device *dev, bool enable);
156 	int (*get_snk_ctrl)(const struct device *dev);
157 	int (*set_snk_ctrl)(const struct device *dev, bool enable);
158 	int (*get_src_ctrl)(const struct device *dev);
159 	int (*set_src_ctrl)(const struct device *dev, bool enable);
160 	int (*get_chip_info)(const struct device *dev, struct tcpc_chip_info *chip_info);
161 	int (*set_low_power_mode)(const struct device *dev, bool enable);
162 	int (*sop_prime_enable)(const struct device *dev, bool enable);
163 	int (*set_bist_test_mode)(const struct device *dev, bool enable);
164 	int (*set_alert_handler_cb)(const struct device *dev, tcpc_alert_handler_cb_t handler,
171 static inline int tcpc_is_cc_rp(enum tc_cc_voltage_state cc)  in tcpc_is_cc_rp()
179 static inline int tcpc_is_cc_open(enum tc_cc_voltage_state cc1, enum tc_cc_voltage_state cc2)  in tcpc_is_cc_open()
187 static inline int tcpc_is_cc_snk_dbg_acc(enum tc_cc_voltage_state cc1, enum tc_cc_voltage_state cc2)  in tcpc_is_cc_snk_dbg_acc()
195 static inline int tcpc_is_cc_src_dbg_acc(enum tc_cc_voltage_state cc1, enum tc_cc_voltage_state cc2)  in tcpc_is_cc_src_dbg_acc()
203 static inline int tcpc_is_cc_audio_acc(enum tc_cc_voltage_state cc1, enum tc_cc_voltage_state cc2)  in tcpc_is_cc_audio_acc()
211 static inline int tcpc_is_cc_at_least_one_rd(enum tc_cc_voltage_state cc1,  in tcpc_is_cc_at_least_one_rd()
212 					     enum tc_cc_voltage_state cc2)  in tcpc_is_cc_at_least_one_rd()
220 static inline int tcpc_is_cc_only_one_rd(enum tc_cc_voltage_state cc1, enum tc_cc_voltage_state cc2)  in tcpc_is_cc_only_one_rd()
231  * @retval -EIO on failure
232  * @retval -EAGAIN if initialization should be postponed
234 static inline int tcpc_init(const struct device *dev)  in tcpc_init()
236 	const struct tcpc_driver_api *api = (const struct tcpc_driver_api *)dev->api;  in tcpc_init()
238 	__ASSERT(api->init != NULL, "Callback pointer should not be NULL");  in tcpc_init()
240 	return api->init(dev);  in tcpc_init()
251  * @retval -EIO on failure
252  * @retval -ENOSYS if not implemented
254 static inline int tcpc_get_cc(const struct device *dev, enum tc_cc_voltage_state *cc1,  in tcpc_get_cc()
255 			      enum tc_cc_voltage_state *cc2)  in tcpc_get_cc()
257 	const struct tcpc_driver_api *api = (const struct tcpc_driver_api *)dev->api;  in tcpc_get_cc()
259 	if (api->get_cc == NULL) {  in tcpc_get_cc()
260 		return -ENOSYS;  in tcpc_get_cc()
263 	return api->get_cc(dev, cc1, cc2);  in tcpc_get_cc()
270  * @param rp    Value of the Pull-Up Resistor.
273  * @retval -ENOSYS
274  * @retval -EIO on failure
276 static inline int tcpc_select_rp_value(const struct device *dev, enum tc_rp_value rp)  in tcpc_select_rp_value()
278 	const struct tcpc_driver_api *api = (const struct tcpc_driver_api *)dev->api;  in tcpc_select_rp_value()
280 	if (api->select_rp_value == NULL) {  in tcpc_select_rp_value()
281 		return -ENOSYS;  in tcpc_select_rp_value()
284 	return api->select_rp_value(dev, rp);  in tcpc_select_rp_value()
291  * @param rp    pointer where the value of the Pull-Up Resistor is stored
294  * @retval -ENOSYS
295  * @retval -EIO on failure
297 static inline int tcpc_get_rp_value(const struct device *dev, enum tc_rp_value *rp)  in tcpc_get_rp_value()
299 	const struct tcpc_driver_api *api = (const struct tcpc_driver_api *)dev->api;  in tcpc_get_rp_value()
301 	if (api->get_rp_value == NULL) {  in tcpc_get_rp_value()
302 		return -ENOSYS;  in tcpc_get_rp_value()
305 	return api->get_rp_value(dev, rp);  in tcpc_get_rp_value()
315  * @retval -EIO on failure
317 static inline int tcpc_set_cc(const struct device *dev, enum tc_cc_pull pull)  in tcpc_set_cc()
319 	const struct tcpc_driver_api *api = (const struct tcpc_driver_api *)dev->api;  in tcpc_set_cc()
321 	__ASSERT(api->set_cc != NULL, "Callback pointer should not be NULL");  in tcpc_set_cc()
323 	return api->set_cc(dev, pull);  in tcpc_set_cc()
338 	const struct tcpc_driver_api *api = (const struct tcpc_driver_api *)dev->api;  in tcpc_set_vconn_cb()
340 	__ASSERT(api->set_vconn_cb != NULL, "Callback pointer should not be NULL");  in tcpc_set_vconn_cb()
342 	api->set_vconn_cb(dev, vconn_cb);  in tcpc_set_vconn_cb()
358 	const struct tcpc_driver_api *api = (const struct tcpc_driver_api *)dev->api;  in tcpc_set_vconn_discharge_cb()
360 	__ASSERT(api->set_vconn_discharge_cb != NULL, "Callback pointer should not be NULL");  in tcpc_set_vconn_discharge_cb()
362 	api->set_vconn_discharge_cb(dev, cb);  in tcpc_set_vconn_discharge_cb()
375  * @retval -EIO on failure
376  * @retval -ENOSYS if not implemented
378 static inline int tcpc_vconn_discharge(const struct device *dev, bool enable)  in tcpc_vconn_discharge()
380 	const struct tcpc_driver_api *api = (const struct tcpc_driver_api *)dev->api;  in tcpc_vconn_discharge()
382 	if (api->vconn_discharge == NULL) {  in tcpc_vconn_discharge()
383 		return -ENOSYS;  in tcpc_vconn_discharge()
386 	return api->vconn_discharge(dev, enable);  in tcpc_vconn_discharge()
399  * @retval -EIO on failure
400  * @retval -ENOSYS if not implemented
402 static inline int tcpc_set_vconn(const struct device *dev, bool enable)  in tcpc_set_vconn()
404 	const struct tcpc_driver_api *api = (const struct tcpc_driver_api *)dev->api;  in tcpc_set_vconn()
406 	if (api->set_vconn == NULL) {  in tcpc_set_vconn()
407 		return -ENOSYS;  in tcpc_set_vconn()
410 	return api->set_vconn(dev, enable);  in tcpc_set_vconn()
423  * @retval -EIO on failure
424  * @retval -ENOSYS if not implemented
426 static inline int tcpc_set_roles(const struct device *dev, enum tc_power_role power_role,  in tcpc_set_roles()
427 				 enum tc_data_role data_role)  in tcpc_set_roles()
429 	const struct tcpc_driver_api *api = (const struct tcpc_driver_api *)dev->api;  in tcpc_set_roles()
431 	if (api->set_roles == NULL) {  in tcpc_set_roles()
432 		return -ENOSYS;  in tcpc_set_roles()
435 	return api->set_roles(dev, power_role, data_role);  in tcpc_set_roles()
441  * -ENODATA means there is no pending message.
448  * @retval -EIO on failure
449  * @retval -ENODATA if no message is pending
451 static inline int tcpc_get_rx_pending_msg(const struct device *dev, struct pd_msg *buf)  in tcpc_get_rx_pending_msg()
453 	const struct tcpc_driver_api *api = (const struct tcpc_driver_api *)dev->api;  in tcpc_get_rx_pending_msg()
455 	__ASSERT(api->get_rx_pending_msg != NULL, "Callback pointer should not be NULL");  in tcpc_get_rx_pending_msg()
457 	return api->get_rx_pending_msg(dev, buf);  in tcpc_get_rx_pending_msg()
468  * @retval -EIO on failure
469  * @retval -ENOSYS if not implemented
471 static inline int tcpc_set_rx_enable(const struct device *dev, bool enable)  in tcpc_set_rx_enable()
473 	const struct tcpc_driver_api *api = (const struct tcpc_driver_api *)dev->api;  in tcpc_set_rx_enable()
475 	if (api->set_rx_enable == NULL) {  in tcpc_set_rx_enable()
476 		return -ENOSYS;  in tcpc_set_rx_enable()
479 	return api->set_rx_enable(dev, enable);  in tcpc_set_rx_enable()
489  * @retval -EIO on failure
491 static inline int tcpc_set_cc_polarity(const struct device *dev, enum tc_cc_polarity polarity)  in tcpc_set_cc_polarity()
493 	const struct tcpc_driver_api *api = (const struct tcpc_driver_api *)dev->api;  in tcpc_set_cc_polarity()
495 	__ASSERT(api->set_cc_polarity != NULL, "Callback pointer should not be NULL");  in tcpc_set_cc_polarity()
497 	return api->set_cc_polarity(dev, polarity);  in tcpc_set_cc_polarity()
507  * @retval -EIO on failure
508  * @retval -ENOSYS if not implemented
510 static inline int tcpc_transmit_data(const struct device *dev, struct pd_msg *msg)  in tcpc_transmit_data()
512 	const struct tcpc_driver_api *api = (const struct tcpc_driver_api *)dev->api;  in tcpc_transmit_data()
514 	if (api->transmit_data == NULL) {  in tcpc_transmit_data()
515 		return -ENOSYS;  in tcpc_transmit_data()
518 	return api->transmit_data(dev, msg);  in tcpc_transmit_data()
527  * @retval -EIO on failure
528  * @retval -ENOSYS if not implemented
530 static inline int tcpc_dump_std_reg(const struct device *dev)  in tcpc_dump_std_reg()
532 	const struct tcpc_driver_api *api = (const struct tcpc_driver_api *)dev->api;  in tcpc_dump_std_reg()
534 	if (api->dump_std_reg == NULL) {  in tcpc_dump_std_reg()
535 		return -ENOSYS;  in tcpc_dump_std_reg()
538 	return api->dump_std_reg(dev);  in tcpc_dump_std_reg()
552  * @retval -EINVAL on failure
554 static inline int tcpc_set_alert_handler_cb(const struct device *dev,  in tcpc_set_alert_handler_cb()
557 	const struct tcpc_driver_api *api = (const struct tcpc_driver_api *)dev->api;  in tcpc_set_alert_handler_cb()
559 	__ASSERT(api->set_alert_handler_cb != NULL, "Callback pointer should not be NULL");  in tcpc_set_alert_handler_cb()
561 	return api->set_alert_handler_cb(dev, handler, data);  in tcpc_set_alert_handler_cb()
572  * @retval -EIO on failure
573  * @retval -ENOSYS if not implemented
575 static inline int tcpc_get_status_register(const struct device *dev, enum tcpc_status_reg reg,  in tcpc_get_status_register()
578 	const struct tcpc_driver_api *api = (const struct tcpc_driver_api *)dev->api;  in tcpc_get_status_register()
580 	if (api->get_status_register == NULL) {  in tcpc_get_status_register()
581 		return -ENOSYS;  in tcpc_get_status_register()
584 	return api->get_status_register(dev, reg, status);  in tcpc_get_status_register()
596  * @retval -EIO on failure
597  * @retval -ENOSYS if not implemented
599 static inline int tcpc_clear_status_register(const struct device *dev, enum tcpc_status_reg reg,  in tcpc_clear_status_register()
602 	const struct tcpc_driver_api *api = (const struct tcpc_driver_api *)dev->api;  in tcpc_clear_status_register()
604 	if (api->clear_status_register == NULL) {  in tcpc_clear_status_register()
605 		return -ENOSYS;  in tcpc_clear_status_register()
608 	return api->clear_status_register(dev, reg, mask);  in tcpc_clear_status_register()
620  * @retval -EIO on failure
621  * @retval -ENOSYS if not implemented
623 static inline int tcpc_mask_status_register(const struct device *dev, enum tcpc_status_reg reg,  in tcpc_mask_status_register()
626 	const struct tcpc_driver_api *api = (const struct tcpc_driver_api *)dev->api;  in tcpc_mask_status_register()
628 	if (api->mask_status_register == NULL) {  in tcpc_mask_status_register()
629 		return -ENOSYS;  in tcpc_mask_status_register()
632 	return api->mask_status_register(dev, reg, mask);  in tcpc_mask_status_register()
642  * @retval -EIO on failure
643  * @retval -ENOSYS if not implemented
645 static inline int tcpc_set_debug_accessory(const struct device *dev, bool enable)  in tcpc_set_debug_accessory()
647 	const struct tcpc_driver_api *api = (const struct tcpc_driver_api *)dev->api;  in tcpc_set_debug_accessory()
649 	if (api->set_debug_accessory == NULL) {  in tcpc_set_debug_accessory()
650 		return -ENOSYS;  in tcpc_set_debug_accessory()
653 	return api->set_debug_accessory(dev, enable);  in tcpc_set_debug_accessory()
662  * @retval -EIO on failure
663  * @retval -ENOSYS if not implemented
665 static inline int tcpc_set_debug_detach(const struct device *dev)  in tcpc_set_debug_detach()
667 	const struct tcpc_driver_api *api = (const struct tcpc_driver_api *)dev->api;  in tcpc_set_debug_detach()
669 	if (api->set_debug_detach == NULL) {  in tcpc_set_debug_detach()
670 		return -ENOSYS;  in tcpc_set_debug_detach()
673 	return api->set_debug_detach(dev);  in tcpc_set_debug_detach()
683  * @retval -EIO on failure
684  * @retval -ENOSYS if not implemented
686 static inline int tcpc_set_drp_toggle(const struct device *dev, bool enable)  in tcpc_set_drp_toggle()
688 	const struct tcpc_driver_api *api = (const struct tcpc_driver_api *)dev->api;  in tcpc_set_drp_toggle()
690 	if (api->set_drp_toggle == NULL) {  in tcpc_set_drp_toggle()
691 		return -ENOSYS;  in tcpc_set_drp_toggle()
694 	return api->set_drp_toggle(dev, enable);  in tcpc_set_drp_toggle()
704  * @retval -ENOSYS if not implemented
706 static inline int tcpc_get_snk_ctrl(const struct device *dev)  in tcpc_get_snk_ctrl()
708 	const struct tcpc_driver_api *api = (const struct tcpc_driver_api *)dev->api;  in tcpc_get_snk_ctrl()
710 	if (api->get_snk_ctrl == NULL) {  in tcpc_get_snk_ctrl()
711 		return -ENOSYS;  in tcpc_get_snk_ctrl()
714 	return api->get_snk_ctrl(dev);  in tcpc_get_snk_ctrl()
723  * @retval -ENOSYS if not implemented
725 static inline int tcpc_set_snk_ctrl(const struct device *dev, bool enable)  in tcpc_set_snk_ctrl()
727 	const struct tcpc_driver_api *api = (const struct tcpc_driver_api *)dev->api;  in tcpc_set_snk_ctrl()
729 	if (api->set_snk_ctrl == NULL) {  in tcpc_set_snk_ctrl()
730 		return -ENOSYS;  in tcpc_set_snk_ctrl()
733 	return api->set_snk_ctrl(dev, enable);  in tcpc_set_snk_ctrl()
743  * @retval -ENOSYS if not implemented
745 static inline int tcpc_get_src_ctrl(const struct device *dev)  in tcpc_get_src_ctrl()
747 	const struct tcpc_driver_api *api = (const struct tcpc_driver_api *)dev->api;  in tcpc_get_src_ctrl()
749 	if (api->get_src_ctrl == NULL) {  in tcpc_get_src_ctrl()
750 		return -ENOSYS;  in tcpc_get_src_ctrl()
753 	return api->get_src_ctrl(dev);  in tcpc_get_src_ctrl()
762  * @retval -ENOSYS if not implemented
764 static inline int tcpc_set_src_ctrl(const struct device *dev, bool enable)  in tcpc_set_src_ctrl()
766 	const struct tcpc_driver_api *api = (const struct tcpc_driver_api *)dev->api;  in tcpc_set_src_ctrl()
768 	if (api->set_src_ctrl == NULL) {  in tcpc_set_src_ctrl()
769 		return -ENOSYS;  in tcpc_set_src_ctrl()
772 	return api->set_src_ctrl(dev, enable);  in tcpc_set_src_ctrl()
783  * @retval -EIO on failure
784  * @retval -ENOSYS if not implemented
786 static inline int tcpc_set_bist_test_mode(const struct device *dev, bool enable)  in tcpc_set_bist_test_mode()
788 	const struct tcpc_driver_api *api = (const struct tcpc_driver_api *)dev->api;  in tcpc_set_bist_test_mode()
790 	if (api->set_bist_test_mode == NULL) {  in tcpc_set_bist_test_mode()
791 		return -ENOSYS;  in tcpc_set_bist_test_mode()
794 	return api->set_bist_test_mode(dev, enable);  in tcpc_set_bist_test_mode()
804  * @retval -EIO on failure
805  * @retval -ENOSYS if not implemented
807 static inline int tcpc_get_chip_info(const struct device *dev, struct tcpc_chip_info *chip_info)  in tcpc_get_chip_info()
809 	const struct tcpc_driver_api *api = (const struct tcpc_driver_api *)dev->api;  in tcpc_get_chip_info()
811 	if (api->get_chip_info == NULL) {  in tcpc_get_chip_info()
812 		return -ENOSYS;  in tcpc_get_chip_info()
815 	return api->get_chip_info(dev, chip_info);  in tcpc_get_chip_info()
825  * @retval -EIO on failure
826  * @retval -ENOSYS if not implemented
828 static inline int tcpc_set_low_power_mode(const struct device *dev, bool enable)  in tcpc_set_low_power_mode()
830 	const struct tcpc_driver_api *api = (const struct tcpc_driver_api *)dev->api;  in tcpc_set_low_power_mode()
832 	if (api->set_low_power_mode == NULL) {  in tcpc_set_low_power_mode()
833 		return -ENOSYS;  in tcpc_set_low_power_mode()
836 	return api->set_low_power_mode(dev, enable);  in tcpc_set_low_power_mode()
846  * @retval -EIO on failure
847  * @retval -ENOSYS if not implemented
849 static inline int tcpc_sop_prime_enable(const struct device *dev, bool enable)  in tcpc_sop_prime_enable()
851 	const struct tcpc_driver_api *api = (const struct tcpc_driver_api *)dev->api;  in tcpc_sop_prime_enable()
853 	if (api->sop_prime_enable == NULL) {  in tcpc_sop_prime_enable()
854 		return -ENOSYS;  in tcpc_sop_prime_enable()
857 	return api->sop_prime_enable(dev, enable);  in tcpc_sop_prime_enable()