1 /*
2  * Copyright (c) 2025 Antmicro
3  *
4  * SPDX-License-Identifier: Apache-2.0
5  */
6 
7 #ifndef _TRACE_BUFFER_H
8 #define _TRACE_BUFFER_H
9 
10 #include <stdbool.h>
11 #include <zephyr/types.h>
12 
13 #ifdef __cplusplus
14 extern "C" {
15 #endif
16 
17 /**
18  * @brief Initialize instrumentation buffer.
19  */
20 void instr_buffer_init(void);
21 
22 /**
23  * @brief Instrumentation buffer is empty or not.
24  *
25  * @return true if the ring buffer is empty, or false if not.
26  */
27 bool instr_buffer_is_empty(void);
28 
29 /**
30  * @brief Get free space in the instrumentation buffer.
31  *
32  * @return Instrumentation buffer free space (in bytes).
33  */
34 uint32_t instr_buffer_space_get(void);
35 
36 /**
37  * @brief Get instrumentation buffer capacity (max size).
38  *
39  * @return Instrumentation buffer capacity (in bytes).
40  */
41 uint32_t instr_buffer_capacity_get(void);
42 
43 /**
44  * @brief Try to allocate buffer in the instrumentation buffer.
45  *
46  * @param data Pointer to the address. It's set to a location
47  *             within the instrumentation buffer.
48  * @param size Requested buffer size (in bytes).
49  *
50  * @return Size of allocated buffer which can be smaller than
51  *         requested if there isn't enough free space or buffer wraps.
52  */
53 uint32_t instr_buffer_put_claim(uint8_t **data, uint32_t size);
54 
55 /**
56  * @brief Indicate number of bytes written to the allocated buffer.
57  *
58  * @param size Number of bytes written to the allocated buffer.
59  *
60  * @retval 0 Successful operation.
61  * @retval -EINVAL Given @a size exceeds free space of instrumentation buffer.
62  */
63 int instr_buffer_put_finish(uint32_t size);
64 
65 /**
66  * @brief Write data to instrumentation buffer.
67  *
68  * @param data Address of data.
69  * @param size Data size (in bytes).
70  *
71  * @retval Number of bytes written to instrumentation buffer.
72  */
73 uint32_t instr_buffer_put(uint8_t *data, uint32_t size);
74 
75 /**
76  * @brief Get address of the first valid data in instrumentation buffer.
77  *
78  * @param data Pointer to the address. It's set to a location pointing to
79  *             the first valid data within the instrumentation buffer.
80  * @param size Requested buffer size (in bytes).
81  *
82  * @return Size of valid buffer which can be smaller than requested
83  *         if there isn't enough valid data or buffer wraps.
84  */
85 uint32_t instr_buffer_get_claim(uint8_t **data, uint32_t size);
86 
87 /**
88  * @brief Indicate number of bytes read from claimed buffer.
89  *
90  * @param size Number of bytes read from claimed buffer.
91  *
92  * @retval 0 Successful operation.
93  * @retval -EINVAL Given @a size exceeds available data of instrumentation buffer.
94  */
95 int instr_buffer_get_finish(uint32_t size);
96 
97 /**
98  * @brief Read data from instrumentation buffer to output buffer.
99  *
100  * @param data Address of the output buffer.
101  * @param size Data size (in bytes).
102  *
103  * @retval Number of bytes written to the output buffer.
104  */
105 uint32_t instr_buffer_get(uint8_t *data, uint32_t size);
106 
107 #ifdef __cplusplus
108 }
109 #endif
110 
111 #endif
112