Line data Source code
1 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 1 : struct tcpci_reg_dump_map {
26 : /** Address of I2C device register */
27 1 : uint8_t addr;
28 : /** Human readable name of register */
29 1 : const char *name;
30 : /** Size in bytes of the register */
31 1 : uint8_t size;
32 : };
33 :
34 : /** Size of the array containing the standard registers used by tcpci dump command */
35 1 : #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 1 : extern const struct tcpci_reg_dump_map tcpci_std_regs[TCPCI_STD_REGS_SIZE];
43 :
44 : /** Type-C Port Controller Interface Specification Revision */
45 1 : #define PD_INT_REV10 0x10 /* Revision 1.0 */
46 0 : #define PD_INT_REV20 0x20 /* Revision 2.0 */
47 :
48 : /**
49 : * @brief Function to read the 8-bit register of TCPCI device
50 : *
51 : * @param bus I2C bus
52 : * @param reg Address of TCPCI register
53 : * @param value Pointer to variable that will store the register value
54 : * @return int Status of I2C operation, 0 in case of success
55 : */
56 1 : int tcpci_read_reg8(const struct i2c_dt_spec *bus, uint8_t reg, uint8_t *value);
57 :
58 : /**
59 : * @brief Function to write a value to the 8-bit register of TCPCI device
60 : *
61 : * @param bus I2C bus
62 : * @param reg Address of TCPCI register
63 : * @param value Value that will be written to the device register
64 : * @return int Status of I2C operation, 0 in case of success
65 : */
66 1 : int tcpci_write_reg8(const struct i2c_dt_spec *bus, uint8_t reg, uint8_t value);
67 :
68 : /**
69 : * @brief Function to read and update part of the 8-bit register of TCPCI device
70 : * The function is NOT performing this operation atomically.
71 : *
72 : * @param bus I2C bus
73 : * @param reg Address of TCPCI register
74 : * @param mask Bitmask specifying which bits of the device register will be modified
75 : * @param value Value that will be written to the device register after being ANDed with mask
76 : * @return int Status of I2C operation, 0 in case of success
77 : */
78 1 : int tcpci_update_reg8(const struct i2c_dt_spec *bus, uint8_t reg, uint8_t mask, uint8_t value);
79 :
80 : /**
81 : * @brief Function to read the 16-bit register of TCPCI device
82 : *
83 : * @param bus I2C bus
84 : * @param reg Address of TCPCI register
85 : * @param value Pointer to variable that will store the register value
86 : * @return int Status of I2C operation, 0 in case of success
87 : */
88 1 : int tcpci_read_reg16(const struct i2c_dt_spec *bus, uint8_t reg, uint16_t *value);
89 :
90 : /**
91 : * @brief Function to write a value to the 16-bit register of TCPCI device
92 : *
93 : * @param bus I2C bus
94 : * @param reg Address of TCPCI register
95 : * @param value Value that will be written to the device register
96 : * @return int Status of I2C operation, 0 in case of success
97 : */
98 1 : int tcpci_write_reg16(const struct i2c_dt_spec *bus, uint8_t reg, uint16_t value);
99 :
100 : /**
101 : * @brief Function that converts the TCPCI alert register to the tcpc_alert enum
102 : * The hard reset value takes priority, where the rest are returned in the bit order from least
103 : * significant to most significant.
104 : *
105 : * @param reg Value of the TCPCI alert register. This parameter must have value other than zero.
106 : * @return enum tcpc_alert Value of one of the flags being set in the alert register
107 : */
108 1 : enum tcpc_alert tcpci_alert_reg_to_enum(uint16_t reg);
109 :
110 : /**
111 : * @brief Function that reads the CC status registers and converts read values to enums
112 : * representing voltages state and partner detection status.
113 : *
114 : * @param bus I2C bus
115 : * @param cc1 Pointer to variable where detected CC1 voltage state will be stored
116 : * @param cc2 Pointer to variable where detected CC2 voltage state will be stored
117 : * @return -EINVAL if cc1 or cc2 pointer is NULL
118 : * @return int Status of I2C operation, 0 in case of success
119 : */
120 1 : int tcpci_tcpm_get_cc(const struct i2c_dt_spec *bus, enum tc_cc_voltage_state *cc1,
121 : enum tc_cc_voltage_state *cc2);
122 :
123 : /**
124 : * @brief Function to retrieve information about the TCPCI chip.
125 : *
126 : * @param bus I2C bus
127 : * @param chip_info Pointer to the structure where the chip information will be stored
128 : * @return int Status of I2C operation, 0 in case of success
129 : */
130 1 : int tcpci_tcpm_get_chip_info(const struct i2c_dt_spec *bus, struct tcpc_chip_info *chip_info);
131 :
132 : /**
133 : * @brief Function to dump the standard TCPCI registers.
134 : *
135 : * @param bus I2C bus
136 : * @return int Status of I2C operation, 0 in case of success
137 : */
138 1 : int tcpci_tcpm_dump_std_reg(const struct i2c_dt_spec *bus);
139 :
140 : /**
141 : * @brief Function to enable or disable the BIST (Built-In Self-Test) mode.
142 : *
143 : * @param bus I2C bus
144 : * @param enable Boolean flag to enable (true) or disable (false) BIST mode
145 : * @return int Status of I2C operation, 0 in case of success
146 : */
147 1 : int tcpci_tcpm_set_bist_test_mode(const struct i2c_dt_spec *bus, bool enable);
148 :
149 : /**
150 : * @brief Function to transmit a PD (Power Delivery) message. The message is transmitted
151 : * with a specified number of retries in case of failure.
152 : *
153 : * @param bus I2C bus
154 : * @param msg Pointer to the PD message structure to be transmitted
155 : * @param retries Number of retries in case of transmission failure
156 : * @return int Status of I2C operation, 0 in case of success
157 : */
158 1 : int tcpci_tcpm_transmit_data(const struct i2c_dt_spec *bus, struct pd_msg *msg,
159 : const uint8_t retries);
160 :
161 : /**
162 : * @brief Function to select the Rp (Pull-up Resistor) value.
163 : *
164 : * @param bus I2C bus
165 : * @param rp Enum representing the Rp value to be set
166 : * @return int Status of I2C operation, 0 in case of success
167 : */
168 1 : int tcpci_tcpm_select_rp_value(const struct i2c_dt_spec *bus, enum tc_rp_value rp);
169 :
170 : /**
171 : * @brief Function to get the currently selected Rp value.
172 : *
173 : * @param bus I2C bus
174 : * @param rp Pointer to the variable where the Rp value will be stored
175 : * @return int Status of I2C operation, 0 in case of success
176 : */
177 1 : int tcpci_tcpm_get_rp_value(const struct i2c_dt_spec *bus, enum tc_rp_value *rp);
178 :
179 : /**
180 : * @brief Function to set the CC pull resistor and set the role as either Source or Sink.
181 : *
182 : * @param bus I2C bus
183 : * @param pull Enum representing the CC pull resistor to be set
184 : * @return int Status of I2C operation, 0 in case of success
185 : */
186 1 : int tcpci_tcpm_set_cc(const struct i2c_dt_spec *bus, enum tc_cc_pull pull);
187 :
188 : /**
189 : * @brief Function to enable or disable TCPC auto dual role toggle.
190 : *
191 : * @param bus I2C bus
192 : * @param pd_int_rev Value of the TCPC_REG_PD_INT_REV bits [15..8]
193 : * @param enable Boolean flag to enable (true) or disable (false) DRP toggle mode
194 : * @return int Status of I2C operation, 0 in case of success
195 : */
196 1 : int tcpci_tcpm_set_drp_toggle(const struct i2c_dt_spec *bus, uint8_t pd_int_rev, bool enable);
197 :
198 : /**
199 : * @brief Function to set the power and data role of the PD message header.
200 : *
201 : * @param bus I2C bus
202 : * @param pd_rev Enum representing the USB−PD Specification Revision to be set
203 : * @param power_role Enum representing the power role to be set
204 : * @param data_role Enum representing the data role to be set
205 : * @return int Status of I2C operation, 0 in case of success
206 : */
207 1 : int tcpci_tcpm_set_roles(const struct i2c_dt_spec *bus, enum pd_rev_type pd_rev,
208 : enum tc_power_role power_role, enum tc_data_role data_role);
209 :
210 : /**
211 : * @brief Function to set the RX type.
212 : *
213 : * @param bus I2C bus
214 : * @param type Value representing the RX type to be set
215 : * @return int Status of I2C operation, 0 in case of success
216 : */
217 1 : int tcpci_tcpm_set_rx_type(const struct i2c_dt_spec *bus, uint8_t type);
218 :
219 : /**
220 : * @brief Function to set the polarity of the CC lines.
221 : *
222 : * @param bus I2C bus
223 : * @param polarity Enum representing the CC polarity to be set
224 : * @return int Status of I2C operation, 0 in case of success
225 : */
226 1 : int tcpci_tcpm_set_cc_polarity(const struct i2c_dt_spec *bus, enum tc_cc_polarity polarity);
227 :
228 : /**
229 : * @brief Function to enable or disable VCONN.
230 : *
231 : * @param bus I2C bus
232 : * @param enable Boolean flag to enable (true) or disable (false) VCONN
233 : * @return int Status of I2C operation, 0 in case of success
234 : */
235 1 : int tcpci_tcpm_set_vconn(const struct i2c_dt_spec *bus, bool enable);
236 :
237 : /**
238 : * @brief Function to get the status of a specific TCPCI status register.
239 : *
240 : * @param bus I2C bus
241 : * @param reg Enum representing the status register to be read
242 : * @param status Pointer to the variable where the status will be stored
243 : * @return int Status of I2C operation, 0 in case of success
244 : */
245 1 : int tcpci_tcpm_get_status_register(const struct i2c_dt_spec *bus, enum tcpc_status_reg reg,
246 : uint16_t *status);
247 :
248 : /**
249 : * @brief Function to clear specific bits in a TCPCI status register.
250 : *
251 : * @param bus I2C bus
252 : * @param reg Enum representing the status register to be cleared
253 : * @param mask Bitmask specifying which bits to clear
254 : * @return int Status of I2C operation, 0 in case of success
255 : */
256 1 : int tcpci_tcpm_clear_status_register(const struct i2c_dt_spec *bus, enum tcpc_status_reg reg,
257 : uint16_t mask);
258 :
259 : /**
260 : * @brief Function to set the mask of a TCPCI status register.
261 : *
262 : * @param bus I2C bus
263 : * @param reg Enum representing the status register to be masked
264 : * @param mask Bitmask specifying which bits to mask
265 : * @return int Status of I2C operation, 0 in case of success
266 : */
267 1 : int tcpci_tcpm_mask_status_register(const struct i2c_dt_spec *bus, enum tcpc_status_reg reg,
268 : uint16_t mask);
269 :
270 : /**
271 : * @brief Queries the current sinking state of the TCPCI.
272 : *
273 : * This function checks if the device is sinking VBUS to the system load.
274 : *
275 : * @param bus I2C bus
276 : * @param sinking Pointer to variable where sinking state will be stored
277 : * @return int Status of I2C operation, 0 in case of success
278 : */
279 1 : int tcpci_tcpm_get_snk_ctrl(const struct i2c_dt_spec *bus, bool *sinking);
280 :
281 : /**
282 : * @brief Queries the current sourcing state of the TCPCI.
283 : *
284 : * This function checks if the device is sourcing VBUS.
285 : *
286 : * @param bus I2C bus
287 : * @param sourcing Pointer to variable where sourcing state will be stored
288 : * @return int Status of I2C operation, 0 in case of success
289 : */
290 1 : int tcpci_tcpm_get_src_ctrl(const struct i2c_dt_spec *bus, bool *sourcing);
291 :
292 : /**
293 : * @brief Function to enable or disable sinking power over VBUS.
294 : *
295 : * @param bus I2C bus
296 : * @param enable Boolean flag to enable (true) or disable (false) sinking power
297 : * @return int Status of I2C operation, 0 in case of success
298 : */
299 1 : int tcpci_tcpm_set_snk_ctrl(const struct i2c_dt_spec *bus, bool enable);
300 :
301 : /**
302 : * @brief Function to enable or disable sourcing power over VBUS.
303 : *
304 : * @param bus I2C bus
305 : * @param enable Boolean flag to enable (true) or disable (false) sourcing power
306 : * @return int Status of I2C operation, 0 in case of success
307 : */
308 1 : int tcpci_tcpm_set_src_ctrl(const struct i2c_dt_spec *bus, bool enable);
309 :
310 : /**
311 : * @brief Function to enable or disable the debug accessory mode.
312 : *
313 : * @param bus I2C bus
314 : * @param enable Boolean flag to enable (true) or disable (false) debug accessory mode
315 : * @return int Status of I2C operation, 0 in case of success
316 : */
317 1 : int tcpci_tcpm_set_debug_accessory(const struct i2c_dt_spec *bus, bool enable);
318 :
319 : /**
320 : * @brief Function to enable or disable the low power mode.
321 : *
322 : * @param bus I2C bus
323 : * @param enable Boolean flag to enable (true) or disable (false) low power mode
324 : * @return int Status of I2C operation, 0 in case of success
325 : */
326 1 : int tcpci_tcpm_set_low_power_mode(const struct i2c_dt_spec *bus, bool enable);
327 :
328 : #endif /* ZEPHYR_INCLUDE_DRIVERS_USBC_TCPCI_PRIV_H_ */
|
