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 : * @typedef charger_custom_value_int_t
125 : * @brief Type for custom signed integer property values.
126 : *
127 : * Used only by downstream custom properties (>= CHARGER_PROP_CUSTOM_BEGIN).
128 : */
129 1 : typedef int32_t charger_custom_value_int_t;
130 :
131 : /**
132 : * @typedef charger_custom_value_uint_t
133 : * @brief Type for custom unsigned integer property values.
134 : *
135 : * Used only by downstream custom properties (>= CHARGER_PROP_CUSTOM_BEGIN).
136 : */
137 1 : typedef uint32_t charger_custom_value_uint_t;
138 :
139 : /**
140 : * @typedef charger_custom_value_bool_t
141 : * @brief Type for custom boolean property values.
142 : *
143 : * Used only by downstream custom properties (>= CHARGER_PROP_CUSTOM_BEGIN),
144 : * typically for feature/status flags (e.g. jeita_active).
145 : */
146 1 : typedef bool charger_custom_value_bool_t;
147 :
148 : /**
149 : * @brief External supply states
150 : */
151 1 : enum charger_online {
152 : /** External supply not present */
153 : CHARGER_ONLINE_OFFLINE = 0,
154 : /** External supply is present and of fixed output */
155 : CHARGER_ONLINE_FIXED,
156 : /** External supply is present and of programmable output*/
157 : CHARGER_ONLINE_PROGRAMMABLE,
158 : };
159 :
160 : /**
161 : * @brief Charging states
162 : */
163 1 : enum charger_status {
164 : /** Charging device state is unknown */
165 : CHARGER_STATUS_UNKNOWN = 0,
166 : /** Charging device is charging a battery */
167 : CHARGER_STATUS_CHARGING,
168 : /** Charging device is not able to charge a battery */
169 : CHARGER_STATUS_DISCHARGING,
170 : /** Charging device is not charging a battery */
171 : CHARGER_STATUS_NOT_CHARGING,
172 : /** The battery is full and the charging device will not attempt charging */
173 : CHARGER_STATUS_FULL,
174 : };
175 :
176 : /**
177 : * @brief Charge algorithm types
178 : */
179 0 : enum charger_charge_type {
180 : /** Charge type is unknown */
181 : CHARGER_CHARGE_TYPE_UNKNOWN = 0,
182 : /** Charging is not occurring */
183 : CHARGER_CHARGE_TYPE_NONE,
184 : /**
185 : * Charging is occurring at the slowest desired charge rate,
186 : * typically for battery detection or preconditioning
187 : */
188 : CHARGER_CHARGE_TYPE_TRICKLE,
189 : /** Charging is occurring at the fastest desired charge rate */
190 : CHARGER_CHARGE_TYPE_FAST,
191 : /** Charging is occurring at a moderate charge rate */
192 : CHARGER_CHARGE_TYPE_STANDARD,
193 : /*
194 : * Charging is being dynamically adjusted by the charger device
195 : */
196 : CHARGER_CHARGE_TYPE_ADAPTIVE,
197 : /*
198 : * Charging is occurring at a reduced charge rate to preserve
199 : * battery health
200 : */
201 : CHARGER_CHARGE_TYPE_LONGLIFE,
202 : /*
203 : * The charger device is being bypassed and the power conversion
204 : * is being handled externally, typically by a "smart" wall adaptor
205 : */
206 : CHARGER_CHARGE_TYPE_BYPASS,
207 : };
208 :
209 : /**
210 : * @brief Charger health conditions
211 : *
212 : * These conditions determine the ability to, or the rate of, charge
213 : */
214 1 : enum charger_health {
215 : /** Charger health condition is unknown */
216 : CHARGER_HEALTH_UNKNOWN = 0,
217 : /** Charger health condition is good */
218 : CHARGER_HEALTH_GOOD,
219 : /** The charger device is overheated */
220 : CHARGER_HEALTH_OVERHEAT,
221 : /** The battery voltage has exceeded its overvoltage threshold */
222 : CHARGER_HEALTH_OVERVOLTAGE,
223 : /**
224 : * The battery or charger device is experiencing an unspecified
225 : * failure.
226 : */
227 : CHARGER_HEALTH_UNSPEC_FAILURE,
228 : /** The battery temperature is below the "cold" threshold */
229 : CHARGER_HEALTH_COLD,
230 : /** The charger device's watchdog timer has expired */
231 : CHARGER_HEALTH_WATCHDOG_TIMER_EXPIRE,
232 : /** The charger device's safety timer has expired */
233 : CHARGER_HEALTH_SAFETY_TIMER_EXPIRE,
234 : /** The charger device requires calibration */
235 : CHARGER_HEALTH_CALIBRATION_REQUIRED,
236 : /** The battery temperature is in the "warm" range */
237 : CHARGER_HEALTH_WARM,
238 : /** The battery temperature is in the "cool" range */
239 : CHARGER_HEALTH_COOL,
240 : /** The battery temperature is below the "hot" threshold */
241 : CHARGER_HEALTH_HOT,
242 : /** The charger device does not detect a battery */
243 : CHARGER_HEALTH_NO_BATTERY,
244 : };
245 :
246 : /**
247 : * @brief Charger severity levels for system notifications
248 : */
249 1 : enum charger_notification_severity {
250 : /** Most severe level, typically triggered instantaneously */
251 : CHARGER_SEVERITY_PEAK = 0,
252 : /** More severe than the warning level, less severe than peak */
253 : CHARGER_SEVERITY_CRITICAL,
254 : /** Base severity level */
255 : CHARGER_SEVERITY_WARNING,
256 : };
257 :
258 : /**
259 : * @brief The input current thresholds for the charger to notify the system
260 : */
261 1 : struct charger_current_notifier {
262 : /** The severity of the notification where CHARGER_SEVERITY_PEAK is the most severe */
263 1 : uint8_t severity;
264 : /** The current threshold to be exceeded */
265 1 : uint32_t current_ua;
266 : /** The duration of excess current before notifying the system */
267 1 : uint32_t duration_us;
268 : };
269 :
270 : /**
271 : * @brief The charger status change callback to notify the system
272 : *
273 : * @param status Current charging state
274 : */
275 1 : typedef void (*charger_status_notifier_t)(enum charger_status status);
276 :
277 : /**
278 : * @brief The charger online change callback to notify the system
279 : *
280 : * @param online Current external supply state
281 : */
282 1 : typedef void (*charger_online_notifier_t)(enum charger_online online);
283 :
284 : /**
285 : * @brief container for a charger_property value
286 : *
287 : */
288 1 : union charger_propval {
289 : /* Fields have the format: */
290 : /* CHARGER_PROPERTY_FIELD */
291 : /* type property_field; */
292 :
293 : /** CHARGER_PROP_ONLINE */
294 1 : enum charger_online online;
295 : /** CHARGER_PROP_PRESENT */
296 1 : bool present;
297 : /** CHARGER_PROP_STATUS */
298 1 : enum charger_status status;
299 : /** CHARGER_PROP_CHARGE_TYPE */
300 1 : enum charger_charge_type charge_type;
301 : /** CHARGER_PROP_HEALTH */
302 1 : enum charger_health health;
303 : /** CHARGER_PROP_CONSTANT_CHARGE_CURRENT_UA */
304 1 : uint32_t const_charge_current_ua;
305 : /** CHARGER_PROP_PRECHARGE_CURRENT_UA */
306 1 : uint32_t precharge_current_ua;
307 : /** CHARGER_PROP_CHARGE_TERM_CURRENT_UA */
308 1 : uint32_t charge_term_current_ua;
309 : /** CHARGER_PROP_CONSTANT_CHARGE_VOLTAGE_UV */
310 1 : uint32_t const_charge_voltage_uv;
311 : /** CHARGER_PROP_INPUT_REGULATION_CURRENT_UA */
312 1 : uint32_t input_current_regulation_current_ua;
313 : /** CHARGER_PROP_INPUT_REGULATION_VOLTAGE_UV */
314 1 : uint32_t input_voltage_regulation_voltage_uv;
315 : /** CHARGER_PROP_INPUT_CURRENT_NOTIFICATION */
316 1 : struct charger_current_notifier input_current_notification;
317 : /** CHARGER_PROP_DISCHARGE_CURRENT_NOTIFICATION */
318 1 : struct charger_current_notifier discharge_current_notification;
319 : /** CHARGER_PROP_SYSTEM_VOLTAGE_NOTIFICATION_UV */
320 1 : uint32_t system_voltage_notification;
321 : /** CHARGER_PROP_STATUS_NOTIFICATION */
322 1 : charger_status_notifier_t status_notification;
323 : /** CHARGER_PROP_ONLINE_NOTIFICATION */
324 1 : charger_online_notifier_t online_notification;
325 : /** Generic integer value for downstream custom properties */
326 1 : charger_custom_value_int_t custom_int;
327 : /** Generic unsigned value for downstream custom properties */
328 1 : charger_custom_value_uint_t custom_uint;
329 : /** Generic boolean value for downstream custom properties */
330 1 : charger_custom_value_bool_t custom_bool;
331 : };
332 :
333 : /**
334 : * @typedef charger_get_property_t
335 : * @brief Callback API for getting a charger property.
336 : *
337 : * See charger_get_property() for argument description
338 : */
339 1 : typedef int (*charger_get_property_t)(const struct device *dev, const charger_prop_t prop,
340 : union charger_propval *val);
341 :
342 : /**
343 : * @typedef charger_set_property_t
344 : * @brief Callback API for setting a charger property.
345 : *
346 : * See charger_set_property() for argument description
347 : */
348 1 : typedef int (*charger_set_property_t)(const struct device *dev, const charger_prop_t prop,
349 : const union charger_propval *val);
350 :
351 : /**
352 : * @typedef charger_charge_enable_t
353 : * @brief Callback API enabling or disabling a charge cycle.
354 : *
355 : * See charger_charge_enable() for argument description
356 : */
357 1 : typedef int (*charger_charge_enable_t)(const struct device *dev, const bool enable);
358 :
359 : /**
360 : * @brief Charging device API
361 : *
362 : * Caching is entirely on the onus of the client
363 : */
364 1 : __subsystem struct charger_driver_api {
365 0 : charger_get_property_t get_property;
366 0 : charger_set_property_t set_property;
367 0 : charger_charge_enable_t charge_enable;
368 : };
369 :
370 : /**
371 : * @brief Fetch a battery charger property
372 : *
373 : * @param dev Pointer to the battery charger device
374 : * @param prop Charger property to get
375 : * @param val Pointer to charger_propval union
376 : *
377 : * @retval 0 if successful
378 : * @retval < 0 if getting property failed
379 : */
380 1 : __syscall int charger_get_prop(const struct device *dev, const charger_prop_t prop,
381 : union charger_propval *val);
382 :
383 : static inline int z_impl_charger_get_prop(const struct device *dev, const charger_prop_t prop,
384 : union charger_propval *val)
385 : {
386 : const struct charger_driver_api *api = (const struct charger_driver_api *)dev->api;
387 :
388 : return api->get_property(dev, prop, val);
389 : }
390 :
391 : /**
392 : * @brief Set a battery charger property
393 : *
394 : * @param dev Pointer to the battery charger device
395 : * @param prop Charger property to set
396 : * @param val Pointer to charger_propval union
397 : *
398 : * @retval 0 if successful
399 : * @retval < 0 if setting property failed
400 : */
401 1 : __syscall int charger_set_prop(const struct device *dev, const charger_prop_t prop,
402 : const union charger_propval *val);
403 :
404 : static inline int z_impl_charger_set_prop(const struct device *dev, const charger_prop_t prop,
405 : const union charger_propval *val)
406 : {
407 : const struct charger_driver_api *api = (const struct charger_driver_api *)dev->api;
408 :
409 : return api->set_property(dev, prop, val);
410 : }
411 :
412 : /**
413 : * @brief Enable or disable a charge cycle
414 : *
415 : * @param dev Pointer to the battery charger device
416 : * @param enable true enables a charge cycle, false disables a charge cycle
417 : *
418 : * @retval 0 if successful
419 : * @retval -EIO if communication with the charger failed
420 : * @retval -EINVAL if the conditions for initiating charging are invalid
421 : */
422 1 : __syscall int charger_charge_enable(const struct device *dev, const bool enable);
423 :
424 : static inline int z_impl_charger_charge_enable(const struct device *dev, const bool enable)
425 : {
426 : const struct charger_driver_api *api = (const struct charger_driver_api *)dev->api;
427 :
428 : return api->charge_enable(dev, enable);
429 : }
430 :
431 : /**
432 : * @}
433 : */
434 :
435 : #ifdef __cplusplus
436 : }
437 : #endif /* __cplusplus */
438 :
439 : #include <zephyr/syscalls/charger.h>
440 :
441 : #endif /* ZEPHYR_INCLUDE_DRIVERS_CHARGER_H_ */
|
