1 /*
2  * Copyright (c) 2019 Intel corporation
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 tracing buffer.
19  */
20 void tracing_buffer_init(void);
21 
22 /**
23  * @brief Tracing buffer is empty or not.
24  *
25  * @return true if the ring buffer is empty, or false if not.
26  */
27 bool tracing_buffer_is_empty(void);
28 
29 /**
30  * @brief Get free space in the tracing buffer.
31  *
32  * @return Tracing buffer free space (in bytes).
33  */
34 uint32_t tracing_buffer_space_get(void);
35 
36 /**
37  * @brief Get tracing buffer capacity (max size).
38  *
39  * @return Tracing buffer capacity (in bytes).
40  */
41 uint32_t tracing_buffer_capacity_get(void);
42 
43 /**
44  * @brief Try to allocate buffer in the tracing buffer.
45  *
46  * @param data Pointer to the address. It's set to a location
47  *             within the tracing 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 tracing_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 tracing buffer.
62  */
63 int tracing_buffer_put_finish(uint32_t size);
64 
65 /**
66  * @brief Write data to tracing buffer.
67  *
68  * @param data Address of data.
69  * @param size Data size (in bytes).
70  *
71  * @retval Number of bytes written to tracing buffer.
72  */
73 uint32_t tracing_buffer_put(uint8_t *data, uint32_t size);
74 
75 /**
76  * @brief Get address of the first valid data in tracing buffer.
77  *
78  * @param data Pointer to the address. It's set to a location pointing to
79  *             the first valid data within the tracing 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 tracing_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 tracing buffer.
94  */
95 int tracing_buffer_get_finish(uint32_t size);
96 
97 /**
98  * @brief Read data from tracing 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 tracing_buffer_get(uint8_t *data, uint32_t size);
106 
107 /**
108  * @brief Get buffer from tracing command buffer.
109  *
110  * @param data Pointer to tracing command buffer start address.
111  *
112  * @return Tracing command buffer size (in bytes).
113  */
114 uint32_t tracing_cmd_buffer_alloc(uint8_t **data);
115 
116 #ifdef __cplusplus
117 }
118 #endif
119 
120 #endif
121