Stop referring to 'tokens' for non-volatile attributes. (#13166)

Our actual storage for these may or may not use something like
'tokens'.

src/app/clusters/ias-zone-server/ias-zone-server.cpp

@@ -149,7 +149,7 @@ static void resetCurrentQueueRetryParams(void)
 // Forward declarations
 
 static void setZoneId(EndpointId endpoint, uint8_t zoneId);
-static bool areZoneServerAttributesTokenized(EndpointId endpoint);
+static bool areZoneServerAttributesNonVolatile(EndpointId endpoint);
 static bool isValidEnrollmentMode(EmberAfIasZoneEnrollmentMode method);
 #if defined(EMBER_AF_PLUGIN_IAS_ZONE_SERVER_ENABLE_QUEUE)
 static uint16_t computeElapsedTimeQs(IasZoneStatusQueueEntry * entry);
@@ -540,7 +540,7 @@ void emberAfPluginIasZoneServerManageQueueEventHandler(void)
 void emberAfIasZoneClusterServerInitCallback(EndpointId endpoint)
 {
     EmberAfIasZoneType zoneType;
-    if (!areZoneServerAttributesTokenized(endpoint))
+    if (!areZoneServerAttributesNonVolatile(endpoint))
     {
         emberAfAppPrint("WARNING: ATTRIBUTES ARE NOT BEING STORED IN FLASH! ");
         emberAfAppPrintln("DEVICE WILL NOT FUNCTION PROPERLY AFTER REBOOTING!!");
@@ -587,37 +587,37 @@ uint8_t emberAfPluginIasZoneServerGetZoneId(EndpointId endpoint)
 //
 // This function will verify that all attributes necessary for the IAS zone
 // server to properly retain functionality through a power failure are
-// tokenized.
+// non-volatile.
 //
 //------------------------------------------------------------------------------
-static bool areZoneServerAttributesTokenized(EndpointId endpoint)
+static bool areZoneServerAttributesNonVolatile(EndpointId endpoint)
 {
     EmberAfAttributeMetadata * metadata;
 
     metadata = emberAfLocateAttributeMetadata(endpoint, ZCL_IAS_ZONE_CLUSTER_ID, ZCL_IAS_CIE_ADDRESS_ATTRIBUTE_ID,
                                               CLUSTER_MASK_SERVER, EMBER_AF_NULL_MANUFACTURER_CODE);
-    if (!emberAfAttributeIsTokenized(metadata))
+    if (!metadata->IsNonVolatile())
     {
         return false;
     }
 
     metadata = emberAfLocateAttributeMetadata(endpoint, ZCL_IAS_ZONE_CLUSTER_ID, ZCL_ZONE_STATE_ATTRIBUTE_ID, CLUSTER_MASK_SERVER,
                                               EMBER_AF_NULL_MANUFACTURER_CODE);
-    if (!emberAfAttributeIsTokenized(metadata))
+    if (!metadata->IsNonVolatile())
     {
         return false;
     }
 
     metadata = emberAfLocateAttributeMetadata(endpoint, ZCL_IAS_ZONE_CLUSTER_ID, ZCL_ZONE_TYPE_ATTRIBUTE_ID, CLUSTER_MASK_SERVER,
                                               EMBER_AF_NULL_MANUFACTURER_CODE);
-    if (!emberAfAttributeIsTokenized(metadata))
+    if (!metadata->IsNonVolatile())
     {
         return false;
     }
 
     metadata = emberAfLocateAttributeMetadata(endpoint, ZCL_IAS_ZONE_CLUSTER_ID, ZCL_ZONE_ID_ATTRIBUTE_ID, CLUSTER_MASK_SERVER,
                                               EMBER_AF_NULL_MANUFACTURER_CODE);
-    if (!emberAfAttributeIsTokenized(metadata))
+    if (!metadata->IsNonVolatile())
     {
         return false;
     }

src/app/clusters/level-control/level-control.cpp

@@ -70,7 +70,7 @@ using namespace chip::app::Clusters;
 using namespace chip::app::Clusters::LevelControl;
 
 #ifdef ZCL_USING_LEVEL_CONTROL_CLUSTER_START_UP_CURRENT_LEVEL_ATTRIBUTE
-static bool areStartUpLevelControlServerAttributesTokenized(EndpointId endpoint);
+static bool areStartUpLevelControlServerAttributesNonVolatile(EndpointId endpoint);
 #endif
 
 #if (EMBER_AF_PLUGIN_LEVEL_CONTROL_RATE == 0)
@@ -970,8 +970,8 @@ void emberAfOnOffClusterLevelControlEffectCallback(EndpointId endpoint, bool new
 void emberAfLevelControlClusterServerInitCallback(EndpointId endpoint)
 {
 #ifdef ZCL_USING_LEVEL_CONTROL_CLUSTER_START_UP_CURRENT_LEVEL_ATTRIBUTE
-    // StartUp behavior relies StartUpCurrentLevel attributes being tokenized.
-    if (areStartUpLevelControlServerAttributesTokenized(endpoint))
+    // StartUp behavior relies StartUpCurrentLevel attributes being non-volatile.
+    if (areStartUpLevelControlServerAttributesNonVolatile(endpoint))
     {
         // Read the StartUpOnOff attribute and set the OnOff attribute as per
         // following from zcl 7 14-0127-20i-zcl-ch-3-general.doc.
@@ -1030,20 +1030,20 @@ void emberAfLevelControlClusterServerInitCallback(EndpointId endpoint)
 }
 
 #ifdef ZCL_USING_LEVEL_CONTROL_CLUSTER_START_UP_CURRENT_LEVEL_ATTRIBUTE
-static bool areStartUpLevelControlServerAttributesTokenized(EndpointId endpoint)
+static bool areStartUpLevelControlServerAttributesNonVolatile(EndpointId endpoint)
 {
     EmberAfAttributeMetadata * metadata;
 
     metadata = emberAfLocateAttributeMetadata(endpoint, LevelControl::Id, ZCL_CURRENT_LEVEL_ATTRIBUTE_ID, CLUSTER_MASK_SERVER,
                                               EMBER_AF_NULL_MANUFACTURER_CODE);
-    if (!emberAfAttributeIsTokenized(metadata))
+    if (!metadata->IsNonVolatile())
     {
         return false;
     }
 
     metadata = emberAfLocateAttributeMetadata(endpoint, LevelControl::Id, ZCL_START_UP_CURRENT_LEVEL_ATTRIBUTE_ID,
                                               CLUSTER_MASK_SERVER, EMBER_AF_NULL_MANUFACTURER_CODE);
-    if (!emberAfAttributeIsTokenized(metadata))
+    if (!metadata->IsNonVolatile())
     {
         return false;
     }

src/app/clusters/on-off-server/on-off-server.cpp

@@ -195,8 +195,8 @@ EmberAfStatus OnOffServer::setOnOffValue(chip::EndpointId endpoint, uint8_t comm
 void OnOffServer::initOnOffServer(chip::EndpointId endpoint)
 {
 #ifdef ZCL_USING_ON_OFF_CLUSTER_START_UP_ON_OFF_ATTRIBUTE
-    // StartUp behavior relies on OnOff and StartUpOnOff attributes being tokenized.
-    if (areStartUpOnOffServerAttributesTokenized(endpoint))
+    // StartUp behavior relies on OnOff and StartUpOnOff attributes being non-volatile.
+    if (areStartUpOnOffServerAttributesNonVolatile(endpoint))
     {
         // Read the StartUpOnOff attribute and set the OnOff attribute as per
         // following from zcl 7 14-0127-20i-zcl-ch-3-general.doc.
@@ -482,20 +482,20 @@ void OnOffServer::updateOnOffTimeCommand(chip::EndpointId endpoint)
 }
 
 #ifdef ZCL_USING_ON_OFF_CLUSTER_START_UP_ON_OFF_ATTRIBUTE
-bool OnOffServer::areStartUpOnOffServerAttributesTokenized(EndpointId endpoint)
+bool OnOffServer::areStartUpOnOffServerAttributesNonVolatile(EndpointId endpoint)
 {
     EmberAfAttributeMetadata * metadata;
 
     metadata = emberAfLocateAttributeMetadata(endpoint, OnOff::Id, Attributes::OnOff::Id, CLUSTER_MASK_SERVER,
                                               EMBER_AF_NULL_MANUFACTURER_CODE);
-    if (!emberAfAttributeIsTokenized(metadata))
+    if (!metadata->IsNonVolatile())
     {
         return false;
     }
 
     metadata = emberAfLocateAttributeMetadata(endpoint, OnOff::Id, Attributes::StartUpOnOff::Id, CLUSTER_MASK_SERVER,
                                               EMBER_AF_NULL_MANUFACTURER_CODE);
-    if (!emberAfAttributeIsTokenized(metadata))
+    if (!metadata->IsNonVolatile())
     {
         return false;
     }

src/app/clusters/on-off-server/on-off-server.h

@@ -63,7 +63,7 @@ class OnOffServer
      *********************************************************/
 
 #ifdef ZCL_USING_ON_OFF_CLUSTER_START_UP_ON_OFF_ATTRIBUTE
-    bool areStartUpOnOffServerAttributesTokenized(chip::EndpointId endpoint);
+    bool areStartUpOnOffServerAttributesNonVolatile(chip::EndpointId endpoint);
 #endif // ZCL_USING_ON_OFF_CLUSTER_START_UP_ON_OFF_ATTRIBUTE
     EmberEventControl * getEventControl(chip::EndpointId endpoint);
     EmberEventControl * configureEventControl(chip::EndpointId endpoint);

src/app/util/af-types.h

@@ -169,8 +169,10 @@ union EmberAfDefaultOrMinMaxAttributeValue
 //
 // Attribute that has this mask is NOT read-only
 #define ATTRIBUTE_MASK_WRITABLE (0x01)
-// Attribute that has this mask is saved to a token
-#define ATTRIBUTE_MASK_TOKENIZE (0x02)
+// Attribute that has this mask is saved in non-volatile memory
+#define ATTRIBUTE_MASK_NONVOLATILE (0x02)
+// Alias until ZAP gets updated to output ATTRIBUTE_MASK_NONVOLATILE
+#define ATTRIBUTE_MASK_TOKENIZE ATTRIBUTE_MASK_NONVOLATILE
 // Attribute that has this mask has a min/max values
 #define ATTRIBUTE_MASK_MIN_MAX (0x04)
 // Attribute requires a timed interaction to write
@@ -228,6 +230,18 @@ struct EmberAfAttributeMetadata
      * Check whether this attribute requires a timed write.
      */
     bool MustUseTimedWrite() const { return mask & ATTRIBUTE_MASK_MUST_USE_TIMED_WRITE; }
+
+    /**
+     * Check whether this attibute's storage is managed outside the built-in
+     * attribute store.
+     */
+    bool IsExternal() const { return mask & ATTRIBUTE_MASK_EXTERNAL_STORAGE; }
+
+    /**
+     * Check whether this attribute is automatically stored in non-volatile
+     * memory.
+     */
+    bool IsNonVolatile() const { return (mask & ATTRIBUTE_MASK_NONVOLATILE) && !IsExternal(); }
 };
 
 /**
@@ -869,36 +883,6 @@ typedef void (*EmberAfNetworkEventHandler)(void);
  */
 typedef void (*EmberAfEndpointEventHandler)(chip::EndpointId endpoint);
 
-#ifdef EMBER_AF_PLUGIN_GROUPS_SERVER
-/**
- * @brief Indicates the absence of a Group table entry.
- */
-#define EMBER_AF_GROUP_TABLE_NULL_INDEX 0xFF
-/**
- * @brief Value used when setting or getting the endpoint in a Group table
- * entry.  It indicates that the entry is not in use.
- */
-#define EMBER_AF_GROUP_TABLE_UNUSED_ENDPOINT_ID 0x00
-/**
- * @brief Maximum length of Group names, not including the length byte.
- */
-#define ZCL_GROUPS_CLUSTER_MAXIMUM_NAME_LENGTH 16
-/**
- * @brief A structure used to store group table entries in RAM or in tokens,
- * depending on the platform.  If the endpoint field is
- * ::EMBER_AF_GROUP_TABLE_UNUSED_ENDPOINT_ID, the entry is unused.
- */
-typedef struct
-{
-    chip::EndpointId endpoint; // 0x00 when not in use
-    chip::GroupId groupId;
-    uint8_t bindingIndex;
-#ifdef EMBER_AF_PLUGIN_GROUPS_SERVER_NAME_SUPPORT
-    uint8_t name[ZCL_GROUPS_CLUSTER_MAXIMUM_NAME_LENGTH + 1];
-#endif
-} EmberAfGroupTableEntry;
-#endif // EMBER_AF_PLUGIN_GROUPS_SERVER
-
 /**
  * @brief Indicates the absence of a Scene table entry.
  */
@@ -921,7 +905,7 @@ typedef struct
  */
 #define ZCL_SCENES_GLOBAL_SCENE_SCENE_ID 0x00
 /**
- * @brief A structure used to store scene table entries in RAM or in tokens,
+ * @brief A structure used to store scene table entries in RAM or in storage,
  * depending on a plugin setting.  If endpoint field is
  * ::EMBER_AF_SCENE_TABLE_UNUSED_ENDPOINT_ID, the entry is unused.
  */

src/app/util/af.h

@@ -381,13 +381,6 @@ uint8_t emberAfGetDataSize(uint8_t dataType);
  */
 #define emberAfAttributeIsClient(metadata) (((metadata)->mask & ATTRIBUTE_MASK_CLIENT) != 0)
 
-/**
- * @brief macro that returns true if attribute is saved to token.
- *
- * @param metadata EmberAfAttributeMetadata* to consider.
- */
-#define emberAfAttributeIsTokenized(metadata) (((metadata)->mask & ATTRIBUTE_MASK_TOKENIZE) != 0)
-
 /**
  * @brief macro that returns true if attribute is saved in external storage.
  *

src/app/util/attribute-storage.cpp

@@ -1200,7 +1200,7 @@ void emberAfResetAttributes(EndpointId endpoint)
     emAfLoadAttributeDefaults(endpoint, true);
 }
 
-void emAfLoadAttributeDefaults(EndpointId endpoint, bool writeTokens)
+void emAfLoadAttributeDefaults(EndpointId endpoint, bool ignoreStorage)
 {
     uint16_t ep;
     uint8_t clusterI, curNetwork = 0 /* emberGetCurrentNetwork() */;
@@ -1289,9 +1289,9 @@ void emAfLoadAttributeDefaults(EndpointId endpoint, bool writeTokens)
                                              ptr,
                                              0,     // buffer size - unused
                                              true); // write?
-                    if (writeTokens)
+                    if (ignoreStorage)
                     {
-                        emAfSaveAttributeToToken(ptr, de->endpoint, record.clusterId, am);
+                        emAfSaveAttributeToStorageIfNeeded(ptr, de->endpoint, record.clusterId, am);
                     }
                 }
             }
@@ -1302,13 +1302,13 @@ void emAfLoadAttributeDefaults(EndpointId endpoint, bool writeTokens)
         }
     }
 
-    if (!writeTokens)
+    if (!ignoreStorage)
     {
-        emAfLoadAttributesFromTokens(endpoint);
+        emAfLoadAttributesFromStorage(endpoint);
     }
 }
 
-void emAfLoadAttributesFromTokens(EndpointId endpoint)
+void emAfLoadAttributesFromStorage(EndpointId endpoint)
 {
     // On EZSP host we currently do not support this. We need to come up with some
     // callbacks.
@@ -1320,10 +1320,11 @@ void emAfLoadAttributesFromTokens(EndpointId endpoint)
 // 'data' argument may be null, since we changed the ptrToDefaultValue
 // to be null instead of pointing to all zeroes.
 // This function has to be able to deal with that.
-void emAfSaveAttributeToToken(uint8_t * data, EndpointId endpoint, ClusterId clusterId, EmberAfAttributeMetadata * metadata)
+void emAfSaveAttributeToStorageIfNeeded(uint8_t * data, EndpointId endpoint, ClusterId clusterId,
+                                        EmberAfAttributeMetadata * metadata)
 {
-    // Get out of here if this attribute doesn't have a token.
-    if (!emberAfAttributeIsTokenized(metadata))
+    // Get out of here if this attribute isn't marked non-volatile.
+    if (!metadata->IsNonVolatile())
     {
         return;
     }

src/app/util/attribute-storage.h

@@ -208,19 +208,19 @@ EmberAfGenericClusterFunction emberAfFindClusterFunction(EmberAfCluster * cluste
 void emberAfInitializeAttributes(chip::EndpointId endpoint);
 void emberAfResetAttributes(chip::EndpointId endpoint);
 
-// Loads the attributes from built-in default and / or tokens
-void emAfLoadAttributeDefaults(chip::EndpointId endpoint, bool writeTokens);
-
-// This function loads from tokens all the attributes that
-// are defined to be stored in tokens.
-void emAfLoadAttributesFromTokens(chip::EndpointId endpoint);
-
-// After the RAM value has changed, code should call this
-// function. If this attribute has been
-// tagged as stored-to-token, then code will store
-// the attribute to token.
-void emAfSaveAttributeToToken(uint8_t * data, chip::EndpointId endpoint, chip::ClusterId clusterId,
-                              EmberAfAttributeMetadata * metadata);
+// Loads the attributes from built-in default and / or storage.  If
+// ignoreStorage is true, only defaults will be read, and the storage for
+// non-volatile attributes will be overwritten with those defaults.
+void emAfLoadAttributeDefaults(chip::EndpointId endpoint, bool ignoreStorage);
+
+// This function loads from storage all the attributes that
+// are defined to be non-volatile.
+void emAfLoadAttributesFromStorage(chip::EndpointId endpoint);
+
+// After the RAM value has changed, code should call this function. If this
+// attribute has been tagged as non-volatile, its value will be stored.
+void emAfSaveAttributeToStorageIfNeeded(uint8_t * data, chip::EndpointId endpoint, chip::ClusterId clusterId,
+                                        EmberAfAttributeMetadata * metadata);
 
 // Calls the attribute changed callback
 void emAfClusterAttributeChangedCallback(const chip::app::ConcreteAttributePath & attributePath, uint8_t clientServerMask);

src/app/util/attribute-table.cpp

@@ -287,11 +287,10 @@ void emberAfPrintAttributeTable(void)
                                        (emberAfAttributeIsClient(metaData) ? "clnt" : "srvr"),
                                        ChipLogValueMEI(metaData->attributeId));
                 emberAfAttributesPrint("----");
-                emberAfAttributesPrint(" / %x (%x) / %p / %p / ", metaData->attributeType, emberAfAttributeSize(metaData),
-                                       (metaData->IsReadOnly() ? "RO" : "RW"),
-                                       (emberAfAttributeIsTokenized(metaData)
-                                            ? " token "
-                                            : (emberAfAttributeIsExternal(metaData) ? "extern " : "  RAM  ")));
+                emberAfAttributesPrint(
+                    " / %x (%x) / %p / %p / ", metaData->attributeType, emberAfAttributeSize(metaData),
+                    (metaData->IsReadOnly() ? "RO" : "RW"),
+                    (metaData->IsNonVolatile() ? " nonvolatile " : (metaData->IsExternal() ? " extern " : "  RAM  ")));
                 emberAfAttributesFlush();
                 status = emAfReadAttribute(ep->endpoint, cluster->clusterId, metaData->attributeId,
                                            (emberAfAttributeIsClient(metaData) ? CLUSTER_MASK_CLIENT : CLUSTER_MASK_SERVER),
@@ -655,9 +654,9 @@ EmberAfStatus emAfWriteAttribute(EndpointId endpoint, ClusterId cluster, Attribu
             return status;
         }
 
-        // Save the attribute to token if needed
-        // Function itself will weed out tokens that are not tokenized.
-        emAfSaveAttributeToToken(data, endpoint, cluster, metadata);
+        // Save the attribute to persistent storage if needed
+        // The callee will weed out attributes that do not need to be stored.
+        emAfSaveAttributeToStorageIfNeeded(data, endpoint, cluster, metadata);
 
         MatterReportingAttributeChangeCallback(endpoint, cluster, attributeID, mask, manufacturerCode, dataType, data);