1 /*
2 * Copyright (c) 2022 Google LLC
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 */
6
7 /**
8 * @file
9 * @brief Public APIs for the USB BC1.2 battery charging detect drivers.
10 */
11
12 #ifndef ZEPHYR_INCLUDE_DRIVERS_USB_USB_BC12_H_
13 #define ZEPHYR_INCLUDE_DRIVERS_USB_USB_BC12_H_
14
15 #include <zephyr/device.h>
16
17 #ifdef __cplusplus
18 extern "C" {
19 #endif
20
21 /**
22 * @brief BC1.2 driver APIs
23 * @defgroup b12_interface BC1.2 driver APIs
24 * @ingroup io_interfaces
25 * @{
26 */
27
28 /* FIXME - make these Kconfig options */
29
30 /**
31 * @name BC1.2 constants
32 * @{
33 */
34
35 /** BC1.2 USB charger voltage. */
36 #define BC12_CHARGER_VOLTAGE_UV 5000 * 1000
37 /**
38 * BC1.2 USB charger minimum current. Set to match the Isusp of 2.5 mA parameter.
39 * This is returned by the driver when either BC1.2 detection fails, or the
40 * attached partner is a SDP (standard downstream port).
41 *
42 * The application may increase the current draw after determing the USB device
43 * state of suspended/unconfigured/configured.
44 * Suspended: 2.5 mA
45 * Unconfigured: 100 mA
46 * Configured: 500 mA (USB 2.0)
47 */
48 #define BC12_CHARGER_MIN_CURR_UA 2500
49 /** BC1.2 USB charger maximum current. */
50 #define BC12_CHARGER_MAX_CURR_UA 1500 * 1000
51
52 /** @} */
53
54 /** @cond INTERNAL_HIDDEN
55 * @brief Helper macro for setting a BC1.2 current limit
56 *
57 * @param val Current limit value, in uA.
58 * @return A valid BC1.2 current limit, in uA, clamped between the BC1.2 minimum
59 * and maximum values.
60 */
61 #define BC12_CURR_UA(val) CLAMP(val, BC12_CHARGER_MIN_CURR_UA, BC12_CHARGER_MAX_CURR_UA)
62 /** @endcond */
63
64 /** @brief BC1.2 device role. */
65 enum bc12_role {
66 BC12_DISCONNECTED,
67 BC12_PORTABLE_DEVICE,
68 BC12_CHARGING_PORT,
69 };
70
71 /** @brief BC1.2 charging partner type. */
72 enum bc12_type {
73 /** No partner connected. */
74 BC12_TYPE_NONE,
75 /** Standard Downstream Port */
76 BC12_TYPE_SDP,
77 /** Dedicated Charging Port */
78 BC12_TYPE_DCP,
79 /** Charging Downstream Port */
80 BC12_TYPE_CDP,
81 /** Proprietary charging port */
82 BC12_TYPE_PROPRIETARY,
83 /** Unknown charging port, BC1.2 detection failed. */
84 BC12_TYPE_UNKNOWN,
85 /** Count of valid BC12 types. */
86 BC12_TYPE_COUNT,
87 };
88
89 /**
90 * @brief BC1.2 detected partner state.
91 *
92 * @param bc12_role Current role of the BC1.2 device.
93 * @param type Charging partner type. Valid when bc12_role is BC12_PORTABLE_DEVICE.
94 * @param current_ma Current, in uA, that the charging partner provides. Valid when bc12_role is
95 * BC12_PORTABLE_DEVICE.
96 * @param voltage_mv Voltage, in uV, that the charging partner provides. Valid when bc12_role is
97 * BC12_PORTABLE_DEVICE.
98 * @param pd_partner_connected True if a PD partner is currently connected. Valid when bc12_role is
99 * BC12_CHARGING_PORT.
100 */
101 struct bc12_partner_state {
102 enum bc12_role bc12_role;
103 union {
104 struct {
105 enum bc12_type type;
106 int current_ua;
107 int voltage_uv;
108 };
109 struct {
110 bool pd_partner_connected;
111 };
112 };
113 };
114
115 /**
116 * @brief BC1.2 callback for charger configuration
117 *
118 * @param dev BC1.2 device which is notifying of the new charger state.
119 * @param state Current state of the BC1.2 client, including BC1.2 type
120 * detected, voltage, and current limits.
121 * If NULL, then the partner charger is disconnected or the BC1.2 device is
122 * operating in host mode.
123 * @param user_data Requester supplied data which is passed along to the callback.
124 */
125 typedef void (*bc12_callback_t)(const struct device *dev, struct bc12_partner_state *state,
126 void *user_data);
127
128 /**
129 * @cond INTERNAL_HIDDEN
130 *
131 * These are for internal use only, so skip these in public documentation.
132 */
133 __subsystem struct bc12_driver_api {
134 int (*set_role)(const struct device *dev, enum bc12_role role);
135 int (*set_result_cb)(const struct device *dev, bc12_callback_t cb, void *user_data);
136 };
137 /**
138 * @endcond
139 */
140
141 /**
142 * @brief Set the BC1.2 role.
143 *
144 * @param dev Pointer to the device structure for the BC1.2 driver instance.
145 * @param role New role for the BC1.2 device.
146 *
147 * @retval 0 If successful.
148 * @retval -EIO general input/output error.
149 */
150 __syscall int bc12_set_role(const struct device *dev, enum bc12_role role);
151
z_impl_bc12_set_role(const struct device * dev,enum bc12_role role)152 static inline int z_impl_bc12_set_role(const struct device *dev, enum bc12_role role)
153 {
154 const struct bc12_driver_api *api = (const struct bc12_driver_api *)dev->api;
155
156 return api->set_role(dev, role);
157 }
158
159 /**
160 * @brief Register a callback for BC1.2 results.
161 *
162 * @param dev Pointer to the device structure for the BC1.2 driver instance.
163 * @param cb Function pointer for the result callback.
164 * @param user_data Requester supplied data which is passed along to the callback.
165 *
166 * @retval 0 If successful.
167 * @retval -EIO general input/output error.
168 */
169 __syscall int bc12_set_result_cb(const struct device *dev, bc12_callback_t cb, void *user_data);
170
z_impl_bc12_set_result_cb(const struct device * dev,bc12_callback_t cb,void * user_data)171 static inline int z_impl_bc12_set_result_cb(const struct device *dev, bc12_callback_t cb,
172 void *user_data)
173 {
174 const struct bc12_driver_api *api = (const struct bc12_driver_api *)dev->api;
175
176 return api->set_result_cb(dev, cb, user_data);
177 }
178
179 #ifdef __cplusplus
180 }
181 #endif
182
183 /**
184 * @}
185 */
186
187 #include <syscalls/usb_bc12.h>
188
189 #endif /* ZEPHYR_INCLUDE_DRIVERS_USB_USB_BC12_H_ */
190
