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 struct coredump_mem_region_node {
38 /** Node of single-linked list, do not modify */
39 sys_snode_t node;
40
41 /** Address of start of memory region */
42 uintptr_t start;
43
44 /** Size of memory region */
45 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 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 */
coredump_device_register_memory(const struct device * dev,struct coredump_mem_region_node * region)114 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 */
coredump_device_unregister_memory(const struct device * dev,struct coredump_mem_region_node * region)133 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 */
coredump_device_register_callback(const struct device * dev,coredump_dump_callback_t callback)151 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_ */
169
