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_ */
|
