Line data Source code
1 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 1 : #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 determining 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 1 : #define BC12_CHARGER_MIN_CURR_UA 2500
49 : /** BC1.2 USB charger maximum current. */
50 1 : #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 0 : enum bc12_role {
66 : BC12_DISCONNECTED,
67 : BC12_PORTABLE_DEVICE,
68 : BC12_CHARGING_PORT,
69 : };
70 :
71 : /** @brief BC1.2 charging partner type. */
72 1 : 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 1 : struct bc12_partner_state {
102 0 : enum bc12_role bc12_role;
103 : union {
104 : struct {
105 0 : enum bc12_type type;
106 0 : int current_ua;
107 0 : int voltage_uv;
108 : };
109 : struct {
110 0 : bool pd_partner_connected;
111 : };
112 0 : };
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 1 : 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 1 : __syscall int bc12_set_role(const struct device *dev, enum bc12_role role);
151 :
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 1 : __syscall int bc12_set_result_cb(const struct device *dev, bc12_callback_t cb, void *user_data);
170 :
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 <zephyr/syscalls/usb_bc12.h>
188 :
189 : #endif /* ZEPHYR_INCLUDE_DRIVERS_USB_USB_BC12_H_ */
|
