Zephyr Project API 4.1.99
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
182
186#define SBS_GAUGE_MANUFACTURER_NAME_MAX_SIZE 20
187#define SBS_GAUGE_DEVICE_NAME_MAX_SIZE 20
188#define SBS_GAUGE_DEVICE_CHEMISTRY_MAX_SIZE 4
189
194
199
204
211typedef int (*fuel_gauge_get_property_t)(const struct device *dev, fuel_gauge_prop_t prop,
212 union fuel_gauge_prop_val *val);
213
220typedef int (*fuel_gauge_set_property_t)(const struct device *dev, fuel_gauge_prop_t prop,
221 union fuel_gauge_prop_val val);
222
229typedef int (*fuel_gauge_get_buffer_property_t)(const struct device *dev,
230 fuel_gauge_prop_t prop_type,
231 void *dst, size_t dst_len);
232
239typedef int (*fuel_gauge_battery_cutoff_t)(const struct device *dev);
240
241/* Caching is entirely on the onus of the client */
242
255
265__syscall int fuel_gauge_get_prop(const struct device *dev, fuel_gauge_prop_t prop,
266 union fuel_gauge_prop_val *val);
267
268static inline int z_impl_fuel_gauge_get_prop(const struct device *dev, fuel_gauge_prop_t prop,
269 union fuel_gauge_prop_val *val)
270{
271 const struct fuel_gauge_driver_api *api = (const struct fuel_gauge_driver_api *)dev->api;
272
273 if (api->get_property == NULL) {
274 return -ENOSYS;
275 }
276
277 return api->get_property(dev, prop, val);
278}
279
295__syscall int fuel_gauge_get_props(const struct device *dev, const fuel_gauge_prop_t *props,
296 union fuel_gauge_prop_val *vals, size_t len);
297static inline int z_impl_fuel_gauge_get_props(const struct device *dev,
298 const fuel_gauge_prop_t *props,
299 union fuel_gauge_prop_val *vals, size_t len)
300{
301 const struct fuel_gauge_driver_api *api = (const struct fuel_gauge_driver_api *)dev->api;
302
303 for (size_t i = 0; i < len; i++) {
304 int ret = api->get_property(dev, props[i], vals + i);
305
306 if (ret) {
307 return ret;
308 }
309 }
310
311 return 0;
312}
313
323__syscall int fuel_gauge_set_prop(const struct device *dev, fuel_gauge_prop_t prop,
324 union fuel_gauge_prop_val val);
325
326static inline int z_impl_fuel_gauge_set_prop(const struct device *dev, fuel_gauge_prop_t prop,
327 union fuel_gauge_prop_val val)
328{
329 const struct fuel_gauge_driver_api *api = (const struct fuel_gauge_driver_api *)dev->api;
330
331 if (api->set_property == NULL) {
332 return -ENOSYS;
333 }
334
335 return api->set_property(dev, prop, val);
336}
349__syscall int fuel_gauge_set_props(const struct device *dev, const fuel_gauge_prop_t *props,
350 const union fuel_gauge_prop_val *vals, size_t len);
351
352static inline int z_impl_fuel_gauge_set_props(const struct device *dev,
353 const fuel_gauge_prop_t *props,
354 const union fuel_gauge_prop_val *vals, size_t len)
355{
356 for (size_t i = 0; i < len; i++) {
357 int ret = fuel_gauge_set_prop(dev, props[i], vals[i]);
358
359 if (ret) {
360 return ret;
361 }
362 }
363
364 return 0;
365}
366
378__syscall int fuel_gauge_get_buffer_prop(const struct device *dev, fuel_gauge_prop_t prop_type,
379 void *dst, size_t dst_len);
380
381static inline int z_impl_fuel_gauge_get_buffer_prop(const struct device *dev,
382 fuel_gauge_prop_t prop_type,
383 void *dst, size_t dst_len)
384{
385 const struct fuel_gauge_driver_api *api = (const struct fuel_gauge_driver_api *)dev->api;
386
387 if (api->get_buffer_property == NULL) {
388 return -ENOSYS;
389 }
390
391 return api->get_buffer_property(dev, prop_type, dst, dst_len);
392}
393
402__syscall int fuel_gauge_battery_cutoff(const struct device *dev);
403
404static inline int z_impl_fuel_gauge_battery_cutoff(const struct device *dev)
405{
406 const struct fuel_gauge_driver_api *api = (const struct fuel_gauge_driver_api *)dev->api;
407
408 if (api->battery_cutoff == NULL) {
409 return -ENOSYS;
410 }
411
412 return api->battery_cutoff(dev);
413}
414
419#ifdef __cplusplus
420}
421#endif /* __cplusplus */
422
423#include <zephyr/syscalls/fuel_gauge.h>
424
425#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:220
int(* fuel_gauge_battery_cutoff_t)(const struct device *dev)
Callback API for doing a battery cutoff.
Definition fuel_gauge.h:239
#define SBS_GAUGE_DEVICE_NAME_MAX_SIZE
Definition fuel_gauge.h:187
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:229
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:211
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:186
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_set_props(const struct device *dev, const fuel_gauge_prop_t *props, const union fuel_gauge_prop_val *vals, size_t len)
Set a battery fuel-gauge property.
fuel_gauge_prop_type
Definition fuel_gauge.h:31
int fuel_gauge_get_props(const struct device *dev, const fuel_gauge_prop_t *props, union fuel_gauge_prop_val *vals, size_t len)
Fetch multiple battery fuel-gauge properties.
#define SBS_GAUGE_DEVICE_CHEMISTRY_MAX_SIZE
Definition fuel_gauge.h:188
@ 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
#define NULL
Definition iar_missing_defs.h:20
__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:504
const void * api
Address of the API structure exposed by the device instance.
Definition device.h:510
Definition fuel_gauge.h:243
fuel_gauge_battery_cutoff_t battery_cutoff
Definition fuel_gauge.h:253
fuel_gauge_set_property_t set_property
Definition fuel_gauge.h:251
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:250
fuel_gauge_get_buffer_property_t get_buffer_property
Definition fuel_gauge.h:252
Definition fuel_gauge.h:200
char device_chemistry[4]
Definition fuel_gauge.h:202
uint8_t device_chemistry_length
Definition fuel_gauge.h:201
Definition fuel_gauge.h:195
uint8_t device_name_length
Definition fuel_gauge.h:196
char device_name[20]
Definition fuel_gauge.h:197
Definition fuel_gauge.h:190
uint8_t manufacturer_name_length
Definition fuel_gauge.h:191
char manufacturer_name[20]
Definition fuel_gauge.h:192
Property field to value/type union.
Definition fuel_gauge.h:119
uint16_t design_volt
FUEL_GAUGE_DESIGN_VOLTAGE.
Definition fuel_gauge.h:168
uint16_t design_cap
FUEL_GAUGE_DESIGN_CAPACITY.
Definition fuel_gauge.h:166
uint32_t runtime_to_full
FUEL_GAUGE_RUNTIME_TO_FULL.
Definition fuel_gauge.h:146
uint8_t absolute_state_of_charge
FUEL_GAUGE_ABSOLUTE_STATE_OF_CHARGE.
Definition fuel_gauge.h:150
uint16_t temperature
FUEL_GAUGE_TEMPERATURE.
Definition fuel_gauge.h:154
uint8_t relative_state_of_charge
FUEL_GAUGE_RELATIVE_STATE_OF_CHARGE.
Definition fuel_gauge.h:152
bool present_state
FUEL_GAUGE_PRESENT_STATE.
Definition fuel_gauge.h:140
uint16_t fg_status
FUEL_GAUGE_STATUS.
Definition fuel_gauge.h:164
uint32_t chg_current
FUEL_GAUGE_CHARGE_CURRENT.
Definition fuel_gauge.h:160
uint16_t sbs_at_rate_time_to_empty
FUEL_GAUGE_SBS_ATRATE_TIME_TO_EMPTY
Definition fuel_gauge.h:174
uint16_t sbs_mode
FUEL_GAUGE_SBS_MODE.
Definition fuel_gauge.h:158
uint16_t sbs_remaining_capacity_alarm
FUEL_GAUGE_SBS_REMAINING_CAPACITY_ALARM.
Definition fuel_gauge.h:178
uint32_t chg_voltage
FUEL_GAUGE_CHARGE_VOLTAGE.
Definition fuel_gauge.h:162
uint16_t sbs_mfr_access_word
FUEL_GAUGE_SBS_MFR_ACCESS.
Definition fuel_gauge.h:148
bool sbs_at_rate_ok
FUEL_GAUGE_SBS_ATRATE_OK.
Definition fuel_gauge.h:176
int current
FUEL_GAUGE_CURRENT.
Definition fuel_gauge.h:130
uint32_t connect_state
FUEL_GAUGE_CONNECT_STATE.
Definition fuel_gauge.h:134
uint16_t sbs_remaining_time_alarm
FUEL_GAUGE_SBS_REMAINING_TIME_ALARM.
Definition fuel_gauge.h:180
uint32_t full_charge_capacity
FUEL_GAUGE_FULL_CHARGE_CAPACITY.
Definition fuel_gauge.h:138
int16_t sbs_at_rate
FUEL_GAUGE_SBS_ATRATE.
Definition fuel_gauge.h:170
int voltage
FUEL_GAUGE_VOLTAGE.
Definition fuel_gauge.h:156
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:136
uint32_t remaining_capacity
FUEL_GAUGE_REMAINING_CAPACITY.
Definition fuel_gauge.h:142
uint32_t runtime_to_empty
FUEL_GAUGE_RUNTIME_TO_EMPTY.
Definition fuel_gauge.h:144
uint16_t sbs_at_rate_time_to_full
FUEL_GAUGE_SBS_ATRATE_TIME_TO_FULL.
Definition fuel_gauge.h:172