1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
|
/* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */
/*
*
* (C) COPYRIGHT 2019-2021 ARM Limited. All rights reserved.
*
* This program is free software and is provided to you under the terms of the
* GNU General Public License version 2 as published by the Free Software
* Foundation, and any use by you of this program is subject to the terms
* of such GNU license.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, you can access it online at
* http://www.gnu.org/licenses/gpl-2.0.html.
*
*/
/*
* mali_kbase_kinstr_jm.h
* Kernel driver public interface to job manager atom tracing. This API provides
* a method to get the atom state changes into user space.
*
* The flow of operation is:
*
* | kernel | user |
* | ----------------------------------- | ----------------------------------- |
* | Initialize API with | |
* | kbase_kinstr_jm_init() | |
* | | |
* | Kernel code injects states with | |
* | kbase_kinstr_jm_atom_state_*() APIs | |
* | | Call ioctl() to get file descriptor |
* | | via KBASE_IOCTL_KINSTR_JM_FD |
* | Allocates a reader attached to FD | |
* | Allocates circular buffer and | |
* | patches, via ASM goto, the | |
* | kbase_kinstr_jm_atom_state_*() | |
* | | loop: |
* | | Call poll() on FD for POLLIN |
* | When threshold of changes is hit, | |
* | the poll is interrupted with | |
* | POLLIN. If circular buffer is | |
* | full then store the missed count | |
* | and interrupt poll | Call read() to get data from |
* | | circular buffer via the fd |
* | Kernel advances tail of circular | |
* | buffer | |
* | | Close file descriptor |
* | Deallocates circular buffer | |
* | | |
* | Terminate API with | |
* | kbase_kinstr_jm_term() | |
*
* All tracepoints are guarded on a static key. The static key is activated when
* a user space reader gets created. This means that there is negligible cost
* inserting the tracepoints into code when there are no readers.
*/
#ifndef _KBASE_KINSTR_JM_H_
#define _KBASE_KINSTR_JM_H_
#include <uapi/gpu/arm/midgard/mali_kbase_kinstr_jm_reader.h>
#ifdef __KERNEL__
#include <linux/version.h>
#include <linux/static_key.h>
#else
/* empty wrapper macros for userspace */
#define static_branch_unlikely(key) (1)
#define KERNEL_VERSION(a, b, c) (0)
#define LINUX_VERSION_CODE (1)
#endif /* __KERNEL__ */
/* Forward declarations */
struct kbase_context;
struct kbase_kinstr_jm;
struct kbase_jd_atom;
union kbase_kinstr_jm_fd;
/**
* kbase_kinstr_jm_init() - Initialise an instrumentation job manager context.
* @ctx: Non-NULL pointer to where the pointer to the created context will
* be stored on success.
*
* Return: 0 on success, else error code.
*/
int kbase_kinstr_jm_init(struct kbase_kinstr_jm **ctx);
/**
* kbase_kinstr_jm_term() - Terminate an instrumentation job manager context.
* @ctx: Pointer to context to be terminated.
*/
void kbase_kinstr_jm_term(struct kbase_kinstr_jm *ctx);
/**
* kbase_kinstr_jm_get_fd() - Retrieves a file descriptor that can be used to
* read the atom state changes from userspace
*
* @ctx: Pointer to the initialized context
* @jm_fd_arg: Pointer to the union containing the in/out params
* Return: -1 on failure, valid file descriptor on success
*/
int kbase_kinstr_jm_get_fd(struct kbase_kinstr_jm *const ctx,
union kbase_kinstr_jm_fd *jm_fd_arg);
/**
* kbasep_kinstr_jm_atom_state() - Signifies that an atom has changed state
* @atom: The atom that has changed state
* @state: The new state of the atom
*
* This performs the actual storage of the state ready for user space to
* read the data. It is only called when the static key is enabled from
* kbase_kinstr_jm_atom_state(). There is almost never a need to invoke this
* function directly.
*/
void kbasep_kinstr_jm_atom_state(
struct kbase_jd_atom *const atom,
const enum kbase_kinstr_jm_reader_atom_state state);
/* Allows ASM goto patching to reduce tracing overhead. This is
* incremented/decremented when readers are created and terminated. This really
* shouldn't be changed externally, but if you do, make sure you use
* a static_key_inc()/static_key_dec() pair.
*/
extern struct static_key_false basep_kinstr_jm_reader_static_key;
/**
* kbase_kinstr_jm_atom_state() - Signifies that an atom has changed state
* @atom: The atom that has changed state
* @state: The new state of the atom
*
* This uses a static key to reduce overhead when tracing is disabled
*/
static inline void kbase_kinstr_jm_atom_state(
struct kbase_jd_atom *const atom,
const enum kbase_kinstr_jm_reader_atom_state state)
{
if (static_branch_unlikely(&basep_kinstr_jm_reader_static_key))
kbasep_kinstr_jm_atom_state(atom, state);
}
/**
* kbase_kinstr_jm_atom_state_queue() - Signifies that an atom has entered a
* hardware or software queue.
* @atom: The atom that has changed state
*/
static inline void kbase_kinstr_jm_atom_state_queue(
struct kbase_jd_atom *const atom)
{
kbase_kinstr_jm_atom_state(
atom, KBASE_KINSTR_JM_READER_ATOM_STATE_QUEUE);
}
/**
* kbase_kinstr_jm_atom_state_start() - Signifies that work has started on an
* atom
* @atom: The atom that has changed state
*/
static inline void kbase_kinstr_jm_atom_state_start(
struct kbase_jd_atom *const atom)
{
kbase_kinstr_jm_atom_state(
atom, KBASE_KINSTR_JM_READER_ATOM_STATE_START);
}
/**
* kbase_kinstr_jm_atom_state_stop() - Signifies that work has stopped on an
* atom
* @atom: The atom that has changed state
*/
static inline void kbase_kinstr_jm_atom_state_stop(
struct kbase_jd_atom *const atom)
{
kbase_kinstr_jm_atom_state(
atom, KBASE_KINSTR_JM_READER_ATOM_STATE_STOP);
}
/**
* kbase_kinstr_jm_atom_state_complete() - Signifies that all work has completed
* on an atom
* @atom: The atom that has changed state
*/
static inline void kbase_kinstr_jm_atom_state_complete(
struct kbase_jd_atom *const atom)
{
kbase_kinstr_jm_atom_state(
atom, KBASE_KINSTR_JM_READER_ATOM_STATE_COMPLETE);
}
/**
* kbase_kinstr_jm_atom_queue() - A software *or* hardware atom is queued for
* execution
* @atom: The atom that has changed state
*/
static inline void kbase_kinstr_jm_atom_queue(struct kbase_jd_atom *const atom)
{
kbase_kinstr_jm_atom_state_queue(atom);
}
/**
* kbase_kinstr_jm_atom_complete() - A software *or* hardware atom is fully
* completed
* @atom: The atom that has changed state
*/
static inline void kbase_kinstr_jm_atom_complete(
struct kbase_jd_atom *const atom)
{
kbase_kinstr_jm_atom_state_complete(atom);
}
/**
* kbase_kinstr_jm_atom_sw_start() - A software atom has started work
* @atom: The atom that has changed state
*/
static inline void kbase_kinstr_jm_atom_sw_start(
struct kbase_jd_atom *const atom)
{
kbase_kinstr_jm_atom_state_start(atom);
}
/**
* kbase_kinstr_jm_atom_sw_stop() - A software atom has stopped work
* @atom: The atom that has changed state
*/
static inline void kbase_kinstr_jm_atom_sw_stop(
struct kbase_jd_atom *const atom)
{
kbase_kinstr_jm_atom_state_stop(atom);
}
/**
* kbasep_kinstr_jm_atom_hw_submit() - A hardware atom has been submitted
* @atom: The atom that has been submitted
*
* This private implementation should not be called directly, it is protected
* by a static key in kbase_kinstr_jm_atom_hw_submit(). Use that instead.
*/
void kbasep_kinstr_jm_atom_hw_submit(struct kbase_jd_atom *const atom);
/**
* kbase_kinstr_jm_atom_hw_submit() - A hardware atom has been submitted
* @atom: The atom that has been submitted
*/
static inline void kbase_kinstr_jm_atom_hw_submit(
struct kbase_jd_atom *const atom)
{
if (static_branch_unlikely(&basep_kinstr_jm_reader_static_key))
kbasep_kinstr_jm_atom_hw_submit(atom);
}
/**
* kbasep_kinstr_jm_atom_hw_release() - A hardware atom has been released
* @atom: The atom that has been released
*
* This private implementation should not be called directly, it is protected
* by a static key in kbase_kinstr_jm_atom_hw_release(). Use that instead.
*/
void kbasep_kinstr_jm_atom_hw_release(struct kbase_jd_atom *const atom);
/**
* kbase_kinstr_jm_atom_hw_release() - A hardware atom has been released
* @atom: The atom that has been released
*/
static inline void kbase_kinstr_jm_atom_hw_release(
struct kbase_jd_atom *const atom)
{
if (static_branch_unlikely(&basep_kinstr_jm_reader_static_key))
kbasep_kinstr_jm_atom_hw_release(atom);
}
#endif /* _KBASE_KINSTR_JM_H_ */
|
