1 /*
2 *
3 * (C) COPYRIGHT 2012-2017 ARM Limited. All rights reserved.
4 *
5 * This program is free software and is provided to you under the terms of the
6 * GNU General Public License version 2 as published by the Free Software
7 * Foundation, and any use by you of this program is subject to the terms
8 * of such GNU licence.
9 *
10 * A copy of the licence is included with the program, and can also be obtained
11 * from Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
12 * Boston, MA 02110-1301, USA.
13 *
14 */
15
16
17
18 /**
19 * @file mali_kbase_sync.h
20 *
21 * This file contains our internal "API" for explicit fences.
22 * It hides the implementation details of the actual explicit fence mechanism
23 * used (Android fences or sync file with DMA fences).
24 */
25
26 #ifndef MALI_KBASE_SYNC_H
27 #define MALI_KBASE_SYNC_H
28
29 #include <linux/syscalls.h>
30 #ifdef CONFIG_SYNC
31 #include <sync.h>
32 #endif
33 #ifdef CONFIG_SYNC_FILE
34 #include "mali_kbase_fence_defs.h"
35 #include <linux/sync_file.h>
36 #endif
37
38 #include "mali_kbase.h"
39
40 /**
41 * struct kbase_sync_fence_info - Information about a fence
42 * @fence: Pointer to fence (type is void*, as underlaying struct can differ)
43 * @name: The name given to this fence when it was created
44 * @status: < 0 means error, 0 means active, 1 means signaled
45 *
46 * Use kbase_sync_fence_in_info_get() or kbase_sync_fence_out_info_get()
47 * to get the information.
48 */
49 struct kbase_sync_fence_info {
50 void *fence;
51 char name[32];
52 int status;
53 };
54
55 /**
56 * kbase_sync_fence_stream_create() - Create a stream object
57 * @name: Name of stream (only used to ease debugging/visualization)
58 * @out_fd: A file descriptor representing the created stream object
59 *
60 * Can map down to a timeline implementation in some implementations.
61 * Exposed as a file descriptor.
62 * Life-time controlled via the file descriptor:
63 * - dup to add a ref
64 * - close to remove a ref
65 *
66 * return: 0 on success, < 0 on error
67 */
68 int kbase_sync_fence_stream_create(const char *name, int *const out_fd);
69
70 /**
71 * kbase_sync_fence_out_create Create an explicit output fence to specified atom
72 * @katom: Atom to assign the new explicit fence to
73 * @stream_fd: File descriptor for stream object to create fence on
74 *
75 * return: Valid file descriptor to fence or < 0 on error
76 */
77 int kbase_sync_fence_out_create(struct kbase_jd_atom *katom, int stream_fd);
78
79 /**
80 * kbase_sync_fence_in_from_fd() Assigns an existing fence to specified atom
81 * @katom: Atom to assign the existing explicit fence to
82 * @fd: File descriptor to an existing fence
83 *
84 * Assigns an explicit input fence to atom.
85 * This can later be waited for by calling @kbase_sync_fence_in_wait
86 *
87 * return: 0 on success, < 0 on error
88 */
89 int kbase_sync_fence_in_from_fd(struct kbase_jd_atom *katom, int fd);
90
91 /**
92 * kbase_sync_fence_validate() - Validate a fd to be a valid fence
93 * @fd: File descriptor to check
94 *
95 * This function is only usable to catch unintentional user errors early,
96 * it does not stop malicious code changing the fd after this function returns.
97 *
98 * return 0: if fd is for a valid fence, < 0 if invalid
99 */
100 int kbase_sync_fence_validate(int fd);
101
102 /**
103 * kbase_sync_fence_out_trigger - Signal explicit output fence attached on katom
104 * @katom: Atom with an explicit fence to signal
105 * @result: < 0 means signal with error, 0 >= indicates success
106 *
107 * Signal output fence attached on katom and remove the fence from the atom.
108 *
109 * return: The "next" event code for atom, typically JOB_CANCELLED or EVENT_DONE
110 */
111 enum base_jd_event_code
112 kbase_sync_fence_out_trigger(struct kbase_jd_atom *katom, int result);
113
114 /**
115 * kbase_sync_fence_in_wait() - Wait for explicit input fence to be signaled
116 * @katom: Atom with explicit fence to wait for
117 *
118 * If the fence is already signaled, then 0 is returned, and the caller must
119 * continue processing of the katom.
120 *
121 * If the fence isn't already signaled, then this kbase_sync framework will
122 * take responsibility to continue the processing once the fence is signaled.
123 *
124 * return: 0 if already signaled, otherwise 1
125 */
126 int kbase_sync_fence_in_wait(struct kbase_jd_atom *katom);
127
128 /**
129 * kbase_sync_fence_in_cancel_wait() - Cancel explicit input fence waits
130 * @katom: Atom to cancel wait for
131 *
132 * This function is fully responsible for continuing processing of this atom
133 * (remove_waiting_soft_job + finish_soft_job + jd_done + js_sched_all)
134 */
135 void kbase_sync_fence_in_cancel_wait(struct kbase_jd_atom *katom);
136
137 /**
138 * kbase_sync_fence_in_remove() - Remove the input fence from the katom
139 * @katom: Atom to remove explicit input fence for
140 *
141 * This will also release the corresponding reference.
142 */
143 void kbase_sync_fence_in_remove(struct kbase_jd_atom *katom);
144
145 /**
146 * kbase_sync_fence_out_remove() - Remove the output fence from the katom
147 * @katom: Atom to remove explicit output fence for
148 *
149 * This will also release the corresponding reference.
150 */
151 void kbase_sync_fence_out_remove(struct kbase_jd_atom *katom);
152
153 /**
154 * kbase_sync_fence_close_fd() - Close a file descriptor representing a fence
155 * @fd: File descriptor to close
156 */
kbase_sync_fence_close_fd(int fd)157 static inline void kbase_sync_fence_close_fd(int fd)
158 {
159 ksys_close(fd);
160 }
161
162 /**
163 * kbase_sync_fence_in_info_get() - Retrieves information about input fence
164 * @katom: Atom to get fence information from
165 * @info: Struct to be filled with fence information
166 *
167 * return: 0 on success, < 0 on error
168 */
169 int kbase_sync_fence_in_info_get(struct kbase_jd_atom *katom,
170 struct kbase_sync_fence_info *info);
171
172 /**
173 * kbase_sync_fence_out_info_get() - Retrieves information about output fence
174 * @katom: Atom to get fence information from
175 * @info: Struct to be filled with fence information
176 *
177 * return: 0 on success, < 0 on error
178 */
179 int kbase_sync_fence_out_info_get(struct kbase_jd_atom *katom,
180 struct kbase_sync_fence_info *info);
181
182 /**
183 * kbase_sync_status_string() - Get string matching @status
184 * @status: Value of fence status.
185 *
186 * return: Pointer to string describing @status.
187 */
188 const char *kbase_sync_status_string(int status);
189
190 /*
191 * Internal worker used to continue processing of atom.
192 */
193 void kbase_sync_fence_wait_worker(struct work_struct *data);
194
195 #ifdef CONFIG_MALI_FENCE_DEBUG
196 /**
197 * kbase_sync_fence_in_dump() Trigger a debug dump of atoms input fence state
198 * @katom: Atom to trigger fence debug dump for
199 */
200 void kbase_sync_fence_in_dump(struct kbase_jd_atom *katom);
201 #endif
202
203 #endif /* MALI_KBASE_SYNC_H */
204