fuel_gauge.h

Go to the documentation of this file.

/*
 * Copyright 2022 Google LLC
 * Copyright 2023 Microsoft Corporation
 *
 * SPDX-License-Identifier: Apache-2.0
 */
 
#ifndef ZEPHYR_INCLUDE_DRIVERS_BATTERY_H_
#define ZEPHYR_INCLUDE_DRIVERS_BATTERY_H_
 
#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */
 
#include <errno.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
 
#include <zephyr/device.h>
 
/* Keep these alphabetized wrt property name */
 
enum fuel_gauge_property {
        FUEL_GAUGE_AVG_CURRENT = 0,
 
        FUEL_GAUGE_CURRENT,
        FUEL_GAUGE_CHARGE_CUTOFF,
        FUEL_GAUGE_CYCLE_COUNT,
        FUEL_GAUGE_CONNECT_STATE,
        FUEL_GAUGE_FLAGS,
        FUEL_GAUGE_FULL_CHARGE_CAPACITY,
        FUEL_GAUGE_PRESENT_STATE,
        FUEL_GAUGE_REMAINING_CAPACITY,
        FUEL_GAUGE_RUNTIME_TO_EMPTY,
        FUEL_GAUGE_RUNTIME_TO_FULL,
        FUEL_GAUGE_SBS_MFR_ACCESS,
        FUEL_GAUGE_ABSOLUTE_STATE_OF_CHARGE,
        FUEL_GAUGE_RELATIVE_STATE_OF_CHARGE,
        FUEL_GAUGE_TEMPERATURE,
        FUEL_GAUGE_VOLTAGE,
        FUEL_GAUGE_SBS_MODE,
        FUEL_GAUGE_CHARGE_CURRENT,
        FUEL_GAUGE_CHARGE_VOLTAGE,
        FUEL_GAUGE_STATUS,
        FUEL_GAUGE_DESIGN_CAPACITY,
        FUEL_GAUGE_DESIGN_VOLTAGE,
        FUEL_GAUGE_SBS_ATRATE,
        FUEL_GAUGE_SBS_ATRATE_TIME_TO_FULL,
        FUEL_GAUGE_SBS_ATRATE_TIME_TO_EMPTY,
        FUEL_GAUGE_SBS_ATRATE_OK,
        FUEL_GAUGE_SBS_REMAINING_CAPACITY_ALARM,
        FUEL_GAUGE_SBS_REMAINING_TIME_ALARM,
        FUEL_GAUGE_MANUFACTURER_NAME,
        FUEL_GAUGE_DEVICE_NAME,
        FUEL_GAUGE_DEVICE_CHEMISTRY,
 
        FUEL_GAUGE_COMMON_COUNT,
        FUEL_GAUGE_CUSTOM_BEGIN,
 
        FUEL_GAUGE_PROP_MAX = UINT16_MAX,
};
 
typedef uint16_t fuel_gauge_prop_t;
 
struct fuel_gauge_get_property {
        fuel_gauge_prop_t property_type;
 
        int status;
 
        union {
                /* Fields have the format: */
                /* FUEL_GAUGE_PROPERTY_FIELD */
                /* type property_field; */
 
                /* Dynamic Battery Info */
                int avg_current;
                bool cutoff;
                int current;
                uint32_t cycle_count;
                uint32_t flags;
                uint32_t full_charge_capacity;
                uint32_t remaining_capacity;
                uint32_t runtime_to_empty;
                uint32_t runtime_to_full;
                uint16_t sbs_mfr_access_word;
                uint8_t absolute_state_of_charge;
                uint8_t relative_state_of_charge;
                uint16_t temperature;
                int voltage;
                uint16_t sbs_mode;
                uint16_t chg_current;
                uint16_t chg_voltage;
                uint16_t fg_status;
                uint16_t design_cap;
                uint16_t design_volt;
                int16_t sbs_at_rate;
                uint16_t sbs_at_rate_time_to_full;
                uint16_t sbs_at_rate_time_to_empty;
                bool sbs_at_rate_ok;
                uint16_t sbs_remaining_capacity_alarm;
                uint16_t sbs_remaining_time_alarm;
        } value;
};
 
struct fuel_gauge_set_property {
        fuel_gauge_prop_t property_type;
 
