Line data    Source code

       1             : /**
       2             :  *
       3             :  *    Copyright (c) 2021 Project CHIP Authors
       4             :  *
       5             :  *    Licensed under the Apache License, Version 2.0 (the "License");
       6             :  *    you may not use this file except in compliance with the License.
       7             :  *    You may obtain a copy of the License at
       8             :  *
       9             :  *        http://www.apache.org/licenses/LICENSE-2.0
      10             :  *
      11             :  *    Unless required by applicable law or agreed to in writing, software
      12             :  *    distributed under the License is distributed on an "AS IS" BASIS,
      13             :  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      14             :  *    See the License for the specific language governing permissions and
      15             :  *    limitations under the License.
      16             :  */
      17             : 
      18             : #pragma once
      19             : 
      20             : #include <access/SubjectDescriptor.h>
      21             : #include <app/EventPathParams.h>
      22             : #include <app/ObjectList.h>
      23             : #include <app/util/basic-types.h>
      24             : #include <lib/core/CHIPCore.h>
      25             : #include <lib/core/Optional.h>
      26             : #include <lib/core/TLV.h>
      27             : #include <system/SystemPacketBuffer.h>
      28             : 
      29             : inline constexpr size_t kNumPriorityLevel = 3;
      30             : namespace chip {
      31             : namespace app {
      32             : 
      33             : /**
      34             :  * @brief
      35             :  *   The Priority of the log entry.
      36             :  *
      37             :  * @details
      38             :  * Priority is used as a way to filter events before they are
      39             :  * actually emitted into the log. After the event is in the log, we
      40             :  * make no further provisions to expunge it from the log.
      41             :  * The priority level serves to prioritize event storage. If an
      42             :  * event of high priority is added to a full buffer, events are
      43             :  * dropped in order of priority (and age) to accommodate it. As such,
      44             :  * priority levels only have relative value. If a system is
      45             :  * using only one priority level, events are dropped only in order
      46             :  * of age, like a ring buffer.
      47             :  */
      48             : 
      49             : enum class PriorityLevel : uint8_t
      50             : {
      51             : 
      52             :     First = 0,
      53             :     /**
      54             :      *  Debug priority denotes log entries of interest to the
      55             :      *  developers of the system and is used primarily in the
      56             :      *  development phase. Debug priority logs are
      57             :      *  not accounted for in the bandwidth or power budgets of the
      58             :      *  constrained devices; as a result, they must be used only over
      59             :      *  a limited time span in production systems.
      60             :      */
      61             : 
      62             :     Debug = First,
      63             :     /**
      64             :      * Info priority denotes log entries that provide extra insight
      65             :      * and diagnostics into the running system. Info logging level may
      66             :      * be used over an extended period of time in a production system,
      67             :      * or may be used as the default log level in a field trial. On
      68             :      * the constrained devices, the entries logged with Info level must
      69             :      * be accounted for in the bandwidth and memory budget, but not in
      70             :      * the power budget.
      71             :      */
      72             :     Info = 1,
      73             : 
      74             :     /**
      75             :      * Critical priority denotes events whose loss would
      76             :      * directly impact customer-facing features. Applications may use
      77             :      * loss of Production Critical events to indicate system failure.
      78             :      * On constrained devices, entries logged with Critical
      79             :      * priority must be accounted for in the power and memory budget,
      80             :      * as it is expected that they are always logged and offloaded
      81             :      * from the device.
      82             :      */
      83             :     Critical = 2,
      84             :     Last     = Critical,
      85             :     Invalid  = Last + 1,
      86             : 
      87             : };
      88             : 
      89             : static_assert(sizeof(std::underlying_type_t<PriorityLevel>) <= sizeof(unsigned),
      90             :               "Logging that converts PriorityLevel to unsigned will be lossy");
      91             : 
      92             : /**
      93             :  * @brief
      94             :  *   The struct that provides an application set System or Epoch timestamp.
      95             :  */
      96             : struct Timestamp
      97             : {
      98             :     enum class Type : uint8_t
      99             :     {
     100             :         kSystem = 0,
     101             :         kEpoch
     102             :     };
     103         568 :     Timestamp() {}
     104        5010 :     Timestamp(Type aType, uint64_t aValue) : mType(aType), mValue(aValue) {}
     105             :     Timestamp(System::Clock::Timestamp aValue) : mType(Type::kSystem), mValue(aValue.count()) {}
     106        4998 :     static Timestamp Epoch(System::Clock::Timestamp aValue)
     107             :     {
     108        4998 :         Timestamp timestamp(Type::kEpoch, aValue.count());
     109        4998 :         return timestamp;
     110             :     }
     111          12 :     static Timestamp System(System::Clock::Timestamp aValue)
     112             :     {
     113          12 :         Timestamp timestamp(Type::kSystem, aValue.count());
     114          12 :         return timestamp;
     115             :     }
     116             : 
     117        1324 :     bool IsSystem() const { return mType == Type::kSystem; }
     118           0 :     bool IsEpoch() const { return mType == Type::kEpoch; }
     119             : 
     120             :     Type mType      = Type::kSystem;
     121             :     uint64_t mValue = 0;
     122             : };
     123             : 
     124             : /**
     125             :  *   The structure that provides options for the different event fields.
     126             :  */
     127             : class EventOptions
     128             : {
     129             : public:
     130           0 :     EventOptions() : mPriority(PriorityLevel::Invalid) {}
     131         662 :     EventOptions(Timestamp aTimestamp) : mTimestamp(aTimestamp), mPriority(PriorityLevel::Invalid) {}
     132             :     ConcreteEventPath mPath;
     133             :     Timestamp mTimestamp;
     134             :     PriorityLevel mPriority = PriorityLevel::Invalid;
     135             :     // kUndefinedFabricIndex 0 means not fabric associated at all
     136             :     FabricIndex mFabricIndex = kUndefinedFabricIndex;
     137             : };
     138             : 
     139             : /**
     140             :  * @brief
     141             :  *   Structure for copying event lists on output.
     142             :  */
     143             : struct EventLoadOutContext
     144             : {
     145        2216 :     EventLoadOutContext(TLV::TLVWriter & aWriter, PriorityLevel aPriority, EventNumber aStartingEventNumber) :
     146        2216 :         mWriter(aWriter), mPriority(aPriority), mStartingEventNumber(aStartingEventNumber), mCurrentEventNumber(0), mFirst(true)
     147        2216 :     {}
     148             : 
     149             :     TLV::TLVWriter & mWriter;
     150             :     PriorityLevel mPriority          = PriorityLevel::Invalid;
     151             :     EventNumber mStartingEventNumber = 0;
     152             :     Timestamp mPreviousTime;
     153             :     Timestamp mCurrentTime;
     154             :     EventNumber mCurrentEventNumber                            = 0;
     155             :     size_t mEventCount                                         = 0;
     156             :     const ObjectList<EventPathParams> * mpInterestedEventPaths = nullptr;
     157             :     bool mFirst                                                = true;
     158             :     Access::SubjectDescriptor mSubjectDescriptor;
     159             : };
     160             : } // namespace app
     161             : } // namespace chip