drivers: fuel_gauge: sbs_gauge: Add support for buffer registers

The buffer registers (chemistry, manufacturer name, device name) were
not implemented. Implemented by adding a new api interface for
retrieving buffer properties. fuel_gauge_get_block_property has been
added, and uses a memory buffer allocated in the app in order to
store the fuel gauge information.

Signed-off-by: Peter Rowley <[email protected]>

Author: Peter Rowley

drivers/fuel_gauge/fuel_gauge_syscall_handlers.c

@@ -1,5 +1,6 @@
 /*
  * Copyright 2023 Google LLC
+ * Copyright 2023 Microsoft Corporation
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -46,3 +47,26 @@ static inline int z_vrfy_fuel_gauge_set_prop(const struct device *dev,
 }
 
 #include <syscalls/fuel_gauge_set_prop_mrsh.c>
+
+static inline int z_vrfy_fuel_gauge_get_buffer_prop(const struct device *dev,
+						    struct fuel_gauge_get_buffer_property *prop,
+						    void *dst, size_t dst_len)
+{
+	struct fuel_gauge_get_buffer_property k_prop;
+
+	Z_OOPS(Z_SYSCALL_DRIVER_FUEL_GAUGE(dev, get_buffer_property));
+
+	Z_OOPS(z_user_from_copy(&k_prop, prop,
+				sizeof(struct fuel_gauge_get_buffer_property)));
+
+	Z_OOPS(Z_SYSCALL_MEMORY_WRITE(dst, dst_len));
+
+	int ret = z_impl_fuel_gauge_get_buffer_prop(dev, &k_prop, dst, dst_len);
+
+	Z_OOPS(z_user_to_copy(prop, &k_prop,
+			      sizeof(struct fuel_gauge_get_buffer_property)));
+
+	return ret;
+}
+
+#include <syscalls/fuel_gauge_get_buffer_prop_mrsh.c>

drivers/fuel_gauge/sbs_gauge/emul_sbs_gauge.c

@@ -1,5 +1,6 @@
 /*
  * Copyright 2022 Google LLC
+ * Copyright 2023 Microsoft Corporation
  *
  * SPDX-License-Identifier: Apache-2.0
  *
@@ -20,6 +21,7 @@ LOG_MODULE_REGISTER(sbs_sbs_gauge);
 #include <zephyr/drivers/i2c.h>
 #include <zephyr/drivers/i2c_emul.h>
 #include <zephyr/sys/byteorder.h>
+#include <zephyr/drivers/fuel_gauge.h>
 
 #include "sbs_gauge.h"
 
@@ -119,6 +121,37 @@ static int emul_sbs_gauge_reg_read(const struct emul *target, int reg, int *val)
 	return 0;
 }
 
+static int emul_sbs_gauge_buffer_read(const struct emul *target, int reg, char *val)
+{
+	char mfg[] = "ACME";
+	char dev[] = "B123456";
+	char chem[] = "LiPO";
+	struct sbs_gauge_manufacturer_name *mfg_name = (struct sbs_gauge_manufacturer_name *)val;
+	struct sbs_gauge_device_name *dev_name = (struct sbs_gauge_device_name *)val;
+	struct sbs_gauge_device_chemistry *dev_chem = (struct sbs_gauge_device_chemistry *)val;
+
+	switch (reg) {
+	case SBS_GAUGE_CMD_MANUFACTURER_NAME:
+		mfg_name->manufacturer_name_length = sizeof(mfg);
+		memcpy(mfg_name->manufacturer_name, mfg, mfg_name->manufacturer_name_length);
+		break;
+	case SBS_GAUGE_CMD_DEVICE_NAME:
+		dev_name->device_name_length = sizeof(dev);
+		memcpy(dev_name->device_name, dev, dev_name->device_name_length);
+		break;
+
+	case SBS_GAUGE_CMD_DEVICE_CHEMISTRY:
+		dev_chem->device_chemistry_length = sizeof(chem);
+		memcpy(dev_chem->device_chemistry, chem, dev_chem->device_chemistry_length);
+		break;
+	default:
+		LOG_ERR("Unknown register 0x%x read", reg);
+		return -EIO;
+	}
+
+	return 0;
+}
+
 static int sbs_gauge_emul_transfer_i2c(const struct emul *target, struct i2c_msg *msgs,
 				       int num_msgs, int addr)
 {
@@ -148,8 +181,8 @@ static int sbs_gauge_emul_transfer_i2c(const struct emul *target, struct i2c_msg
 		/* Now process the 'read' part of the message */
 		msgs++;
 		if (msgs->flags & I2C_MSG_READ) {
-			switch (msgs->len - 1) {
-			case 1:
+			switch (msgs->len) {
+			case 2:
 				rc = emul_sbs_gauge_reg_read(target, reg, &val);
 				if (rc) {
 					/* Return before writing bad value to message buffer */
@@ -158,6 +191,11 @@ static int sbs_gauge_emul_transfer_i2c(const struct emul *target, struct i2c_msg
 
 				/* SBS uses SMBus, which sends data in little-endian format. */
 				sys_put_le16(val, msgs->buf);
+				break;
+					/* buffer properties */
+			case (sizeof(struct sbs_gauge_manufacturer_name)):
+			case (sizeof(struct sbs_gauge_device_chemistry)):
+				rc = emul_sbs_gauge_buffer_read(target, reg, (char *)msgs->buf);
 				break;
 			default:
 				LOG_ERR("Unexpected msg1 length %d", msgs->len);

drivers/fuel_gauge/sbs_gauge/sbs_gauge.c

@@ -2,6 +2,7 @@
  * Copyright (c) 2022 Leica Geosystems AG
  *
  * Copyright 2022 Google LLC
+ * Copyright 2023 Microsoft Corporation
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -45,6 +46,22 @@ static int sbs_cmd_reg_write(const struct device *dev, uint8_t reg_addr, uint16_
 	return i2c_burst_write_dt(&config->i2c, reg_addr, buf, sizeof(buf));
 }
 
+static int sbs_cmd_buffer_read(const struct device *dev, uint8_t reg_addr, char *buffer,
+			      const uint8_t buffer_size)
+{
+	const struct sbs_gauge_config *cfg;
+	int status;
+
+	cfg = dev->config;
+	status = i2c_burst_read_dt(&cfg->i2c, reg_addr, buffer, buffer_size);
+	if (status < 0) {
+		LOG_ERR("Unable to read register");
+		return status;
+	}
+
+	return 0;
+}
+
 static int sbs_gauge_get_prop(const struct device *dev, struct fuel_gauge_get_property *prop)
 {
 	int rc = 0;
@@ -196,6 +213,45 @@ static int sbs_gauge_set_prop(const struct device *dev, struct fuel_gauge_set_pr
 	return rc;
 }
 
+static int sbs_gauge_get_buffer_prop(const struct device *dev,
+				    struct fuel_gauge_get_buffer_property *prop, void *dst,
+				    size_t dst_len)
+{
+	int rc = 0;
+
+	switch (prop->property_type) {
+	case FUEL_GAUGE_MANUFACTURER_NAME:
+		if (dst_len == sizeof(struct sbs_gauge_manufacturer_name)) {
+			rc = sbs_cmd_buffer_read(dev, SBS_GAUGE_CMD_MANUFACTURER_NAME, (char *)dst,
+						dst_len);
+		} else {
+			rc = -EINVAL;
+		}
+		break;
+	case FUEL_GAUGE_DEVICE_NAME:
+		if (dst_len == sizeof(struct sbs_gauge_device_name)) {
+			rc = sbs_cmd_buffer_read(dev, SBS_GAUGE_CMD_DEVICE_NAME, (char *)dst,
+						dst_len);
+		} else {
+			rc = -EINVAL;
+		}
+		break;
+	case FUEL_GAUGE_DEVICE_CHEMISTRY:
+		if (dst_len == sizeof(struct sbs_gauge_device_chemistry)) {
+			rc = sbs_cmd_buffer_read(dev, SBS_GAUGE_CMD_DEVICE_CHEMISTRY, (char *)dst,
+						dst_len);
+		} else {
+			rc = -EINVAL;
+		}
+		break;
+	default:
+		rc = -ENOTSUP;
+	}
+
+	prop->status = rc;
+	return rc;
+}
+
 static int sbs_gauge_get_props(const struct device *dev, struct fuel_gauge_get_property *props,
 			       size_t len)
 {
@@ -250,6 +306,7 @@ static int sbs_gauge_init(const struct device *dev)
 static const struct fuel_gauge_driver_api sbs_gauge_driver_api = {
 	.get_property = &sbs_gauge_get_props,
 	.set_property = &sbs_gauge_set_props,
+	.get_buffer_property = &sbs_gauge_get_buffer_prop,
 };
 
 /* FIXME: fix init priority */

drivers/fuel_gauge/sbs_gauge/sbs_gauge.h

@@ -42,7 +42,7 @@
 #define SBS_GAUGE_CMD_SN                    0x1C /* SerialNumber */
 #define SBS_GAUGE_CMD_MANUFACTURER_NAME     0x20 /* ManufacturerName */
 #define SBS_GAUGE_CMD_DEVICE_NAME           0x21 /* DeviceName */
-#define SBS_GAUGE_CMD_DEVICE_CHEM           0x22 /* DeviceChemistry */
+#define SBS_GAUGE_CMD_DEVICE_CHEMISTRY      0x22 /* DeviceChemistry */
 #define SBS_GAUGE_CMD_MANUFACTURER_DATA     0x23 /* ManufacturerData */
 
 #define SBS_GAUGE_DELAY                     1000

include/zephyr/drivers/fuel_gauge.h

@@ -1,5 +1,6 @@
 /*
  * Copyright 2022 Google LLC
+ * Copyright 2023 Microsoft Corporation
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -90,9 +91,15 @@ extern "C" {
 #define FUEL_GAUGE_SBS_REMAINING_CAPACITY_ALARM FUEL_GAUGE_SBS_ATRATE_OK + 1
 /** Remaining Time Alarm (minutes) */
 #define FUEL_GAUGE_SBS_REMAINING_TIME_ALARM	FUEL_GAUGE_SBS_REMAINING_CAPACITY_ALARM + 1
+/** Manufacturer of pack (1 byte length + 20 bytes data) */
+#define FUEL_GAUGE_MANUFACTURER_NAME		FUEL_GAUGE_SBS_REMAINING_TIME_ALARM + 1
+/** Name of pack (1 byte length + 20 bytes data) */
+#define FUEL_GAUGE_DEVICE_NAME			FUEL_GAUGE_MANUFACTURER_NAME + 1
+/** Chemistry (1 byte length + 4 bytes data) */
+#define FUEL_GAUGE_DEVICE_CHEMISTRY		FUEL_GAUGE_DEVICE_NAME + 1
 
 /** Reserved to demark end of common fuel gauge properties */
-#define FUEL_GAUGE_COMMON_COUNT FUEL_GAUGE_DESIGN_VOLTAGE + 1
+#define FUEL_GAUGE_COMMON_COUNT FUEL_GAUGE_DEVICE_CHEMISTRY + 1
 /**
  * Reserved to demark downstream custom properties - use this value as the actual value may change
  * over future versions of this API
@@ -198,6 +205,37 @@ struct fuel_gauge_set_property {
 	} value;
 };
 
+/** Buffer properties are separated due to size */
+struct fuel_gauge_get_buffer_property {
+	/** Battery fuel gauge property to get */
+	uint16_t property_type;
+
+	/** Negative error status set by callee e.g. -ENOTSUP for an unsupported property */
+	int status;
+};
+
+/**
+ * Data structures for reading SBS buffer properties
+ */
+#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 fuel_gauge_get_property_t
  * @brief Callback API for getting a fuel_gauge property.
@@ -216,11 +254,23 @@ typedef int (*fuel_gauge_get_property_t)(const struct device *dev,
 typedef int (*fuel_gauge_set_property_t)(const struct device *dev,
 					 struct fuel_gauge_set_property *props, size_t props_len);
 
+/**
+ * @typedef fuel_gauge_get_buffer_property_t
+ * @brief Callback API for getting a fuel_gauge buffer property.
+ *
+ * See fuel_gauge_get_buffer_property() for argument description
+ */
+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;
 };
 
 /**
@@ -280,6 +330,35 @@ static inline int z_impl_fuel_gauge_set_prop(const struct device *dev,
 	return api->set_property(dev, props, props_len);
 }
 
+/**
+ * @brief Fetch a battery fuel-gauge buffer property
+ *
+ * @param dev Pointer to the battery fuel-gauge device
+ * @param prop pointer to single fuel_gauge_get_buffer_property struct where the property struct
+ * field is set by the caller to determine what property is read from the
+ * fuel gauge device into the dst field.
+ * @param dst byte array or struct that will hold the buffer data that is read from the fuel gauge
+ * @param dst_len the length of the destination array in bytes
+ *
+ * @return return=0 if successful, return < 0 if getting property failed, return 0 on success
+ */
+__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);
+}
+
 /**
  * @}
  */

tests/drivers/fuel_gauge/sbs_gauge/src/test_sbs_gauge.c

@@ -1,5 +1,6 @@
 /*
  * Copyright 2022 Google LLC
+ * Copyright 2023 Microsoft Corporation
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -317,4 +318,31 @@ ZTEST_USER_F(sbs_gauge_new_api, test_set_props__returns_ok)
 	zassert_ok(ret);
 }
 
+
+ZTEST_USER_F(sbs_gauge_new_api, test_get_buffer_props__returns_ok)
+{
+	/* Validate what properties are supported by the driver */
+	struct fuel_gauge_get_buffer_property prop;
+	struct sbs_gauge_manufacturer_name mfg_name;
+	struct sbs_gauge_device_name dev_name;
+	struct sbs_gauge_device_chemistry chem;
+	int ret;
+
+	prop.property_type = FUEL_GAUGE_MANUFACTURER_NAME;
+	ret = fuel_gauge_get_buffer_prop(fixture->dev, &prop, &mfg_name, sizeof(mfg_name));
+	zassert_ok(prop.status, "Property %d has a bad status.", prop.property_type);
+	zassert_ok(ret);
+
+	prop.property_type = FUEL_GAUGE_DEVICE_NAME;
+	ret = fuel_gauge_get_buffer_prop(fixture->dev, &prop, &dev_name, sizeof(dev_name));
+	zassert_ok(prop.status, "Property %d has a bad status.", prop.property_type);
+	zassert_ok(ret);
+
+	prop.property_type = FUEL_GAUGE_DEVICE_CHEMISTRY;
+	ret = fuel_gauge_get_buffer_prop(fixture->dev, &prop, &chem, sizeof(chem));
+	zassert_ok(prop.status, "Property %d has a bad status.", prop.property_type);
+	zassert_ok(ret);
+}
+
+
 ZTEST_SUITE(sbs_gauge_new_api, NULL, sbs_gauge_new_api_setup, NULL, NULL, NULL);