        int status;
 
        union {
                /* Fields have the format: */
                /* FUEL_GAUGE_PROPERTY_FIELD */
                /* type property_field; */
 
                /* Writable Dynamic Battery Info */
                uint16_t sbs_mfr_access_word;
                uint16_t sbs_remaining_capacity_alarm;
                uint16_t sbs_remaining_time_alarm;
                uint16_t sbs_mode;
                int16_t sbs_at_rate;
        } value;
};
 
struct fuel_gauge_get_buffer_property {
        fuel_gauge_prop_t property_type;
 
        int status;
};
 
#define SBS_GAUGE_MANUFACTURER_NAME_MAX_SIZE 20
#define SBS_GAUGE_DEVICE_NAME_MAX_SIZE       20
#define SBS_GAUGE_DEVICE_CHEMISTRY_MAX_SIZE  4
 
struct sbs_gauge_manufacturer_name {
        uint8_t manufacturer_name_length;
        char manufacturer_name[SBS_GAUGE_MANUFACTURER_NAME_MAX_SIZE];
} __packed;
 
struct sbs_gauge_device_name {
        uint8_t device_name_length;
        char device_name[SBS_GAUGE_DEVICE_NAME_MAX_SIZE];
} __packed;
 
struct sbs_gauge_device_chemistry {
        uint8_t device_chemistry_length;
        char device_chemistry[SBS_GAUGE_DEVICE_CHEMISTRY_MAX_SIZE];
} __packed;
 
typedef int (*fuel_gauge_get_property_t)(const struct device *dev,
                                         struct fuel_gauge_get_property *props, size_t props_len);
 
typedef int (*fuel_gauge_set_property_t)(const struct device *dev,
                                         struct fuel_gauge_set_property *props, size_t props_len);
 
typedef int (*fuel_gauge_get_buffer_property_t)(const struct device *dev,
                                               struct fuel_gauge_get_buffer_property *prop,
                                               void *dst, size_t dst_len);
 
 
/* Caching is entirely on the onus of the client */
 
__subsystem struct fuel_gauge_driver_api {
        fuel_gauge_get_property_t get_property;
        fuel_gauge_set_property_t set_property;
        fuel_gauge_get_buffer_property_t get_buffer_property;
};
 
__syscall int fuel_gauge_get_prop(const struct device *dev, struct fuel_gauge_get_property *props,
                                  size_t props_len);
 
static inline int z_impl_fuel_gauge_get_prop(const struct device *dev,
                                             struct fuel_gauge_get_property *props,
                                             size_t props_len)
{
        const struct fuel_gauge_driver_api *api = (const struct fuel_gauge_driver_api *)dev->api;
 
        if (api->get_property == NULL) {
                return -ENOSYS;
        }
 
        return api->get_property(dev, props, props_len);
}
 
__syscall int fuel_gauge_set_prop(const struct device *dev, struct fuel_gauge_set_property *props,
                                  size_t props_len);
 
static inline int z_impl_fuel_gauge_set_prop(const struct device *dev,
                                             struct fuel_gauge_set_property *props,
                                             size_t props_len)
{
        const struct fuel_gauge_driver_api *api = (const struct fuel_gauge_driver_api *)dev->api;
 
        if (api->set_property == NULL) {
                return -ENOSYS;
        }
 
        return api->set_property(dev, props, props_len);
}
 
__syscall int fuel_gauge_get_buffer_prop(const struct device *dev,
                                        struct fuel_gauge_get_buffer_property *prop, void *dst,
                                        size_t dst_len);
 
static inline int z_impl_fuel_gauge_get_buffer_prop(const struct device *dev,
                                                   struct fuel_gauge_get_buffer_property *prop,
                                                   void *dst, size_t dst_len)
{
        const struct fuel_gauge_driver_api *api = (const struct fuel_gauge_driver_api *)dev->api;
 
        if (api->get_buffer_property == NULL) {
                return -ENOSYS;
        }
 
        return api->get_buffer_property(dev, prop, dst, dst_len);
}
 
#ifdef __cplusplus
}
#endif /* __cplusplus */
 
#include <syscalls/fuel_gauge.h>
 
#endif /* ZEPHYR_INCLUDE_DRIVERS_BATTERY_H_ */