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