Line data Source code
1 1 : /* 2 : * Copyright Meta Platforms, Inc. and its affiliates. 3 : * 4 : * SPDX-License-Identifier: Apache-2.0 5 : */ 6 : 7 : /** 8 : * @file 9 : * @brief Public APIs for coredump pseudo-device driver 10 : */ 11 : 12 : #ifndef INCLUDE_ZEPHYR_DRIVERS_COREDUMP_H_ 13 : #define INCLUDE_ZEPHYR_DRIVERS_COREDUMP_H_ 14 : 15 : #include <zephyr/device.h> 16 : #include <zephyr/sys/slist.h> 17 : 18 : #ifdef __cplusplus 19 : extern "C" { 20 : #endif 21 : 22 : /** 23 : * @brief Coredump pseudo-device driver APIs 24 : * @defgroup coredump_device_interface Coredump pseudo-device driver APIs 25 : * @ingroup io_interfaces 26 : * @{ 27 : */ 28 : 29 : /** 30 : * @brief Structure describing a region in memory that may be 31 : * stored in core dump at the time it is generated 32 : * 33 : * Instances of this are passed to the coredump_device_register_memory() and 34 : * coredump_device_unregister_memory() functions to indicate addition and removal 35 : * of memory regions to be captured 36 : */ 37 1 : struct coredump_mem_region_node { 38 : /** Node of single-linked list, do not modify */ 39 1 : sys_snode_t node; 40 : 41 : /** Address of start of memory region */ 42 1 : uintptr_t start; 43 : 44 : /** Size of memory region */ 45 1 : size_t size; 46 : }; 47 : 48 : /** 49 : * @brief Callback that occurs at dump time, data copied into dump_area will 50 : * be included in the dump that is generated 51 : * 52 : * @param dump_area Pointer to area to copy data into for inclusion in dump 53 : * @param dump_area_size Size of available memory at dump_area 54 : */ 55 1 : typedef void (*coredump_dump_callback_t)(uintptr_t dump_area, size_t dump_area_size); 56 : 57 : /** 58 : * @cond INTERNAL_HIDDEN 59 : * 60 : * For internal use only, skip these in public documentation. 61 : */ 62 : 63 : /* 64 : * Type definition of coredump API function for adding specified 65 : * data into coredump 66 : */ 67 : typedef void (*coredump_device_dump_t)(const struct device *dev); 68 : 69 : /* 70 : * Type definition of coredump API function for registering a memory 71 : * region 72 : */ 73 : typedef bool (*coredump_device_register_memory_t)(const struct device *dev, 74 : struct coredump_mem_region_node *region); 75 : 76 : /* 77 : * Type definition of coredump API function for unregistering a memory 78 : * region 79 : */ 80 : typedef bool (*coredump_device_unregister_memory_t)(const struct device *dev, 81 : struct coredump_mem_region_node *region); 82 : 83 : /* 84 : * Type definition of coredump API function for registering a dump 85 : * callback 86 : */ 87 : typedef bool (*coredump_device_register_callback_t)(const struct device *dev, 88 : coredump_dump_callback_t callback); 89 : 90 : /* 91 : * API which a coredump pseudo-device driver should expose 92 : */ 93 : __subsystem struct coredump_driver_api { 94 : coredump_device_dump_t dump; 95 : coredump_device_register_memory_t register_memory; 96 : coredump_device_unregister_memory_t unregister_memory; 97 : coredump_device_register_callback_t register_callback; 98 : }; 99 : 100 : /** 101 : * @endcond 102 : */ 103 : 104 : /** 105 : * @brief Register a region of memory to be stored in core dump at the 106 : * time it is generated 107 : * 108 : * @param dev Pointer to the device structure for the driver instance. 109 : * @param region Struct describing memory to be collected 110 : * 111 : * @return true if registration succeeded 112 : * @return false if registration failed 113 : */ 114 1 : static inline bool coredump_device_register_memory(const struct device *dev, 115 : struct coredump_mem_region_node *region) 116 : { 117 : const struct coredump_driver_api *api = 118 : (const struct coredump_driver_api *)dev->api; 119 : 120 : return api->register_memory(dev, region); 121 : } 122 : 123 : /** 124 : * @brief Unregister a region of memory to be stored in core dump at the 125 : * time it is generated 126 : * 127 : * @param dev Pointer to the device structure for the driver instance. 128 : * @param region Struct describing memory to be collected 129 : * 130 : * @return true if unregistration succeeded 131 : * @return false if unregistration failed 132 : */ 133 1 : static inline bool coredump_device_unregister_memory(const struct device *dev, 134 : struct coredump_mem_region_node *region) 135 : { 136 : const struct coredump_driver_api *api = 137 : (const struct coredump_driver_api *)dev->api; 138 : 139 : return api->unregister_memory(dev, region); 140 : } 141 : 142 : /** 143 : * @brief Register a callback to be invoked at dump time 144 : * 145 : * @param dev Pointer to the device structure for the driver instance. 146 : * @param callback Callback to be invoked at dump time 147 : * 148 : * @return true if registration succeeded 149 : * @return false if registration failed 150 : */ 151 1 : static inline bool coredump_device_register_callback(const struct device *dev, 152 : coredump_dump_callback_t callback) 153 : { 154 : const struct coredump_driver_api *api = 155 : (const struct coredump_driver_api *)dev->api; 156 : 157 : return api->register_callback(dev, callback); 158 : } 159 : 160 : /** 161 : * @} 162 : */ 163 : 164 : #ifdef __cplusplus 165 : } 166 : #endif 167 : 168 : #endif /* INCLUDE_ZEPHYR_DRIVERS_COREDUMP_H_ */
