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 bbram_read() and 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

group bbram_interface

BBRAM Interface.

Typedefs

typedef int (*bbram_api_check_invalid_t)(const struct device *dev)

API template to check if the BBRAM is invalid.

See also

bbram_check_invalid

typedef int (*bbram_api_check_standby_power_t)(const struct device *dev)

API template to check for standby power failure.

See also

bbram_check_standby_power

typedef int (*bbram_api_check_power_t)(const struct device *dev)

API template to check for V CC1 power failure.

See also

bbram_check_power

typedef int (*bbram_api_get_size_t)(const struct device *dev, size_t *size)

API template to check the size of the BBRAM.

See also

bbram_get_size

typedef int (*bbram_api_read_t)(const struct device *dev, size_t offset, size_t size, uint8_t *data)

API template to read from BBRAM.

See also

bbram_read

typedef int (*bbram_api_write_t)(const struct device *dev, size_t offset, size_t size, const uint8_t *data)

API template to write to BBRAM.

See also

bbram_write

Functions

int bbram_check_invalid(const struct device *dev)

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.

Parameters:

  • dev – [in] BBRAM device pointer.

Returns:

0 if the Battery-Backed RAM data is valid, -EFAULT otherwise.

int bbram_check_standby_power(const struct device *dev)

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.

Parameters:

  • dev – [in] BBRAM device pointer.

Returns:

0 if V SBY power domain is in normal operation.

int bbram_check_power(const struct device *dev)

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.

Parameters:

  • dev – [in] BBRAM device pointer.

Returns:

0 if the V CC1 power domain is in normal operation, -EFAULT otherwise.

int bbram_get_size(const struct device *dev, size_t *size)

Get the size of the BBRAM (in bytes).

Parameters:

  • dev – [in] BBRAM device pointer.

  • size – [out] Pointer to write the size to.

Returns:

0 for success, -EFAULT otherwise.

int bbram_read(const struct device *dev, size_t offset, size_t size, uint8_t *data)

Read bytes from BBRAM.

Parameters:

  • dev – [in] The BBRAM device pointer to read from.

  • offset – [in] The offset into the RAM address to start reading from.

  • size – [in] The number of bytes to read.

  • data – [out] The buffer to load the data into.

Returns:

0 on success, -EFAULT if the address range is out of bounds.

int bbram_write(const struct device *dev, size_t offset, size_t size, const uint8_t *data)

Write bytes to BBRAM.

Parameters:

  • dev – [in] The BBRAM device pointer to write to.

  • offset – [in] The offset into the RAM address to start writing to.

  • size – [in] The number of bytes to write.

  • data – [out] Pointer to the start of data to write.

Returns:

0 on success, -EFAULT if the address range is out of bounds.

int bbram_emul_set_invalid(const struct device *dev, bool is_invalid)

Set the emulated BBRAM driver’s invalid state.

Calling this will affect the emulated behavior of bbram_check_invalid().

Parameters:

  • dev – [in] The emulated device to modify

  • is_invalid – [in] The new invalid state

Returns:

0 on success, negative values on error.

int bbram_emul_set_standby_power_state(const struct device *dev, bool failure)

Set the emulated BBRAM driver’s standby power state.

Calling this will affect the emulated behavior of bbram_check_standby_power().

Parameters:

  • dev – [in] The emulated device to modify

  • failure – [in] Whether or not standby power failure should be emulated

Returns:

0 on success, negative values on error.

int bbram_emul_set_power_state(const struct device *dev, bool failure)

Set the emulated BBRAM driver’s power state.

Calling this will affect the emulated behavior of bbram_check_power().

Parameters:

  • dev – [in] The emulated device to modify

  • failure – [in] Whether or not a power failure should be emulated

Returns:

0 on success, negative values on error.

struct bbram_driver_api
#include <bbram.h>