privates.h revision 6747b715 
1/***********************************************************
2
3THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
4IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
5FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
6AUTHOR BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
7AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
8CONNECTION 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
24typedef struct _Private PrivateRec, *PrivatePtr;
25
26typedef 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
37    /* These cannot have any objects before all relevant keys are registered */
38    PRIVATE_DEVICE,
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
55    /* last private type */
56    PRIVATE_LAST,
57} DevPrivateType;
58
59typedef struct _DevPrivateKeyRec {
60    int			offset;
61    int			size;
62    Bool		initialized;
63    Bool		allocated;
64    DevPrivateType	type;
65    struct _DevPrivateKeyRec	*next;
66} DevPrivateKeyRec, *DevPrivateKey;
67
68/*
69 * Let drivers know how to initialize private keys
70 */
71
72#define HAS_DEVPRIVATEKEYREC		1
73#define HAS_DIXREGISTERPRIVATEKEY	1
74
75/*
76 * Register a new private index for the private type.
77 *
78 * This initializes the specified key and optionally requests pre-allocated
79 * private space for your driver/module. If you request no extra space, you
80 * may set and get a single pointer value using this private key. Otherwise,
81 * you can get the address of the extra space and store whatever data you like
82 * there.
83 *
84 * You may call dixRegisterPrivateKey more than once on the same key, but the
85 * size and type must match or the server will abort.
86 *
87 * dixRegisterPrivateKey returns FALSE if it fails to allocate memory
88 * during its operation.
89 */
90extern _X_EXPORT Bool
91dixRegisterPrivateKey(DevPrivateKey key, DevPrivateType type, unsigned size);
92
93/*
94 * Check whether a private key has been registered
95 */
96static inline Bool
97dixPrivateKeyRegistered(DevPrivateKey key)
98{
99    return key->initialized;
100}
101
102/*
103 * Allocate a new private key.
104 *
105 * This manages the storage of the key object itself, freeing it when the
106 * privates system is restarted at server reset time. All other keys
107 * are expected to be statically allocated as the privates must be
108 * reset after all objects have been freed
109 */
110extern _X_EXPORT DevPrivateKey
111dixCreatePrivateKey(DevPrivateType type, unsigned size);
112
113/*
114 * Get the address of the private storage.
115 *
116 * For keys with pre-defined storage, this gets the base of that storage
117 * Otherwise, it returns the place where the private pointer is stored.
118 */
119static inline void *
120dixGetPrivateAddr(PrivatePtr *privates, const DevPrivateKey key)
121{
122    assert(key->initialized);
123    return (char *) (*privates) + key->offset;
124}
125
126/*
127 * Fetch a private pointer stored in the object
128 *
129 * Returns the pointer stored with dixSetPrivate.
130 * This must only be used with keys that have
131 * no pre-defined storage
132 */
133static inline void *
134dixGetPrivate(PrivatePtr *privates, const DevPrivateKey key)
135{
136    assert (key->size == 0);
137    return *(void **) dixGetPrivateAddr(privates, key);
138}
139
140/*
141 * Associate 'val' with 'key' in 'privates' so that later calls to
142 * dixLookupPrivate(privates, key) will return 'val'.
143 */
144static inline void
145dixSetPrivate(PrivatePtr *privates, const DevPrivateKey key, pointer val)
146{
147    assert (key->size == 0);
148    *(pointer *) dixGetPrivateAddr(privates, key) = val;
149}
150
151#include "dix.h"
152#include "resource.h"
153
154/*
155 * Lookup a pointer to the private record.
156 *
157 * For privates with defined storage, return the address of the
158 * storage. For privates without defined storage, return the pointer
159 * contents
160 */
161static inline pointer
162dixLookupPrivate(PrivatePtr *privates, const DevPrivateKey key)
163{
164    if (key->size)
165	return dixGetPrivateAddr(privates, key);
166    else
167	return dixGetPrivate(privates, key);
168}
169
170/*
171 * Look up the address of the pointer to the storage
172 *
173 * This returns the place where the private pointer is stored,
174 * which is only valid for privates without predefined storage.
175 */
176static inline pointer *
177dixLookupPrivateAddr(PrivatePtr *privates, const DevPrivateKey key)
178{
179    assert (key->size == 0);
180    return (pointer *)dixGetPrivateAddr(privates, key);
181}
182
183/*
184 * Allocates private data separately from main object.
185 *
186 * For objects created during server initialization, this allows those
187 * privates to be re-allocated as new private keys are registered.
188 *
189 * This includes screens, the serverClient, default colormaps and
190 * extensions entries.
191 */
192extern _X_EXPORT Bool
193dixAllocatePrivates(PrivatePtr *privates, DevPrivateType type);
194
195/*
196 * Frees separately allocated private data
197 */
198extern _X_EXPORT void
199dixFreePrivates(PrivatePtr privates, DevPrivateType type);
200
201/*
202 * Initialize privates by zeroing them
203 */
204extern _X_EXPORT void
205_dixInitPrivates(PrivatePtr *privates, void *addr, DevPrivateType type);
206
207#define dixInitPrivates(o, v, type) _dixInitPrivates(&(o)->devPrivates, (v), type);
208
209/*
210 * Clean up privates
211 */
212extern _X_EXPORT void
213_dixFiniPrivates(PrivatePtr privates, DevPrivateType type);
214
215#define dixFiniPrivates(o,t)	_dixFiniPrivates((o)->devPrivates,t)
216
217/*
218 * Allocates private data at object creation time. Required
219 * for almost all objects, except for the list described
220 * above for dixAllocatePrivates.
221 */
222extern _X_EXPORT void *
223_dixAllocateObjectWithPrivates(unsigned size, unsigned clear, unsigned offset, DevPrivateType type);
224
225#define dixAllocateObjectWithPrivates(t, type) (t *) _dixAllocateObjectWithPrivates(sizeof(t), sizeof(t), offsetof(t, devPrivates), type)
226
227extern _X_EXPORT void
228_dixFreeObjectWithPrivates(void *object, PrivatePtr privates, DevPrivateType type);
229
230#define dixFreeObjectWithPrivates(o,t) _dixFreeObjectWithPrivates(o, (o)->devPrivates, t)
231
232/*
233 * Return size of privates for the specified type
234 */
235extern _X_EXPORT int
236dixPrivatesSize(DevPrivateType type);
237
238/*
239 * Dump out private stats to ErrorF
240 */
241extern void
242dixPrivateUsage(void);
243
244/*
245 * Resets the privates subsystem.  dixResetPrivates is called from the main loop
246 * before each server generation.  This function must only be called by main().
247 */
248extern _X_EXPORT void
249dixResetPrivates(void);
250
251/*
252 * Looks up the offset where the devPrivates field is located.
253 *
254 * Returns -1 if the specified resource has no dev privates.
255 * The position of the devPrivates field varies by structure
256 * and calling code might only know the resource type, not the
257 * structure definition.
258 */
259extern _X_EXPORT int
260dixLookupPrivateOffset(RESTYPE type);
261
262/*
263 * Convenience macro for adding an offset to an object pointer
264 * when making a call to one of the devPrivates functions
265 */
266#define DEVPRIV_AT(ptr, offset) ((PrivatePtr *)((char *)(ptr) + offset))
267
268#endif /* PRIVATES_H */
269