hw/xfree86/common/xf86Module.h

   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 "misc.h"
  45 #include "extension.h"
  46 #ifndef NULL
  47 #define NULL ((void *)0)
  48 #endif
  49
  50 typedef enum {
  51     LD_RESOLV_IFDONE = 0,       /* only check if no more
  52                                    delays pending */
  53     LD_RESOLV_NOW = 1,          /* finish one delay step */
  54     LD_RESOLV_FORCE = 2         /* force checking... */
  55 } LoaderResolveOptions;
  56
  57 #define DEFAULT_LIST ((char *)-1)
  58
  59 /* Built-in ABI classes.  These definitions must not be changed. */
  60 #define ABI_CLASS_NONE          NULL
  61 #define ABI_CLASS_ANSIC         "X.Org ANSI C Emulation"
  62 #define ABI_CLASS_VIDEODRV      "X.Org Video Driver"
  63 #define ABI_CLASS_XINPUT        "X.Org XInput driver"
  64 #define ABI_CLASS_EXTENSION     "X.Org Server Extension"
  65 #define ABI_CLASS_FONT          "X.Org Font Renderer"
  66
  67 #define ABI_MINOR_MASK          0x0000FFFF
  68 #define ABI_MAJOR_MASK          0xFFFF0000
  69 #define GET_ABI_MINOR(v)        ((v) & ABI_MINOR_MASK)
  70 #define GET_ABI_MAJOR(v)        (((v) & ABI_MAJOR_MASK) >> 16)
  71 #define SET_ABI_VERSION(maj, min) \
  72                 ((((maj) << 16) & ABI_MAJOR_MASK) | ((min) & ABI_MINOR_MASK))
  73
  74 /*
  75  * ABI versions.  Each version has a major and minor revision.  Modules
  76  * using lower minor revisions must work with servers of a higher minor
  77  * revision.  There is no compatibility between different major revisions.
  78  * Whenever the ABI_ANSIC_VERSION is changed, the others must also be
  79  * changed.  The minor revision mask is 0x0000FFFF and the major revision
  80  * mask is 0xFFFF0000.
  81  */
  82 #define ABI_ANSIC_VERSION       SET_ABI_VERSION(0, 4)
  83 #define ABI_VIDEODRV_VERSION    SET_ABI_VERSION(15, 0)
  84 #define ABI_XINPUT_VERSION      SET_ABI_VERSION(20, 0)
  85 #define ABI_EXTENSION_VERSION   SET_ABI_VERSION(8, 0)
  86 #define ABI_FONT_VERSION        SET_ABI_VERSION(0, 6)
  87
  88 #define MODINFOSTRING1  0xef23fdc5
  89 #define MODINFOSTRING2  0x10dc023a
  90
  91 #ifndef MODULEVENDORSTRING
  92 #define MODULEVENDORSTRING      "X.Org Foundation"
  93 #endif
  94
  95 /* Error return codes for errmaj.  New codes must only be added at the end. */
  96 typedef enum {
  97     LDR_NOERROR = 0,
  98     LDR_NOMEM,                  /* memory allocation failed */
  99     LDR_NOENT,                  /* Module file does not exist */
 100     LDR_NOSUBENT,               /* pre-requsite file to be sub-loaded does not exist */
 101     LDR_NOSPACE,                /* internal module array full */
 102     LDR_NOMODOPEN,              /* module file could not be opened (check errmin) */
 103     LDR_UNKTYPE,                /* file is not a recognized module type */
 104     LDR_NOLOAD,                 /* type specific loader failed */
 105     LDR_ONCEONLY,               /* Module should only be loaded once (not an error) */
 106     LDR_NOPORTOPEN,             /* could not open port (check errmin) */
 107     LDR_NOHARDWARE,             /* could not query/initialize the hardware device */
 108     LDR_MISMATCH,               /* the module didn't match the spec'd requirments */
 109     LDR_BADUSAGE,               /* LoadModule is called with bad arguments */
 110     LDR_INVALID,                /* The module doesn't have a valid ModuleData object */
 111     LDR_BADOS,                  /* The module doesn't support the OS */
 112     LDR_MODSPECIFIC             /* A module-specific error in the SetupProc */
 113 } LoaderErrorCode;
 114
 115 /*
 116  * Some common module classes.  The moduleclass can be used to identify
 117  * that modules loaded are of the correct type.  This is a finer
 118  * classification than the ABI classes even though the default set of
 119  * classes have the same names.  For example, not all modules that require
 120  * the video driver ABI are themselves video drivers.
 121  */
 122 #define MOD_CLASS_NONE          NULL
 123 #define MOD_CLASS_VIDEODRV      "X.Org Video Driver"
 124 #define MOD_CLASS_XINPUT        "X.Org XInput Driver"
 125 #define MOD_CLASS_FONT          "X.Org Font Renderer"
 126 #define MOD_CLASS_EXTENSION     "X.Org Server Extension"
 127
 128 /* This structure is expected to be returned by the initfunc */
 129 typedef struct {
 130     const char *modname;        /* name of module, e.g. "foo" */
 131     const char *vendor;         /* vendor specific string */
 132     CARD32 _modinfo1_;          /* constant MODINFOSTRING1/2 to find */
 133     CARD32 _modinfo2_;          /* infoarea with a binary editor or sign tool */
 134     CARD32 xf86version;         /* contains XF86_VERSION_CURRENT */
 135     CARD8 majorversion;         /* module-specific major version */
 136     CARD8 minorversion;         /* module-specific minor version */
 137     CARD16 patchlevel;          /* module-specific patch level */
 138     const char *abiclass;       /* ABI class that the module uses */
 139     CARD32 abiversion;          /* ABI version */
 140     const char *moduleclass;    /* module class description */
 141     CARD32 checksum[4];         /* contains a digital signature of the */
 142     /* version info structure */
 143 } XF86ModuleVersionInfo;
 144
 145 /*
 146  * This structure can be used to callers of LoadModule and LoadSubModule to
 147  * specify version and/or ABI requirements.
 148  */
 149 typedef struct {
 150     CARD8 majorversion;         /* module-specific major version */
 151     CARD8 minorversion;         /* moudle-specific minor version */
 152     CARD16 patchlevel;          /* module-specific patch level */
 153     const char *abiclass;       /* ABI class that the module uses */
 154     CARD32 abiversion;          /* ABI version */
 155     const char *moduleclass;    /* module class */
 156 } XF86ModReqInfo;
 157
 158 /* values to indicate unspecified fields in XF86ModReqInfo. */
 159 #define MAJOR_UNSPEC            0xFF
 160 #define MINOR_UNSPEC            0xFF
 161 #define PATCH_UNSPEC            0xFFFF
 162 #define ABI_VERS_UNSPEC         0xFFFFFFFF
 163
 164 #define MODULE_VERSION_NUMERIC(maj, min, patch) \
 165         ((((maj) & 0xFF) << 24) | (((min) & 0xFF) << 16) | (patch & 0xFFFF))
 166 #define GET_MODULE_MAJOR_VERSION(vers)  (((vers) >> 24) & 0xFF)
 167 #define GET_MODULE_MINOR_VERSION(vers)  (((vers) >> 16) & 0xFF)
 168 #define GET_MODULE_PATCHLEVEL(vers)     ((vers) & 0xFFFF)
 169
 170 #define INITARGS void
 171
 172 /* Prototypes for Loader functions that are exported to modules */
 173 extern _X_EXPORT pointer LoadSubModule(pointer, const char *, const char **,
 174                                        const char **, pointer,
 175                                        const XF86ModReqInfo *, int *, int *);
 176 extern _X_EXPORT void UnloadSubModule(pointer);
 177 extern _X_EXPORT void UnloadModule(pointer);
 178 extern _X_EXPORT pointer LoaderSymbol(const char *);
 179 extern _X_EXPORT char **LoaderListDirs(const char **, const char **);
 180 extern _X_EXPORT void LoaderFreeDirList(char **);
 181 extern _X_EXPORT void LoaderErrorMsg(const char *, const char *, int, int);
 182 extern _X_EXPORT void LoaderGetOS(const char **name, int *major, int *minor,
 183                                   int *teeny);
 184 extern _X_EXPORT Bool LoaderShouldIgnoreABI(void);
 185 extern _X_EXPORT int LoaderGetABIVersion(const char *abiclass);
 186
 187 typedef pointer (*ModuleSetupProc) (pointer, pointer, int *, int *);
 188 typedef void (*ModuleTearDownProc) (pointer);
 189
 190 #define MODULESETUPPROTO(func) pointer func(pointer, pointer, int*, int*)
 191 #define MODULETEARDOWNPROTO(func) void func(pointer)
 192
 193 typedef struct {
 194     XF86ModuleVersionInfo *vers;
 195     ModuleSetupProc setup;
 196     ModuleTearDownProc teardown;
 197 } XF86ModuleData;
 198
 199 #endif                          /* _XF86STR_H */