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