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