ha.h (7190B)
1 /*! \file ha.h 2 * 3 * Sample HA management definitions. 4 */ 5 /* 6 * This license is set out in https://raw.githubusercontent.com/Broadcom-Network-Switching-Software/OpenBCM/master/Legal/LICENSE file. 7 * 8 * Copyright 2007-2020 Broadcom Inc. All rights reserved. 9 */ 10 11 #ifndef DIAG_LTSW_HA_H 12 #define DIAG_LTSW_HA_H 13 14 #include <sal/sal_types.h> 15 #include <shr/shr_pb.h> 16 17 /*! The default HA file size. */ 18 #define DEFAULT_HA_FILE_SIZE 0x400000 19 20 /*! The default HA generic file size. */ 21 #define DEFAULT_HA_GEN_FILE_SIZE 0x2800 /* 10 KB */ 22 23 /*! 24 * \brief Initialize HA for a unit. 25 * This function must be called prior to device attach. 26 * 27 * \param [in] unit The unit number. 28 * \param [in] size is the total HA memory that is expected to be used for 29 * this unit. If the number is too small the system will automatically 30 * adjust to the proper size. However, it will be slightly more efficient 31 * to provide sufficient size that doesn't require any expantions. Note that 32 * significantly larger size than necessary simply consumes more memory. 33 * \param [in] enable If true enable using HA memory, otherwise implement via 34 * \c SAL alloc and free functions. 35 * \param [in] warm Indicates if this is a warm or cold boot. 36 * 37 * \return SHR_E_NONE success, otherwise failure. 38 */ 39 extern int 40 appl_ltsw_ha_unit_open(int unit, int size, int enabled, int warm); 41 42 /*! 43 * \brief Close HA files for a unit. 44 * This function closes the HA file for a given unit. It should be called 45 * post the detach functions of all modules. 46 * 47 * \param [in] unit The unit number to close. 48 * \param [in] enable Indicates if HA share memory is enabled. 49 * \param [in] warm_exit If the value of this parameter is true, it indicates 50 * that the current HA file should be kept for next (warm) boot. Otherwise, 51 * the current HA file will be erased. 52 * 53 * \return 0 if no errors, otherwise error code. 54 */ 55 extern int 56 appl_ltsw_ha_unit_close(int unit, int enabled, int warm_exit); 57 58 /*! 59 * \brief Initialize HA file for generic category. 60 * This function must be called prior to device attach. 61 * 62 * \param [in] size is the total HA memory that is expected to be used for 63 * this unit. If the number is too small the system will automatically 64 * adjust to the proper size. However, it will be slightly more efficient 65 * to provide sufficient size that doesn't require any expantions. Note that 66 * significantly larger size than necessary simply consumes more memory. 67 * \param [in] enable If true enable using HA memory, otherwise implement via 68 * \c SAL alloc and free functions. 69 * \param [in] warm Indicates if this is a warm or cold boot. 70 * 71 * \return SHR_E_NONE success, otherwise failure. 72 */ 73 extern int 74 appl_ltsw_ha_gen_open(int size, int enabled, int warm); 75 76 /*! 77 * \brief Close HA files for generic category. 78 * This function closes the HA generic file. It should be called 79 * post the detach functions of all modules. 80 * 81 * \param [in] enable Indicates if HA share memory is enabled. 82 * \param [in] warm_exit If the value of this parameter is true, it indicates 83 * that the current HA file should be kept for next (warm) boot. Otherwise, 84 * the current HA file will be erased. 85 * 86 * \return 0 if no errors, otherwise error code. 87 */ 88 extern int 89 appl_ltsw_ha_gen_close(int enabled, int warm_exit); 90 91 /*! 92 * \brief Get HA file name of the specified unit. 93 * 94 * This function can provide the HA file name in full path for the specified 95 * instance. 96 * 97 * \param [in] inst Instance number. 98 * \param [in] buf Buffer to hold the HA file path/name. 99 * \param [in] buf_size The size of \c buf. 100 * 101 * \return 0 if no errors, otherwise error code. 102 */ 103 extern int 104 appl_ltsw_ha_file_name_get(int inst, char *buf, int buf_size); 105 106 /*! 107 * \brief Get generic HA file name. 108 * 109 * This function can provide the HA generic file name in full path. 110 * 111 * \param [in] buf Buffer to hold the HA file path/name. 112 * \param [in] buf_size The size of \c buf. 113 * 114 * \return 0 if no errors, otherwise error code. 115 */ 116 extern int 117 appl_ltsw_ha_gen_file_name_get(char *buf, int buf_size); 118 119 /*! 120 * \brief Dump the system state with respect to a single unit. 121 * 122 * This function saves the current HA file content for the associated given unit 123 * into external storage. The saved content can later be compared with the 124 * running HA content using the function \ref bcma_ha_unit_state_comp(). 125 * 126 * \param [in] unit Associated with the HA state to save. 127 * \param [in] state_path The path where the state file had been stored. 128 * 129 * 130 * \retval SHR_E_NONE Success. 131 * \retval SHR_E_IO Failed to create output storage. 132 */ 133 extern int 134 appl_ltsw_ha_unit_state_dump(int unit, const char *state_path); 135 136 137 /*! 138 * \brief Compare the current system state to its store state for a single unit. 139 * 140 * This function compares the content of the system state stored in HA memory 141 * to the content that was previously saved 142 * (see \ref bcma_ha_unit_state_dump()). 143 * 144 * \param [in] unit Associated with the HA state to compare. 145 * \param [in] state_path The path where the state file had been stored. 146 * 147 * \retval SHR_E_NONE Success. 148 * \retval SHR_E_IO Failed to access the output storage. 149 * \retval SHR_E_MEMORY Failed to allocate working buffer. 150 * \retval SHR_E_FAIL Comparison failed. 151 */ 152 extern int 153 appl_ltsw_ha_unit_state_comp(int unit, const char *state_path); 154 155 /*! 156 * \brief Get the HA memory usage for the specified component name. 157 * 158 * The HA component memory usage includes per-unit memory usage and 159 * generic memory usage. The argument \c gen_mem_inc can be used to decide 160 * whether to include generic memory usage to the HA memory usage result. 161 * 162 * This function will also format the component memory usage 163 * (including per sub-id of the specified component) to print buffer 164 * if \c pb is not NULL. If \c fmt_hdr is TRUE, a header information will 165 * be first added to print buffer \c pb. 166 * 167 * \param [in] unit Unit number. 168 * \param [in] comp_name Component name. 169 * \param [in] gen_mem_inc Include HA generic memory usage if TURE. 170 * \param [in] pb Print buffer. 171 * \param [in] fmt_hdr Whether to format header to print buffer. 172 * 173 * \return The HA memory usage in bytes for component \c comp_name. 174 */ 175 extern uint32_t 176 appl_ltsw_ha_comp_mem_usage(int unit, const char *comp_name, bool gen_mem_inc, 177 shr_pb_t *pb, bool fmt_hdr); 178 179 /*! 180 * \brief Get the HA memory usage for the current device. 181 * 182 * The HA memory usage includes per-unit memory usage and generic memory usage. 183 * The argument \c gen_mem_inc can be used to decide whether to include 184 * generic memory usage to the HA memory usage result. 185 * 186 * This function will also format the HA memory usage (including per-component 187 * usage) to print buffer if \c pb is not NULL. If \c fmt_hdr is TRUE, 188 * a header information will be first added to print buffer \c pb. 189 * 190 * \param [in] unit Unit number. 191 * \param [in] gen_mem_inc Include HA generic memory usage if TURE. 192 * \param [in] pb Print buffer. 193 * \param [in] fmt_hdr Whether to format header to print buffer. 194 * 195 * \return The HA memory usage in bytes for the current device. 196 */ 197 extern uint32_t 198 appl_ltsw_ha_mem_usage(int unit, bool gen_mem_inc, shr_pb_t *pb, bool fmt_hdr); 199 200 #endif /* DIAG_LTSW_HA_H */