rom/graphics/adddisplaydrivera.c

   1 /*
   2     Copyright © 1995-2011, The AROS Development Team. All rights reserved.
   3     $Id$
   4
   5     Desc: AROS-specific function for adding a display driver
   6     Lang: english
   7 */
   8
   9 #include <aros/debug.h>
  10 #include <graphics/driver.h>
  11 #include <hidd/compositing.h>
  12 #include <oop/oop.h>
  13
  14 #include <proto/utility.h>
  15
  16 #include "graphics_intern.h"
  17 #include "compositing_driver.h"
  18 #include "dispinfo.h"
  19
  20 #define CL(x) ((OOP_Class *)x)
  21 #define IS_CLASS(x, n) (CL(x)->ClassNode.ln_Name && (!strcmp(CL(x)->ClassNode.ln_Name, n)))
  22
  23 /*****************************************************************************
  24
  25     NAME */
  26 #include <proto/graphics.h>
  27
  28         AROS_LH3(ULONG, AddDisplayDriverA,
  29
  30 /*  SYNOPSIS */
  31         AROS_LHA(APTR, gfxclass, A0),
  32         AROS_LHA(struct TagItem *, attrs, A1),
  33         AROS_LHA(const struct TagItem *, tags, A2),
  34
  35 /*  LOCATION */
  36         struct GfxBase *, GfxBase, 107, Graphics)
  37
  38 /*  FUNCTION
  39         Add a display driver to the system.
  40
  41     INPUTS
  42         gfxhidd - A pointer to an OOP class of the display driver
  43         attrs   - Additional attributes to supply to the driver class during object creation
  44         tags    - An optional TagList describing how graphics.library should handle the driver.
  45                   Valid tags are:
  46
  47             DDRV_BootMode     - A boolean value telling that a boot mode driver
  48                                 is being added. Boot mode drivers will automatically
  49                                 shutdown on next AddDisplayDriverA() call, unless
  50                                 DDRV_KeepBootMode = TRUE is specified. Defaults to FALSE.
  51             DDRV_MonitorID    - Starting monitor ID to assign to the driver. Use it
  52                                 with care. Attempt to add already existing ID will
  53                                 fail with DD_ID_EXISTS code. By default a next available
  54                                 ID will be picked up automatically.
  55             DDRV_ReserveIDs   - A number of subsequent monitor IDs to reserve. Reserved IDs
  56                                 can be reused only with DDRV_MonitorID tag. This tag is
  57                                 provided as an aid to support possible removable display
  58                                 devices. Defaults to 1.
  59             DDRV_KeepBootMode - Do not shut down boot mode drivers. Use this tag if you
  60                                 are 100% sure that your driver won't conflict with boot mode
  61                                 driver (like VGA or VESA) and won't attempt to take over its
  62                                 hardware. Defaults to FALSE.
  63             DDRV_ResultID     - A pointer to ULONG location where ID assigned to your driver
  64                                 will be placed. Useful if you reserve some ID for future use.
  65                                 Note that returned ID will be the one just assigned to your
  66                                 driver instance. Increment it yourself in order to obtain
  67                                 other reserved IDs.
  68             DDRV_IDMask       - A mask for separating monitor ID from HIDD-specific part.
  69                                 This mask specifies what mode ID bits are monitor ID and
  70                                 what bits actually specify the mode. A default value is
  71                                 0xFFFF0000.
  72
  73                                 Using the mask you can split your monitor ID into 'sub-Ids'.
  74                                 Example:
  75
  76                                 Supplied tags: DDRV_IDMask, 0xFFFFFF00, DDRV_ResultID, &myid
  77
  78                                 After succesfull call myid will contain base ID assigned by
  79                                 graphics.library to your driver, let's say 0x00140000. However,
  80                                 since you specified longer mask, you leave only one byte for mode
  81                                 designation, and reserve the whole range of IDs from 0x001400xx to
  82                                 0x0014FFxx for different instances of your driver. They can now be
  83                                 used by specifying DDRV_MonitorID with corresponding value.
  84
  85                                 Note that for this feature to work correctly, you also need to override
  86                                 mode ID processing in your driver class. Default methods provided by
  87                                 hidd.graphics.graphics base class suppose that the whole lower word
  88                                 of mode ID specifies the display mode.
  89
  90                                 It is generally not allowed to specify shorter masks than 0xFFFF0000.
  91                                 The only driver which can do this is Amiga(tm) chipset driver, which
  92                                 need to occupy the reserved range of IDs from 0x0000xxxx to 0x000Axxxx.
  93                                 In any other case supplying short mask will cause undefined behavior.
  94
  95                                 Since DDRV_ReserveIDs provide simpler way to reserve IDs for your driver
  96                                 (without the need to override mode ID processing), this option can be
  97                                 considered experimental and even private. In fact the primary reason for
  98                                 it to exist is to provide support for Amiga(tm) chipset driver.
  99
 100     RESULT
 101         error - One of following codes:
 102
 103             DD_OK           - Operation completed OK.
 104             DD_NO_MEM       - There is not enough memory to set up internal data.
 105             DD_ID_EXISTS    - Attempt to assign monitor IDs that are already used.
 106             DD_IN_USE       - One of boot-mode drivers is in use and can not be shut down.
 107             DD_DRIVER_ERROR - Failure to create driver object.
 108
 109     NOTES
 110         This function is AROS-specific.
 111
 112     EXAMPLE
 113
 114     BUGS
 115
 116     SEE ALSO
 117
 118     INTERNALS
 119
 120     HISTORY
 121         29-10-95    digulla automatically created from
 122                             graphics_lib.fd and clib/graphics_protos.h
 123
 124 *****************************************************************************/
 125 {
 126     AROS_LIBFUNC_INIT
 127
 128     struct TagItem *tag, *tstate = (struct TagItem *)tags;
 129     struct monitor_driverdata *mdd;
 130     ULONG FirstID = INVALID_ID;
 131     ULONG NextID;
 132     ULONG NumIDs = 1;
 133     ULONG IDMask = AROS_MONITOR_ID_MASK;
 134     BOOL keep_boot = FALSE;
 135     UWORD flags = 0;
 136     ULONG *ResultID = NULL;
 137     ULONG ret = DD_OK;
 138
 139     EnterFunc(bug("AddDisplayDriverA(0x%p) <%s>\n", gfxclass, CL(gfxclass)->ClassNode.ln_Name));
 140
 141     /*
 142      * MAGIC: Detect composition HIDD here.
 143      * This allows to hotplug it, and even (potentially) replace.
 144      */
 145     if (IS_CLASS(gfxclass, CLID_Hidd_Compositing))
 146     {
 147         ObtainSemaphore(&CDD(GfxBase)->displaydb_sem);
 148         ret = composer_Install(gfxclass, GfxBase);
 149         ReleaseSemaphore(&CDD(GfxBase)->displaydb_sem);
 150
 151         return ret;
 152     }
 153
 154     /* First parse parameters */
 155     while ((tag = NextTagItem(&tstate)))
 156     {
 157         switch (tag->ti_Tag)
 158         {
 159         case DDRV_MonitorID:
 160             FirstID = tag->ti_Data;
 161             break;
 162
 163         case DDRV_ReserveIDs:
 164             NumIDs = tag->ti_Data;
 165             break;
 166
 167         case DDRV_IDMask:
 168             IDMask = tag->ti_Data;
 169             break;
 170
 171         case DDRV_KeepBootMode:
 172             keep_boot = tag->ti_Data;
 173             break;
 174
 175         case DDRV_BootMode:
 176             flags = tag->ti_Data ? DF_BootMode : 0;
 177             break;
 178
 179         case DDRV_ResultID:
 180             ResultID = (ULONG *)tag->ti_Data;
 181             break;
 182         }
 183     }
 184
 185     /* We lock for the entire function because we want to be sure that
 186        IDs will remain free during driver_Setup() */
 187     ObtainSemaphore(&CDD(GfxBase)->displaydb_sem);
 188
 189     /* Default value for monitor ID */
 190     if (FirstID == INVALID_ID)
 191     {
 192         /*
 193          * The logic here prevents ID clash if specified mask is wider than previous one.
 194          * Example situation:
 195          * 1. Add driver with mask = 0xFFFF0000. FirstID = 0x00100000, NextID = 0x00110000.
 196          * 2. Add driver with mask = 0xF0000000. FirstID = 0x00110000, AND with this mask
 197          *    would give monitor ID = 0.
 198          * In order to prevent this, we make one more increment, so that in (2) FirstID becomes
 199          * 0x10000000. The increment mechanism itself is explained below.
 200          * Note that the adjustments happens only for automatic ID assignment. In case of manual
 201          * one (DDRV_MonitorID specified) we suggest our caller knows what he does.
 202          */
 203         FirstID = CDD(GfxBase)->last_id & IDMask;
 204
 205         if (FirstID < CDD(GfxBase)->last_id)
 206             FirstID += (~(IDMask & AROS_MONITOR_ID_MASK) + 1);
 207     }
 208
 209     /*
 210      * Calculate next free ID.
 211      * Mechanism of increment calculation: we invert the mask and add 1 to it.
 212      * This way for example 0xFFFF0000 becomes 0x00010000.
 213      * Before doing this we make sure that mask used in this equation is not
 214      * longer than 0xFFFF0000, for proper ID counting.
 215      */
 216     NextID = FirstID + NumIDs * (~(IDMask & AROS_MONITOR_ID_MASK) + 1);
 217     D(bug("[AddDisplayDriverA] First ID 0x%08X, next ID 0x%08X\n", FirstID, NextID));
 218
 219     /* First check if the operation can actually be performed */
 220     for (mdd = CDD(GfxBase)->monitors; mdd; mdd = mdd->next)
 221     {
 222         /* Check if requested IDs are already allocated */
 223         if ((mdd->id >= FirstID && mdd->id < NextID))
 224         {
 225             ret = DD_ID_EXISTS;
 226             break;
 227         }
 228
 229         /*
 230          * Now check if boot mode drivers can really be unloaded.
 231          * Display drivers can start playing with their hardware during
 232          * object creation, so we need to check it before instantiating
 233          * the given class.
 234          */
 235         if (!keep_boot)
 236         {
 237             /* The driver can be unloaded if it has nothing on display */
 238             if ((mdd->flags & DF_BootMode) && (mdd->display))
 239             {
 240                 ret = DD_IN_USE;
 241                 break;
 242             }
 243         }
 244     }
 245
 246     /*
 247      * Now, if everything is okay, we are ready to instantiate the driver.
 248      * A well-behaved driver must touch the hardware only in object, not
 249      * in class. This makes this function much safer. If we can't exit boot mode,
 250      * the driver will not be instantiated and hardware state will not be clobbered.
 251      */
 252     if (ret == DD_OK)
 253     {
 254         OOP_Object *gfxhidd = OOP_NewObject(gfxclass, NULL, attrs);
 255
 256         if (gfxhidd)
 257         {
 258             D(bug("[AddDisplayDriverA] Installing driver\n"));
 259
 260             /* Attach system structures to the driver */
 261             mdd = driver_Setup(gfxhidd, GfxBase);
 262             D(bug("[AddDisplayDriverA] monitor_driverdata 0x%p\n", mdd));
 263
 264             if (mdd)
 265             {
 266                 struct monitor_driverdata *last, *old;
 267
 268                 mdd->id    =  FirstID;
 269                 mdd->mask  =  IDMask;
 270                 mdd->flags |= flags;
 271
 272                 if (CDD(GfxBase)->DriverNotify)
 273                 {
 274                     /* Use mdd->gfxhidd here because it can be substituted by fakegfx object */
 275                     mdd->userdata = CDD(GfxBase)->DriverNotify(mdd, TRUE, CDD(GfxBase)->notify_data);
 276                 }
 277
 278                 /* Remove boot mode drivers */
 279                 if (!keep_boot)
 280                 {
 281                     D(bug("[AddDisplayDriverA] Shutting down boot mode drivers\n"));
 282                     for (last = (struct monitor_driverdata *)CDD(GfxBase);; last = last->next)
 283                     {
 284                         D(bug("[AddDisplayDriverA] Current 0x%p, next 0x%p\n", last, last->next));
 285
 286                         while (last->next && (last->next->flags & DF_BootMode))
 287                         {
 288                             old = last->next;
 289                             D(bug("[AddDisplayDriverA] Shutting down driver 0x%p (ID 0x%08lX, next 0x%p)\n", old, old->id, old->next));
 290
 291                             last->next = old->next;
 292                             driver_Expunge(old, GfxBase);
 293                             D(bug("[AddDisplayDriverA] Shutdown OK, next 0x%p\n", last->next));
 294                         }
 295
 296                         /*
 297                          * We check this condition here explicitly because last->next is modified inside loop body.
 298                          * If we check it in for() statement, last = last->next will be executed BEFORE the check,
 299                          * and NULL pointer may be hit.
 300                          */
 301                         if (!last->next)
 302                             break;
 303                     }
 304                 }
 305
 306                 /* Insert the driverdata into chain, sorted by ID */
 307                 D(bug("[AddDisplayDriverA] Inserting driver 0x%p, ID 0x%08lX\n", mdd, mdd->id));
 308                 for (last = (struct monitor_driverdata *)CDD(GfxBase); last->next; last = last->next)
 309                 {
 310                     D(bug("[AddDisplayDriverA] Current 0x%p, next 0x%p, ID 0x%08lX\n", last, last->next, last->next->id));
 311                     if (mdd->id < last->next->id)
 312                         break;
 313                 }
 314
 315                 D(bug("[AddDisplayDriverA] Inserting after 0x%p\n", last));
 316                 mdd->next = last->next;
 317                 last->next = mdd;
 318
 319                 /* Remember next available ID */
 320                 if (NextID > CDD(GfxBase)->last_id)
 321                     CDD(GfxBase)->last_id = NextID;
 322
 323                 /* Return the assigned ID if the caller asked to do so */
 324                 if (ResultID)
 325                     *ResultID = FirstID;
 326             }
 327             else /* if (mdd) */
 328             {
 329                 OOP_DisposeObject(gfxhidd);
 330                 ret = DD_NO_MEM;
 331             }
 332         }
 333         else /* if (gfxhidd) */
 334         {
 335             ret = DD_DRIVER_ERROR;
 336         }
 337     } /* if (ret == DD_OK) */
 338
 339     ReleaseSemaphore(&CDD(GfxBase)->displaydb_sem);
 340
 341     /* Set the first non-boot non-planar driver as default */
 342     if ((ret == DD_OK) && (!GfxBase->default_monitor) && (!(mdd->flags & DF_BootMode)))
 343     {
 344         /*
 345          * Amiga(tm) chipset driver does not become a default.
 346          * This is done because RTG modes (if any) are commonly preferred
 347          * over it.
 348          * TODO: in future some prefs program could be implemented. It would
 349          * allow the user to describe the physical placement of several displays
 350          * in his environment, and explicitly set the preferred display.
 351          */
 352         if (!IS_CLASS(gfxclass, "hidd.gfx.amigavideo"))
 353         {
 354             /*
 355              * graphics.library uses struct MonitorSpec pointers for historical reasons,
 356              * so we satisfy it.
 357              * Here we just get the first available sync object from the driver and
 358              * set default_monitor fo its MonitorSpec. This allows BestModeIDA() to
 359              * obtain preferred monitor back from this MonitorSpec (by asking the associated
 360              * sync object about its parent driver).
 361              *
 362              * TODO:
 363              * Originally display drivers in AmigaOS had a concept of "preferred mode ID".
 364              * Every driver supplied own hardcoded ID which can be retrieved by GetDisplayInfoData()
 365              * in MonitorInfo->PreferredModeID. Currently AROS does not implement this concept.
 366              * However this sync could be a preferred mode's sync.
 367              * It needs to be researched what exactly this mode ID is. Implementing this concept would
 368              * improve AmigaOS(tm) compatibility.
 369              */
 370             OOP_Object *sync = HIDD_Gfx_GetSync(mdd->gfxhidd_orig, 0);
 371
 372             OOP_GetAttr(sync, aHidd_Sync_MonitorSpec, (IPTR *)&GfxBase->default_monitor);
 373         }
 374     }
 375
 376     D(bug("[AddDisplayDriverA] Returning %u\n", ret));
 377     return ret;
 378
 379     AROS_LIBFUNC_EXIT
 380 } /* LateGfxInit */