Zephyr Project API 3.7.0
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
fuel_gauge.h
Go to the documentation of this file.
1/*
2 * Copyright 2022 Google LLC
3 * Copyright 2023 Microsoft Corporation
4 *
5 * SPDX-License-Identifier: Apache-2.0
6 */
7
8#ifndef ZEPHYR_INCLUDE_DRIVERS_BATTERY_H_
9#define ZEPHYR_INCLUDE_DRIVERS_BATTERY_H_
10
20#ifdef __cplusplus
21extern "C" {
22#endif /* __cplusplus */
23
24#include <errno.h>
25#include <stdbool.h>
26#include <stddef.h>
27#include <stdint.h>
28
29#include <zephyr/device.h>
30
115
117
178
182#define SBS_GAUGE_MANUFACTURER_NAME_MAX_SIZE 20
183#define SBS_GAUGE_DEVICE_NAME_MAX_SIZE 20
184#define SBS_GAUGE_DEVICE_CHEMISTRY_MAX_SIZE 4
185
190
195
200
207typedef int (*fuel_gauge_get_property_t)(const struct device *dev, fuel_gauge_prop_t prop,
208 union fuel_gauge_prop_val *val);
209
216typedef int (*fuel_gauge_set_property_t)(const struct device *dev, fuel_gauge_prop_t prop,
217 union fuel_gauge_prop_val val);
218
225typedef int (*fuel_gauge_get_buffer_property_t)(const struct device *dev,
226 fuel_gauge_prop_t prop_type,
227 void *dst, size_t dst_len);
228
235typedef int (*fuel_gauge_battery_cutoff_t)(const struct device *dev);
236
237/* Caching is entirely on the onus of the client */
238
251
261__syscall int fuel_gauge_get_prop(const struct device *dev, fuel_gauge_prop_t prop,
262 union fuel_gauge_prop_val *val);
263
264static inline int z_impl_fuel_gauge_get_prop(const struct device *dev, fuel_gauge_prop_t prop,
265 union fuel_gauge_prop_val *val)
266{
267 const struct fuel_gauge_driver_api *api = (const struct fuel_gauge_driver_api *)dev->api;
268
269 if (api->get_property == NULL) {
270 return -ENOSYS;
271 }
272
273 return api->get_property(dev, prop, val);
274}
275
291__syscall int fuel_gauge_get_props(const struct device *dev, fuel_gauge_prop_t *props,
292 union fuel_gauge_prop_val *vals, size_t len);
293static inline int z_impl_fuel_gauge_get_props(const struct device *dev,
294 fuel_gauge_prop_t *props,
295 union fuel_gauge_prop_val *vals, size_t len)
296{
297 const struct fuel_gauge_driver_api *api = dev->api;
298
299 for (int i = 0; i < len; i++) {
300 int ret = api->get_property(dev, props[i], vals + i);
301
302 if (ret) {
303 return ret;
304 }
305 }
306
307 return 0;
308}
309
319__syscall int fuel_gauge_set_prop(const struct device *dev, fuel_gauge_prop_t prop,
320 union fuel_gauge_prop_val val);
321
322static inline int z_impl_fuel_gauge_set_prop(const struct device *dev, fuel_gauge_prop_t prop,
323 union fuel_gauge_prop_val val)
324{
325 const struct fuel_gauge_driver_api *api = dev->api;
326
327 if (api->set_property == NULL) {
328 return -ENOSYS;
329 }
330
331 return api->set_property(dev, prop, val);
332}
345__syscall int fuel_gauge_set_props(const struct device *dev, fuel_gauge_prop_t *props,
346 union fuel_gauge_prop_val *vals, size_t len);
347
348static inline int z_impl_fuel_gauge_set_props(const struct device *dev,
349 fuel_gauge_prop_t *props,
350 union fuel_gauge_prop_val *vals, size_t len)
351{
352 for (int i = 0; i < len; i++) {
353 int ret = fuel_gauge_set_prop(dev, props[i], vals[i]);
354
355 if (ret) {
356 return ret;
357 }
358 }
359
360 return 0;
361}
362
374__syscall int fuel_gauge_get_buffer_prop(const struct device *dev, fuel_gauge_prop_t prop_type,
375 void *dst, size_t dst_len);
376
377static inline int z_impl_fuel_gauge_get_buffer_prop(const struct device *dev,
378 fuel_gauge_prop_t prop_type,
379 void *dst, size_t dst_len)
380{
381 const struct fuel_gauge_driver_api *api = (const struct fuel_gauge_driver_api *)dev->api;
382
383 if (api->get_buffer_property == NULL) {
384 return -ENOSYS;
385 }
386
387 return api->get_buffer_property(dev, prop_type, dst, dst_len);
388}
389
398__syscall int fuel_gauge_battery_cutoff(const struct device *dev);
399
400static inline int z_impl_fuel_gauge_battery_cutoff(const struct device *dev)
401{
402 const struct fuel_gauge_driver_api *api = (const struct fuel_gauge_driver_api *)dev->api;
403
404 if (api->battery_cutoff == NULL) {
405 return -ENOSYS;
406 }
407
408 return api->battery_cutoff(dev);
409}
410
415#ifdef __cplusplus
416}
417#endif /* __cplusplus */
418
419#include <zephyr/syscalls/fuel_gauge.h>
420
421#endif /* ZEPHYR_INCLUDE_DRIVERS_BATTERY_H_ */
System error numbers.
int(* fuel_gauge_set_property_t)(const struct device *dev, fuel_gauge_prop_t prop, union fuel_gauge_prop_val val)
Callback API for setting a fuel_gauge property.
Definition fuel_gauge.h:216
int(* fuel_gauge_battery_cutoff_t)(const struct device *dev)
Callback API for doing a battery cutoff.
Definition fuel_gauge.h:235
#define SBS_GAUGE_DEVICE_NAME_MAX_SIZE
Definition fuel_gauge.h:183
int(* fuel_gauge_get_buffer_property_t)(const struct device *dev, fuel_gauge_prop_t prop_type, void *dst, size_t dst_len)
Callback API for getting a fuel_gauge buffer property.
Definition fuel_gauge.h:225
int fuel_gauge_set_props(const struct device *dev, fuel_gauge_prop_t *props, union fuel_gauge_prop_val *vals, size_t len)
Set a battery fuel-gauge property.
int(* fuel_gauge_get_property_t)(const struct device *dev, fuel_gauge_prop_t prop, union fuel_gauge_prop_val *val)
Callback API for getting a fuel_gauge property.
Definition fuel_gauge.h:207
uint16_t fuel_gauge_prop_t
Definition fuel_gauge.h:116
int fuel_gauge_battery_cutoff(const struct device *dev)
Have fuel gauge cutoff its associated battery.
int fuel_gauge_get_buffer_prop(const struct device *dev, fuel_gauge_prop_t prop_type, void *dst, size_t dst_len)
Fetch a battery fuel-gauge buffer property.
#define SBS_GAUGE_MANUFACTURER_NAME_MAX_SIZE
Data structures for reading SBS buffer properties.
Definition fuel_gauge.h:182
int fuel_gauge_set_prop(const struct device *dev, fuel_gauge_prop_t prop, union fuel_gauge_prop_val val)
Set a battery fuel-gauge property.
int fuel_gauge_get_prop(const struct device *dev, fuel_gauge_prop_t prop, union fuel_gauge_prop_val *val)
Fetch a battery fuel-gauge property.
int fuel_gauge_get_props(const struct device *dev, fuel_gauge_prop_t *props, union fuel_gauge_prop_val *vals, size_t len)
Fetch multiple battery fuel-gauge properties.
fuel_gauge_prop_type
Definition fuel_gauge.h:31
#define SBS_GAUGE_DEVICE_CHEMISTRY_MAX_SIZE
Definition fuel_gauge.h:184
@ FUEL_GAUGE_CURRENT
Battery current (uA); negative=discharging.
Definition fuel_gauge.h:44
@ FUEL_GAUGE_STATUS
Alarm, Status and Error codes (flags)
Definition fuel_gauge.h:80
@ FUEL_GAUGE_SBS_MFR_ACCESS
Retrieve word from SBS1.1 ManufactuerAccess.
Definition fuel_gauge.h:64
@ FUEL_GAUGE_CONNECT_STATE
Connect state of battery.
Definition fuel_gauge.h:50
@ FUEL_GAUGE_FLAGS
General Error/Runtime Flags.
Definition fuel_gauge.h:52
@ FUEL_GAUGE_CYCLE_COUNT
Cycle count in 1/100ths (number of charge/discharge cycles)
Definition fuel_gauge.h:48
@ FUEL_GAUGE_COMMON_COUNT
Reserved to demark end of common fuel gauge properties.
Definition fuel_gauge.h:105
@ FUEL_GAUGE_MANUFACTURER_NAME
Manufacturer of pack (1 byte length + 20 bytes data)
Definition fuel_gauge.h:98
@ FUEL_GAUGE_SBS_MODE
Battery Mode (flags)
Definition fuel_gauge.h:74
@ FUEL_GAUGE_SBS_ATRATE
AtRate (mA or 10 mW)
Definition fuel_gauge.h:86
@ FUEL_GAUGE_DESIGN_VOLTAGE
Design Voltage (mV)
Definition fuel_gauge.h:84
@ FUEL_GAUGE_AVG_CURRENT
Runtime Dynamic Battery Parameters.
Definition fuel_gauge.h:39
@ FUEL_GAUGE_RUNTIME_TO_FULL
Remaining time in minutes until battery reaches full charge.
Definition fuel_gauge.h:62
@ FUEL_GAUGE_CHARGE_CURRENT
Battery desired Max Charging Current (uA)
Definition fuel_gauge.h:76
@ FUEL_GAUGE_CUSTOM_BEGIN
Reserved to demark downstream custom properties - use this value as the actual value may change over ...
Definition fuel_gauge.h:110
@ FUEL_GAUGE_DEVICE_CHEMISTRY
Chemistry (1 byte length + 4 bytes data)
Definition fuel_gauge.h:102
@ FUEL_GAUGE_PROP_MAX
Reserved to demark end of valid enum properties.
Definition fuel_gauge.h:113
@ FUEL_GAUGE_SBS_ATRATE_TIME_TO_EMPTY
AtRateTimeToEmpty (minutes)
Definition fuel_gauge.h:90
@ FUEL_GAUGE_DESIGN_CAPACITY
Design Capacity (mAh or 10mWh)
Definition fuel_gauge.h:82
@ FUEL_GAUGE_VOLTAGE
Battery voltage (uV)
Definition fuel_gauge.h:72
@ FUEL_GAUGE_SBS_REMAINING_TIME_ALARM
Remaining Time Alarm (minutes)
Definition fuel_gauge.h:96
@ FUEL_GAUGE_CHARGE_CUTOFF
Whether the battery underlying the fuel-gauge is cut off from charge.
Definition fuel_gauge.h:46
@ FUEL_GAUGE_CHARGE_VOLTAGE
Battery desired Max Charging Voltage (uV)
Definition fuel_gauge.h:78
@ FUEL_GAUGE_ABSOLUTE_STATE_OF_CHARGE
Absolute state of charge (percent, 0-100) - expressed as % of design capacity.
Definition fuel_gauge.h:66
@ FUEL_GAUGE_DEVICE_NAME
Name of pack (1 byte length + 20 bytes data)
Definition fuel_gauge.h:100
@ FUEL_GAUGE_SBS_ATRATE_TIME_TO_FULL
AtRateTimeToFull (minutes)
Definition fuel_gauge.h:88
@ FUEL_GAUGE_TEMPERATURE
Temperature in 0.1 K.
Definition fuel_gauge.h:70
@ FUEL_GAUGE_FULL_CHARGE_CAPACITY
Full Charge Capacity in uAh (might change in some implementations to determine wear)
Definition fuel_gauge.h:54
@ FUEL_GAUGE_RUNTIME_TO_EMPTY
Remaining battery life time in minutes.
Definition fuel_gauge.h:60
@ FUEL_GAUGE_PRESENT_STATE
Is the battery physically present.
Definition fuel_gauge.h:56
@ FUEL_GAUGE_REMAINING_CAPACITY
Remaining capacity in uAh.
Definition fuel_gauge.h:58
@ FUEL_GAUGE_SBS_REMAINING_CAPACITY_ALARM
Remaining Capacity Alarm (mAh or 10mWh)
Definition fuel_gauge.h:94
@ FUEL_GAUGE_BATTERY_CUTOFF
Used to cutoff the battery from the system - useful for storage/shipping of devices.
Definition fuel_gauge.h:42
@ FUEL_GAUGE_RELATIVE_STATE_OF_CHARGE
Relative state of charge (percent, 0-100) - expressed as % of full charge capacity.
Definition fuel_gauge.h:68
@ FUEL_GAUGE_SBS_ATRATE_OK
AtRateOK (boolean)
Definition fuel_gauge.h:92
#define ENOSYS
Function not implemented.
Definition errno.h:82
static ZTEST_BMEM int ret
Definition main.c:16
__UINT32_TYPE__ uint32_t
Definition stdint.h:90
__UINT8_TYPE__ uint8_t
Definition stdint.h:88
#define UINT16_MAX
Definition stdint.h:28
__UINT16_TYPE__ uint16_t
Definition stdint.h:89
__INT16_TYPE__ int16_t
Definition stdint.h:73
Runtime device structure (in ROM) per driver instance.
Definition device.h:403
const void * api
Address of the API structure exposed by the device instance.
Definition device.h:409
Definition fuel_gauge.h:239
fuel_gauge_battery_cutoff_t battery_cutoff
Definition fuel_gauge.h:249
fuel_gauge_set_property_t set_property
Definition fuel_gauge.h:247
fuel_gauge_get_property_t get_property
Note: Historically this API allowed drivers to implement a custom multi-get/set property function,...
Definition fuel_gauge.h:246
fuel_gauge_get_buffer_property_t get_buffer_property
Definition fuel_gauge.h:248
Definition fuel_gauge.h:196
char device_chemistry[4]
Definition fuel_gauge.h:198
uint8_t device_chemistry_length
Definition fuel_gauge.h:197
Definition fuel_gauge.h:191
uint8_t device_name_length
Definition fuel_gauge.h:192
char device_name[20]
Definition fuel_gauge.h:193
Definition fuel_gauge.h:186
uint8_t manufacturer_name_length
Definition fuel_gauge.h:187
char manufacturer_name[20]
Definition fuel_gauge.h:188
Property field to value/type union.
Definition fuel_gauge.h:119
uint16_t design_volt
FUEL_GAUGE_DESIGN_VOLTAGE.
Definition fuel_gauge.h:164
uint16_t design_cap
FUEL_GAUGE_DESIGN_CAPACITY.
Definition fuel_gauge.h:162
uint32_t runtime_to_full
FUEL_GAUGE_RUNTIME_TO_FULL.
Definition fuel_gauge.h:142
uint8_t absolute_state_of_charge
FUEL_GAUGE_ABSOLUTE_STATE_OF_CHARGE.
Definition fuel_gauge.h:146
uint16_t temperature
FUEL_GAUGE_TEMPERATURE.
Definition fuel_gauge.h:150
uint8_t relative_state_of_charge
FUEL_GAUGE_RELATIVE_STATE_OF_CHARGE.
Definition fuel_gauge.h:148
uint16_t fg_status
FUEL_GAUGE_STATUS.
Definition fuel_gauge.h:160
uint32_t chg_current
FUEL_GAUGE_CHARGE_CURRENT.
Definition fuel_gauge.h:156
uint16_t sbs_at_rate_time_to_empty
FUEL_GAUGE_SBS_ATRATE_TIME_TO_EMPTY
Definition fuel_gauge.h:170
uint16_t sbs_mode
FUEL_GAUGE_SBS_MODE.
Definition fuel_gauge.h:154
uint16_t sbs_remaining_capacity_alarm
FUEL_GAUGE_SBS_REMAINING_CAPACITY_ALARM.
Definition fuel_gauge.h:174
uint32_t chg_voltage
FUEL_GAUGE_CHARGE_VOLTAGE.
Definition fuel_gauge.h:158
uint16_t sbs_mfr_access_word
FUEL_GAUGE_SBS_MFR_ACCESS.
Definition fuel_gauge.h:144
bool sbs_at_rate_ok
FUEL_GAUGE_SBS_ATRATE_OK.
Definition fuel_gauge.h:172
int current
FUEL_GAUGE_CURRENT.
Definition fuel_gauge.h:130
uint16_t sbs_remaining_time_alarm
FUEL_GAUGE_SBS_REMAINING_TIME_ALARM.
Definition fuel_gauge.h:176
uint32_t full_charge_capacity
FUEL_GAUGE_FULL_CHARGE_CAPACITY.
Definition fuel_gauge.h:136
int16_t sbs_at_rate
FUEL_GAUGE_SBS_ATRATE.
Definition fuel_gauge.h:166
int voltage
FUEL_GAUGE_VOLTAGE.
Definition fuel_gauge.h:152
uint32_t cycle_count
FUEL_GAUGE_CYCLE_COUNT.
Definition fuel_gauge.h:132
bool cutoff
FUEL_GAUGE_CHARGE_CUTOFF.
Definition fuel_gauge.h:128
int avg_current
FUEL_GAUGE_AVG_CURRENT.
Definition fuel_gauge.h:126
uint32_t flags
FUEL_GAUGE_FLAGS.
Definition fuel_gauge.h:134
uint32_t remaining_capacity
FUEL_GAUGE_REMAINING_CAPACITY.
Definition fuel_gauge.h:138
uint32_t runtime_to_empty
FUEL_GAUGE_RUNTIME_TO_EMPTY.
Definition fuel_gauge.h:140
uint16_t sbs_at_rate_time_to_full
FUEL_GAUGE_SBS_ATRATE_TIME_TO_FULL.
Definition fuel_gauge.h:168