Line data Source code
1 : /*
2 : *
3 : * Copyright (c) 2021 Project CHIP Authors
4 : * All rights reserved.
5 : *
6 : * Licensed under the Apache License, Version 2.0 (the "License");
7 : * you may not use this file except in compliance with the License.
8 : * You may obtain a copy of the License at
9 : *
10 : * http://www.apache.org/licenses/LICENSE-2.0
11 : *
12 : * Unless required by applicable law or agreed to in writing, software
13 : * distributed under the License is distributed on an "AS IS" BASIS,
14 : * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 : * See the License for the specific language governing permissions and
16 : * limitations under the License.
17 : */
18 :
19 : /**
20 : * @file
21 : * This file defines Reporting Engine for a CHIP Interaction Model
22 : *
23 : */
24 :
25 : #pragma once
26 :
27 : #include <access/AccessControl.h>
28 : #include <app/EventReporter.h>
29 : #include <app/MessageDef/ReportDataMessage.h>
30 : #include <app/ReadHandler.h>
31 : #include <app/data-model-provider/ProviderChangeListener.h>
32 : #include <app/util/basic-types.h>
33 : #include <lib/core/CHIPCore.h>
34 : #include <lib/support/CodeUtils.h>
35 : #include <lib/support/logging/CHIPLogging.h>
36 : #include <messaging/ExchangeContext.h>
37 : #include <messaging/ExchangeMgr.h>
38 : #include <protocols/Protocols.h>
39 : #include <system/SystemPacketBuffer.h>
40 : #include <system/TLVPacketBufferBackingStore.h>
41 :
42 : namespace chip {
43 : namespace app {
44 :
45 : class InteractionModelEngine;
46 : class TestReadInteraction;
47 :
48 : namespace reporting {
49 : /*
50 : * @class Engine
51 : *
52 : * @brief The reporting engine is responsible for generating reports to reader. It is able to find the intersection
53 : * between the path interest set of each reader with what has changed in the publisher data store and generate tailored
54 : * reports for each reader.
55 : *
56 : * At its core, it tries to gather and pack as much relevant attributes changes and/or events as possible into a report
57 : * message before sending that to the reader. It continues to do so until it has no more work to do.
58 : */
59 : class Engine : public DataModel::ProviderChangeListener, public EventReporter
60 : {
61 : public:
62 : /**
63 : * Constructor Engine with a valid InteractionModelEngine pointer.
64 : */
65 : Engine(InteractionModelEngine * apImEngine);
66 :
67 : /**
68 : * Initializes the reporting engine. Should only be called once.
69 : *
70 : * @param[in] A pointer to EventManagement, should not be a nullptr.
71 : *
72 : * @retval #CHIP_NO_ERROR On success.
73 : * @retval other Was unable to retrieve data and write it into the writer.
74 : */
75 : CHIP_ERROR Init(EventManagement * apEventManagement);
76 :
77 : void Shutdown();
78 :
79 : #if CONFIG_BUILD_FOR_HOST_UNIT_TEST
80 572 : void SetWriterReserved(uint32_t aReservedSize) { mReservedSize = aReservedSize; }
81 :
82 9 : void SetMaxAttributesPerChunk(uint32_t aMaxAttributesPerChunk) { mMaxAttributesPerChunk = aMaxAttributesPerChunk; }
83 : #endif
84 :
85 : /**
86 : * Should be invoked when the device receives a Status report, or when the Report data request times out.
87 : * This allows the engine to do some clean-up.
88 : *
89 : */
90 : void OnReportConfirm();
91 :
92 : /**
93 : * Main work-horse function that executes the run-loop asynchronously on the CHIP thread
94 : */
95 : CHIP_ERROR ScheduleRun();
96 :
97 : /**
98 : * Application marks mutated change path and would be sent out in later report.
99 : */
100 : CHIP_ERROR SetDirty(const AttributePathParams & aAttributePathParams);
101 :
102 : /*
103 : * Resets the tracker that tracks the currently serviced read handler.
104 : * apReadHandler can be non-null to indicate that the reset is due to a
105 : * specific ReadHandler being deallocated.
106 : */
107 868 : void ResetReadHandlerTracker(ReadHandler * apReadHandlerBeingDeleted)
108 : {
109 868 : if (apReadHandlerBeingDeleted == mRunningReadHandler)
110 : {
111 : // Just decrement, so our increment after we finish running it will
112 : // do the right thing.
113 738 : --mCurReadHandlerIdx;
114 : }
115 : else
116 : {
117 : // No idea what to do here to make the indexing sane. Just start at
118 : // the beginning. We need to do better here; see
119 : // https://github.com/project-chip/connectedhomeip/issues/13809
120 130 : mCurReadHandlerIdx = 0;
121 : }
122 868 : }
123 :
124 20 : uint32_t GetNumReportsInFlight() const { return mNumReportsInFlight; }
125 :
126 2856 : uint64_t GetDirtySetGeneration() const { return mDirtyGeneration; }
127 :
128 : #if CONFIG_BUILD_FOR_HOST_UNIT_TEST
129 : size_t GetGlobalDirtySetSize() { return mGlobalDirtySet.Allocated(); }
130 : #endif
131 :
132 : /* ProviderChangeListener implementation */
133 : void MarkDirty(const AttributePathParams & path) override;
134 :
135 : private:
136 : /**
137 : * Main work-horse function that executes the run-loop.
138 : */
139 : void Run();
140 :
141 : friend class TestReportingEngine;
142 : friend class ::chip::app::TestReadInteraction;
143 :
144 2181 : bool IsRunScheduled() const { return mRunScheduled; }
145 :
146 : struct AttributePathParamsWithGeneration : public AttributePathParams
147 : {
148 121 : AttributePathParamsWithGeneration() {}
149 119 : AttributePathParamsWithGeneration(const AttributePathParams aPath) : AttributePathParams(aPath) {}
150 : uint64_t mGeneration = 0;
151 : };
152 :
153 : /**
154 : * Build Single Report Data including attribute changes and event data stream, and send out
155 : *
156 : */
157 : CHIP_ERROR BuildAndSendSingleReportData(ReadHandler * apReadHandler);
158 :
159 : CHIP_ERROR BuildSingleReportDataAttributeReportIBs(ReportDataMessage::Builder & reportDataBuilder, ReadHandler * apReadHandler,
160 : bool * apHasMoreChunks, bool * apHasEncodedData);
161 : CHIP_ERROR BuildSingleReportDataEventReports(ReportDataMessage::Builder & reportDataBuilder, ReadHandler * apReadHandler,
162 : bool aBufferIsUsed, bool * apHasMoreChunks, bool * apHasEncodedData);
163 :
164 : /**
165 : * Encodes StatusIB event reports for non-wildcard paths that fail to be validated:
166 : * - invalid paths (invalid endpoint/cluster id)
167 : * - failure to validate ACL (cannot fetch ACL requirement or ACL failure)
168 : *
169 : * Returns CHIP_NO_ERROR if encoding succeeds, returns error code on a fatal error (generally failure to encode EventStatusIB
170 : * values).
171 : */
172 : CHIP_ERROR CheckAccessDeniedEventPaths(TLV::TLVWriter & aWriter, bool & aHasEncodedData, ReadHandler * apReadHandler);
173 :
174 : // If version match, it means don't send, if version mismatch, it means send.
175 : // If client sends the same path with multiple data versions, client will get the data back per the spec, because at least one
176 : // of those will fail to match. This function should return false if either nothing in the list matches the given
177 : // endpoint+cluster in the path or there is an entry in the list that matches the endpoint+cluster in the path but does not
178 : // match the current data version of that cluster.
179 : bool IsClusterDataVersionMatch(const SingleLinkedListNode<DataVersionFilter> * aDataVersionFilterList,
180 : const ConcreteReadAttributePath & aPath);
181 :
182 : /**
183 : * EventReporter implementation.
184 : */
185 : CHIP_ERROR NewEventGenerated(ConcreteEventPath & aPath, uint32_t aBytesConsumed) override;
186 : void ScheduleUrgentEventDeliverySync(Optional<FabricIndex> fabricIndex = NullOptional) override;
187 :
188 : /**
189 : * Send Report via ReadHandler
190 : *
191 : */
192 : CHIP_ERROR SendReport(ReadHandler * apReadHandler, System::PacketBufferHandle && aPayload, bool aHasMoreChunks);
193 :
194 : /**
195 : * Generate and send the report data request when there exists subscription or read request
196 : *
197 : */
198 : static void Run(System::Layer * aSystemLayer, void * apAppState);
199 :
200 : CHIP_ERROR ScheduleBufferPressureEventDelivery(uint32_t aBytesWritten);
201 : void GetMinEventLogPosition(uint32_t & aMinLogPosition);
202 :
203 : /**
204 : * If the provided path is a superset of our of our existing paths, update that existing path to match the
205 : * provided path.
206 : *
207 : * Return whether one of our paths is now a superset of the provided path.
208 : */
209 : bool MergeOverlappedAttributePath(const AttributePathParams & aAttributePath);
210 :
211 : /**
212 : * If we are running out of ObjectPool for the global dirty set, we will try to merge the existing items by clusters.
213 : *
214 : * Returns whether we have released any paths.
215 : */
216 : bool MergeDirtyPathsUnderSameCluster();
217 :
218 : /**
219 : * If we are running out of ObjectPool for the global dirty set and we cannot find a slot after merging the existing items by
220 : * clusters, we will try to merge the existing items by endpoints.
221 : *
222 : * Returns whether we have released any paths.
223 : */
224 : bool MergeDirtyPathsUnderSameEndpoint();
225 :
226 : /**
227 : * During the iterating of the paths, releasing the object in the inner loop will cause undefined behavior of the ObjectPool, so
228 : * we replace the items to be cleared by a tomb first, then clear all the tombs after the iteration.
229 : *
230 : * Returns whether we have released any paths.
231 : */
232 : bool ClearTombPaths();
233 :
234 : CHIP_ERROR InsertPathIntoDirtySet(const AttributePathParams & aAttributePath);
235 :
236 5413 : inline void BumpDirtySetGeneration() { mDirtyGeneration++; }
237 :
238 : /**
239 : * Boolean to indicate if ScheduleRun is pending. This flag is used to prevent calling ScheduleRun multiple times
240 : * within the same execution context to avoid applying too much pressure on platforms that use small, fixed size event queues.
241 : *
242 : */
243 : bool mRunScheduled = false;
244 :
245 : /**
246 : * The number of report date request in flight
247 : *
248 : */
249 : uint32_t mNumReportsInFlight = 0;
250 :
251 : /**
252 : * Current read handler index
253 : *
254 : */
255 : uint32_t mCurReadHandlerIdx = 0;
256 :
257 : /**
258 : * The read handler we're calling BuildAndSendSingleReportData on right now.
259 : */
260 : ReadHandler * mRunningReadHandler = nullptr;
261 :
262 : /**
263 : * mGlobalDirtySet is used to track the set of attribute/event paths marked dirty for reporting purposes.
264 : *
265 : */
266 : #if CONFIG_BUILD_FOR_HOST_UNIT_TEST
267 : // For unit tests, always use inline allocation for code coverage.
268 : ObjectPool<AttributePathParamsWithGeneration, CHIP_IM_SERVER_MAX_NUM_DIRTY_SET, ObjectPoolMem::kInline> mGlobalDirtySet;
269 : #else
270 : ObjectPool<AttributePathParamsWithGeneration, CHIP_IM_SERVER_MAX_NUM_DIRTY_SET> mGlobalDirtySet;
271 : #endif
272 :
273 : /**
274 : * A generation counter for the dirty attrbute set.
275 : * ReadHandlers can save the generation value when generating reports.
276 : *
277 : * Then we can tell whether they might have missed reporting an attribute by
278 : * comparing its generation counter to the saved one.
279 : *
280 : * mDirtySetGeneration will increase by one when SetDirty is called.
281 : *
282 : * Count it from 1, so 0 can be used in ReadHandler to indicate "the read handler has never
283 : * completed a report".
284 : */
285 : uint64_t mDirtyGeneration = 1;
286 :
287 : #if CONFIG_BUILD_FOR_HOST_UNIT_TEST
288 : uint32_t mReservedSize = 0;
289 : uint32_t mMaxAttributesPerChunk = UINT32_MAX;
290 : #endif
291 :
292 : InteractionModelEngine * mpImEngine = nullptr;
293 :
294 : EventManagement * mpEventManagement = nullptr;
295 : };
296 :
297 : }; // namespace reporting
298 : }; // namespace app
299 : }; // namespace chip
|
