1 /* 2 * Arm SCP/MCP Software 3 * Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved. 4 * 5 * SPDX-License-Identifier: BSD-3-Clause 6 */ 7 #ifndef CHECKPOINT_H 8 #define CHECKPOINT_H 9 10 #include <stdbool.h> 11 #include <stdint.h> 12 13 /*! 14 * \addtogroup GroupCLIDebugger 15 * \{ 16 */ 17 18 /*! 19 * Length of checkpoint thread names. 20 * 21 */ 22 #define CHECKPOINT_NAME_LEN 16 23 24 /*! 25 * Length of checkpoint tags. 26 * 27 */ 28 #define CHECKPOINT_TAG_LEN 32 29 30 /*! 31 * Maximum number of checkpoints. 32 * 33 */ 34 #define CHECKPOINT_NUM 4 35 36 /*! 37 * \brief Checkpoint bypass value. 38 * 39 */ 40 enum cp_bypass_value { 41 /*! Stop execution when checkpoint is reached. */ 42 CHECKPOINT_ENABLED = 0, 43 /*! Ignore checkpoint */ 44 CHECKPOINT_DISABLED = -1 45 }; 46 47 /*! 48 * \brief Checkpoint descriptor 49 * 50 * \details This structure holds the proparities of a checkpoint. 51 * It should be populated by calling checkpoint_register function. 52 * 53 */ 54 typedef struct { 55 /*! Index in the checkpoint table */ 56 uint32_t index; 57 /*! Description of the function registering */ 58 char name[CHECKPOINT_NAME_LEN]; 59 /*! Tag is used to identify the checkpoint */ 60 char tag[CHECKPOINT_TAG_LEN]; 61 /*! Enable or disable the checkpoint */ 62 volatile int32_t bypass; 63 /*! Valid checkpoint in the checkpoint table */ 64 bool in_use; 65 } checkpoint_st; 66 67 /*! 68 * \brief Disables all checkpoints in the system. 69 * 70 */ 71 void checkpoint_disable_all(void); 72 73 #ifdef BUILD_HAS_DEBUGGER 74 75 /*! 76 * \brief Enables all checkpoints in the system. 77 * 78 */ 79 void checkpoint_enable_all(void); 80 81 /*! 82 * \brief Request a new checkpoint structure 83 * 84 * \param c Pointer to a checkpoint_st pointer, is set when the function returns 85 * successfully. 86 * \param name Name or description of the function registering. Must be less 87 * than CHECKPOINT_NAME_LEN characters in length. 88 * \retval ::FWK_SUCCESS if operation is successful. 89 * \retval ::FWK_E_NOMEM when checkpoints limit is reached. 90 * 91 */ 92 int32_t checkpoint_register(checkpoint_st **c, char *name); 93 94 /*! 95 * \brief Insert a checkpoint 96 * 97 * \details Checkpoint function for use within code. When this function is 98 * called and checkpoints are disabled, it will return immediately. 99 * If checkpoints are enabled, it will print a message indicating that 100 * it is pausing and activate the CLI. When the command line exists This 101 * function will return and normal execution is resumed. 102 * 103 * \param c Pointer to valid checkpoint structure, obtained through a call to 104 * checkpoint_register. 105 * \param file Name of the file in which the checkpoint exists, 106 * use __FILE__ macro. 107 * \param line Line number of the checkpoint, use __LINE__ macro. 108 * \param tag Checkpoint tag string. 109 */ 110 void checkpoint(checkpoint_st *c, char *file, int32_t line, char *tag); 111 112 #else 113 114 /*! 115 * \brief Enables all checkpoints in the system. 116 * 117 */ 118 #define checkpoint_enable_all() (void)0 119 120 /*! 121 * \brief Request a new checkpoint structure 122 * 123 * \param c Pointer to a checkpoint_st pointer, is set when the function returns 124 * successfully. 125 * \param name Name or description of the function registering. Must be less 126 * than CHECKPOINT_NAME_LEN characters in length. 127 * \retval ::FWK_SUCCESS if operation is successful. 128 * \retval ::FWK_E_NOMEM when checkpoints limit is reached. 129 * 130 */ 131 # define checkpoint_register(c, name) \ 132 ({ \ 133 (void)c; \ 134 (void)name; \ 135 FWK_SUCCESS; \ 136 }) 137 138 /*! 139 * \brief Insert a checkpoint 140 * 141 * \details Checkpoint function for use within code. When this function is 142 * called and checkpoints are disabled, it will return immediately. 143 * If checkpoints are enabled, it will print a message indicating that 144 * it is pausing and activate the CLI. When the command line exists This 145 * function will return and normal execution is resumed. 146 * 147 * \param c Pointer to valid checkpoint structure, obtained through a call to 148 * checkpoint_register. 149 * \param file Name of the file in which the checkpoint exists, 150 * use __FILE__ macro. 151 * \param line Line number of the checkpoint, use __LINE__ macro. 152 * \param tag Checkpoint tag string. 153 */ 154 # define checkpoint(c, file, line, tag) \ 155 do { \ 156 (void)c; \ 157 (void)file; \ 158 (void)line; \ 159 (void)tag; \ 160 } while (0) 161 162 #endif 163 164 /*! 165 * \} 166 */ 167 168 #endif /* CHECKPOINT_H */ 169