drivers/staging/android/binder.h

   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 _LINUX_BINDER_H
  21 #define _LINUX_BINDER_H
  22
  23 #include <linux/ioctl.h>
  24
  25 #define B_PACK_CHARS(c1, c2, c3, c4) \
  26         ((((c1)<<24)) | (((c2)<<16)) | (((c3)<<8)) | (c4))
  27 #define B_TYPE_LARGE 0x85
  28
  29 enum {
  30         BINDER_TYPE_BINDER      = B_PACK_CHARS('s', 'b', '*', B_TYPE_LARGE),
  31         BINDER_TYPE_WEAK_BINDER = B_PACK_CHARS('w', 'b', '*', B_TYPE_LARGE),
  32         BINDER_TYPE_HANDLE      = B_PACK_CHARS('s', 'h', '*', B_TYPE_LARGE),
  33         BINDER_TYPE_WEAK_HANDLE = B_PACK_CHARS('w', 'h', '*', B_TYPE_LARGE),
  34         BINDER_TYPE_FD          = B_PACK_CHARS('f', 'd', '*', B_TYPE_LARGE),
  35 };
  36
  37 enum {
  38         FLAT_BINDER_FLAG_PRIORITY_MASK = 0xff,
  39         FLAT_BINDER_FLAG_ACCEPTS_FDS = 0x100,
  40 };
  41
  42 /*
  43  * This is the flattened representation of a Binder object for transfer
  44  * between processes.  The 'offsets' supplied as part of a binder transaction
  45  * contains offsets into the data where these structures occur.  The Binder
  46  * driver takes care of re-writing the structure type and data as it moves
  47  * between processes.
  48  */
  49 struct flat_binder_object {
  50         /* 8 bytes for large_flat_header. */
  51         unsigned long           type;
  52         unsigned long           flags;
  53
  54         /* 8 bytes of data. */
  55         union {
  56                 void            *binder;        /* local object */
  57                 signed long     handle;         /* remote object */
  58         };
  59
  60         /* extra data associated with local object */
  61         void                    *cookie;
  62 };
  63
  64 /*
  65  * On 64-bit platforms where user code may run in 32-bits the driver must
  66  * translate the buffer (and local binder) addresses apropriately.
  67  */
  68
  69 struct binder_write_read {
  70         signed long     write_size;     /* bytes to write */
  71         signed long     write_consumed; /* bytes consumed by driver */
  72         unsigned long   write_buffer;
  73         signed long     read_size;      /* bytes to read */
  74         signed long     read_consumed;  /* bytes consumed by driver */
  75         unsigned long   read_buffer;
  76 };
  77
  78 /* Use with BINDER_VERSION, driver fills in fields. */
  79 struct binder_version {
  80         /* driver protocol version -- increment with incompatible change */
  81         signed long     protocol_version;
  82 };
  83
  84 /* This is the current protocol version. */
  85 #define BINDER_CURRENT_PROTOCOL_VERSION 7
  86
  87 #define BINDER_WRITE_READ               _IOWR('b', 1, struct binder_write_read)
  88 #define BINDER_SET_IDLE_TIMEOUT         _IOW('b', 3, int64_t)
  89 #define BINDER_SET_MAX_THREADS          _IOW('b', 5, size_t)
  90 #define BINDER_SET_IDLE_PRIORITY        _IOW('b', 6, int)
  91 #define BINDER_SET_CONTEXT_MGR          _IOW('b', 7, int)
  92 #define BINDER_THREAD_EXIT              _IOW('b', 8, int)
  93 #define BINDER_VERSION                  _IOWR('b', 9, struct binder_version)
  94
  95 /*
  96  * NOTE: Two special error codes you should check for when calling
  97  * in to the driver are:
  98  *
  99  * EINTR -- The operation has been interupted.  This should be
 100  * handled by retrying the ioctl() until a different error code
 101  * is returned.
 102  *
 103  * ECONNREFUSED -- The driver is no longer accepting operations
 104  * from your process.  That is, the process is being destroyed.
 105  * You should handle this by exiting from your process.  Note
 106  * that once this error code is returned, all further calls to
 107  * the driver from any thread will return this same code.
 108  */
 109
 110 enum transaction_flags {
 111         TF_ONE_WAY      = 0x01, /* this is a one-way call: async, no return */
 112         TF_ROOT_OBJECT  = 0x04, /* contents are the component's root object */
 113         TF_STATUS_CODE  = 0x08, /* contents are a 32-bit status code */
 114         TF_ACCEPT_FDS   = 0x10, /* allow replies with file descriptors */
 115 };
 116
 117 struct binder_transaction_data {
 118         /* The first two are only used for bcTRANSACTION and brTRANSACTION,
 119          * identifying the target and contents of the transaction.
 120          */
 121         union {
 122                 size_t  handle; /* target descriptor of command transaction */
 123                 void    *ptr;   /* target descriptor of return transaction */
 124         } target;
 125         void            *cookie;        /* target object cookie */
 126         unsigned int    code;           /* transaction command */
 127
 128         /* General information about the transaction. */
 129         unsigned int    flags;
 130         pid_t           sender_pid;
 131         uid_t           sender_euid;
 132         size_t          data_size;      /* number of bytes of data */
 133         size_t          offsets_size;   /* number of bytes of offsets */
 134
 135         /* If this transaction is inline, the data immediately
 136          * follows here; otherwise, it ends with a pointer to
 137          * the data buffer.
 138          */
 139         union {
 140                 struct {
 141                         /* transaction data */
 142                         const void      *buffer;
 143                         /* offsets from buffer to flat_binder_object structs */
 144                         const void      *offsets;
 145                 } ptr;
 146                 uint8_t buf[8];
 147         } data;
 148 };
 149
 150 struct binder_ptr_cookie {
 151         void *ptr;
 152         void *cookie;
 153 };
 154
 155 struct binder_pri_desc {
 156         int priority;
 157         int desc;
 158 };
 159
 160 struct binder_pri_ptr_cookie {
 161         int priority;
 162         void *ptr;
 163         void *cookie;
 164 };
 165
 166 enum BinderDriverReturnProtocol {
 167         BR_ERROR = _IOR('r', 0, int),
 168         /*
 169          * int: error code
 170          */
 171
 172         BR_OK = _IO('r', 1),
 173         /* No parameters! */
 174
 175         BR_TRANSACTION = _IOR('r', 2, struct binder_transaction_data),
 176         BR_REPLY = _IOR('r', 3, struct binder_transaction_data),
 177         /*
 178          * binder_transaction_data: the received command.
 179          */
 180
 181         BR_ACQUIRE_RESULT = _IOR('r', 4, int),
 182         /*
 183          * not currently supported
 184          * int: 0 if the last bcATTEMPT_ACQUIRE was not successful.
 185          * Else the remote object has acquired a primary reference.
 186          */
 187
 188         BR_DEAD_REPLY = _IO('r', 5),
 189         /*
 190          * The target of the last transaction (either a bcTRANSACTION or
 191          * a bcATTEMPT_ACQUIRE) is no longer with us.  No parameters.
 192          */
 193
 194         BR_TRANSACTION_COMPLETE = _IO('r', 6),
 195         /*
 196          * No parameters... always refers to the last transaction requested
 197          * (including replies).  Note that this will be sent even for
 198          * asynchronous transactions.
 199          */
 200
 201         BR_INCREFS = _IOR('r', 7, struct binder_ptr_cookie),
 202         BR_ACQUIRE = _IOR('r', 8, struct binder_ptr_cookie),
 203         BR_RELEASE = _IOR('r', 9, struct binder_ptr_cookie),
 204         BR_DECREFS = _IOR('r', 10, struct binder_ptr_cookie),
 205         /*
 206          * void *:      ptr to binder
 207          * void *: cookie for binder
 208          */
 209
 210         BR_ATTEMPT_ACQUIRE = _IOR('r', 11, struct binder_pri_ptr_cookie),
 211         /*
 212          * not currently supported
 213          * int: priority
 214          * void *: ptr to binder
 215          * void *: cookie for binder
 216          */
 217
 218         BR_NOOP = _IO('r', 12),
 219         /*
 220          * No parameters.  Do nothing and examine the next command.  It exists
 221          * primarily so that we can replace it with a BR_SPAWN_LOOPER command.
 222          */
 223
 224         BR_SPAWN_LOOPER = _IO('r', 13),
 225         /*
 226          * No parameters.  The driver has determined that a process has no
 227          * threads waiting to service incomming transactions.  When a process
 228          * receives this command, it must spawn a new service thread and
 229          * register it via bcENTER_LOOPER.
 230          */
 231
 232         BR_FINISHED = _IO('r', 14),
 233         /*
 234          * not currently supported
 235          * stop threadpool thread
 236          */
 237
 238         BR_DEAD_BINDER = _IOR('r', 15, void *),
 239         /*
 240          * void *: cookie
 241          */
 242         BR_CLEAR_DEATH_NOTIFICATION_DONE = _IOR('r', 16, void *),
 243         /*
 244          * void *: cookie
 245          */
 246
 247         BR_FAILED_REPLY = _IO('r', 17),
 248         /*
 249          * The the last transaction (either a bcTRANSACTION or
 250          * a bcATTEMPT_ACQUIRE) failed (e.g. out of memory).  No parameters.
 251          */
 252 };
 253
 254 enum BinderDriverCommandProtocol {
 255         BC_TRANSACTION = _IOW('c', 0, struct binder_transaction_data),
 256         BC_REPLY = _IOW('c', 1, struct binder_transaction_data),
 257         /*
 258          * binder_transaction_data: the sent command.
 259          */
 260
 261         BC_ACQUIRE_RESULT = _IOW('c', 2, int),
 262         /*
 263          * not currently supported
 264          * int:  0 if the last BR_ATTEMPT_ACQUIRE was not successful.
 265          * Else you have acquired a primary reference on the object.
 266          */
 267
 268         BC_FREE_BUFFER = _IOW('c', 3, int),
 269         /*
 270          * void *: ptr to transaction data received on a read
 271          */
 272
 273         BC_INCREFS = _IOW('c', 4, int),
 274         BC_ACQUIRE = _IOW('c', 5, int),
 275         BC_RELEASE = _IOW('c', 6, int),
 276         BC_DECREFS = _IOW('c', 7, int),
 277         /*
 278          * int: descriptor
 279          */
 280
 281         BC_INCREFS_DONE = _IOW('c', 8, struct binder_ptr_cookie),
 282         BC_ACQUIRE_DONE = _IOW('c', 9, struct binder_ptr_cookie),
 283         /*
 284          * void *: ptr to binder
 285          * void *: cookie for binder
 286          */
 287
 288         BC_ATTEMPT_ACQUIRE = _IOW('c', 10, struct binder_pri_desc),
 289         /*
 290          * not currently supported
 291          * int: priority
 292          * int: descriptor
 293          */
 294
 295         BC_REGISTER_LOOPER = _IO('c', 11),
 296         /*
 297          * No parameters.
 298          * Register a spawned looper thread with the device.
 299          */
 300
 301         BC_ENTER_LOOPER = _IO('c', 12),
 302         BC_EXIT_LOOPER = _IO('c', 13),
 303         /*
 304          * No parameters.
 305          * These two commands are sent as an application-level thread
 306          * enters and exits the binder loop, respectively.  They are
 307          * used so the binder can have an accurate count of the number
 308          * of looping threads it has available.
 309          */
 310
 311         BC_REQUEST_DEATH_NOTIFICATION = _IOW('c', 14, struct binder_ptr_cookie),
 312         /*
 313          * void *: ptr to binder
 314          * void *: cookie
 315          */
 316
 317         BC_CLEAR_DEATH_NOTIFICATION = _IOW('c', 15, struct binder_ptr_cookie),
 318         /*
 319          * void *: ptr to binder
 320          * void *: cookie
 321          */
 322
 323         BC_DEAD_BINDER_DONE = _IOW('c', 16, void *),
 324         /*
 325          * void *: cookie
 326          */
 327 };
 328
 329 #endif /* _LINUX_BINDER_H */
 330