Split out non-codegen callback logic from callbacks.h into separate header (#23617)

* Move all non-codegen callbacks into a separate header file. Compilation still needs to be fixed

* Update some ember files so that at least chip-tool compiles. Only generic callbacks are required

* Add back callbacks.h to the attribute storage header

* Minor comment update

* Restyle

Author: andy31415

src/app/util/attribute-storage.cpp

@@ -21,13 +21,21 @@
 #include <app/reporting/reporting.h>
 #include <app/util/af.h>
 #include <app/util/attribute-storage.h>
+#include <app/util/generic-callbacks.h>
 #include <lib/support/CodeUtils.h>
 #include <lib/support/logging/CHIPLogging.h>
 #include <platform/LockTracker.h>
 
-#include <app-common/zap-generated/attribute-type.h>
+// Attribute storage depends on knowing the current layout/setup of attributes
+// and corresponding callbacks. Specifically:
+//   - zap-generated/callback.h is needed because endpoint_config will call the
+//     corresponding callbacks (via GENERATED_FUNCTION_ARRAYS) and the include
+//     for it is:
+//       util/common.h
+//           -> util/af.h
+//           -> util/config.h
+//           -> zap-generated/endpoint_config.h
 #include <app-common/zap-generated/callback.h>
-#include <app-common/zap-generated/ids/Attributes.h>
 
 using namespace chip;
 

src/app/util/attribute-table.cpp

@@ -21,8 +21,8 @@
 
 // for pulling in defines dealing with EITHER server or client
 #include "app/util/common.h"
-#include <app-common/zap-generated/callback.h>
 #include <app/util/error-mapping.h>
+#include <app/util/generic-callbacks.h>
 #include <app/util/odd-sized-integers.h>
 
 #include <app/reporting/reporting.h>

src/app/util/generic-callbacks.h

@@ -0,0 +1,197 @@
+/*
+ *
+ *    Copyright (c) 2022 Project CHIP Authors
+ *
+ *    Licensed under the Apache License, Version 2.0 (the "License");
+ *    you may not use this file except in compliance with the License.
+ *    You may obtain a copy of the License at
+ *
+ *        http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *    Unless required by applicable law or agreed to in writing, software
+ *    distributed under the License is distributed on an "AS IS" BASIS,
+ *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *    See the License for the specific language governing permissions and
+ *    limitations under the License.
+ */
+
+#pragma once
+
+#include <app-common/zap-generated/af-structs.h>
+#include <app-common/zap-generated/cluster-objects.h>
+#include <app/util/af-types.h>
+#include <app/util/attribute-metadata.h>
+#include <app/util/basic-types.h>
+
+#include <app/CommandHandler.h>
+#include <app/CommandSender.h>
+#include <app/ConcreteAttributePath.h>
+#include <app/ConcreteCommandPath.h>
+#include <lib/support/Span.h>
+#include <protocols/interaction_model/Constants.h>
+
+/** @brief Cluster Init
+ *
+ * This function is called when a specific cluster is initialized. It gives the
+ * application an opportunity to take care of cluster initialization procedures.
+ * It is called exactly once for each endpoint where cluster is present.
+ *
+ * @param endpoint   Ver.: always
+ * @param clusterId   Ver.: always
+ */
+void emberAfClusterInitCallback(chip::EndpointId endpoint, chip::ClusterId clusterId);
+
+/** @brief Allow Network Write Attribute
+ *
+ * This function is called by the application framework before it writes an
+ * attribute in response to a write attribute request from an external device.
+ * The value passed into this callback is the value to which the attribute is to
+ * be set by the framework.
+        Example:    In mirroring simple metering data
+ * on an Energy Services Interface (ESI) (formerly called Energy Service Portal
+ * (ESP) in SE 1.0).), a mirrored simple meter needs to write read-only
+ * attributes on its mirror. The-meter-mirror sample application, located in
+ * app/framework/sample-apps, uses this callback to allow the mirrored device to
+ * write simple metering attributes on the mirror regardless of the fact that
+ * most simple metering attributes are defined as read-only by the ZigBee
+ * specification.
+        Note:   The ZCL specification does not (as of this
+ * writing) specify any permission-level security for writing writeable
+ * attributes. As far as the ZCL specification is concerned, if an attribute is
+ * writeable, any device that has a link key for the device should be able to
+ * write that attribute. Furthermore if an attribute is read only, it should not
+ * be written over the air. Thus, if you implement permissions for writing
+ * attributes as a feature, you MAY be operating outside the specification. This
+ * is unlikely to be a problem for writing read-only attributes, but it may be a
+ * problem for attributes that are writeable according to the specification but
+ * restricted by the application implementing this callback.
+ */
+EmberAfAttributeWritePermission emberAfAllowNetworkWriteAttributeCallback(chip::EndpointId endpoint, chip::ClusterId clusterId,
+                                                                          chip::AttributeId attributeId, uint8_t * value,
+                                                                          uint8_t type);
+
+/** @brief Attribute Read Access
+ *
+ * This function is called whenever the Application Framework needs to check
+ * access permission for an attribute read.
+ */
+bool emberAfAttributeReadAccessCallback(chip::EndpointId endpoint, chip::ClusterId clusterId, chip::AttributeId attributeId);
+
+/** @brief Attribute Write Access
+ *
+ * This function is called whenever the Application Framework needs to check
+ * access permission for an attribute write.
+ */
+bool emberAfAttributeWriteAccessCallback(chip::EndpointId endpoint, chip::ClusterId clusterId, chip::AttributeId attributeId);
+
+/** @brief External Attribute Read
+ *
+ * Like emberAfExternalAttributeWriteCallback above, this function is called
+ * when the framework needs to read an attribute that is not stored within the
+ * Application Framework's data structures.
+        All of the important
+ * information about the attribute itself is passed as a pointer to an
+ * EmberAfAttributeMetadata struct, which is stored within the application and
+ * used to manage the attribute. A complete description of the
+ * EmberAfAttributeMetadata struct is provided in
+ * app/framework/include/af-types.h
+        This function assumes that the
+ * application is able to read the attribute, write it into the passed buffer,
+ * and return immediately. Any attributes that require a state machine for
+ * reading and writing are not really candidates for externalization at the
+ * present time. The Application Framework does not currently include a state
+ * machine for reading or writing attributes that must take place across a
+ * series of application ticks. Attributes that cannot be read in a timely
+ * manner should be stored within the Application Framework and updated
+ * occasionally by the application code from within the
+ * emberAfMainTickCallback.
+        If the application was successfully able to
+ * read the attribute and write it into the passed buffer, it should return a
+ * value of EMBER_ZCL_STATUS_SUCCESS. Ensure that the size of the externally
+ * managed attribute value is smaller than what the buffer can hold. In the case
+ * of a buffer overflow throw an appropriate error such as
+ * EMBER_ZCL_STATUS_INSUFFICIENT_SPACE. Any other return value indicates the
+ * application was not able to read the attribute.
+ */
+EmberAfStatus emberAfExternalAttributeReadCallback(chip::EndpointId endpoint, chip::ClusterId clusterId,
+                                                   const EmberAfAttributeMetadata * attributeMetadata, uint8_t * buffer,
+                                                   uint16_t maxReadLength);
+
+/** @brief External Attribute Write
+ *
+ * This function is called whenever the Application Framework needs to write an
+ * attribute which is not stored within the data structures of the Application
+ * Framework itself. One of the new features in Version 2 is the ability to
+ * store attributes outside the Framework. This is particularly useful for
+ * attributes that do not need to be stored because they can be read off the
+ * hardware when they are needed, or are stored in some central location used by
+ * many modules within the system. In this case, you can indicate that the
+ * attribute is stored externally. When the framework needs to write an external
+ * attribute, it makes a call to this callback.
+        This callback is very
+ * useful for host micros which need to store attributes in persistent memory.
+ * Because each host micro (used with an Ember NCP) has its own type of
+ * persistent memory storage, the Application Framework does not include the
+ * ability to mark attributes as stored in flash the way that it does for Ember
+ * SoCs like the EM35x. On a host micro, any attributes that need to be stored
+ * in persistent memory should be marked as external and accessed through the
+ * external read and write callbacks. Any host code associated with the
+ * persistent storage should be implemented within this callback.
+        All of
+ * the important information about the attribute itself is passed as a pointer
+ * to an EmberAfAttributeMetadata struct, which is stored within the application
+ * and used to manage the attribute. A complete description of the
+ * EmberAfAttributeMetadata struct is provided in
+ * app/framework/include/af-types.h.
+        This function assumes that the
+ * application is able to write the attribute and return immediately. Any
+ * attributes that require a state machine for reading and writing are not
+ * candidates for externalization at the present time. The Application Framework
+ * does not currently include a state machine for reading or writing attributes
+ * that must take place across a series of application ticks. Attributes that
+ * cannot be written immediately should be stored within the Application
+ * Framework and updated occasionally by the application code from within the
+ * emberAfMainTickCallback.
+        If the application was successfully able to
+ * write the attribute, it returns a value of EMBER_ZCL_STATUS_SUCCESS. Any
+ * other return value indicates the application was not able to write the
+ * attribute.
+ */
+EmberAfStatus emberAfExternalAttributeWriteCallback(chip::EndpointId endpoint, chip::ClusterId clusterId,
+                                                    const EmberAfAttributeMetadata * attributeMetadata, uint8_t * buffer);
+
+/** @brief Registration Abort
+ *
+ * This callback is called when the device should abort the registration
+ * process.
+ *
+ */
+void emberAfRegistrationAbortCallback();
+
+/** @brief Start Move
+ *
+ * This function is called to initiate the process for a device to move (rejoin)
+ * to a new parent.
+ *
+ */
+bool emberAfStartMoveCallback();
+
+/** @brief Pre Attribute Change
+ *
+ * This function is called by the application framework before it changes an
+ * attribute value.  The value passed into this callback is the value to which
+ * the attribute is to be set by the framework.  The application should return
+ * chip::Protocols::InteractionModel::Status::Success to permit the change or
+ * any other code to reject it.
+ */
+chip::Protocols::InteractionModel::Status MatterPreAttributeChangeCallback(const chip::app::ConcreteAttributePath & attributePath,
+                                                                           uint8_t type, uint16_t size, uint8_t * value);
+
+/** @brief Post Attribute Change
+ *
+ * This function is called by the application framework after it changes an
+ * attribute value. The value passed into this callback is the value to which
+ * the attribute was set by the framework.
+ */
+void MatterPostAttributeChangeCallback(const chip::app::ConcreteAttributePath & attributePath, uint8_t type, uint16_t size,
+                                       uint8_t * value);

src/app/util/util.cpp

@@ -18,13 +18,13 @@
 #include "app/util/common.h"
 #include <app-common/zap-generated/attribute-id.h>
 #include <app-common/zap-generated/attribute-type.h>
-#include <app-common/zap-generated/callback.h>
 #include <app-common/zap-generated/cluster-id.h>
 #include <app-common/zap-generated/command-id.h>
 #include <app-common/zap-generated/print-cluster.h>
 #include <app/util/af-event.h>
 #include <app/util/af.h>
 #include <app/util/ember-compatibility-functions.h>
+#include <app/util/generic-callbacks.h>
 
 // TODO: figure out a clear path for compile-time codegen
 #include <app/PluginApplicationCallbacks.h>