xf86Module.h revision ed6184df 
1/*
2 * Copyright (c) 1997-2003 by The XFree86 Project, Inc.
3 *
4 * Permission is hereby granted, free of charge, to any person obtaining a
5 * copy of this software and associated documentation files (the "Software"),
6 * to deal in the Software without restriction, including without limitation
7 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
8 * and/or sell copies of the Software, and to permit persons to whom the
9 * Software is furnished to do so, subject to the following conditions:
10 *
11 * The above copyright notice and this permission notice shall be included in
12 * all copies or substantial portions of the Software.
13 *
14 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
17 * THE COPYRIGHT HOLDER(S) OR AUTHOR(S) BE LIABLE FOR ANY CLAIM, DAMAGES OR
18 * OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
19 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
20 * OTHER DEALINGS IN THE SOFTWARE.
21 *
22 * Except as contained in this notice, the name of the copyright holder(s)
23 * and author(s) shall not be used in advertising or otherwise to promote
24 * the sale, use or other dealings in this Software without prior written
25 * authorization from the copyright holder(s) and author(s).
26 */
27
28/*
29 * This file contains the parts of the loader interface that are visible
30 * to modules.  This is the only loader-related header that modules should
31 * include.
32 *
33 * It should include a bare minimum of other headers.
34 *
35 * Longer term, the module/loader code should probably live directly under
36 * Xserver/.
37 *
38 * XXX This file arguably belongs in xfree86/loader/.
39 */
40
41#ifndef _XF86MODULE_H
42#define _XF86MODULE_H
43
44#include <X11/Xfuncproto.h>
45#include <X11/Xdefs.h>
46#include <X11/Xmd.h>
47
48#ifndef NULL
49#define NULL ((void *)0)
50#endif
51
52#define DEFAULT_LIST ((char *)-1)
53
54/* Built-in ABI classes.  These definitions must not be changed. */
55#define ABI_CLASS_NONE		NULL
56#define ABI_CLASS_ANSIC		"X.Org ANSI C Emulation"
57#define ABI_CLASS_VIDEODRV	"X.Org Video Driver"
58#define ABI_CLASS_XINPUT	"X.Org XInput driver"
59#define ABI_CLASS_EXTENSION	"X.Org Server Extension"
60
61#define ABI_MINOR_MASK		0x0000FFFF
62#define ABI_MAJOR_MASK		0xFFFF0000
63#define GET_ABI_MINOR(v)	((v) & ABI_MINOR_MASK)
64#define GET_ABI_MAJOR(v)	(((v) & ABI_MAJOR_MASK) >> 16)
65#define SET_ABI_VERSION(maj, min) \
66		((((maj) << 16) & ABI_MAJOR_MASK) | ((min) & ABI_MINOR_MASK))
67
68/*
69 * ABI versions.  Each version has a major and minor revision.  Modules
70 * using lower minor revisions must work with servers of a higher minor
71 * revision.  There is no compatibility between different major revisions.
72 * Whenever the ABI_ANSIC_VERSION is changed, the others must also be
73 * changed.  The minor revision mask is 0x0000FFFF and the major revision
74 * mask is 0xFFFF0000.
75 */
76#define ABI_ANSIC_VERSION	SET_ABI_VERSION(0, 4)
77#define ABI_VIDEODRV_VERSION	SET_ABI_VERSION(25, 2)
78#define ABI_XINPUT_VERSION	SET_ABI_VERSION(24, 4)
79#define ABI_EXTENSION_VERSION	SET_ABI_VERSION(10, 0)
80
81#define MODINFOSTRING1	0xef23fdc5
82#define MODINFOSTRING2	0x10dc023a
83
84#ifndef MODULEVENDORSTRING
85#define MODULEVENDORSTRING	"X.Org Foundation"
86#endif
87
88/* Error return codes for errmaj */
89typedef enum {
90    LDR_NOERROR = 0,
91    LDR_NOMEM,                  /* memory allocation failed */
92    LDR_NOENT,                  /* Module file does not exist */
93    LDR_NOLOAD,                 /* type specific loader failed */
94    LDR_ONCEONLY,               /* Module should only be loaded once (not an error) */
95    LDR_MISMATCH,               /* the module didn't match the spec'd requirements */
96    LDR_BADUSAGE,               /* LoadModule is called with bad arguments */
97    LDR_INVALID,                /* The module doesn't have a valid ModuleData object */
98    LDR_BADOS,                  /* The module doesn't support the OS */
99    LDR_MODSPECIFIC             /* A module-specific error in the SetupProc */
100} LoaderErrorCode;
101
102/*
103 * Some common module classes.  The moduleclass can be used to identify
104 * that modules loaded are of the correct type.  This is a finer
105 * classification than the ABI classes even though the default set of
106 * classes have the same names.  For example, not all modules that require
107 * the video driver ABI are themselves video drivers.
108 */
109#define MOD_CLASS_NONE		NULL
110#define MOD_CLASS_VIDEODRV	"X.Org Video Driver"
111#define MOD_CLASS_XINPUT	"X.Org XInput Driver"
112#define MOD_CLASS_EXTENSION	"X.Org Server Extension"
113
114/* This structure is expected to be returned by the initfunc */
115typedef struct {
116    const char *modname;        /* name of module, e.g. "foo" */
117    const char *vendor;         /* vendor specific string */
118    CARD32 _modinfo1_;          /* constant MODINFOSTRING1/2 to find */
119    CARD32 _modinfo2_;          /* infoarea with a binary editor or sign tool */
120    CARD32 xf86version;         /* contains XF86_VERSION_CURRENT */
121    CARD8 majorversion;         /* module-specific major version */
122    CARD8 minorversion;         /* module-specific minor version */
123    CARD16 patchlevel;          /* module-specific patch level */
124    const char *abiclass;       /* ABI class that the module uses */
125    CARD32 abiversion;          /* ABI version */
126    const char *moduleclass;    /* module class description */
127    CARD32 checksum[4];         /* contains a digital signature of the */
128    /* version info structure */
129} XF86ModuleVersionInfo;
130
131/*
132 * This structure can be used to callers of LoadModule and LoadSubModule to
133 * specify version and/or ABI requirements.
134 */
135typedef struct {
136    CARD8 majorversion;         /* module-specific major version */
137    CARD8 minorversion;         /* moudle-specific minor version */
138    CARD16 patchlevel;          /* module-specific patch level */
139    const char *abiclass;       /* ABI class that the module uses */
140    CARD32 abiversion;          /* ABI version */
141    const char *moduleclass;    /* module class */
142} XF86ModReqInfo;
143
144#define MODULE_VERSION_NUMERIC(maj, min, patch) \
145	((((maj) & 0xFF) << 24) | (((min) & 0xFF) << 16) | (patch & 0xFFFF))
146#define GET_MODULE_MAJOR_VERSION(vers)	(((vers) >> 24) & 0xFF)
147#define GET_MODULE_MINOR_VERSION(vers)	(((vers) >> 16) & 0xFF)
148#define GET_MODULE_PATCHLEVEL(vers)	((vers) & 0xFFFF)
149
150#define INITARGS void
151
152/* Prototypes for Loader functions that are exported to modules */
153extern _X_EXPORT void *LoadSubModule(void *, const char *, const char **,
154                                       const char **, void *,
155                                       const XF86ModReqInfo *, int *, int *);
156extern _X_EXPORT void UnloadSubModule(void *);
157extern _X_EXPORT void UnloadModule(void *);
158extern _X_EXPORT void *LoaderSymbol(const char *);
159extern _X_EXPORT void *LoaderSymbolFromModule(void *, const char *);
160extern _X_EXPORT void LoaderErrorMsg(const char *, const char *, int, int);
161extern _X_EXPORT Bool LoaderShouldIgnoreABI(void);
162extern _X_EXPORT int LoaderGetABIVersion(const char *abiclass);
163
164typedef void *(*ModuleSetupProc) (void *, void *, int *, int *);
165typedef void (*ModuleTearDownProc) (void *);
166
167#define MODULESETUPPROTO(func) void *func(void *, void *, int*, int*)
168#define MODULETEARDOWNPROTO(func) void func(void *)
169
170typedef struct {
171    XF86ModuleVersionInfo *vers;
172    ModuleSetupProc setup;
173    ModuleTearDownProc teardown;
174} XF86ModuleData;
175
176#endif                          /* _XF86STR_H */
177