bbram: Add documentation

- Add doxygen group and improve documentation for bbram.h
- Add a bbram section under peripherals in the main doc/ directory

Fixes #55257

Signed-off-by: Yuval Peress <[email protected]>

Author: Yuval Peress

doc/hardware/peripherals/bbram.rst

@@ -0,0 +1,21 @@
+.. _bbram_api:
+
+Battery Backed RAM (BBRAM)
+##########################
+
+The BBRAM APIs allow interfacing with the unique properties of this memory region. The following
+common types of BBRAM properties are easily accessed via this API:
+
+- IBBR (invalid) state - check that the BBRAM is not corrupt.
+- VSBY (voltage standby) state - check if the BBRAM is using standby voltage.
+- VCC (active power) state - check if the BBRAM is on normal power.
+- Size - get the size (in bytes) of the BBRAM region.
+
+Along with these, the API provides a means for reading and writing to the memory region via
+:c:func:`bbram_read` and :c:func:`bbram_write` respectively. Both functions are expected to only
+succeed if the BBRAM is in a valid state and the operation is bounded to the memory region.
+
+API Reference
+*************
+
+.. doxygengroup:: bbram_interface

doc/hardware/peripherals/index.rst

@@ -12,6 +12,7 @@ Peripherals
    w1.rst
    adc.rst
    audio/index.rst
+   bbram.rst
    bc12.rst
    clock_control.rst
    canbus/index.rst

include/zephyr/drivers/bbram.h

@@ -11,70 +11,83 @@
 
 #include <zephyr/device.h>
 
+/**
+ * @brief BBRAM Interface
+ * @defgroup bbram_interface BBRAM Interface
+ * @ingroup io_interfaces
+ * @{
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 /**
- * API template to check if the BBRAM is invalid.
+ * @typedef bbram_api_check_invalid_t
+ * @brief API template to check if the BBRAM is invalid.
  *
  * @see bbram_check_invalid
  */
-typedef int (*bbram_api_check_invalid)(const struct device *dev);
+typedef int (*bbram_api_check_invalid_t)(const struct device *dev);
 
 /**
- * API template to check for standby power failure.
+ * @typedef bbram_api_check_standby_power_t
+ * @brief API template to check for standby power failure.
  *
  * @see bbram_check_standby_power
  */
-typedef int (*bbram_api_check_standby_power)(const struct device *dev);
+typedef int (*bbram_api_check_standby_power_t)(const struct device *dev);
 
 /**
- * API template to check for V CC1 power failure.
+ * @typedef bbram_api_check_power_t
+ * @brief API template to check for V CC1 power failure.
  *
  * @see bbram_check_power
  */
-typedef int (*bbram_api_check_power)(const struct device *dev);
+typedef int (*bbram_api_check_power_t)(const struct device *dev);
 
 /**
- * API template to check the size of the BBRAM
+ * @typedef bbram_api_get_size_t
+ * @brief API template to check the size of the BBRAM
  *
  * @see bbram_get_size
  */
-typedef int (*bbram_api_get_size)(const struct device *dev, size_t *size);
+typedef int (*bbram_api_get_size_t)(const struct device *dev, size_t *size);
 
 /**
- * API template to read from BBRAM.
+ * @typedef bbram_api_read_t
+ * @brief API template to read from BBRAM.
  *
  * @see bbram_read
  */
