include/privates.h

   1 /***********************************************************
   2
   3 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
   4 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
   5 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
   6 AUTHOR BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
   7 AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
   8 CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
   9
  10 ******************************************************************/
  11
  12 #ifndef PRIVATES_H
  13 #define PRIVATES_H 1
  14
  15 #include <X11/Xdefs.h>
  16 #include <X11/Xosdefs.h>
  17 #include <X11/Xfuncproto.h>
  18 #include "misc.h"
  19
  20 /*****************************************************************
  21  * STUFF FOR PRIVATES
  22  *****************************************************************/
  23
  24 typedef struct _Private PrivateRec, *PrivatePtr;
  25
  26 typedef enum {
  27     /* XSELinux uses the same private keys for numerous objects */
  28     PRIVATE_XSELINUX,
  29
  30     /* Otherwise, you get a private in just the requested structure
  31      */
  32     /* These can have objects created before all of the keys are registered */
  33     PRIVATE_SCREEN,
  34     PRIVATE_EXTENSION,
  35     PRIVATE_COLORMAP,
  36     PRIVATE_DEVICE,
  37
  38     /* These cannot have any objects before all relevant keys are registered */
  39     PRIVATE_CLIENT,
  40     PRIVATE_PROPERTY,
  41     PRIVATE_SELECTION,
  42     PRIVATE_WINDOW,
  43     PRIVATE_PIXMAP,
  44     PRIVATE_GC,
  45     PRIVATE_CURSOR,
  46     PRIVATE_CURSOR_BITS,
  47
  48     /* extension privates */
  49     PRIVATE_DBE_WINDOW,
  50     PRIVATE_DAMAGE,
  51     PRIVATE_GLYPH,
  52     PRIVATE_GLYPHSET,
  53     PRIVATE_PICTURE,
  54     PRIVATE_SYNC_FENCE,
  55
  56     /* last private type */
  57     PRIVATE_LAST,
  58 } DevPrivateType;
  59
  60 typedef struct _DevPrivateKeyRec {
  61     int offset;
  62     int size;
  63     Bool initialized;
  64     Bool allocated;
  65     DevPrivateType type;
  66     struct _DevPrivateKeyRec *next;
  67 } DevPrivateKeyRec, *DevPrivateKey;
  68
  69 typedef struct _DevPrivateSetRec {
  70     DevPrivateKey key;
  71     unsigned offset;
  72     int created;
  73     int allocated;
  74 } DevPrivateSetRec, *DevPrivateSetPtr;
  75
  76 typedef struct _DevScreenPrivateKeyRec {
  77     DevPrivateKeyRec screenKey;
  78 } DevScreenPrivateKeyRec, *DevScreenPrivateKey;
  79
  80 /*
  81  * Let drivers know how to initialize private keys
  82  */
  83
  84 #define HAS_DEVPRIVATEKEYREC            1
  85 #define HAS_DIXREGISTERPRIVATEKEY       1
  86
  87 /*
  88  * Register a new private index for the private type.
  89  *
  90  * This initializes the specified key and optionally requests pre-allocated
  91  * private space for your driver/module. If you request no extra space, you
  92  * may set and get a single pointer value using this private key. Otherwise,
  93  * you can get the address of the extra space and store whatever data you like
  94  * there.
  95  *
  96  * You may call dixRegisterPrivateKey more than once on the same key, but the
  97  * size and type must match or the server will abort.
  98  *
  99  * dixRegisterPrivateKey returns FALSE if it fails to allocate memory
 100  * during its operation.
 101  */
 102 extern _X_EXPORT Bool
 103  dixRegisterPrivateKey(DevPrivateKey key, DevPrivateType type, unsigned size);
 104
 105 /*
 106  * Check whether a private key has been registered
 107  */
 108 static inline Bool
 109 dixPrivateKeyRegistered(DevPrivateKey key)
 110 {
 111     return key->initialized;
 112 }
 113
 114 /*
 115  * Get the address of the private storage.
 116  *
 117  * For keys with pre-defined storage, this gets the base of that storage
 118  * Otherwise, it returns the place where the private pointer is stored.
 119  */
 120 static inline void *
 121 dixGetPrivateAddr(PrivatePtr *privates, const DevPrivateKey key)
 122 {
 123     assert(key->initialized);
 124     return (char *) (*privates) + key->offset;
 125 }
 126
 127 /*
 128  * Fetch a private pointer stored in the object
 129  *
 130  * Returns the pointer stored with dixSetPrivate.
 131  * This must only be used with keys that have
 132  * no pre-defined storage
 133  */
 134 static inline void *
 135 dixGetPrivate(PrivatePtr *privates, const DevPrivateKey key)
 136 {
 137     assert(key->size == 0);
 138     return *(void **) dixGetPrivateAddr(privates, key);
 139 }
 140
 141 /*
 142  * Associate 'val' with 'key' in 'privates' so that later calls to
 143  * dixLookupPrivate(privates, key) will return 'val'.
 144  */
 145 static inline void
 146 dixSetPrivate(PrivatePtr *privates, const DevPrivateKey key, pointer val)
 147 {
 148     assert(key->size == 0);
 149     *(pointer *) dixGetPrivateAddr(privates, key) = val;
 150 }
 151
 152 #include "dix.h"
 153 #include "resource.h"
 154
 155 /*
 156  * Lookup a pointer to the private record.
 157  *
 158  * For privates with defined storage, return the address of the
 159  * storage. For privates without defined storage, return the pointer
 160  * contents
 161  */
 162 static inline pointer
 163 dixLookupPrivate(PrivatePtr *privates, const DevPrivateKey key)
 164 {
 165     if (key->size)
 166         return dixGetPrivateAddr(privates, key);
 167     else
 168         return dixGetPrivate(privates, key);
 169 }
 170
 171 /*
 172  * Look up the address of the pointer to the storage
 173  *
 174  * This returns the place where the private pointer is stored,
 175  * which is only valid for privates without predefined storage.
 176  */
 177 static inline pointer *
 178 dixLookupPrivateAddr(PrivatePtr *privates, const DevPrivateKey key)
 179 {
 180     assert(key->size == 0);
 181     return (pointer *) dixGetPrivateAddr(privates, key);
 182 }
 183
 184 extern _X_EXPORT Bool
 185
 186 dixRegisterScreenPrivateKey(DevScreenPrivateKey key, ScreenPtr pScreen,
 187                             DevPrivateType type, unsigned size);
 188
 189 extern _X_EXPORT DevPrivateKey
 190  _dixGetScreenPrivateKey(const DevScreenPrivateKey key, ScreenPtr pScreen);
 191
 192 static inline void *
 193 dixGetScreenPrivateAddr(PrivatePtr *privates, const DevScreenPrivateKey key,
 194                         ScreenPtr pScreen)
 195 {
 196     return dixGetPrivateAddr(privates, _dixGetScreenPrivateKey(key, pScreen));
 197 }
 198
 199 static inline void *
 200 dixGetScreenPrivate(PrivatePtr *privates, const DevScreenPrivateKey key,
 201                     ScreenPtr pScreen)
 202 {
 203     return dixGetPrivate(privates, _dixGetScreenPrivateKey(key, pScreen));
 204 }
 205
 206 static inline void
 207 dixSetScreenPrivate(PrivatePtr *privates, const DevScreenPrivateKey key,
 208                     ScreenPtr pScreen, pointer val)
 209 {
 210     dixSetPrivate(privates, _dixGetScreenPrivateKey(key, pScreen), val);
 211 }
 212
 213 static inline pointer
 214 dixLookupScreenPrivate(PrivatePtr *privates, const DevScreenPrivateKey key,
 215                        ScreenPtr pScreen)
 216 {
 217     return dixLookupPrivate(privates, _dixGetScreenPrivateKey(key, pScreen));
 218 }
 219
 220 static inline pointer *
 221 dixLookupScreenPrivateAddr(PrivatePtr *privates, const DevScreenPrivateKey key,
 222                            ScreenPtr pScreen)
 223 {
 224     return dixLookupPrivateAddr(privates,
 225                                 _dixGetScreenPrivateKey(key, pScreen));
 226 }
 227
 228 /*
 229  * These functions relate to allocations related to a specific screen;
 230  * space will only be available for objects allocated for use on that
 231  * screen. As such, only objects which are related directly to a specific
 232  * screen are candidates for allocation this way, this includes
 233  * windows, pixmaps, gcs, pictures and colormaps. This key is
 234  * used just like any other key using dixGetPrivate and friends.
 235  *
 236  * This is distinctly different from the ScreenPrivateKeys above which
 237  * allocate space in global objects like cursor bits for a specific
 238  * screen, allowing multiple screen-related chunks of storage in a
 239  * single global object.
 240  */
 241
 242 #define HAVE_SCREEN_SPECIFIC_PRIVATE_KEYS       1
 243
 244 extern _X_EXPORT Bool
 245 dixRegisterScreenSpecificPrivateKey(ScreenPtr pScreen, DevPrivateKey key,
 246                                     DevPrivateType type, unsigned size);
 247
 248 /* Clean up screen-specific privates before CloseScreen */
 249 extern void
 250 dixFreeScreenSpecificPrivates(ScreenPtr pScreen);
 251
 252 /* Initialize screen-specific privates in AddScreen */
 253 extern void
 254 dixInitScreenSpecificPrivates(ScreenPtr pScreen);
 255
 256 extern _X_EXPORT void *
 257 _dixAllocateScreenObjectWithPrivates(ScreenPtr pScreen,
 258                                      unsigned size,
 259                                      unsigned clear,
 260                                      unsigned offset,
 261                                      DevPrivateType type);
 262
 263 #define dixAllocateScreenObjectWithPrivates(s, t, type) _dixAllocateScreenObjectWithPrivates(s, sizeof(t), sizeof(t), offsetof(t, devPrivates), type)
 264
 265 extern _X_EXPORT int
 266 dixScreenSpecificPrivatesSize(ScreenPtr pScreen, DevPrivateType type);
 267
 268 extern _X_EXPORT void
 269 _dixInitScreenPrivates(ScreenPtr pScreen, PrivatePtr *privates, void *addr, DevPrivateType type);
 270
 271 #define dixInitScreenPrivates(s, o, v, type) _dixInitScreenPrivates(s, &(o)->devPrivates, (v), type);
 272
 273 /*
 274  * Allocates private data separately from main object.
 275  *
 276  * For objects created during server initialization, this allows those
 277  * privates to be re-allocated as new private keys are registered.
 278  *
 279  * This includes screens, the serverClient, default colormaps and
 280  * extensions entries.
 281  */
 282 extern _X_EXPORT Bool
 283  dixAllocatePrivates(PrivatePtr *privates, DevPrivateType type);
 284
 285 /*
 286  * Frees separately allocated private data
 287  */
 288 extern _X_EXPORT void
 289  dixFreePrivates(PrivatePtr privates, DevPrivateType type);
 290
 291 /*
 292  * Initialize privates by zeroing them
 293  */
 294 extern _X_EXPORT void
 295 _dixInitPrivates(PrivatePtr *privates, void *addr, DevPrivateType type);
 296
 297 #define dixInitPrivates(o, v, type) _dixInitPrivates(&(o)->devPrivates, (v), type);
 298
 299 /*
 300  * Clean up privates
 301  */
 302 extern _X_EXPORT void
 303  _dixFiniPrivates(PrivatePtr privates, DevPrivateType type);
 304
 305 #define dixFiniPrivates(o,t)    _dixFiniPrivates((o)->devPrivates,t)
 306
 307 /*
 308  * Allocates private data at object creation time. Required
 309  * for almost all objects, except for the list described
 310  * above for dixAllocatePrivates.
 311  */
 312 extern _X_EXPORT void *_dixAllocateObjectWithPrivates(unsigned size,
 313                                                       unsigned clear,
 314                                                       unsigned offset,
 315                                                       DevPrivateType type);
 316
 317 #define dixAllocateObjectWithPrivates(t, type) (t *) _dixAllocateObjectWithPrivates(sizeof(t), sizeof(t), offsetof(t, devPrivates), type)
 318
 319 extern _X_EXPORT void
 320
 321 _dixFreeObjectWithPrivates(void *object, PrivatePtr privates,
 322                            DevPrivateType type);
 323
 324 #define dixFreeObjectWithPrivates(o,t) _dixFreeObjectWithPrivates(o, (o)->devPrivates, t)
 325
 326 /*
 327  * Return size of privates for the specified type
 328  */
 329 extern _X_EXPORT int
 330  dixPrivatesSize(DevPrivateType type);
 331
 332 /*
 333  * Dump out private stats to ErrorF
 334  */
 335 extern void
 336  dixPrivateUsage(void);
 337
 338 /*
 339  * Resets the privates subsystem.  dixResetPrivates is called from the main loop
 340  * before each server generation.  This function must only be called by main().
 341  */
 342 extern _X_EXPORT void
 343  dixResetPrivates(void);
 344
 345 /*
 346  * Looks up the offset where the devPrivates field is located.
 347  *
 348  * Returns -1 if the specified resource has no dev privates.
 349  * The position of the devPrivates field varies by structure
 350  * and calling code might only know the resource type, not the
 351  * structure definition.
 352  */
 353 extern _X_EXPORT int
 354  dixLookupPrivateOffset(RESTYPE type);
 355
 356 /*
 357  * Convenience macro for adding an offset to an object pointer
 358  * when making a call to one of the devPrivates functions
 359  */
 360 #define DEVPRIV_AT(ptr, offset) ((PrivatePtr *)((char *)(ptr) + offset))
 361
 362 #endif                          /* PRIVATES_H */