Merge pull request #20588 from crasbe/master

drivers/at24cxxx: Add M24C01 device and enhance documentation

drivers/Makefile.dep

@@ -104,6 +104,10 @@ ifneq (,$(filter ltc4150_%,$(USEMODULE)))
   USEMODULE += ltc4150
 endif
 
+ifneq (,$(filter m24c%,$(USEMODULE)))
+  USEMODULE += at24cxxx
+endif
+
 ifneq (,$(filter mhz19_%,$(USEMODULE)))
   USEMODULE += mhz19
 endif

drivers/at24cxxx/Makefile.include

@@ -1,5 +1,7 @@
 PSEUDOMODULES += at24c%
 PSEUDOMODULES += mtd_at24cxxx
+PSEUDOMODULES += m24c%
+
 # handle at24cxxx being a distinct module
 NO_PSEUDOMODULES += at24cxxx
 

drivers/at24cxxx/include/at24cxxx_defines.h

@@ -11,7 +11,12 @@
  * @{
  *
  * @file
- * @brief       Constants for AT24CXXX EEPROM devices.
+ * @brief       Constants for various I2C EEPROM devices.
+ *
+ * All the devices listed below are accessible as pseudomodules.
+ *
+ * @note Even though the library is called "AT24CXXX", the support for
+ * I2C EEPROMs is not limited to Atmel/Microchip devices.
  *
  * @author      Fabian Hüßler <[email protected]>
  */
@@ -367,6 +372,29 @@ extern "C" {
                                          / AT24CXXX_POLL_DELAY_US))
 /** @} */
 
+/**
+ * @name M24C01 constants
+ * @{
+ */
+/**
+ * @brief   128 byte memory
+ */
+#define M24C01_EEPROM_SIZE              (128U)
+/**
+ * @brief   16 pages of 16 bytes each
+ */
+#define M24C01_PAGE_SIZE                (16U)
+/**
+ * @brief   Delay to complete write operation
+ */
+#define M24C01_PAGE_WRITE_DELAY_US      (5000U)
+/**
+ * @brief   Number of poll attempts
+ */
+#define M24C01_MAX_POLLS                (1 + (M24C01_PAGE_WRITE_DELAY_US \
+                                         / AT24CXXX_POLL_DELAY_US))
+/** @} */
+
 /**
  * @name Set constants depending on module
  * @{
@@ -427,6 +455,10 @@ extern "C" {
 #define AT24CXXX_EEPROM_SIZE            (AT24MAC_EEPROM_SIZE)
 #define AT24CXXX_PAGE_SIZE              (AT24MAC_PAGE_SIZE)
 #define AT24CXXX_MAX_POLLS              (AT24MAC_MAX_POLLS)
+#elif IS_USED(MODULE_M24C01)
+#define AT24CXXX_EEPROM_SIZE            (M24C01_EEPROM_SIZE)
+#define AT24CXXX_PAGE_SIZE              (M24C01_PAGE_SIZE)
+#define AT24CXXX_MAX_POLLS              (M24C01_MAX_POLLS)
 #else /* minimal */
 #define AT24CXXX_EEPROM_SIZE            (128U)  /**< EEPROM size */
 #define AT24CXXX_PAGE_SIZE              (4U)    /**< page size */

drivers/at24cxxx/include/at24cxxx_params.h

@@ -11,7 +11,7 @@
  * @{
  *
  * @file
- * @brief       Default configuration for AT24CXXX
+ * @brief       Default configuration for the AT24CXXX driver
  *
  * @author      Fabian Hüßler <[email protected]>
  */

drivers/include/at24cxxx.h

@@ -11,6 +11,51 @@
  * @ingroup     drivers_misc
  * @brief       Device driver interface for the AT24CXXX EEPROM units
  *
+ * @section overview Overview
+ * Various manufacturers such as Atmel/Microchip or ST offer small I2C EEPROMs which usually
+ * come in 8-pin packages and are used for persistent data storage of settings, counters, etc.
+ * This driver adds support for these devices with direct read and write functions.
+ *
+ * The high level wrapper for RIOTs MTD interface to utilize the I2C EEPROMs as MTD storage
+ * is described in drivers_mtd_at24cxxx.
+ *
+ * A list of supported devices can be found in the at24cxxx_defines.h file.
+ *
+ * @section usage Usage
+ *
+ * The preconfigured devices in the at24cxxx_defines.h file devices are easily
+ * accessible as pseudomodules and can be added to the Makefile of your project:
+ *
+ *      USEMODULE += at24c02
+ *
+ * When using one of the pseudomodules, the configuration of the device is already
+ * predefined in the AT24CXXX_PARAMS macro and can be used for the
+ * initialization:
+ *
+ *      at24cxxx_t eeprom_dev;
+ *      at24cxxx_params_t eeprom_params = AT24CXXX_PARAMS;
+ *
+ *      at24cxxx_init(&eeprom_dev, &eeprom_params);
+ *
+ * \n
+ * For other devices that are not yet part of the library, the generic module
+ * has to be added:
+ *
+ *      USEMODULE += at24cxxx
+ *
+ * The predefined macro can not be used in this case, so the parameters of the
+ * device have to be added to the at24cxxx_params_t structure manually with
+ * the values from the corresponding datasheet:
+ *
+ *      at24cxxx_t eeprom_dev;
+ *      at24cxxx_params_t eeprom_params = {
+ *          .i2c = I2C_DEV(0), \
+ *          ...
+ *      };
+ *
+ *      at24cxxx_init(&eeprom_dev, &eeprom_params);
+ *
+ *
  * @{
  *
  * @file