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