-typedef int (*bbram_api_read)(const struct device *dev, size_t offset, size_t size,
+typedef int (*bbram_api_read_t)(const struct device *dev, size_t offset, size_t size,
 			      uint8_t *data);
 
 /**
- * API template to write to BBRAM.
+ * @typedef bbram_api_write_t
+ * @brief API template to write to BBRAM.
  *
  * @see bbram_write
  */
-typedef int (*bbram_api_write)(const struct device *dev, size_t offset, size_t size,
+typedef int (*bbram_api_write_t)(const struct device *dev, size_t offset, size_t size,
 			       const uint8_t *data);
 
 __subsystem struct bbram_driver_api {
-	bbram_api_check_invalid check_invalid;
-	bbram_api_check_standby_power check_standby_power;
-	bbram_api_check_power check_power;
-	bbram_api_get_size get_size;
-	bbram_api_read read;
-	bbram_api_write write;
+	bbram_api_check_invalid_t check_invalid;
+	bbram_api_check_standby_power_t check_standby_power;
+	bbram_api_check_power_t check_power;
+	bbram_api_get_size_t get_size;
+	bbram_api_read_t read;
+	bbram_api_write_t write;
 };
 
 /**
  * @brief Check if BBRAM is invalid
  *
- * Check if "Invalid Battery-Backed RAM" status is set then reset the status
- * bit. This may occur as a result to low voltage at the VBAT pin.
+ * Check if "Invalid Battery-Backed RAM" status is set then reset the status bit. This may occur as
+ * a result to low voltage at the VBAT pin.
  *
- * @param dev BBRAM device pointer.
+ * @param[in] dev BBRAM device pointer.
  * @return 0 if the Battery-Backed RAM data is valid, -EFAULT otherwise.
  */
 __syscall int bbram_check_invalid(const struct device *dev);
@@ -94,10 +107,9 @@ static inline int z_impl_bbram_check_invalid(const struct device *dev)
 /**
  * @brief Check for standby (Volt SBY) power failure.
  *
- * Check if the V standby power domain is turned on after it was off then reset
- * the status bit.
+ * Check if the V standby power domain is turned on after it was off then reset the status bit.
  *
- * @param dev BBRAM device pointer.
+ * @param[in] dev BBRAM device pointer.
  * @return 0 if V SBY power domain is in normal operation.
  */
 __syscall int bbram_check_standby_power(const struct device *dev);
@@ -117,12 +129,11 @@ static inline int z_impl_bbram_check_standby_power(const struct device *dev)
 /**
  * @brief Check for V CC1 power failure.
  *
- * This will return an error if the V CC1 power domain is turned on after it was
- * off and reset the status bit.
+ * This will return an error if the V CC1 power domain is turned on after it was off and reset the
+ * status bit.
  *
- * @param dev BBRAM device pointer.
- * @return 0 if the V CC1 power domain is in normal operation, -EFAULT
- * otherwise.
+ * @param[in] dev BBRAM device pointer.
+ * @return 0 if the V CC1 power domain is in normal operation, -EFAULT otherwise.
  */
 __syscall int bbram_check_power(const struct device *dev);
 
@@ -139,10 +150,10 @@ static inline int z_impl_bbram_check_power(const struct device *dev)
 }
 
 /**
- * Get the size of the BBRAM (in bytes).
+ * @brief Get the size of the BBRAM (in bytes).
  *
- * @param dev BBRAM device pointer.
- * @param size Pointer to write the size to.
+ * @param[in] dev BBRAM device pointer.
+ * @param[out] size Pointer to write the size to.
  * @return 0 for success, -EFAULT otherwise.
  */
 __syscall int bbram_get_size(const struct device *dev, size_t *size);
@@ -160,12 +171,12 @@ static inline int z_impl_bbram_get_size(const struct device *dev, size_t *size)
 }
 
 /**
- * Read bytes from BBRAM.
+ * @brief Read bytes from BBRAM.
  *
- * @param dev The BBRAM device pointer to read from.
- * @param offset The offset into the RAM address to start reading from.
- * @param size The number of bytes to read.
- * @param data The buffer to load the data into.
+ * @param[in]  dev The BBRAM device pointer to read from.
+ * @param[in]  offset The offset into the RAM address to start reading from.
+ * @param[in]  size The number of bytes to read.
+ * @param[out] data The buffer to load the data into.
  * @return 0 on success, -EFAULT if the address range is out of bounds.
  */
 __syscall int bbram_read(const struct device *dev, size_t offset, size_t size,
@@ -185,12 +196,12 @@ static inline int z_impl_bbram_read(const struct device *dev, size_t offset,
 }
 
 /**
- * Write bytes to BBRAM.
+ * @brief Write bytes to BBRAM.
  *
- * @param dev The BBRAM device pointer to write to.
- * @param offset The offset into the RAM address to start writing to.
- * @param size The number of bytes to write.
- * @param data Pointer to the start of data to write.
+ * @param[in]  dev The BBRAM device pointer to write to.
+ * @param[in]  offset The offset into the RAM address to start writing to.
+ * @param[in]  size The number of bytes to write.
+ * @param[out] data Pointer to the start of data to write.
  * @return 0 on success, -EFAULT if the address range is out of bounds.
  */
 __syscall int bbram_write(const struct device *dev, size_t offset, size_t size,
@@ -210,21 +221,46 @@ static inline int z_impl_bbram_write(const struct device *dev, size_t offset,
 }
 
 /**
+ * @brief Set the emulated BBRAM driver's invalid state
+ *
+ * Calling this will affect the emulated behavior of :c:func:`bbram_check_invalid`
  *
- * @param dev
- * @param is_invalid
- * @return
+ * @param[in] dev The emulated device to modify
+ * @param[in] is_invalid The new invalid state
+ * @return 0 on success, negative values on error.
  */
 int bbram_emul_set_invalid(const struct device *dev, bool is_invalid);
 
+/**
+ * @brief Set the emulated BBRAM driver's standby power state
+ *
+ * Calling this will affect the emulated behavior of :c:func:`bbram_check_standby_power`
+ *
+ * @param[in] dev The emulated device to modify
+ * @param[in] failure Whether or not standby power failure should be emulated
+ * @return 0 on success, negative values on error.
+ */
 int bbram_emul_set_standby_power_state(const struct device *dev, bool failure);
 
+/**
+ * @brief Set the emulated BBRAM driver's  power state
+ *
+ * Calling this will affect the emulated behavior of :c:func:`bbram_check_power`
+ *
+ * @param[in] dev The emulated device to modify
+ * @param[in] failure Whether or not a power failure should be emulated
+ * @return 0 on success, negative values on error.
+ */
 int bbram_emul_set_power_state(const struct device *dev, bool failure);
 
 #ifdef __cplusplus
 }
 #endif
 
+/**
+ * @}
+ */
+
 #include <syscalls/bbram.h>
 
 #endif /* ZEPHYR_INCLUDE_DRIVERS_BBRAM_H */