src/system/SystemFaultInjection.h

   1 /*
   2  *
   3  *    Copyright (c) 2020 Project CHIP Authors
   4  *    Copyright (c) 2016-2017 Nest Labs, Inc.
   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  *      Header file for the fault-injection utilities for CHIP System Layer.
  22  */
  23
  24 #pragma once
  25
  26 #include <system/SystemConfig.h>
  27
  28 #if CHIP_SYSTEM_CONFIG_TEST && CHIP_WITH_NLFAULTINJECTION
  29
  30 #include <nlfaultinjection.hpp>
  31
  32 #include <support/DLLUtil.h>
  33
  34 namespace chip {
  35 namespace System {
  36 namespace FaultInjection {
  37
  38 using nl::FaultInjection::Manager;
  39
  40 /**
  41  * @brief   Fault injection points
  42  *
  43  * @details
  44  * Each point in the code at which a fault can be injected
  45  * is identified by a member of this enum.
  46  */
  47 typedef enum
  48 {
  49     kFault_PacketBufferNew,  /**< Fail the allocation of a PacketBuffer */
  50     kFault_TimeoutImmediate, /**< Override the timeout value of a timer being started with 0 */
  51     kFault_AsyncEvent,       /**< Inject asynchronous events; when the fault is enabled, it expects
  52                                   one integer argument, which is passed to application to signal the event
  53                                   to be injected; @see CHIP_SYSTEM_FAULT_INJECT_ASYNC_EVENT */
  54     kFault_NumberOfFaultIdentifiers,
  55 } Id;
  56
  57 DLL_EXPORT nl::FaultInjection::Manager & GetManager();
  58
  59 /**
  60  * Callback to the application that returns how many asynchronous events the application could
  61  * inject at the time of the call.
  62  *
  63  * @return The number of events
  64  */
  65 typedef int32_t (*GetNumEventsAvailableCb)();
  66
  67 /**
  68  * Callback to the application to inject the asynchronous event specified by argument.
  69  *
  70  * @param[in]   aEventIndex     An index (0 to the value returned by GetNumEventsAvailableCb -1)
  71  *                              that identifies the event to be injected.
  72  */
  73 typedef void (*InjectAsyncEventCb)(int32_t aEventIndex);
  74
  75 /**
  76  * Store the GetNumEventsAvailableCb and InjectAsyncEventCb callbacks used by
  77  * @see CHIP_SYSTEM_FAULT_INJECT_ASYNC_EVENT
  78  *
  79  * @param[in] aGetNumEventsAvailable    A GetNumEventsAvailableCb
  80  * @param[in] aInjectAsyncEvent         An InjectAsyncEventCb
  81  *
  82  */
  83 DLL_EXPORT void SetAsyncEventCallbacks(GetNumEventsAvailableCb aGetNumEventsAvailable, InjectAsyncEventCb aInjectAsyncEvent);
  84
  85 /**
  86  * @see CHIP_SYSTEM_FAULT_INJECT_ASYNC_EVENT
  87  */
  88 DLL_EXPORT void InjectAsyncEvent();
  89
  90 } // namespace FaultInjection
  91 } // namespace System
  92 } // namespace chip
  93
  94 /**
  95  * Execute the statements included if the System fault is
  96  * to be injected.
  97  *
  98  * @param[in] aFaultID      A System fault-injection id
  99  * @param[in] aStatements   Statements to be executed if the fault is enabled.
 100  */
 101 #define CHIP_SYSTEM_FAULT_INJECT(aFaultId, aStatement)                                                                             \
 102     nlFAULT_INJECT(::chip::System::FaultInjection::GetManager(), aFaultId, aStatement)
 103
 104 /**
 105  * This macro implements the injection of asynchronous events.
 106  *
 107  * It polls the application by calling the GetNumEventsAvailableCb callback
 108  * to know if there are asynchronous events that can be injected.
 109  * If there are any, it instances kFault_AsyncEvent.
 110  * If the fault is to be injected, the code injected calls the InjectAsyncEventCb
 111  * callback passing the integer argument stored in the fault Record.
 112  * If the fault is not configured (and therefore no arguments are stored in the Record)
 113  * the macro stores the return value of GetNumEventsAvailableCb into the Records arguments,
 114  * so that the application can log it from a callback installed into the fault.
 115  */
 116 #define CHIP_SYSTEM_FAULT_INJECT_ASYNC_EVENT()                                                                                     \
 117     do                                                                                                                             \
 118     {                                                                                                                              \
 119         chip::System::FaultInjection::InjectAsyncEvent();                                                                          \
 120     } while (0)
 121
 122 #else // CHIP_SYSTEM_CONFIG_TEST
 123
 124 #define CHIP_SYSTEM_FAULT_INJECT(aFaultId, aStatement)
 125
 126 #define CHIP_SYSTEM_FAULT_INJECT_ASYNC_EVENT()
 127
 128 #endif // CHIP_SYSTEM_CONFIG_TEST