xref: /linux/include/uapi/linux/android/binder.h (revision fcc8487d477a3452a1d0ccbdd4c5e0e1e3cb8bed)
1 /*
2  * Copyright (C) 2008 Google, Inc.
3  *
4  * Based on, but no longer compatible with, the original
5  * OpenBinder.org binder driver interface, which is:
6  *
7  * Copyright (c) 2005 Palmsource, Inc.
8  *
9  * This software is licensed under the terms of the GNU General Public
10  * License version 2, as published by the Free Software Foundation, and
11  * may be copied, distributed, and modified under those terms.
12  *
13  * This program is distributed in the hope that it will be useful,
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16  * GNU General Public License for more details.
17  *
18  */
19 
20 #ifndef _UAPI_LINUX_BINDER_H
21 #define _UAPI_LINUX_BINDER_H
22 
23 #include <linux/types.h>
24 #include <linux/ioctl.h>
25 
26 #define B_PACK_CHARS(c1, c2, c3, c4) \
27 	((((c1)<<24)) | (((c2)<<16)) | (((c3)<<8)) | (c4))
28 #define B_TYPE_LARGE 0x85
29 
30 enum {
31 	BINDER_TYPE_BINDER	= B_PACK_CHARS('s', 'b', '*', B_TYPE_LARGE),
32 	BINDER_TYPE_WEAK_BINDER	= B_PACK_CHARS('w', 'b', '*', B_TYPE_LARGE),
33 	BINDER_TYPE_HANDLE	= B_PACK_CHARS('s', 'h', '*', B_TYPE_LARGE),
34 	BINDER_TYPE_WEAK_HANDLE	= B_PACK_CHARS('w', 'h', '*', B_TYPE_LARGE),
35 	BINDER_TYPE_FD		= B_PACK_CHARS('f', 'd', '*', B_TYPE_LARGE),
36 	BINDER_TYPE_FDA		= B_PACK_CHARS('f', 'd', 'a', B_TYPE_LARGE),
37 	BINDER_TYPE_PTR		= B_PACK_CHARS('p', 't', '*', B_TYPE_LARGE),
38 };
39 
40 enum {
41 	FLAT_BINDER_FLAG_PRIORITY_MASK = 0xff,
42 	FLAT_BINDER_FLAG_ACCEPTS_FDS = 0x100,
43 };
44 
45 #ifdef BINDER_IPC_32BIT
46 typedef __u32 binder_size_t;
47 typedef __u32 binder_uintptr_t;
48 #else
49 typedef __u64 binder_size_t;
50 typedef __u64 binder_uintptr_t;
51 #endif
52 
53 /**
54  * struct binder_object_header - header shared by all binder metadata objects.
55  * @type:	type of the object
56  */
57 struct binder_object_header {
58 	__u32        type;
59 };
60 
61 /*
62  * This is the flattened representation of a Binder object for transfer
63  * between processes.  The 'offsets' supplied as part of a binder transaction
64  * contains offsets into the data where these structures occur.  The Binder
65  * driver takes care of re-writing the structure type and data as it moves
66  * between processes.
67  */
68 struct flat_binder_object {
69 	struct binder_object_header	hdr;
70 	__u32				flags;
71 
72 	/* 8 bytes of data. */
73 	union {
74 		binder_uintptr_t	binder;	/* local object */
75 		__u32			handle;	/* remote object */
76 	};
77 
78 	/* extra data associated with local object */
79 	binder_uintptr_t	cookie;
80 };
81 
82 /**
83  * struct binder_fd_object - describes a filedescriptor to be fixed up.
84  * @hdr:	common header structure
85  * @pad_flags:	padding to remain compatible with old userspace code
86  * @pad_binder:	padding to remain compatible with old userspace code
87  * @fd:		file descriptor
88  * @cookie:	opaque data, used by user-space
89  */
90 struct binder_fd_object {
91 	struct binder_object_header	hdr;
92 	__u32				pad_flags;
93 	union {
94 		binder_uintptr_t	pad_binder;
95 		__u32			fd;
96 	};
97 
98 	binder_uintptr_t		cookie;
99 };
100 
101 /* struct binder_buffer_object - object describing a userspace buffer
102  * @hdr:		common header structure
103  * @flags:		one or more BINDER_BUFFER_* flags
104  * @buffer:		address of the buffer
105  * @length:		length of the buffer
106  * @parent:		index in offset array pointing to parent buffer
107  * @parent_offset:	offset in @parent pointing to this buffer
108  *
109  * A binder_buffer object represents an object that the
110  * binder kernel driver can copy verbatim to the target
111  * address space. A buffer itself may be pointed to from
112  * within another buffer, meaning that the pointer inside
113  * that other buffer needs to be fixed up as well. This
114  * can be done by setting the BINDER_BUFFER_FLAG_HAS_PARENT
115  * flag in @flags, by setting @parent buffer to the index
116  * in the offset array pointing to the parent binder_buffer_object,
117  * and by setting @parent_offset to the offset in the parent buffer
118  * at which the pointer to this buffer is located.
119  */
120 struct binder_buffer_object {
121 	struct binder_object_header	hdr;
122 	__u32				flags;
123 	binder_uintptr_t		buffer;
124 	binder_size_t			length;
125 	binder_size_t			parent;
126 	binder_size_t			parent_offset;
127 };
128 
129 enum {
130 	BINDER_BUFFER_FLAG_HAS_PARENT = 0x01,
131 };
132 
133 /* struct binder_fd_array_object - object describing an array of fds in a buffer
134  * @hdr:		common header structure
135  * @num_fds:		number of file descriptors in the buffer
136  * @parent:		index in offset array to buffer holding the fd array
137  * @parent_offset:	start offset of fd array in the buffer
138  *
139  * A binder_fd_array object represents an array of file
140  * descriptors embedded in a binder_buffer_object. It is
141  * different from a regular binder_buffer_object because it
142  * describes a list of file descriptors to fix up, not an opaque
143  * blob of memory, and hence the kernel needs to treat it differently.
144  *
145  * An example of how this would be used is with Android's
146  * native_handle_t object, which is a struct with a list of integers
147  * and a list of file descriptors. The native_handle_t struct itself
148  * will be represented by a struct binder_buffer_objct, whereas the
149  * embedded list of file descriptors is represented by a
150  * struct binder_fd_array_object with that binder_buffer_object as
151  * a parent.
152  */
153 struct binder_fd_array_object {
154 	struct binder_object_header	hdr;
155 	binder_size_t			num_fds;
156 	binder_size_t			parent;
157 	binder_size_t			parent_offset;
158 };
159 
160 /*
161  * On 64-bit platforms where user code may run in 32-bits the driver must
162  * translate the buffer (and local binder) addresses appropriately.
163  */
164 
165 struct binder_write_read {
166 	binder_size_t		write_size;	/* bytes to write */
167 	binder_size_t		write_consumed;	/* bytes consumed by driver */
168 	binder_uintptr_t	write_buffer;
169 	binder_size_t		read_size;	/* bytes to read */
170 	binder_size_t		read_consumed;	/* bytes consumed by driver */
171 	binder_uintptr_t	read_buffer;
172 };
173 
174 /* Use with BINDER_VERSION, driver fills in fields. */
175 struct binder_version {
176 	/* driver protocol version -- increment with incompatible change */
177 	__s32       protocol_version;
178 };
179 
180 /* This is the current protocol version. */
181 #ifdef BINDER_IPC_32BIT
182 #define BINDER_CURRENT_PROTOCOL_VERSION 7
183 #else
184 #define BINDER_CURRENT_PROTOCOL_VERSION 8
185 #endif
186 
187 #define BINDER_WRITE_READ		_IOWR('b', 1, struct binder_write_read)
188 #define BINDER_SET_IDLE_TIMEOUT		_IOW('b', 3, __s64)
189 #define BINDER_SET_MAX_THREADS		_IOW('b', 5, __u32)
190 #define BINDER_SET_IDLE_PRIORITY	_IOW('b', 6, __s32)
191 #define BINDER_SET_CONTEXT_MGR		_IOW('b', 7, __s32)
192 #define BINDER_THREAD_EXIT		_IOW('b', 8, __s32)
193 #define BINDER_VERSION			_IOWR('b', 9, struct binder_version)
194 
195 /*
196  * NOTE: Two special error codes you should check for when calling
197  * in to the driver are:
198  *
199  * EINTR -- The operation has been interupted.  This should be
200  * handled by retrying the ioctl() until a different error code
201  * is returned.
202  *
203  * ECONNREFUSED -- The driver is no longer accepting operations
204  * from your process.  That is, the process is being destroyed.
205  * You should handle this by exiting from your process.  Note
206  * that once this error code is returned, all further calls to
207  * the driver from any thread will return this same code.
208  */
209 
210 enum transaction_flags {
211 	TF_ONE_WAY	= 0x01,	/* this is a one-way call: async, no return */
212 	TF_ROOT_OBJECT	= 0x04,	/* contents are the component's root object */
213 	TF_STATUS_CODE	= 0x08,	/* contents are a 32-bit status code */
214 	TF_ACCEPT_FDS	= 0x10,	/* allow replies with file descriptors */
215 };
216 
217 struct binder_transaction_data {
218 	/* The first two are only used for bcTRANSACTION and brTRANSACTION,
219 	 * identifying the target and contents of the transaction.
220 	 */
221 	union {
222 		/* target descriptor of command transaction */
223 		__u32	handle;
224 		/* target descriptor of return transaction */
225 		binder_uintptr_t ptr;
226 	} target;
227 	binder_uintptr_t	cookie;	/* target object cookie */
228 	__u32		code;		/* transaction command */
229 
230 	/* General information about the transaction. */
231 	__u32	        flags;
232 	pid_t		sender_pid;
233 	uid_t		sender_euid;
234 	binder_size_t	data_size;	/* number of bytes of data */
235 	binder_size_t	offsets_size;	/* number of bytes of offsets */
236 
237 	/* If this transaction is inline, the data immediately
238 	 * follows here; otherwise, it ends with a pointer to
239 	 * the data buffer.
240 	 */
241 	union {
242 		struct {
243 			/* transaction data */
244 			binder_uintptr_t	buffer;
245 			/* offsets from buffer to flat_binder_object structs */
246 			binder_uintptr_t	offsets;
247 		} ptr;
248 		__u8	buf[8];
249 	} data;
250 };
251 
252 struct binder_transaction_data_sg {
253 	struct binder_transaction_data transaction_data;
254 	binder_size_t buffers_size;
255 };
256 
257 struct binder_ptr_cookie {
258 	binder_uintptr_t ptr;
259 	binder_uintptr_t cookie;
260 };
261 
262 struct binder_handle_cookie {
263 	__u32 handle;
264 	binder_uintptr_t cookie;
265 } __packed;
266 
267 struct binder_pri_desc {
268 	__s32 priority;
269 	__u32 desc;
270 };
271 
272 struct binder_pri_ptr_cookie {
273 	__s32 priority;
274 	binder_uintptr_t ptr;
275 	binder_uintptr_t cookie;
276 };
277 
278 enum binder_driver_return_protocol {
279 	BR_ERROR = _IOR('r', 0, __s32),
280 	/*
281 	 * int: error code
282 	 */
283 
284 	BR_OK = _IO('r', 1),
285 	/* No parameters! */
286 
287 	BR_TRANSACTION = _IOR('r', 2, struct binder_transaction_data),
288 	BR_REPLY = _IOR('r', 3, struct binder_transaction_data),
289 	/*
290 	 * binder_transaction_data: the received command.
291 	 */
292 
293 	BR_ACQUIRE_RESULT = _IOR('r', 4, __s32),
294 	/*
295 	 * not currently supported
296 	 * int: 0 if the last bcATTEMPT_ACQUIRE was not successful.
297 	 * Else the remote object has acquired a primary reference.
298 	 */
299 
300 	BR_DEAD_REPLY = _IO('r', 5),
301 	/*
302 	 * The target of the last transaction (either a bcTRANSACTION or
303 	 * a bcATTEMPT_ACQUIRE) is no longer with us.  No parameters.
304 	 */
305 
306 	BR_TRANSACTION_COMPLETE = _IO('r', 6),
307 	/*
308 	 * No parameters... always refers to the last transaction requested
309 	 * (including replies).  Note that this will be sent even for
310 	 * asynchronous transactions.
311 	 */
312 
313 	BR_INCREFS = _IOR('r', 7, struct binder_ptr_cookie),
314 	BR_ACQUIRE = _IOR('r', 8, struct binder_ptr_cookie),
315 	BR_RELEASE = _IOR('r', 9, struct binder_ptr_cookie),
316 	BR_DECREFS = _IOR('r', 10, struct binder_ptr_cookie),
317 	/*
318 	 * void *:	ptr to binder
319 	 * void *: cookie for binder
320 	 */
321 
322 	BR_ATTEMPT_ACQUIRE = _IOR('r', 11, struct binder_pri_ptr_cookie),
323 	/*
324 	 * not currently supported
325 	 * int:	priority
326 	 * void *: ptr to binder
327 	 * void *: cookie for binder
328 	 */
329 
330 	BR_NOOP = _IO('r', 12),
331 	/*
332 	 * No parameters.  Do nothing and examine the next command.  It exists
333 	 * primarily so that we can replace it with a BR_SPAWN_LOOPER command.
334 	 */
335 
336 	BR_SPAWN_LOOPER = _IO('r', 13),
337 	/*
338 	 * No parameters.  The driver has determined that a process has no
339 	 * threads waiting to service incoming transactions.  When a process
340 	 * receives this command, it must spawn a new service thread and
341 	 * register it via bcENTER_LOOPER.
342 	 */
343 
344 	BR_FINISHED = _IO('r', 14),
345 	/*
346 	 * not currently supported
347 	 * stop threadpool thread
348 	 */
349 
350 	BR_DEAD_BINDER = _IOR('r', 15, binder_uintptr_t),
351 	/*
352 	 * void *: cookie
353 	 */
354 	BR_CLEAR_DEATH_NOTIFICATION_DONE = _IOR('r', 16, binder_uintptr_t),
355 	/*
356 	 * void *: cookie
357 	 */
358 
359 	BR_FAILED_REPLY = _IO('r', 17),
360 	/*
361 	 * The the last transaction (either a bcTRANSACTION or
362 	 * a bcATTEMPT_ACQUIRE) failed (e.g. out of memory).  No parameters.
363 	 */
364 };
365 
366 enum binder_driver_command_protocol {
367 	BC_TRANSACTION = _IOW('c', 0, struct binder_transaction_data),
368 	BC_REPLY = _IOW('c', 1, struct binder_transaction_data),
369 	/*
370 	 * binder_transaction_data: the sent command.
371 	 */
372 
373 	BC_ACQUIRE_RESULT = _IOW('c', 2, __s32),
374 	/*
375 	 * not currently supported
376 	 * int:  0 if the last BR_ATTEMPT_ACQUIRE was not successful.
377 	 * Else you have acquired a primary reference on the object.
378 	 */
379 
380 	BC_FREE_BUFFER = _IOW('c', 3, binder_uintptr_t),
381 	/*
382 	 * void *: ptr to transaction data received on a read
383 	 */
384 
385 	BC_INCREFS = _IOW('c', 4, __u32),
386 	BC_ACQUIRE = _IOW('c', 5, __u32),
387 	BC_RELEASE = _IOW('c', 6, __u32),
388 	BC_DECREFS = _IOW('c', 7, __u32),
389 	/*
390 	 * int:	descriptor
391 	 */
392 
393 	BC_INCREFS_DONE = _IOW('c', 8, struct binder_ptr_cookie),
394 	BC_ACQUIRE_DONE = _IOW('c', 9, struct binder_ptr_cookie),
395 	/*
396 	 * void *: ptr to binder
397 	 * void *: cookie for binder
398 	 */
399 
400 	BC_ATTEMPT_ACQUIRE = _IOW('c', 10, struct binder_pri_desc),
401 	/*
402 	 * not currently supported
403 	 * int: priority
404 	 * int: descriptor
405 	 */
406 
407 	BC_REGISTER_LOOPER = _IO('c', 11),
408 	/*
409 	 * No parameters.
410 	 * Register a spawned looper thread with the device.
411 	 */
412 
413 	BC_ENTER_LOOPER = _IO('c', 12),
414 	BC_EXIT_LOOPER = _IO('c', 13),
415 	/*
416 	 * No parameters.
417 	 * These two commands are sent as an application-level thread
418 	 * enters and exits the binder loop, respectively.  They are
419 	 * used so the binder can have an accurate count of the number
420 	 * of looping threads it has available.
421 	 */
422 
423 	BC_REQUEST_DEATH_NOTIFICATION = _IOW('c', 14,
424 						struct binder_handle_cookie),
425 	/*
426 	 * int: handle
427 	 * void *: cookie
428 	 */
429 
430 	BC_CLEAR_DEATH_NOTIFICATION = _IOW('c', 15,
431 						struct binder_handle_cookie),
432 	/*
433 	 * int: handle
434 	 * void *: cookie
435 	 */
436 
437 	BC_DEAD_BINDER_DONE = _IOW('c', 16, binder_uintptr_t),
438 	/*
439 	 * void *: cookie
440 	 */
441 
442 	BC_TRANSACTION_SG = _IOW('c', 17, struct binder_transaction_data_sg),
443 	BC_REPLY_SG = _IOW('c', 18, struct binder_transaction_data_sg),
444 	/*
445 	 * binder_transaction_data_sg: the sent command.
446 	 */
447 };
448 
449 #endif /* _UAPI_LINUX_BINDER_H */
450 
451