1 /* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */
2 /*
3 *
4 * (C) COPYRIGHT 2021 ARM Limited. All rights reserved.
5 *
6 * This program is free software and is provided to you under the terms of the
7 * GNU General Public License version 2 as published by the Free Software
8 * Foundation, and any use by you of this program is subject to the terms
9 * of such GNU license.
10 *
11 * This program is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU General Public License for more details.
15 *
16 * You should have received a copy of the GNU General Public License
17 * along with this program; if not, you can access it online at
18 * http://www.gnu.org/licenses/gpl-2.0.html.
19 *
20 */
21
22 #ifndef _KBASE_CSF_EVENT_H_
23 #define _KBASE_CSF_EVENT_H_
24
25 #include <linux/types.h>
26 #include <linux/wait.h>
27
28 struct kbase_context;
29 struct kbase_csf_event;
30 enum kbase_csf_event_callback_action;
31
32 /**
33 * kbase_csf_event_callback_action - type for callback functions to be
34 * called upon CSF events.
35 * @param: Generic parameter to pass to the callback function.
36 *
37 * This is the type of callback functions that can be registered
38 * for CSF events. These function calls shall be triggered by any call
39 * to kbase_csf_event_signal.
40 *
41 * Return: KBASE_CSF_EVENT_CALLBACK_KEEP if the callback should remain
42 * registered, or KBASE_CSF_EVENT_CALLBACK_REMOVE if it should be removed.
43 */
44 typedef enum kbase_csf_event_callback_action kbase_csf_event_callback(void *param);
45
46 /**
47 * kbase_csf_event_wait_add - Add a CSF event callback
48 *
49 * @kctx: The Kbase context the @callback should be registered to.
50 * @callback: The callback function to register.
51 * @param: Custom parameter to be passed to the @callback function.
52 *
53 * This function adds an event callback to the list of CSF event callbacks
54 * belonging to a given Kbase context, to be triggered when a CSF event is
55 * signalled by kbase_csf_event_signal.
56 *
57 * Return: 0 on success, or negative on failure.
58 */
59 int kbase_csf_event_wait_add(struct kbase_context *kctx,
60 kbase_csf_event_callback *callback, void *param);
61
62 /**
63 * kbase_csf_event_wait_remove - Remove a CSF event callback
64 *
65 * @kctx: The kbase context the @callback should be removed from.
66 * @callback: The callback function to remove.
67 * @param: Custom parameter that would have been passed to the @p callback
68 * function.
69 *
70 * This function removes an event callback from the list of CSF event callbacks
71 * belonging to a given Kbase context.
72 */
73 void kbase_csf_event_wait_remove(struct kbase_context *kctx,
74 kbase_csf_event_callback *callback, void *param);
75
76 /**
77 * kbase_csf_event_term - Removes all CSF event callbacks
78 *
79 * @kctx: The kbase context for which CSF event callbacks have to be removed.
80 *
81 * This function empties the list of CSF event callbacks belonging to a given
82 * Kbase context.
83 */
84 void kbase_csf_event_term(struct kbase_context *kctx);
85
86 /**
87 * kbase_csf_event_signal - Signal a CSF event
88 *
89 * @kctx: The kbase context whose CSF event callbacks shall be triggered.
90 * @notify_gpu: Flag to indicate if CSF firmware should be notified of the
91 * signaling of event that happened on the Driver side, either
92 * the signal came from userspace or from kcpu queues.
93 *
94 * This function triggers all the CSF event callbacks that are registered to
95 * a given Kbase context, and also signals the event handling thread of
96 * userspace driver waiting for the CSF event.
97 */
98 void kbase_csf_event_signal(struct kbase_context *kctx, bool notify_gpu);
99
kbase_csf_event_signal_notify_gpu(struct kbase_context * kctx)100 static inline void kbase_csf_event_signal_notify_gpu(struct kbase_context *kctx)
101 {
102 kbase_csf_event_signal(kctx, true);
103 }
104
kbase_csf_event_signal_cpu_only(struct kbase_context * kctx)105 static inline void kbase_csf_event_signal_cpu_only(struct kbase_context *kctx)
106 {
107 kbase_csf_event_signal(kctx, false);
108 }
109
110 /**
111 * kbase_csf_event_init - Initialize event object
112 *
113 * This function initializes the event object.
114 *
115 * @kctx: The kbase context whose event object will be initialized.
116 */
117 void kbase_csf_event_init(struct kbase_context *const kctx);
118
119 struct kbase_csf_notification;
120 struct base_csf_notification;
121 /**
122 * kbase_csf_event_read_error - Read and remove an error from error list in event
123 *
124 * @kctx: The kbase context.
125 * @event_data: Caller-provided buffer to copy the fatal error to
126 *
127 * This function takes the CS fatal error from context's ordered
128 * error_list, copies its contents to @event_data.
129 *
130 * Return: true if error is read out or false if there is no error in error list.
131 */
132 bool kbase_csf_event_read_error(struct kbase_context *kctx,
133 struct base_csf_notification *event_data);
134
135 /**
136 * kbase_csf_event_add_error - Add an error into event error list
137 *
138 * @kctx: Address of a base context associated with a GPU address space.
139 * @error: Address of the item to be added to the context's pending error list.
140 * @data: Error data to be returned to userspace.
141 *
142 * Does not wake up the event queue blocking a user thread in kbase_poll. This
143 * is to make it more efficient to add multiple errors.
144 *
145 * The added error must not already be on the context's list of errors waiting
146 * to be reported (e.g. because a previous error concerning the same object has
147 * not yet been reported).
148 *
149 */
150 void kbase_csf_event_add_error(struct kbase_context *const kctx,
151 struct kbase_csf_notification *const error,
152 struct base_csf_notification const *const data);
153
154 /**
155 * kbase_csf_event_remove_error - Remove an error from event error list
156 *
157 * @kctx: Address of a base context associated with a GPU address space.
158 * @error: Address of the item to be removed from the context's event error list.
159 */
160 void kbase_csf_event_remove_error(struct kbase_context *kctx,
161 struct kbase_csf_notification *error);
162
163 /**
164 * kbase_csf_event_error_pending - Check the error pending status
165 *
166 * @kctx: The kbase context to check fatal error upon.
167 *
168 * Return: true if there is error in the list.
169 */
170 bool kbase_csf_event_error_pending(struct kbase_context *kctx);
171 #endif /* _KBASE_CSF_EVENT_H_ */
172