1 /*
2  * Copyright 2024 Google LLC
3  * SPDX-License-Identifier: Apache-2.0
4  */
5 
6 /**
7  * @file
8  * @brief Helper functions to use by the TCPCI-compliant drivers
9  *
10  * This file contains generic TCPCI functions that may be used by the drivers to TCPCI-compliant
11  * devices that want to implement vendor-specific functionality without the need to reimplement the
12  * TCPCI generic functionality and register operations.
13  */
14 
15 #ifndef ZEPHYR_INCLUDE_DRIVERS_USBC_TCPCI_PRIV_H_
16 #define ZEPHYR_INCLUDE_DRIVERS_USBC_TCPCI_PRIV_H_
17 
18 #include <stdint.h>
19 #include <zephyr/drivers/i2c.h>
20 #include <zephyr/usb_c/usbc.h>
21 
22 /**
23  * @brief Structure used to bind the register address to name in registers dump
24  */
25 struct tcpci_reg_dump_map {
26 	/** Address of I2C device register */
27 	uint8_t addr;
28 	/** Human readable name of register */
29 	const char *name;
30 	/** Size in bytes of the register */
31 	uint8_t size;
32 };
33 
34 /** Size of the array containing the standard registers used by tcpci dump command */
35 #define TCPCI_STD_REGS_SIZE 38
36 /**
37  * @brief Array containing the standard TCPCI registers list.
38  * If the TCPC driver contain any vendor-specific registers, it may override the TCPCI dump_std_reg
39  * function tp dump them and should also dump the standard registers using this array.
40  *
41  */
42 extern const struct tcpci_reg_dump_map tcpci_std_regs[TCPCI_STD_REGS_SIZE];
43 
44 /**
45  * @brief Function to read the 8-bit register of TCPCI device
46  *
47  * @param bus I2C bus
48  * @param reg Address of TCPCI register
49  * @param value Pointer to variable that will store the register value
50  * @return int Status of I2C operation, 0 in case of success
51  */
52 int tcpci_read_reg8(const struct i2c_dt_spec *bus, uint8_t reg, uint8_t *value);
53 
54 /**
55  * @brief Function to write a value to the 8-bit register of TCPCI device
56  *
57  * @param bus I2C bus
58  * @param reg Address of TCPCI register
59  * @param value Value that will be written to the device register
60  * @return int Status of I2C operation, 0 in case of success
61  */
62 int tcpci_write_reg8(const struct i2c_dt_spec *bus, uint8_t reg, uint8_t value);
63 
64 /**
65  * @brief Function to read and update part of the 8-bit register of TCPCI device
66  * The function is NOT performing this operation atomically.
67  *
68  * @param bus I2C bus
69  * @param reg Address of TCPCI register
70  * @param mask Bitmask specifying which bits of the device register will be modified
71  * @param value Value that will be written to the device register after being ANDed with mask
72  * @return int Status of I2C operation, 0 in case of success
73  */
74 int tcpci_update_reg8(const struct i2c_dt_spec *bus, uint8_t reg, uint8_t mask, uint8_t value);
75 
76 /**
77  * @brief Function to read the 16-bit register of TCPCI device
78  *
79  * @param bus I2C bus
80  * @param reg Address of TCPCI register
81  * @param value Pointer to variable that will store the register value
82  * @return int Status of I2C operation, 0 in case of success
83  */
84 int tcpci_read_reg16(const struct i2c_dt_spec *bus, uint8_t reg, uint16_t *value);
85 
86 /**
87  * @brief Function to write a value to the 16-bit register of TCPCI device
88  *
89  * @param bus I2C bus
90  * @param reg Address of TCPCI register
91  * @param value Value that will be written to the device register
92  * @return int Status of I2C operation, 0 in case of success
93  */
94 int tcpci_write_reg16(const struct i2c_dt_spec *bus, uint8_t reg, uint16_t value);
95 
96 /**
97  * @brief Function that converts the TCPCI alert register to the tcpc_alert enum
98  * The hard reset value takes priority, where the rest are returned in the bit order from least
99  * significant to most significant.
100  *
101  * @param reg Value of the TCPCI alert register. This parameter must have value other than zero.
102  * @return enum tcpc_alert Value of one of the flags being set in the alert register
103  */
104 enum tcpc_alert tcpci_alert_reg_to_enum(uint16_t reg);
105 
106 /**
107  * @brief Function that reads the CC status registers and converts read values to enums
108  * representing voltages state and partner detection status.
109  *
110  * @param bus I2C bus
111  * @param cc1 Pointer to variable where detected CC1 voltage state will be stored
112  * @param cc2 Pointer to variable where detected CC2 voltage state will be stored
113  * @return -EINVAL if cc1 or cc2 pointer is NULL
114  * @return int Status of I2C operation, 0 in case of success
115  */
116 int tcpci_tcpm_get_cc(const struct i2c_dt_spec *bus, enum tc_cc_voltage_state *cc1,
117 		      enum tc_cc_voltage_state *cc2);
118 
119 /**
120  * @brief Function to retrieve information about the TCPCI chip.
121  *
122  * @param bus I2C bus
123  * @param chip_info Pointer to the structure where the chip information will be stored
124  * @return int Status of I2C operation, 0 in case of success
125  */
126 int tcpci_tcpm_get_chip_info(const struct i2c_dt_spec *bus, struct tcpc_chip_info *chip_info);
127 
128 /**
129  * @brief Function to dump the standard TCPCI registers.
130  *
131  * @param bus I2C bus
132  * @return int Status of I2C operation, 0 in case of success
133  */
134 int tcpci_tcpm_dump_std_reg(const struct i2c_dt_spec *bus);
135 
136 /**
137  * @brief Function to enable or disable the BIST (Built-In Self-Test) mode.
138  *
139  * @param bus I2C bus
140  * @param enable Boolean flag to enable (true) or disable (false) BIST mode
141  * @return int Status of I2C operation, 0 in case of success
142  */
143 int tcpci_tcpm_set_bist_test_mode(const struct i2c_dt_spec *bus, bool enable);
144 
145 /**
146  * @brief Function to transmit a PD (Power Delivery) message. The message is transmitted
147  * with a specified number of retries in case of failure.
148  *
149  * @param bus I2C bus
150  * @param msg Pointer to the PD message structure to be transmitted
151  * @param retries Number of retries in case of transmission failure
152  * @return int Status of I2C operation, 0 in case of success
153  */
154 int tcpci_tcpm_transmit_data(const struct i2c_dt_spec *bus, struct pd_msg *msg,
155 			     const uint8_t retries);
156 
157 /**
158  * @brief Function to select the Rp (Pull-up Resistor) value.
159  *
160  * @param bus I2C bus
161  * @param rp Enum representing the Rp value to be set
162  * @return int Status of I2C operation, 0 in case of success
163  */
164 int tcpci_tcpm_select_rp_value(const struct i2c_dt_spec *bus, enum tc_rp_value rp);
165 
166 /**
167  * @brief Function to get the currently selected Rp value.
168  *
169  * @param bus I2C bus
170  * @param rp Pointer to the variable where the Rp value will be stored
171  * @return int Status of I2C operation, 0 in case of success
172  */
173 int tcpci_tcpm_get_rp_value(const struct i2c_dt_spec *bus, enum tc_rp_value *rp);
174 
175 /**
176  * @brief Function to set the CC pull resistor and set the role as either Source or Sink.
177  *
178  * @param bus I2C bus
179  * @param pull Enum representing the CC pull resistor to be set
180  * @return int Status of I2C operation, 0 in case of success
181  */
182 int tcpci_tcpm_set_cc(const struct i2c_dt_spec *bus, enum tc_cc_pull pull);
183 
184 /**
185  * @brief Function to enable or disable TCPC auto dual role toggle.
186  *
187  * @param bus I2C bus
188  * @param enable Boolean flag to enable (true) or disable (false) DRP toggle mode
189  * @return int Status of I2C operation, 0 in case of success
190  */
191 int tcpci_tcpm_set_drp_toggle(const struct i2c_dt_spec *bus, bool enable);
192 
193 /**
194  * @brief Function to set the power and data role of the PD message header.
195  *
196  * @param bus I2C bus
197  * @param pd_rev Enum representing the USB−PD Specification Revision to be set
198  * @param power_role Enum representing the power role to be set
199  * @param data_role Enum representing the data role to be set
200  * @return int Status of I2C operation, 0 in case of success
201  */
202 int tcpci_tcpm_set_roles(const struct i2c_dt_spec *bus, enum pd_rev_type pd_rev,
203 			 enum tc_power_role power_role, enum tc_data_role data_role);
204 
205 /**
206  * @brief Function to set the RX type.
207  *
208  * @param bus I2C bus
209  * @param type Value representing the RX type to be set
210  * @return int Status of I2C operation, 0 in case of success
211  */
212 int tcpci_tcpm_set_rx_type(const struct i2c_dt_spec *bus, uint8_t type);
213 
214 /**
215  * @brief Function to set the polarity of the CC lines.
216  *
217  * @param bus I2C bus
218  * @param polarity Enum representing the CC polarity to be set
219  * @return int Status of I2C operation, 0 in case of success
220  */
221 int tcpci_tcpm_set_cc_polarity(const struct i2c_dt_spec *bus, enum tc_cc_polarity polarity);
222 
223 /**
224  * @brief Function to enable or disable VCONN.
225  *
226  * @param bus I2C bus
227  * @param enable Boolean flag to enable (true) or disable (false) VCONN
228  * @return int Status of I2C operation, 0 in case of success
229  */
230 int tcpci_tcpm_set_vconn(const struct i2c_dt_spec *bus, bool enable);
231 
232 /**
233  * @brief Function to get the status of a specific TCPCI status register.
234  *
235  * @param bus I2C bus
236  * @param reg Enum representing the status register to be read
237  * @param status Pointer to the variable where the status will be stored
238  * @return int Status of I2C operation, 0 in case of success
239  */
240 int tcpci_tcpm_get_status_register(const struct i2c_dt_spec *bus, enum tcpc_status_reg reg,
241 				   uint16_t *status);
242 
243 /**
244  * @brief Function to clear specific bits in a TCPCI status register.
245  *
246  * @param bus I2C bus
247  * @param reg Enum representing the status register to be cleared
248  * @param mask Bitmask specifying which bits to clear
249  * @return int Status of I2C operation, 0 in case of success
250  */
251 int tcpci_tcpm_clear_status_register(const struct i2c_dt_spec *bus, enum tcpc_status_reg reg,
252 				     uint16_t mask);
253 
254 /**
255  * @brief Function to set the mask of a TCPCI status register.
256  *
257  * @param bus I2C bus
258  * @param reg Enum representing the status register to be masked
259  * @param mask Bitmask specifying which bits to mask
260  * @return int Status of I2C operation, 0 in case of success
261  */
262 int tcpci_tcpm_mask_status_register(const struct i2c_dt_spec *bus, enum tcpc_status_reg reg,
263 				    uint16_t mask);
264 
265 #endif /* ZEPHYR_INCLUDE_DRIVERS_USBC_TCPCI_PRIV_H_ */
266