Line data Source code
1 1 : /*
2 : * Copyright 2023 Cirrus Logic, Inc.
3 : *
4 : * SPDX-License-Identifier: Apache-2.0
5 : */
6 :
7 : /**
8 : * @file
9 : * @brief Charger APIs
10 : */
11 :
12 : #ifndef ZEPHYR_INCLUDE_DRIVERS_CHARGER_H_
13 : #define ZEPHYR_INCLUDE_DRIVERS_CHARGER_H_
14 :
15 : /**
16 : * @brief Charger Interface
17 : * @defgroup charger_interface Charger Interface
18 : * @ingroup io_interfaces
19 : * @{
20 : */
21 :
22 : #include <stdbool.h>
23 : #include <stddef.h>
24 : #include <stdint.h>
25 :
26 : #include <zephyr/device.h>
27 :
28 : #ifdef __cplusplus
29 : extern "C" {
30 : #endif /* __cplusplus */
31 :
32 : /**
33 : * @brief Runtime Dynamic Battery Parameters
34 : */
35 1 : enum charger_property {
36 : /** Indicates if external supply is present for the charger. */
37 : /** Value should be of type enum charger_online */
38 : CHARGER_PROP_ONLINE = 0,
39 : /** Reports whether or not a battery is present. */
40 : /** Value should be of type bool*/
41 : CHARGER_PROP_PRESENT,
42 : /** Represents the charging status of the charger. */
43 : /** Value should be of type enum charger_status */
44 : CHARGER_PROP_STATUS,
45 : /** Represents the charging algo type of the charger. */
46 : /** Value should be of type enum charger_charge_type */
47 : CHARGER_PROP_CHARGE_TYPE,
48 : /** Represents the health of the charger. */
49 : /** Value should be of type enum charger_health */
50 : CHARGER_PROP_HEALTH,
51 : /** Configuration of current sink used for charging in µA */
52 : CHARGER_PROP_CONSTANT_CHARGE_CURRENT_UA,
53 : /** Configuration of current sink used for conditioning in µA */
54 : CHARGER_PROP_PRECHARGE_CURRENT_UA,
55 : /** Configuration of charge termination target in µA */
56 : CHARGER_PROP_CHARGE_TERM_CURRENT_UA,
57 : /** Configuration of charge voltage regulation target in µV */
58 : CHARGER_PROP_CONSTANT_CHARGE_VOLTAGE_UV,
59 : /**
60 : * Configuration of the input current regulation target in µA
61 : *
62 : * This value is a rising current threshold that is regulated by reducing the charge
63 : * current output
64 : */
65 : CHARGER_PROP_INPUT_REGULATION_CURRENT_UA,
66 : /**
67 : * Configuration of the input voltage regulation target in µV
68 : *
69 : * This value is a falling voltage threshold that is regulated by reducing the charge
70 : * current output
71 : */
72 : CHARGER_PROP_INPUT_REGULATION_VOLTAGE_UV,
73 : /**
74 : * Configuration to issue a notification to the system based on the input current
75 : * level and timing
76 : *
77 : * Value should be of type struct charger_current_notifier
78 : */
79 : CHARGER_PROP_INPUT_CURRENT_NOTIFICATION,
80 : /**
81 : * Configuration to issue a notification to the system based on the battery discharge
82 : * current level and timing
83 : *
84 : * Value should be of type struct charger_current_notifier
85 : */
86 : CHARGER_PROP_DISCHARGE_CURRENT_NOTIFICATION,
87 : /**
88 : * Configuration of the falling system voltage threshold where a notification
89 : * is issued to the system, measured in µV
90 : */
91 : CHARGER_PROP_SYSTEM_VOLTAGE_NOTIFICATION_UV,
92 : /**
93 : * Configuration to issue a notification to the system based on the charger status change
94 : *
95 : * Value should be of type charger_status_notifier_t
96 : */
97 : CHARGER_PROP_STATUS_NOTIFICATION,
98 : /**
99 : * Configuration to issue a notification to the system based on the charger online change
100 : *
101 : * Value should be of type charger_online_notifier_t
102 : */
103 : CHARGER_PROP_ONLINE_NOTIFICATION,
104 : /** Reserved to demark end of common charger properties */
105 : CHARGER_PROP_COMMON_COUNT,
106 : /**
107 : * Reserved to demark downstream custom properties - use this value as the actual value may
108 : * change over future versions of this API
109 : */
110 : CHARGER_PROP_CUSTOM_BEGIN = CHARGER_PROP_COMMON_COUNT + 1,
111 : /** Reserved to demark end of valid enum properties */
112 : CHARGER_PROP_MAX = UINT16_MAX,
113 : };
114 :
115 : /**
116 : * @typedef charger_prop_t
117 : * @brief A charger property's identifier
118 : *
119 : * See charger_property for a list of identifiers
120 : */
121 1 : typedef uint16_t charger_prop_t;
122 :
123 : /**
124 : * @brief External supply states
125 : */
126 1 : enum charger_online {
127 : /** External supply not present */
128 : CHARGER_ONLINE_OFFLINE = 0,
129 : /** External supply is present and of fixed output */
130 : CHARGER_ONLINE_FIXED,
131 : /** External supply is present and of programmable output*/
132 : CHARGER_ONLINE_PROGRAMMABLE,
133 : };
134 :
135 : /**
136 : * @brief Charging states
137 : */
138 1 : enum charger_status {
139 : /** Charging device state is unknown */
140 : CHARGER_STATUS_UNKNOWN = 0,
141 : /** Charging device is charging a battery */
142 : CHARGER_STATUS_CHARGING,
143 : /** Charging device is not able to charge a battery */
144 : CHARGER_STATUS_DISCHARGING,
145 : /** Charging device is not charging a battery */
146 : CHARGER_STATUS_NOT_CHARGING,
147 : /** The battery is full and the charging device will not attempt charging */
148 : CHARGER_STATUS_FULL,
149 : };
150 :
151 : /**
152 : * @brief Charge algorithm types
153 : */
154 0 : enum charger_charge_type {
155 : /** Charge type is unknown */
156 : CHARGER_CHARGE_TYPE_UNKNOWN = 0,
157 : /** Charging is not occurring */
158 : CHARGER_CHARGE_TYPE_NONE,
159 : /**
160 : * Charging is occurring at the slowest desired charge rate,
161 : * typically for battery detection or preconditioning
162 : */
163 : CHARGER_CHARGE_TYPE_TRICKLE,
164 : /** Charging is occurring at the fastest desired charge rate */
165 : CHARGER_CHARGE_TYPE_FAST,
166 : /** Charging is occurring at a moderate charge rate */
167 : CHARGER_CHARGE_TYPE_STANDARD,
168 : /*
169 : * Charging is being dynamically adjusted by the charger device
170 : */
171 : CHARGER_CHARGE_TYPE_ADAPTIVE,
172 : /*
173 : * Charging is occurring at a reduced charge rate to preserve
174 : * battery health
175 : */
176 : CHARGER_CHARGE_TYPE_LONGLIFE,
177 : /*
178 : * The charger device is being bypassed and the power conversion
179 : * is being handled externally, typically by a "smart" wall adaptor
180 : */
181 : CHARGER_CHARGE_TYPE_BYPASS,
182 : };
183 :
184 : /**
185 : * @brief Charger health conditions
186 : *
187 : * These conditions determine the ability to, or the rate of, charge
188 : */
189 1 : enum charger_health {
190 : /** Charger health condition is unknown */
191 : CHARGER_HEALTH_UNKNOWN = 0,
192 : /** Charger health condition is good */
193 : CHARGER_HEALTH_GOOD,
194 : /** The charger device is overheated */
195 : CHARGER_HEALTH_OVERHEAT,
196 : /** The battery voltage has exceeded its overvoltage threshold */
197 : CHARGER_HEALTH_OVERVOLTAGE,
198 : /**
199 : * The battery or charger device is experiencing an unspecified
200 : * failure.
201 : */
202 : CHARGER_HEALTH_UNSPEC_FAILURE,
203 : /** The battery temperature is below the "cold" threshold */
204 : CHARGER_HEALTH_COLD,
205 : /** The charger device's watchdog timer has expired */
206 : CHARGER_HEALTH_WATCHDOG_TIMER_EXPIRE,
207 : /** The charger device's safety timer has expired */
208 : CHARGER_HEALTH_SAFETY_TIMER_EXPIRE,
209 : /** The charger device requires calibration */
210 : CHARGER_HEALTH_CALIBRATION_REQUIRED,
211 : /** The battery temperature is in the "warm" range */
212 : CHARGER_HEALTH_WARM,
213 : /** The battery temperature is in the "cool" range */
214 : CHARGER_HEALTH_COOL,
215 : /** The battery temperature is below the "hot" threshold */
216 : CHARGER_HEALTH_HOT,
217 : /** The charger device does not detect a battery */
218 : CHARGER_HEALTH_NO_BATTERY,
219 : };
220 :
221 : /**
222 : * @brief Charger severity levels for system notifications
223 : */
224 1 : enum charger_notification_severity {
225 : /** Most severe level, typically triggered instantaneously */
226 : CHARGER_SEVERITY_PEAK = 0,
227 : /** More severe than the warning level, less severe than peak */
228 : CHARGER_SEVERITY_CRITICAL,
229 : /** Base severity level */
230 : CHARGER_SEVERITY_WARNING,
231 : };
232 :
233 : /**
234 : * @brief The input current thresholds for the charger to notify the system
235 : */
236 1 : struct charger_current_notifier {
237 : /** The severity of the notification where CHARGER_SEVERITY_PEAK is the most severe */
238 1 : uint8_t severity;
239 : /** The current threshold to be exceeded */
240 1 : uint32_t current_ua;
241 : /** The duration of excess current before notifying the system */
242 1 : uint32_t duration_us;
243 : };
244 :
245 : /**
246 : * @brief The charger status change callback to notify the system
247 : *
248 : * @param status Current charging state
249 : */
250 1 : typedef void (*charger_status_notifier_t)(enum charger_status status);
251 :
252 : /**
253 : * @brief The charger online change callback to notify the system
254 : *
255 : * @param online Current external supply state
256 : */
257 1 : typedef void (*charger_online_notifier_t)(enum charger_online online);
258 :
259 : /**
260 : * @brief container for a charger_property value
261 : *
262 : */
263 1 : union charger_propval {
264 : /* Fields have the format: */
265 : /* CHARGER_PROPERTY_FIELD */
266 : /* type property_field; */
267 :
268 : /** CHARGER_PROP_ONLINE */
269 1 : enum charger_online online;
270 : /** CHARGER_PROP_PRESENT */
271 1 : bool present;
272 : /** CHARGER_PROP_STATUS */
273 1 : enum charger_status status;
274 : /** CHARGER_PROP_CHARGE_TYPE */
275 1 : enum charger_charge_type charge_type;
276 : /** CHARGER_PROP_HEALTH */
277 1 : enum charger_health health;
278 : /** CHARGER_PROP_CONSTANT_CHARGE_CURRENT_UA */
279 1 : uint32_t const_charge_current_ua;
280 : /** CHARGER_PROP_PRECHARGE_CURRENT_UA */
281 1 : uint32_t precharge_current_ua;
282 : /** CHARGER_PROP_CHARGE_TERM_CURRENT_UA */
283 1 : uint32_t charge_term_current_ua;
284 : /** CHARGER_PROP_CONSTANT_CHARGE_VOLTAGE_UV */
285 1 : uint32_t const_charge_voltage_uv;
286 : /** CHARGER_PROP_INPUT_REGULATION_CURRENT_UA */
287 1 : uint32_t input_current_regulation_current_ua;
288 : /** CHARGER_PROP_INPUT_REGULATION_VOLTAGE_UV */
289 1 : uint32_t input_voltage_regulation_voltage_uv;
290 : /** CHARGER_PROP_INPUT_CURRENT_NOTIFICATION */
291 1 : struct charger_current_notifier input_current_notification;
292 : /** CHARGER_PROP_DISCHARGE_CURRENT_NOTIFICATION */
293 1 : struct charger_current_notifier discharge_current_notification;
294 : /** CHARGER_PROP_SYSTEM_VOLTAGE_NOTIFICATION_UV */
295 1 : uint32_t system_voltage_notification;
296 : /** CHARGER_PROP_STATUS_NOTIFICATION */
297 1 : charger_status_notifier_t status_notification;
298 : /** CHARGER_PROP_ONLINE_NOTIFICATION */
299 1 : charger_online_notifier_t online_notification;
300 : };
301 :
302 : /**
303 : * @typedef charger_get_property_t
304 : * @brief Callback API for getting a charger property.
305 : *
306 : * See charger_get_property() for argument description
307 : */
308 1 : typedef int (*charger_get_property_t)(const struct device *dev, const charger_prop_t prop,
309 : union charger_propval *val);
310 :
311 : /**
312 : * @typedef charger_set_property_t
313 : * @brief Callback API for setting a charger property.
314 : *
315 : * See charger_set_property() for argument description
316 : */
317 1 : typedef int (*charger_set_property_t)(const struct device *dev, const charger_prop_t prop,
318 : const union charger_propval *val);
319 :
320 : /**
321 : * @typedef charger_charge_enable_t
322 : * @brief Callback API enabling or disabling a charge cycle.
323 : *
324 : * See charger_charge_enable() for argument description
325 : */
326 1 : typedef int (*charger_charge_enable_t)(const struct device *dev, const bool enable);
327 :
328 : /**
329 : * @brief Charging device API
330 : *
331 : * Caching is entirely on the onus of the client
332 : */
333 1 : __subsystem struct charger_driver_api {
334 0 : charger_get_property_t get_property;
335 0 : charger_set_property_t set_property;
336 0 : charger_charge_enable_t charge_enable;
337 : };
338 :
339 : /**
340 : * @brief Fetch a battery charger property
341 : *
342 : * @param dev Pointer to the battery charger device
343 : * @param prop Charger property to get
344 : * @param val Pointer to charger_propval union
345 : *
346 : * @retval 0 if successful
347 : * @retval < 0 if getting property failed
348 : */
349 1 : __syscall int charger_get_prop(const struct device *dev, const charger_prop_t prop,
350 : union charger_propval *val);
351 :
352 : static inline int z_impl_charger_get_prop(const struct device *dev, const charger_prop_t prop,
353 : union charger_propval *val)
354 : {
355 : const struct charger_driver_api *api = (const struct charger_driver_api *)dev->api;
356 :
357 : return api->get_property(dev, prop, val);
358 : }
359 :
360 : /**
361 : * @brief Set a battery charger property
362 : *
363 : * @param dev Pointer to the battery charger device
364 : * @param prop Charger property to set
365 : * @param val Pointer to charger_propval union
366 : *
367 : * @retval 0 if successful
368 : * @retval < 0 if setting property failed
369 : */
370 1 : __syscall int charger_set_prop(const struct device *dev, const charger_prop_t prop,
371 : const union charger_propval *val);
372 :
373 : static inline int z_impl_charger_set_prop(const struct device *dev, const charger_prop_t prop,
374 : const union charger_propval *val)
375 : {
376 : const struct charger_driver_api *api = (const struct charger_driver_api *)dev->api;
377 :
378 : return api->set_property(dev, prop, val);
379 : }
380 :
381 : /**
382 : * @brief Enable or disable a charge cycle
383 : *
384 : * @param dev Pointer to the battery charger device
385 : * @param enable true enables a charge cycle, false disables a charge cycle
386 : *
387 : * @retval 0 if successful
388 : * @retval -EIO if communication with the charger failed
389 : * @retval -EINVAL if the conditions for initiating charging are invalid
390 : */
391 1 : __syscall int charger_charge_enable(const struct device *dev, const bool enable);
392 :
393 : static inline int z_impl_charger_charge_enable(const struct device *dev, const bool enable)
394 : {
395 : const struct charger_driver_api *api = (const struct charger_driver_api *)dev->api;
396 :
397 : return api->charge_enable(dev, enable);
398 : }
399 :
400 : /**
401 : * @}
402 : */
403 :
404 : #ifdef __cplusplus
405 : }
406 : #endif /* __cplusplus */
407 :
408 : #include <zephyr/syscalls/charger.h>
409 :
410 : #endif /* ZEPHYR_INCLUDE_DRIVERS_CHARGER_H_ */
|
