include/igd.h

   1 /*
   2  *-----------------------------------------------------------------------------
   3  * Filename: igd.h
   4  * $Revision: 1.22 $
   5  *-----------------------------------------------------------------------------
   6  * Copyright (c) 2002-2010, Intel Corporation.
   7  *
   8  * Permission is hereby granted, free of charge, to any person obtaining a copy
   9  * of this software and associated documentation files (the "Software"), to deal
  10  * in the Software without restriction, including without limitation the rights
  11  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  12  * copies of the Software, and to permit persons to whom the Software is
  13  * furnished to do so, subject to the following conditions:
  14  *
  15  * The above copyright notice and this permission notice shall be included in
  16  * all copies or substantial portions of the Software.
  17  *
  18  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  19  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  20  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  21  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  22  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  23  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  24  * THE SOFTWARE.
  25  *
  26  *-----------------------------------------------------------------------------
  27  * Description:
  28  *  This file contains the top level dispatch table definition and includes
  29  *  the common header files necessary to interface with the shingle springs
  30  *  graphics driver.
  31  *-----------------------------------------------------------------------------
  32  */
  33
  34 #ifndef _IGD_H
  35 #define _IGD_H
  36
  37 #include <config.h>
  38 #include <igd_errno.h>
  39 #include <igd_mode.h>
  40 #include <igd_appcontext.h>
  41 #include <igd_render.h>
  42 #include <igd_2d.h>
  43 #include <igd_pd.h>
  44 #include <igd_gmm.h>
  45 #include <igd_rb.h>
  46 #include <igd_ovl.h>
  47 #include <emgd_shared.h>
  48
  49 /*
  50  * This is needed so that 16bit ports can use a far pointer on some
  51  * of the prototypes.
  52  */
  53 #ifndef FAR
  54 #define FAR
  55 #endif
  56
  57
  58
  59 /*!
  60  * @ingroup render_group
  61  * @brief Dispatch table for accessing all runtime driver functions.
  62  *
  63  * This is the dispatch table for the driver. All rendering and driver
  64  * manipulation functionality is done by calling functions within this
  65  * dispatch table.
  66  * This dispatch table will be populated during the igd_module_init()
  67  * function call. Upon returning from that call all usable members
  68  * will be populated. Any members left as NULL are not supported in the
  69  * current HAL configuration and cannot be used.
  70  */
  71 typedef struct _igd_dispatch {
  72         /*!
  73          * Save the register state of the graphics engine.
  74          * This function is optional in the HAL. The caller must check that it
  75          * is non-null before calling.
  76          *
  77          * @param driver_handle The driver handle returned from igd_driver_init().
  78          *
  79          * @param flags Any combination of the @ref driver_save_flags
  80          *  flags which control the types of state to be saved. Also used to
  81          *  specify where we save the register data.
  82          *
  83          * @return 0 on Success
  84          * @return <0 on Error
  85          */
  86         int (*driver_save)(igd_driver_h driver_handle,
  87                 const unsigned long flags);
  88
  89         /*!
  90          * Restore the graphics engine to a previously saved state.
  91          * This function is optional in the HAL. The caller must check that it
  92          * is non-null before calling.
  93          *
  94          * @param driver_handle The driver handle returned from igd_driver_init().
  95          *
  96          * @param flags Used to specify where we are restoring from,
  97          *  @ref driver_save_flags
  98          *
  99          * @return 0 on Success
 100          * @return <0 on Error
 101          */
 102         int (*driver_restore)(igd_driver_h driver_handle,
 103                 const unsigned long flags);
 104
 105         /*!
 106          * Save all driver registers and then restore all
 107          *   registers from a previously saved set.
 108          * This function is optional in the HAL. The caller must check that it
 109          * is non-null before calling.
 110          *
 111          * @param driver_handle The driver handle returned from igd_driver_init().
 112          * @param flags Flags indicating what registers to save
 113          *
 114          * @return 0 on Success
 115          * @return <0 on Error
 116          */
 117         int (*driver_save_restore)(igd_driver_h driver_handle, unsigned long flags);
 118
 119         /*!
 120          * Gets the value of a runtime driver parameter. These parameters are
 121          * each defined with a unique ID and may be altered at runtime.
 122          *
 123          * @note: There is a wrapper for this function in the dispatch table that
 124          * takes a display instead of a driver handle. This version is for use
 125          * when displays are not yet available.
 126          *
 127          * @return 0 Success
 128          * @return -IGD_INVAL Error
 129          */
 130         int (*get_param)(igd_display_h display_handle, unsigned long id,
 131                 unsigned long *value);
 132
 133         /*!
 134          * Sets the value of a runtime driver parameter. These parameters are
 135          * each defined with a unique ID and may be altered at runtime.
 136          *
 137          * Note: There is a wrapper for this function in the dispatch table that
 138          * takes a display instead of a driver handle. This version is for use
 139          * when displays are not yet available.
 140          *
 141          * @return 0 Success
 142          * @return  -IGD_INVAL Error
 143          */
 144         int (*set_param)(igd_display_h display_handle, unsigned long id,
 145                 unsigned long value);
 146
 147         /*!
 148          *  This function returns the list of available pixel formats for the
 149          *  framebuffer and the list of available pixel formats for the cursor.
 150          *
 151          *  Both lists end with NULL.  They are read only and should
 152          *  not be modified.
 153          *
 154          *  @bug To be converted to take a driver handle for IEGD 5.1
 155          *
 156          *  @param display_handle A igd_display_h type returned from a previous
 157          *    display->alter_displays() call.
 158          *
 159          *  fb_list_pfs  - Returns the list of pixel formats for the framebuffer.
 160          *
 161          *  cu_list_pfs - Returns the list of pixel formats for the cursor.
 162          *
 163          *
 164          * Returns:
 165          *  0: Success
 166          *  -IGD_INVAL: Error;
 167          */
 168         int (*get_pixelformats)(igd_display_h display_handle,
 169                 unsigned long **fb_list_pfs, unsigned long **cu_list_pfs,
 170                 unsigned long **overlay_pfs, unsigned long **render_pfs,
 171                 unsigned long **texture_pfs);
 172
 173         /*!
 174          * @brief Return the list of available DCs.
 175          *
 176          * query_dc() returns the live zero terminated Display Configuration list.
 177          *  All usable display configurations are returned from the HAL. The IAL
 178          *  must select one from the list when calling alter_displays().
 179          *
 180          * @param driver_handle The driver handle returned from igd_driver_init()
 181          *
 182          * @param dc_list The returned display configuration(s) list. The IAL
 183          *  should use a dc from the list when calling alter_displays(). The
 184          *  dc_list is zero terminated and live. It should not be altered by the
 185          *  IAL. See @ref dc_defines
 186          *
 187          * @param flags modifies the behavior of the function.
 188          *   See: @ref query_dc_flags
 189          *
 190          * @return 0: Success.
 191          * @return -IGD_INVAL:  Otherwise
 192          */
 193         int (*query_dc)(igd_driver_h driver_handle, unsigned long request,
 194                 unsigned long **dc_list, unsigned long flags);
 195
 196         /*!
 197          * Returns a live copy of the current mode list
 198          * for the requested display. This mode list will be for the master
 199          * port on the pipe and therefore may be the mode list for a TWIN
 200          * of the display requested.
 201          *
 202          * @param driver_handle The driver handle returned from igd_driver_init()
 203          *
 204          * @param dc The display configuration data to use when determining the
 205          *  available modes. See @ref dc_defines
 206          *
 207          * @param mode_list The returned mode list. This data should be freed by
 208          *   calling free_modes() unless the QUERY_LIVE_MODES flag was passed, in
 209          *   that case the live, in-use, data structure is returned. It should not
 210          *   be modified or freed.
 211          *
 212          * @param flags Flags to modify the operation of the function. Flags
 213          *   may contain any combination of the IGD_QUERY_* flags.
 214          *   See: @ref query_mode_list_flags
 215          *
 216          * @return 0: Success.
 217          * @return -IGD_ERROR_INVAL:  Otherwise
 218          */
 219         int (*query_mode_list)(igd_driver_h driver_handle, unsigned long dc,
 220                 igd_display_info_t **mode_list, unsigned long flags);
 221
 222         /*!
 223          * Free modes that were returned from a previous call to query mode list.
 224          *
 225          * @param mode_list The mode list to be free. This data was returned
 226          *   from an earlier call to query_modes.=
 227          */
 228         void (*free_mode_list)(igd_display_info_t *mode_list);
 229
 230         /*!
 231          * alter_displays() Modifies the modes associated with one or both display
 232          *  pipes according to the dc provided. The primary and secondary
 233          *  display handles are returned for use when rendering to these displays.
 234          *
 235          *  In extended or DIH modes only one fb_info needs to be provided at a
 236          *  time. In this manner two calls can be used one per framebuffer, as
 237          *  may be required by the OS.
 238          *
 239          *  @param driver_handle - required.  This is returned from a call to
 240          *   igd_init_driver().
 241          *
 242          *  @param primary A pointer to a display handle that will be populated
 243          *   during the call. This handle should be used for all rendering
 244          *   tasks directed to the primary framebuffer and pipe.
 245          *
 246          *  @param primary_pt_info The display timing information to be used for
 247          *    the primary display pipe.
 248          *
 249          *  @param primary_fb_info The framebuffer parameters to be used for the
 250          *   primary display. This data may be larger or smaller than the display
 251          *   timings to allow for centered/panned or scaled modes.
 252          *
 253          *  @param secondary A pointer to a display handle that will be populated
 254          *   during the call. This handle should be used for all rendering
 255          *   tasks directed to the secondary framebuffer or pipe.
 256          *
 257          *  @param secondary_pt_info The display timing information to be used for
 258          *   the secondary display pipe.
 259          *
 260          *  @param secondary_fb_info The framebuffer parameters to be used for the
 261          *   secondary display. This data may be larger or smaller than the display
 262          *   timings to allow for centered/panned or scaled modes.
 263          *
 264          *  @param dc A unique identifer to describe the configuration of the
 265          *   displays to be used. This identifier should be one returned from
 266          *   the _igd_dispatch::query_dc() call. See @ref dc_defines.
 267          *
 268          *  @param flags Bitfield to alter the behavior of the call.
 269          */
 270         int (*alter_displays)(igd_driver_h driver_handle,
 271                 igd_display_h *primary,
 272                 igd_display_info_t *primary_pt_info,
 273                 igd_framebuffer_info_t *primary_fb_info,
 274                 igd_display_h *secondary,
 275                 igd_display_info_t *secondary_pt_info,
 276                 igd_framebuffer_info_t *secondary_fb_info,
 277                 unsigned long dc,
 278                 unsigned long flags);
 279
 280         /*!
 281          * igd_configure_display() Modifies the modes associated with one display
 282          *  pipes according to the dc provided.
 283          *
 284          *  @param driver_handle - required.  This is returned from a call to
 285          *   igd_init_driver().
 286          *
 287          *  @param display A pointer to a display handle that will be used
 288          *   during the call. This handle should be used for all rendering
 289          *   tasks directed to the secondary framebuffer or pipe.
 290          *
 291          *  @param pt_info The display timing information to be used for
 292          *    the display pipe.
 293          *
 294          *  @param fb_info The framebuffer parameters to be used for the
 295          *   display. This data may be larger or smaller than the display
 296          *   timings to allow for centered/panned or scaled modes.
 297          *
 298          *  @param dc A unique identifer to describe the configuration of the
 299          *   displays to be used. This identifier should be one returned from
 300          *   the _igd_dispatch::query_dc() call. See @ref dc_defines.
 301          *
 302          *  @param fb_index What is the 0-based framebuffer index
 303          *
 304          *  @param flags Bitfield to alter the behavior of the call.
 305          */
 306         int (*igd_configure_display)(
 307             igd_driver_h driver_handle,
 308             igd_display_h *display,
 309             igd_display_info_t *pt_info,
 310             igd_framebuffer_info_t *fb_info,
 311             unsigned long dc,
 312             int fb_index,
 313                 unsigned long flags);
 314
 315         /*!
 316          *  pan_display() pans the display on the display device.
 317          *  It takes a @a x_offset, @a y_offset into the frame buffer and
 318          *  sets the display from (x_offset, y_offset) to
 319          *  (x_offset+width, y_offset+height).
 320          *  If x_offset+width, y_offset+height crosses frame buffer
 321          *  width and heigth, then it will return error.
 322          *
 323          * @param display_handle pointer to an IGD_DISPLAY pointer returned
 324          *    from a successful call to dispatch->alter_displays().
 325          *
 326          * @param x_offset these are frame buffer offsets from (0, 0).
 327          * @param y_offset these are frame buffer offsets from (0, 0).
 328          *
 329          * @return 0: The paning was successfull.
 330          * @return -IGD_INVAL:  Otherwise
 331          */
 332         long (*pan_display)(igd_display_h display_handle,
 333                 unsigned long x_offset,
 334                 unsigned long y_offset);
 335
 336         /*!
 337          * Alters the current power state for the display. This does not
 338          * change the power state for the graphics hardware device.
 339          *
 340          * @bug Needs to be modified to power all displays on a pipe
 341          *
 342          * @param driver_handle - handle to a driver handle returned from a
 343          *    previous call to igd_driver_init()
 344          *
 345          * @param port_number - specific display (port) to change.
 346          *
 347          * @param power_state - D state to change to.
 348          *
 349          * @returns 0 on Success
 350          * @returns <0 on Error
 351          */
 352         int (*power_display)(igd_driver_h driver_handle,
 353                         unsigned short port_number,
 354                         unsigned int power_state);
 355
 356         /*!
 357          *  This function sets one palette entry for the framebuffer when the
 358          *  pixel format for the framebuffer indicates a palette is used.
 359          *
 360          * @param display_handle Display handle returned from a call to
 361          *   _igd_dispatch::alter_displays()
 362          *
 363          * @param palette_color A 32bit ARGB color
 364          *
 365          * @param palette_entry The palette index to set.
 366          *
 367          * @returns
 368          *  - 0: Success
 369          *  - -IGD_INVAL:  Otherwise
 370          */
 371         int (*set_palette_entry)(igd_display_h display_handle,
 372                 unsigned long palette_entry,
 373                 unsigned long palette_color);
 374         /*!
 375          *  This function gets the requested palette entry from the hardware.
 376          *  The results are undefined when not in a paletted mode or in a
 377          *  mode that uses palette for color correction.
 378          *
 379          * @param display_handle Display handle returned from a call to
 380          *   _igd_dispatch::alter_displays()
 381          *
 382          * @param palette_color A 32bit ARGB color
 383          *
 384          * @param palette_entry The palette index to return.
 385          *
 386          * @returns 0 on Success
 387          * @returns -IGD_ERROR_INVAL Otherwise
 388          */
 389         int (*get_palette_entry)(igd_display_h display_handle,
 390                 unsigned long palete_entry,
 391                 unsigned long *palette_color);
 392
 393         /*!
 394          *  This function sets "count" palette entries starting with "count"
 395          *  offset into the palette_colors array.
 396          *
 397          * @param display_handle Display handle returned from a call to
 398          *   _igd_dispatch::alter_displays()
 399          *
 400          *  @param palette_colors A 32bit ARGB color array
 401          *
 402          *  @param start_index The first palette index to program.
 403          *
 404          *  @param count The number of palette entries to program.
 405          *
 406          * @returns 0 on Success
 407          * @return -IGD_ERROR_INVAL Otherwise
 408          */
 409         int (*set_palette_entries)(igd_display_h display_handle,
 410                 unsigned long *palette_colors, unsigned int start_index,
 411                 unsigned int count);
 412
 413
 414         /*!
 415          * Gets attributes for a display. SS will allocate the memory required to
 416          * return the *attr_list. This is a live copy of attributes used by both
 417          * IAL and HAL. Don't deallocate this memory. This will be freed by the
 418          * HAL.
 419          *
 420          * @param driver_handle Driver handle returned from a call to
 421          *   igd_driver_init()
 422          *
 423          * @param num_attrs pointer to return the number of attributes
 424          *    returned in attr_list.
 425          *
 426          * @param attr_list pointer to return the attributes.
 427          *
 428          * @returns 0 onSuccess
 429          * @returns -IGD_ERROR_NOATTR No attributes defined for this display
 430          * @returns -IGD_INVAL otherwise
 431          */
 432         int (*get_attrs)(igd_driver_h driver_handle,
 433                         unsigned short port_number,
 434                         unsigned long *num_attrs,
 435                         igd_attr_t **attr_list);
 436
 437         /*!
 438          * set attributes for a display.
 439          *
 440          * @param driver_handle Driver handle returned from a call to
 441          *   igd_driver_init()
 442          *
 443          * @param num_attrs pointer to return the number of attributes
 444          *   returned in attr_list. This is equal to the num_attrs returned by
 445          *   igd_get_attrs().
 446          *
 447          * @param attr_list pointer returned from igd_get_attrs(). Change
 448          *   the attributes to desired values.
 449          *
 450          * @returns 0 on Success
 451          * @returns -IGD_ERROR_NOATTR No attributes defined for this display
 452          * @returns -IGD_INVAL Otherwise
 453          */
 454         int (*set_attrs)(igd_driver_h driver_handle,
 455                         unsigned short port_number,
 456                         unsigned long num_attrs,
 457                         igd_attr_t *attr_list);
 458
 459         /*!
 460          * set flags for a display.
 461          *
 462          * @param display_handle Display handle returned from a call to
 463          *   _igd_dispatch::alter_displays()
 464          *
 465          * @param port_number of the port to modify.  (use zero to change
 466          *   all ports associated with a display?)
 467          *
 468          * @param flag to set in the port's pt_info before calling program
 469          *   port.
 470          *
 471          * @returns 0 on Success
 472          * @returns -IGD_INVAL Otherwise
 473          */
 474         int (*enable_port)(igd_display_h display_handle,
 475                         unsigned short port_number,
 476                         unsigned long flag,
 477                         unsigned long test);
 478
 479         /*!
 480          * This functions returns the current scanline for the display handle
 481          * provided. The scanline will be accurate when possible, or equal
 482          * to IGD_IN_VBLANK, or IGD_IN_VSYNC during the vblank/vsync periods.
 483          * See @ref get_scanline_defs
 484          *
 485          * @param display_handle Display handle returned from a call to
 486          *   _igd_dispatch::alter_displays()
 487          *
 488          * @param scanline An unsigned long pointer which will be populated by
 489          *    the HAL during the call.
 490          *
 491          * @returns 0 on Success
 492          * @returns <0 on Error
 493          */
 494         int (*get_scanline)(igd_display_h display_handle, int *scanline);
 495
 496         /*!
 497          *  This function alters the parameters associated with a cursor.
 498          *
 499          * @param display_handle Display handle returned from a call to
 500          *   _igd_dispatch::alter_displays()
 501          *
 502          * @param cursor_info An igd_cursor_info_t data structure with the
 503          *   parameters to be applied to the cursor.
 504          *
 505          * @param image A pointer to cursor image data. The image data
 506          *   will only be programmed with the cursor flag has either
 507          *   IGD_CURSOR_LOAD_ARGB_IMAGE or IGD_CURSOR_LOAD_XOR_IMAGE.
 508          *
 509          * @param 0 on Success
 510          * @param <0 on Error
 511          */
 512         int (*alter_cursor)(igd_display_h display_handle,
 513                 igd_cursor_info_t *cursor_info, unsigned char *image);
 514
 515         /*!
 516          *  This function alters the position parameters associated with a cursor.
 517          *
 518          * @param display_handle Display handle returned from a call to
 519          *   _igd_dispatch::alter_displays()
 520          *
 521          * @param cursor_info An igd_cursor_info_t data structure with the
 522          *   parameters to be applied to the cursor. Only the x_offset and y_offset
 523          *   parameters will be used.
 524          *
 525          * @param 0 on Success
 526          * @param <0 on Error
 527          */
 528         int (*alter_cursor_pos)(igd_display_h display_handle,
 529                 igd_cursor_info_t *cursor_info);
 530
 531         /*!
 532          * This function will block until the start of the next vblank/vsync
 533          * period.
 534          *
 535          * @param display_handle Display handle returned from a call to
 536          *   _igd_dispatch::alter_displays()
 537          *
 538          * @returns 0 on Success
 539          * @returns <0 on Error
 540          */
 541         int (*wait_vblank)(igd_display_h display_handle);
 542
 543         /*!
 544          * This function will block until the start of the next vblank/vsync
 545          * period.
 546          *
 547          * @param display_handle Display handle returned from a call to
 548          *   _igd_dispatch::alter_displays()
 549          *
 550          * @returns 0 on Success
 551          * @returns <0 on Error
 552          */
 553         int (*wait_vsync)(igd_display_h display_handle);
 554
 555         int (*query_in_vblank)(igd_display_h display_handle);
 556
 557         /*!
 558          * This function is to access I2C register values for the specified I2C
 559          * bus. Memory for 'igd_i2c_reg_t->buffer' should be allocated and freed
 560          * by caller.
 561          * This function is valid only for display connected via DIGITAL (DVO)
 562          * ports.
 563          *
 564          * @bug Documentation needs update or Remove
 565          *
 566          *  @param driver IGD driver handle.
 567          *
 568          *  @param i2c_reg pointer to the i2c register structure.
 569          *
 570          *  @param flags If the flags is
 571          *    IGD_I2C_WRITE - then igd_i2c_reg_t->buffer should point
 572          *       to array of 'num_bytes' number of valid I2C registers values.
 573          *    IGD_I2C_READ  - then igd_i2c_reg_t->buffer pointer should have space
 574          *       for 'num_bytes' number of valid I2C registers.
 575          *
 576          * @returns 0 on Success
 577          * @returns <0 on Error
 578          */
 579         int (*access_i2c)(igd_display_h display, igd_i2c_reg_t *i2c_reg,
 580                         unsigned long flags);
 581
 582         /*!
 583          * This function is to get the EDID information (not the actual block) for
 584          * the display device associated with the 'display_handle'.
 585          *
 586          * @param driver_handle The driver handle returned from igd_driver_init().
 587          * @param port_number display port number connected to display.
 588          * @param edid_version EDID version number.
 589          * @param edid_revision EDID revision number.
 590          * @param edid_size Tells the caller what size of buffer to allocate
 591          *   for the transfer.
 592          *
 593          * @returns 0 on Success
 594          * @returns -IGD_ERROR_EDID Error while reading EDID or no EDID
 595          * @return -IGD_INVAL Other error
 596          */
 597         int (*get_EDID_info)(igd_driver_h driver_handle,
 598                         unsigned short port_number,
 599                         unsigned char *edid_version,
 600                         unsigned char *edid_revision,
 601                         unsigned long *edid_size);
 602
 603         /*!
 604          * This function is to get the EDID block of the specified size. The size
 605          * is returned from previous call to igd_get_EDID_info().
 606          *
 607          * @note The return value indicates success/failure, blocksize should be
 608          *  set by the API to the actual number of bytes transferred upon return.
 609          * @param driver_handle The driver handle returned from igd_driver_init().
 610          * @param port_number Specific display to query for EDID block data.
 611          * @param edid_ptr Buffer to hold the EDID block data, must be 128bytes.
 612          * @param block_number Tells the API which EDID block to read.
 613          *
 614          *  @returns 0 on Success
 615          *  @returns -IGD_ERROR_EDID Error while reading EDID or no EDID
 616          *  @returns -IGD_INVAL Other error
 617          */
 618         int (*get_EDID_block)(igd_driver_h driver_handle,
 619                 unsigned short port_number,
 620                 unsigned char FAR *edid_ptr,
 621                 unsigned char block_number);
 622
 623         /*!
 624          * This function returns the information about the port/display
 625          *
 626          * @param driver_handle pointer to an IGD_DRIVER_H pointer returned
 627          *    from a successful call to igd_driver_init().
 628          *
 629          * @param port_number Specific port to get information for.
 630          *
 631          * @param port_info Port/display information
 632          *
 633          * @returns 0 on Success
 634          * @returns -IGD_INVAL Otherwise
 635          */
 636         int (*get_port_info)(igd_driver_h driver_handle,
 637                         unsigned short port_number,
 638                         igd_port_info_t *port_info);
 639
 640         /*
 641          * Sync is used to insert and check the status of synchronization
 642          * points in the command queue. A sync inserted into the queue and
 643          * then check insures that all rendering commands inserted before the
 644          * sync are now complete.
 645          *
 646          * Sync should be called with the IGD_RENDER_NONBLOCK flag to insert
 647          * a new sync without waiting for completion. When called with
 648          * IGD_RENDER_BLOCK the call will wait for completion but may return
 649          * due to a timeout. The caller should determine if calling again is
 650          * prudent or if some other action should be taken insead of busy
 651          * waiting.
 652          *
 653          * @param display_handle pointer to an IGD_DISPLAY pointer returned
 654          *    from a successful call to dispatch->alter_displays().
 655          *
 656          * @param priority The command queue to use. IGD_PRIORITY_NORMAL is
 657          *    correct for most circumstances.
 658          *
 659          * @param sync The sync identifier that will be populated and returned
 660          *    during the call. To insert a new sync, this should be passed
 661          *    containing 0 (A pointer to a zero). To check the status of an
 662          *    existing sync pass the value returned from a previous call to
 663          *    this function.
 664          *
 665          * @param flags Sync flags.
 666          *
 667          * @returns
 668          *   0: On Success
 669          *   -IGD_ERROR_BUSY: When the sync is not yet complete
 670          */
 671         int (*sync)(igd_display_h display_handle, int priority,
 672                 unsigned long *sync, unsigned long flags);
 673         /*
 674          * Idle stalls until the entire engine has been idled.
 675          */
 676         int (*idle)(igd_driver_h driver_handle);
 677
 678         /* igd_appcontext.h */
 679         igd_appcontext_h (*appcontext_alloc)(igd_display_h display_handle,
 680                 int priority, unsigned int flags);
 681         void (*appcontext_free)(igd_display_h display_handle,
 682                 int priority, igd_appcontext_h context_handle);
 683
 684         /* igd_pwr.h */
 685         int (*pwr_alter)(igd_driver_h driver_handle, unsigned int power_state);
 686         int (*pwr_query)(igd_driver_h driver_handle, unsigned int power_state);
 687
 688         /* igd_reset.h */
 689         int (*reset_alter)(igd_driver_h driver_handle);
 690
 691         /* igd_gmm.h */
 692
 693         /*!
 694          * This function is used by igd client drivers to allocate surfaces from
 695          * graphics memory. A driver must use this function to allocate all
 696          * surfaces, and must in turn free the surfaces with dispatch->gmm_free()
 697          * before exit. Calls to this function are only valid after the gmm_init()
 698          * function has been called by the igd init module.
 699          *
 700          * @param offset The offset into the Gtt memory space that the surface
 701          *   begins. This is an output only. Each element of this array can be
 702          *   added to the base physical or virtual address to obtain a full
 703          *   virtual or physical address. Therefore this parameter should be
 704          *   accessed as offset[x]. The number of offset elements is dependent on
 705          *   the surface type. Normal and Buffer surfaces return 1 element, Mip Map
 706          *   surfaces return NumMips level elements. Cube Map surfaces return
 707          *   NumMips level elements. Volume Map surfaces return NumSlices elements.
 708          *   For Volume Maps: The number of planes decreases by half for each
 709          *   mip level just as the number of X and Y pixels decreases by half.
 710          *   All plane offsets for the first mip are returned first followed
 711          *   by all planes for the second mip and so-forth.
 712          *
 713          * @param pixel_format The pixel format id. See @ref pixel_formats
 714          *
 715          * @param width The width in pixels of the surface. This may be modified
 716          *   to be larger than the requested value.
 717          *
 718          * @param height Height in pixels of the surface. This may be modified to
 719          *   be larger than the requested value.
 720          *
 721          * @param pitch The pitch in bytes of the surface. This value is returned
 722          *   by the driver.
 723          *
 724          * @param size The size of the surface in bytes. This value is returned by
 725          *   the driver. In Planar formats this will be greater than height*pitch
 726          *
 727          * @param type The defined type of the surface to be allocated.
 728          *   See @ref alloc_surface_types
 729          *
 730          * @param flags A bitfied of potential uses for the surface. These
 731          *   potentially impact the requried alignment of the surface offset.
 732          *   See @ref surface_info_flags
 733          *
 734          * @returns 0 on Success
 735          * @returns <0 Error
 736          */
 737         int (*gmm_alloc_surface)(unsigned long *offset,
 738                 unsigned long pixel_format,
 739                 unsigned int *width,
 740                 unsigned int *height,
 741                 unsigned int *pitch,
 742                 unsigned long *size,
 743                 unsigned int type,
 744                 unsigned long *flags);
 745
 746
 747         int (*gmm_map_ci)(unsigned long *gtt_offset,
 748                         unsigned long ci_param, /*virtaddr or v4l2_offset*/
 749                         unsigned long *virt_addr,
 750                         unsigned int map_method,
 751                         unsigned long size);
 752
 753
 754         int (*gmm_unmap_ci)(unsigned long virt_addr);
 755
 756
 757         /*!
 758          * This function maps an existing list of pages into the GTT.
 759          *
 760          * @param pagelist The live list of pages to be mapped.  The GMM
 761          *   should not modify or release this list.
 762          * @param gtt_offset The offset into the Gtt memory space at which the
 763          *   pages begin.  This is an output only.
 764          *
 765          * @param numpages The number of pages to map (i.e., length of pagelist).
 766          *
 767          * @returns 0 on Success
 768          * @returns <0 Error
 769          */
 770         int (*gmm_import_pages)(void **pagelist,
 771                         unsigned long *gtt_offset,
 772                         unsigned long numpages);
 773
 774         int (*gmm_get_num_surface)(unsigned long *count);
 775         int (*gmm_get_surface_list)(unsigned long allocated_size,
 776                 unsigned long *list_size,
 777                 igd_surface_list_t **surface_list);
 778
 779         /*!
 780          * This function is used by igd client drivers to allocate regions from
 781          * graphics memory. Regions are portions of video memory that do not have
 782          * width and height parameters, only a linear size. A driver must use this
 783          * function to allocate all regions, and must in turn free the regions with
 784          * igd_mm_free() before exit.
 785          * Calls to this function are only valid after the gmm_init() function
 786          * has been called by the igd init module.
 787          *
 788          * @param offset The offset into the Gtt memory space that the region
 789          *   begins. This is an output only. This value can be added to the base
 790          *   physical or virtual address to obtain a full virtual or physical
 791          *   address.
 792          *
 793          * @param size The size of the region, this value may be modified to be
 794          *   larger or smaller than the requested value.
 795          *
 796          * @param type The defined type of the surface to be allocated.
 797          *   See @ref alloc_region_types
 798          *
 799          * @param flags A bitfied of potential uses for the region. These
 800          *   potentially impact the requried alignment of the region offset.
 801          *   See @ref alloc_region_flags
 802          *
 803          * @returns 0 on Success
 804          * @returns <0 on Error
 805          */
 806         int (*gmm_alloc_region)(unsigned long *offset,
 807                 unsigned long *size,
 808                 unsigned int type,
 809                 unsigned long flags);
 810
 811         /*!
 812          * This function is used to find the actual physical address of the
 813          * system memory page given an offset into Gtt memory. This function
 814          * will only be successful if the offset provided was allocated to a
 815          * cursor or overlay register type.
 816          *
 817          * @param offset The offset as provided by the allocation function.
 818          *
 819          * @returns 0 on Success
 820          * @returns  <0 on Error
 821          */
 822         int (*gmm_virt_to_phys)(unsigned long offset,
 823                 unsigned long *physical);
 824
 825         /*!
 826          *  This function should be used to free any regions or surfaces allocated
 827          *  during igd use. Calling with offsets that were not obtained via a
 828          *  prior call to _igd_dispatch::gmm_alloc_surface() or
 829          *  _igd_dispatch::gmm_alloc_region() are invalid and will produce
 830          *  undefined results.
 831          *  Calls to this function are only valid after the igd_module_init()
 832          *  function has been called.
 833          *
 834          * @param offset The offset as provided by the allocation function.
 835          *
 836          * @returns void
 837          */
 838         void (*gmm_free)(unsigned long offset);
 839
 840         /*!
 841          *  This function should be used to release externally-allocated
 842          *  page lists that have been imported into the GMM.  This will
 843          *  simply unmap the pages from the GTT; the pages themselves
 844          *  should subsequently be freed by the external source.
 845          *  Calling with offsets that were not obtained via a
 846          *  prior call to _igd_dispatch::gmm_import_pages() or
 847          *  are invalid and will produce undefined results.
 848          *  Calls to this function are only valid after the igd_module_init()
 849          *  function has been called.
 850          *
 851          * @param offset The offset as provided by the allocation function.
 852          *
 853          * @returns void
 854          */
 855         void (*gmm_release_import)(unsigned long offset);
 856
 857         /*!
 858          * This function returns current memory statistics.
 859          *
 860          * @param memstat An _igd_memstat structure to be populated during the call
 861          *
 862          * @returns 0 on Success
 863          * @returns  <0 on Error
 864          */
 865         int (*gmm_memstat)(igd_memstat_t *memstat);
 866
 867         /*!
 868          * Allocates a surface similar to _igd_dispatch::gmm_alloc_surface();
 869          * however, in this case the surface is allocated from a cached pool of
 870          * similar surfaces to improve performance. The surface cache shrinks and
 871          * grows automatically based on usage model. The surface cache should
 872          * be used when many surfaces of similar format and size are allocated
 873          * and freed repeatedly and the highest performance is required. The
 874          * tradeoff is that memory will be consumed by the cache and which
 875          * can lead to the need to flush the cache when non-cached surfaces
 876          * fail due to out-of-memory conditions.
 877          *
 878          * Surface is passed in, and populated during call.
 879          * All inputs are the same as with gmm_alloc_surface.
 880          *
 881          * @param display_handle Display used with this surface
 882          * @param surface Input/Output structure containing surface information
 883          * @param flags used to modify the behavior of the function.
 884          *     See @ref gmm_alloc_cached_flags
 885          *
 886          * @returns 0 on Success
 887          * @returns  <0 on Error
 888          */
 889         int (*gmm_alloc_cached)(igd_display_h display_handle,
 890                 igd_surface_t *surface, unsigned int flags);
 891
 892         /*!
 893          * Free a surface previously allocated with the
 894          * _igd_dispatch::gmm_alloc_cached() dispatch function. When freeing
 895          * a cached surface it is not necessary for rendering to be complete. In
 896          * this manner better performance can be achieved because it is likely
 897          * that the rendering will be complete before the surface could be reused.
 898          * When freeing a cached surface a sync ID obtained from
 899          * _igd_dispatch::sync() after all rendering commands to the surface
 900          * should be provided such that the cache manager can be sure rendering
 901          * is complete before the surface is reused or freed.
 902          *
 903          * @param display_handle Display used with this surface
 904          * @param surface structure containing surface information
 905          * @param sync_id obtained after all rendering to/from this surface
 906          */
 907         void (*gmm_free_cached)(igd_display_h display_handle,
 908                 igd_surface_t *surface,
 909                 unsigned long sync_id);
 910
 911         /*!
 912          * Allocates a region similar to _igd_dispatch::gmm_alloc_region();
 913          * however, in this case the region is allocated from a cached pool of
 914          * similar regions to improve performance. The region cache shrinks and
 915          * grows automatically based on usage model. The region cache should
 916          * be used when many regions of similar format and size are allocated
 917          * and freed repeatedly and the highest performance is required. The
 918          * tradeoff is that memory will be consumed by the cache and which
 919          * can lead to the need to flush the cache when non-cached regions
 920          * fail due to out-of-memory conditions.
 921          *
 922          * Region information is passed in, and populated during call.
 923          * All inputs are the same as with gmm_alloc_region.
 924          *
 925          * @param display_handle Display used with this region
 926          *
 927          * @param offset The offset into the Gtt memory space that the region
 928          *   begins. This is an output only. This value can be added to the base
 929          *   physical or virtual address to obtain a full virtual or physical
 930          *   address.
 931          *
 932          * @param size The size of the region, this value may be modified to be
 933          *   larger or smaller than the requested value.
 934          *
 935          * @param type The defined type of the region to be allocated.
 936          *   See @ref alloc_region_types
 937          *
 938          * @param region_flags A bitfied of potential uses for the region. These
 939          *   potentially impact the requried alignment of the region offset.
 940          *   See @ref alloc_region_flags
 941          *
 942          * @param flags used to modify the behavior of the function.
 943          *     See @ref gmm_alloc_cached_flags
 944          *
 945          * @returns 0 on Success
 946          * @returns  <0 on Error
 947          */
 948         int (*gmm_alloc_cached_region)(igd_display_h display_handle,
 949                 unsigned long *offset,
 950                 unsigned long *size,
 951                 unsigned int type,
 952                 unsigned int region_flags,
 953                 unsigned int flags);
 954
 955         /*!
 956          * Free a region previously allocated with the
 957          * _igd_dispatch::gmm_alloc_cached_region() dispatch function. When freeing
 958          * a cached region it is not necessary for rendering to be complete. In
 959          * this manner better performance can be achieved because it is likely
 960          * that the rendering will be complete before the region could be reused.
 961          * When freeing a cached region a sync ID obtained from
 962          * _igd_dispatch::sync() after all rendering commands to the region
 963          * should be provided such that the cache manager can be sure rendering
 964          * is complete before the region is reused or freed.
 965          *
 966          * @param display_handle Display used with this region
 967          *
 968          * @param offset The offset into the Gtt memory space that the region
 969          *   begins. This is an output only. This value can be added to the base
 970          *   physical or virtual address to obtain a full virtual or physical
 971          *   address.
 972          *
 973          * @param size The size of the region, this value may be modified to be
 974          *   larger or smaller than the requested value.
 975          *
 976          * @param type The defined type of the region to be allocated.
 977          *   See @ref alloc_region_types
 978          *
 979          * @param region_flags A bitfied of potential uses for the region. These
 980          *   potentially impact the requried alignment of the region offset.
 981          *   See @ref alloc_region_flags
 982          *
 983          * @param sync_id_write obtained after all rendering to this region
 984          * @param sync_id_read obtained after all rendering from this region
 985          */
 986         void (*gmm_free_cached_region)(igd_display_h display_handle,
 987                 unsigned long offset,
 988                 unsigned long size,
 989                 unsigned int type,
 990                 unsigned int region_flags,
 991                 unsigned long sync_id_write,
 992                 unsigned long sync_id_read);
 993
 994         /*!
 995          *  Flushes surfaces out of the internal surface cache. During normal
 996          * operation an IAL will not need to call this. Only when an IAL is
 997          * making use of the surface cache for some operations and direct
 998          * gmm operations for others would it be necessary to flush the cache.
 999          *
1000          *
1001          * @returns 0 No surfaces flushed
1002          * @returns >0 Surfaces flushed
1003          * @returns <0 Error
1004          */
1005         int (*gmm_flush_cache)(void);
1006
1007         /*!
1008          * Allocates a heap of the requested size.  The heap allocated is managed
1009          * by the GMM through "gmm_alloc_heapblock", "gmm_free_heapblock", and
1010          * "gmm_free_heap" functions.
1011          *
1012          * @param display_handle Used to access other GMM dispatch functions
1013          *
1014          * @param heap_offset The offset into the Gtt memory space that the heap
1015          *   begins.  This also serves as a "heap ID"
1016          *
1017          * @param heap_size The size of the heap.
1018          *
1019          * @param type Set to zero
1020          *
1021          * @param alignment The alignment of the blocks in this heap
1022          *
1023          * @returns 0 on Success
1024          * @returns  <0 on Error
1025          */
1026         int (*gmm_alloc_heap)(igd_display_h display_handle,
1027                 unsigned long *heap_offset,
1028                 unsigned long *heap_size,
1029                 unsigned int   type,
1030                 unsigned long  alignment);
1031
1032         /*!
1033          * Frees the heap allocated by gmm_alloc_heap
1034          *
1035          * @param heap_offset The offset into the Gtt memory space that the heap
1036          *   begins
1037          */
1038         void (*gmm_free_heap)(igd_display_h display_handle,
1039                                 unsigned long heap_offset);
1040
1041         unsigned long (*gmm_get_pvtheap_size)(void);
1042         unsigned long (*gmm_get_cache_mem)(void);
1043         /*!
1044          * Allocates a block of the requested size from the heap indicated by
1045          * heap_offset.
1046          *
1047          * @param display_handle Used to access other GMM dispatch functions
1048          *
1049          * @param heap_offset The heap ID
1050          *
1051          * @param block_offset
1052          *
1053          * @param size The size of the block.
1054          *
1055          * @param type Set to zero
1056          *
1057          * @param flags Set to zero
1058          *
1059          * @returns 0 on Success
1060          * @returns  <0 on Error
1061          */
1062         int (*gmm_alloc_heap_block)(igd_display_h display_handle,
1063                 unsigned long heap_offset,
1064                 unsigned long *block_offset,
1065                 unsigned long *size,
1066                 unsigned long flags);
1067
1068         /*!
1069          * Frees a block of previously allocated by gmm_alloc_heap_block
1070          *
1071          * @param display_handle Used to access other GMM dispatch functions
1072          *
1073          * @param block_offset Offset given by gmm_alloc_heap_block
1074          */
1075         void (*gmm_free_heap_block)(igd_display_h display_handle,
1076                 unsigned long heap_offset,
1077                 unsigned long block_offset,
1078                 unsigned long sync_id_write,
1079                 unsigned long sync_id_read);
1080
1081         /*!
1082          * Gets the heap id/offset from which the block
1083          *
1084          * @param block_offset Offset given by gmm_alloc_heap_block
1085          * @param heap_offset Head ID/Offset associated with the block offset
1086          *
1087          * @returns 0 on Success
1088          * @returns  <0 on Error
1089          */
1090         int (*gmm_get_heap_from_block)(unsigned long block_offset,
1091                 unsigned long *heap_offset);
1092
1093         /*!
1094          * Allocates a reservation of the requested size. A reservation is a
1095          * memory range that is dedicated for the callers use but it not
1096          * populated with usable memory. The caller must make a single call to
1097          * gmm_alloc_surface() or gmm_alloc_region() passing in the reservation
1098          * address to allocate a surface within the reservation. Only a single
1099          * surface or region may be placed in a reservation.
1100          *
1101          * @param offset The offset into the Gtt memory space that the reservation
1102          *   begins. This is an output only. This value can be added to the base
1103          *   physical or virtual address to obtain a full virtual or physical
1104          *   address.
1105          *
1106          * @param size The size of the reservation.
1107          *
1108          * @param flags A bitfied of potential uses for the reservation. These
1109          *   potentially impact the requried alignment of the reservation.
1110          *   See @ref alloc_reservation_flags
1111          */
1112         int (*gmm_alloc_reservation)(unsigned long *offset,
1113                 unsigned long size,
1114                 unsigned long flags);
1115
1116         /*!
1117          * Allocates a region similar to _igd_dispatch::gmm_alloc_region();
1118          * however, in this case the region is allocated from a pool of
1119          * persisent regions.  The pool can only grow as additional regions
1120          * are allocated. The pool can be flushed but this should only be
1121          * done when GMM is being shutdown.
1122          *
1123          * Region information is passed in, and populated during call.
1124          * All inputs are the same as with gmm_alloc_region.
1125          *
1126          * @param display_handle Display used with this region
1127          *
1128          * @param offset The offset into the Gtt memory space that the region
1129          *   begins. This is an output only. This value can be added to the base
1130          *   physical or virtual address to obtain a full virtual or physical
1131          *   address.
1132          *
1133          * @param size The size of the region, this value may be modified to be
1134          *   larger or smaller than the requested value.
1135          *
1136          * @param type The defined type of the region to be allocated.
1137          *   See @ref alloc_region_types
1138          *
1139          * @param region_flags A bitfied of potential uses for the region. These
1140          *   potentially impact the requried alignment of the region offset.
1141          *   See @ref alloc_region_flags
1142          *
1143          * @param flags used to modify the behavior of the function.
1144          *     See @ref gmm_alloc_cached_flags
1145          *
1146          * @returns 0 on Success
1147          * @returns  <0 on Error
1148          */
1149         int (*gmm_alloc_persistent_region)(igd_display_h display_handle,
1150                 unsigned long *offset,
1151                 unsigned long *size,
1152                 unsigned int type,
1153                 unsigned int region_flags,
1154                 unsigned int flags);
1155
1156         /*!
1157          * Free a region previously allocated with the
1158          * _igd_dispatch::gmm_alloc_persistent_region() dispatch function.
1159          * The region is marked as available and may be reused by the next
1160          * allocation request.  It is the callers responsibilty to make sure
1161          * rendering to the region is complete before freeing it.
1162          *
1163          * @param display_handle Display used with this region
1164          *
1165          * @param offset The offset into the Gtt memory space that the region
1166          *   begins. This is an input only.
1167          */
1168         int (*gmm_free_persistent_region)(unsigned long offset);
1169
1170         /*!
1171          * Flushes regions out of the internal persistent list. During normal
1172          * operation an IAL will not need to call this. Only when an IAL is
1173          * exiting should it flush the list.
1174          *
1175          *
1176          * @returns 0 regions flushed
1177          * @returns <0 Error
1178          */
1179         int (*gmm_flush_persistent_regions)(igd_display_h display_handle);
1180
1181         /*!
1182          * Creates a linear mapping of a video memory region into the
1183          * current process address space.
1184          *
1185          * @param offset Offset used to identifiy the memory region
1186          *
1187          * @returns address to mapping
1188          * @returns NULL Error
1189          */
1190         void *(*gmm_map)(unsigned long offset);
1191
1192         /*!
1193          * Unmaps a linear mapping created by gmm_map.
1194          *
1195          * @param address pointer to the mapping
1196          */
1197         void (*gmm_unmap)(void *address);
1198
1199         /*!
1200          * Export the list of physical pages allocated to a memory
1201          * retion.
1202          *
1203          * @param offset Offset used to identify the memory region
1204          * @param pages  Array of page structures holding the physical page
1205          *               addresses.
1206          * @param page_cnt Number of pages in the page array.
1207          *
1208          * @returns 0 if successful
1209          *          -IGD_ERROR_NOMEM if offset is invalid.
1210          */
1211         int (*gmm_get_page_list)(unsigned long offset,
1212                         unsigned long **pages,
1213                         unsigned long *page_cnt);
1214
1215         void (*gmm_dump)(void);
1216         void (*gmm_dump_v)(void);
1217         char *gmm_debug_desc;
1218
1219         /* igd_2d.h */
1220         int (*setup_clip_blt)(igd_display_h display_h, int priority,
1221                 igd_surface_t *dest, igd_rect_t *dest_rect,
1222                 igd_appcontext_h appcontext_handle, unsigned int flags);
1223         int (*setup_blt)(igd_display_h display_handle, int priority,
1224                 igd_surface_t *dest_surf, igd_rect_t *dest_rect,
1225                 unsigned long raster_ops, unsigned long bg_color,
1226                 unsigned long fg_color, igd_appcontext_h appcontext_handle,
1227                 unsigned int flags);
1228         int (*color_blt)(igd_display_h display_h, int priority,
1229                 igd_surface_t *dest, igd_rect_t *dest_rect, unsigned int byte_mask,
1230                 unsigned int color, unsigned int raster_ops,
1231                 igd_appcontext_h appcontext, unsigned int flags);
1232         int (*rgb_color_blt)(igd_display_h display_h, int priority,
1233                 igd_surface_t *dest, igd_rect_t *dest_rect, unsigned int byte_mask,
1234                 unsigned int color, unsigned int raster_ops,
1235                 igd_appcontext_h appcontext, unsigned int flags);
1236         int (*pat_blt)(igd_display_h display_h, int priority,
1237                 igd_surface_t *dest, igd_rect_t *dest_rect, unsigned int byte_mask,
1238                 igd_pat_t *pat, igd_chroma_t *chroma, unsigned int raster_ops,
1239                 igd_appcontext_h appcontext, unsigned int flags);
1240         int (*mono_pat_blt)(igd_display_h display_h, int priority,
1241                 igd_surface_t *dest, igd_rect_t *dest_rect, unsigned int byte_mask,
1242                 igd_mono_pat_t *pat, unsigned int raster_ops,
1243                 igd_appcontext_h appcontext, unsigned int flags);
1244         int (*src_copy_blt)(igd_display_h display_h, int priority,
1245                 igd_surface_t *dest, igd_rect_t *dest_rect, igd_surface_t *src,
1246                 igd_coord_t *src_coord, unsigned int byte_mask, igd_chroma_t *chroma,
1247                 unsigned int raster_ops, igd_appcontext_h appcontext,
1248                 unsigned int flags);
1249         int (*mono_src_copy_blt)(igd_display_h display_h, int priority,
1250                 igd_surface_t *dest, igd_rect_t *dest_rect, igd_mono_src_t *src,
1251                 unsigned int byte_mask, unsigned int raster_ops,
1252                 igd_appcontext_h appcontext, unsigned int flags);
1253         int (*mono_src_copy_immed_blt)(igd_display_h display_h, int priority,
1254                 igd_surface_t *dest, igd_rect_t *dest_rect, igd_mono_src_t *src,
1255                 igd_surface_t *src_surface,     igd_rect_t *src_rect,
1256                 unsigned int byte_mask, unsigned int raster_ops,
1257                 igd_appcontext_h appcontext, unsigned int flags);
1258         int (*full_blt)(igd_display_h display_h, int priority,
1259                 igd_surface_t *dest, igd_rect_t *dest_rect, igd_surface_t *src,
1260                 igd_coord_t *src_coord, unsigned int byte_mask, igd_pat_t *pat,
1261                 unsigned int raster_ops, igd_appcontext_h appcontext,
1262                 unsigned int flags);
1263         int (*full_mono_src_blt)(igd_display_h display_h, int priority,
1264                 igd_surface_t *dest, igd_rect_t *dest_rect, igd_mono_src_t *src,
1265                 unsigned int byte_mask, igd_pat_t *pat, unsigned int raster_ops,
1266                 igd_appcontext_h appcontext, unsigned int flags);
1267         int (*full_mono_pat_blt)(igd_display_h display_h, int priority,
1268                 igd_surface_t *dest, igd_rect_t *dest_rect, igd_coord_t *src_coord,
1269                 igd_surface_t *src,     unsigned int byte_mask, igd_mono_pat_t *pat,
1270                 unsigned int raster_ops, igd_appcontext_h appcontext,
1271                 unsigned int flags);
1272         int (*full_mono_pat_mono_src_blt)(igd_display_h display_h,
1273                 int priority, igd_surface_t *dest, igd_rect_t *dest_rect,
1274                 igd_mono_src_t *src, unsigned int byte_mask, igd_mono_pat_t *pat,
1275                 unsigned int raster_ops, igd_appcontext_h appcontext,
1276                 unsigned int flags);
1277         int (*text_immed_blt)(igd_display_h display_h,
1278                 int priority, igd_surface_t *dest_surf,
1279                 igd_rect_t *dest_rect,
1280                 unsigned char *glyph_data, unsigned int num_glyph_bytes,
1281                 igd_appcontext_h appcontext_handle, unsigned long raster_ops,
1282                 unsigned long bg_color, unsigned long fg_color,
1283                 unsigned int flags);
1284
1285         /* igd_blend.h */
1286         /*!
1287          * Blend and stretch and color convert a stack of input surfaces into a
1288          * destination surface.
1289          *
1290          * Blend takes N input surfaces and N corresponding input rectangles
1291          * and output rectangles. This allows for any subset of an input surface
1292          * to be output to any rectangle on the destination surface. The input
1293          * and output rectangles need not have any correlation between inputs.
1294          * Also, the input and output rectangle for any given surface need not
1295          * be the same size or aspect ratio, full up and down scaling is possible.
1296          * The destination surface is provided with a clip rectangle. All
1297          * rendering will be clipped to this rectangle regardless of the
1298          * provided destination rectangles.
1299          * Each input surface has a set of render_ops that will be respected
1300          * during the blend operation.
1301          * The IGD_RENDER_OP_BLEND render operation will allow the surface to
1302          * blend with the surfaces below it in the stack. The bottom surface
1303          * in the stack will then optionally blend with the existing contents
1304          * of the destination surface.
1305          *
1306          * All input surface must be allocated with the IGD_SURFACE_TEXTURE
1307          * flag and all output surfaces must be allocated with the
1308          * IGD_SURFACE_RENDER flag.
1309          *
1310          * When a stretch blit is performed (No blending) the surface should not
1311          * have the IGD_RENDER_OP_BLEND bit set in the render_ops to insure
1312          * that the fastest possible method is used and that no format
1313          * conversion takes place.
1314          *
1315          * Due to the number of possible permutations of this API it is
1316          * necessary to constrain the parameters that can be expected to work.
1317          * Specific hardware implementations may support more, however there is
1318          * no guarentee of functionality beyond those listed here.
1319          *
1320          * Blend will accept 1 or 2 input surfaces.
1321          * Blend will accept a maximum of 1 input surface with a palette.
1322          * Blend will accept a maximum of 1 input surface in planar format.
1323          * All Surfaces can output to ARGB format.
1324          * Only YUV inputs may output to YUV format.
1325          * xRGB formats will output ARGB with Alpha of 1.0 when
1326          *  IGD_RENDER_OP_BLEND is set on the surface. Otherwise the x will
1327          *  be retained from the original source.
1328          * Surfaces that are not pre-multipled cannot have a global alpha.
1329          *
1330          */
1331         int (*blend)(igd_display_h display, int priority,
1332                 igd_appcontext_h appcontext,
1333                 igd_surface_t *src_surface, igd_rect_t *src_rect,
1334                 igd_surface_t *mask_surface, igd_rect_t *mask_rect,
1335                 igd_rect_t *dest_rect, igd_surface_t *dest_surface,
1336                 igd_rect_t *clip_rect, unsigned long flags);
1337
1338         /* igd_ovl.h */
1339         /*!
1340          * Alter the overlay associated with the given display_h.
1341          *  Only 1 video surface can be associated with a given display_h
1342          *  (i.e. you can not have 2 video surfaces using the same display).
1343          *  This function should be called once for each unique framebuffer.
1344          *  Therefore, single, twin, clone, and vertical extended  modes
1345          *  should call this function once, and the HAL will properly display
1346          *  video using the primary overlay and second overlay if necessary.
1347          *  Whereas extended should call this function twice (once for each
1348          *  display_h) if the video spans multiple displays.
1349          *  In DIH, this function can be called once for each display, since a
1350          *  video surface can not span displays in DIH.
1351          *
1352          * The primary display in clone, the primary display in vertical extended,
1353          *  and the primary display in extended will always use the primary
1354          *  overlay.  The secondary display in clone, the secondary display in
1355          *  vertical extended, and the secondary display in extended will always
1356          *  use the secondary overlay.  The hardware overlay resources (excluding
1357          *  any video memory) will be allocated internal to the HAL during the
1358          *  _igd_dispatch::alter_displays() call.  Video memory surfaces required
1359          *  internal to the HAL, for stretching or pixel format conversions, will
1360          *  be dynamically allocated and freed as necessary.
1361          *
1362          * @param display_h Input display used with this overlay
1363          * @param appcontext_h Input appcontext which may be used for blend.
1364          *     This can be the same appcontext which is used for blend and
1365          *     2d (DD and XAA/EXA).
1366          * @param src_surf Input src surface information
1367          * @param src_rect Input src surface rectangle.
1368          *     This is useful for clone, extended, and vertical extended modes
1369          *     where the entire src_surf may not be displayed.
1370          * @param dest_rect Input dest surface rectangle.  This is relative to the
1371          *     framebuffer not the display (so clone mode works properly).
1372          * @param ovl_info Input overlay information to display.
1373          *     The color key, video quality, and gamma must be valid
1374          *     and correct when the overlay is on.  That means NO passing in NULL
1375          *     values to use previous settings.
1376          * @param flags Input to turn on/off the overlay and set other flags.
1377          *   See: @ref alter_ovl_flags
1378          *
1379          * @returns 0 (IGD_SUCCESS) on Success
1380          * @returns <0 (-igd_errno) on Error.  The overlay will be off, no need
1381          *     for the IAL to call the HAL to turn the overlay off.
1382          *     If -IGD_ERROR_INVAL is returned, something is either to big or
1383          *      to small for the overlay to handle, or it is panned off of the
1384          *      displayed.  This is likely not critical, since it may be stretched
1385          *      or panned back, so the overlay can support it.  The IAL
1386          *      should not return an error to the application, or else the
1387          *      application will likely exit.
1388          *     If -IGD_ERROR_HWERROR is returned, something is outside of what
1389          *      the overlay can support (pitch to large, dot clock to large,
1390          *      invalid pixel format, ring or flip not happening).  In this case,
1391          *      the IAL should return an error to the application, since
1392          *      additional calls will always fail as well.
1393          */
1394         int (*alter_ovl)(igd_display_h display_h,
1395                 igd_appcontext_h     appcontext_h,
1396                 igd_surface_t       *src_surf,
1397                 igd_rect_t          *src_rect,
1398                 igd_rect_t          *dest_rect,
1399                 igd_ovl_info_t      *ovl_info,
1400                 unsigned int         flags);
1401
1402         int (*alter_ovl2)(igd_display_h display_h,
1403                 igd_surface_t       *src_surf,
1404                 igd_rect_t          *src_rect,
1405                 igd_rect_t          *dest_rect,
1406                 igd_ovl_info_t      *ovl_info,
1407                 unsigned int         flags);
1408
1409 /*      int (*alter_ovl2_dihclone)(igd_display_h display_h,
1410                 igd_surface_t       *src_surf,
1411                 igd_rect_t          *src_rect,
1412                 igd_rect_t          *dest_rect,
1413                 igd_ovl_info_t      *ovl_info,
1414                 unsigned int         flags);*/
1415
1416
1417         /* igd_ovl.h */
1418         /*!
1419          *  Retrieve the kernel mode initialization parameters for overlay.
1420          *  This function should be called by user-mode drivers as they are
1421          *  initialized, to retrieve overlay initialization parameters
1422          *  discovered and held by the kernel driver.
1423          *
1424          * @returns 0 (IGD_SUCCESS) on Success
1425          * @returns <0 (-igd_errno) on Error.
1426          */
1427         int (*get_ovl_init_params)(igd_driver_h driver_handle,
1428                                    ovl_um_context_t *ovl_um_context);
1429
1430         /*!
1431          * Query the overlay to determine if an event is complete or if a given
1432          * capability is present.
1433          *
1434          * @param display_h Display used with this overlay
1435          * @param flags Used to check for which event is complete or which
1436          *     capability is present.
1437          *     See @ref query_ovl_flags
1438          *
1439          * @returns TRUE if event has occured or capability is available
1440          * @returns FALSE if event is pending or capability is not available
1441          */
1442         int (*query_ovl)(igd_display_h display_h,
1443                 unsigned int flags);
1444
1445         /*!
1446          * Query the overlay for the maximum width and height given the input
1447          * src video pixel format.
1448          *
1449          * @param display_h Display used with this overlay
1450          * @param pf Input src video pixel format
1451          * @param max_width Output maximum overlay width supported (in pixels)
1452          * @param max_height Output maximum overlay height supported (in pixels)
1453          *
1454          * @returns 0 (IGD_SUCCESS) on Success - will return success
1455          *    even if overlay is currently in use.
1456          * @returns <0 (-igd_errno) on Error
1457          */
1458         int (*query_max_size_ovl)(igd_display_h display_h,
1459                 unsigned long pf,
1460                 unsigned int *max_width,
1461                 unsigned int *max_height);
1462
1463         /*!
1464          * Alter the sprite C plane with the associated osd/subpicture data
1465          */
1466     int (*alter_ovl_osd)(igd_display_h display_h,
1467         igd_appcontext_h     appcontext_h,
1468         igd_surface_t *sub_surface,
1469         igd_rect_t *sub_src_rect,
1470         igd_rect_t *sub_dest_rect,
1471         igd_ovl_info_t      *ovl_info,
1472         unsigned int         flags);
1473
1474         int (*alter_ovl2_osd)(igd_display_h display_h,
1475                 igd_surface_t *sub_surface,
1476                 igd_rect_t *sub_src_rect,
1477                 igd_rect_t *sub_dest_rect,
1478                 igd_ovl_info_t      *ovl_info,
1479                 unsigned int         flags);
1480
1481         /* igd_render.h */
1482         _igd_get_surface_fn_t get_surface;
1483         _igd_set_surface_fn_t set_surface;
1484         _igd_query_event_fn_t query_event;
1485
1486         /* These functions are only to be used by priveledged IALs */
1487         _igd_alloc_ring_fn_t alloc_ring;
1488         _igd_exec_buffer_fn_t execute_buffer;
1489         _igd_rb_reserve_fn_t rb_reserve;
1490         _igd_rb_update_fn_t rb_update;
1491         _igd_get_sync_slot_fn_t get_sync_slot;
1492         _igd_query_buffer_fn_t query_buffer;
1493
1494         /*!
1495          *  dispatch->get_display() returns the current framebuffer and
1496          *  display information.
1497          *
1498          * @param display_handle required.  The display_handle contains the
1499          *  display information to return.  This parameter was returned from a
1500          *  previous call to dispatch->alter_displays().
1501          *
1502          * @param port_number required. The port number will determine which
1503          *  port's display info data to return.
1504          *
1505          * @param fb_info required and allocated by the caller.  The fb_info
1506          *  struct is returned to the caller describing the current
1507          *  frame buffer.
1508          *
1509          * @param pt_info required and allocated by the caller.  The
1510          *  pt_info struct is returned to caller describing the
1511          *  requested display parameters.
1512          *
1513          * @param flags - Currently not used
1514          *
1515          * @returns 0 The mode was successfully returned for all displays.
1516          * @returns -IGD_INVAL: Was not able to return the display information.
1517          */
1518         int (*get_display)(igd_display_h display_handle,
1519                         unsigned short port_number, igd_framebuffer_info_t *fb_info,
1520                         igd_display_info_t *pt_info, unsigned long flags);
1521
1522 #ifdef D3D_DPM_ALLOC
1523    /* FIXEME: Somehow this D3D_DPM_ALLOC is always invisible to display dll.
1524     * To avoid the whole structure corruption, the following delcaration
1525     * appended at the very end.
1526     */
1527    unsigned long* (*gmm_map_sgx)(unsigned long size, unsigned long offset,
1528       unsigned long flag);
1529 #endif
1530         int (*get_golden_htotal)(igd_display_info_t *drm_mode_in, igd_display_info_t *drm_mode_out  );
1531
1532         /*!
1533          *  Registers a VBlank interrupt callback function (and its parameter) to
1534          *  call when a VBlank interrupt occurs for a given port.
1535          *
1536          * @param callback (IN).  A callback (function pointer) to a non-HAL
1537          * function that processes a VBlank interrupt.
1538          *
1539          * @param priv (IN).  An opaque pointer to a non-HAL data structure.
1540          *  This pointer is passed as a parameter of the callback function.
1541          *
1542          * @param port_number (IN).  The EMGD port number to register a VBlank
1543          *  interrupt callback for.
1544          *
1545          * @return A handle that uniquely identifies this callback/port
1546          *  combination, or NULL if a failure.
1547          */
1548         emgd_vblank_callback_h (*register_vblank_callback)(
1549                 emgd_process_vblank_interrupt_t callback,
1550                 void *priv,
1551                 unsigned long port_number);
1552
1553         /*!
1554          *  Unregisters a previously-registered VBlank interrupt callback function
1555          *  for a given port.
1556          *
1557          * @param callback_h (IN).  The handle that uniquely identifies the VBlank
1558          *  interrupt callback to unregister.
1559          */
1560         void (*unregister_vblank_callback)(
1561                 emgd_vblank_callback_h callback_h);
1562
1563         /*!
1564          *  Enable delivering VBlank interrupts to the callback function for the
1565          *  registered callback/port combination.
1566          *
1567          * @param callback_h (IN).  The handle that uniquely identifies which
1568          *  VBlank interrupt callback/port combination to enable.
1569          *
1570          * @return Zero if successful, non-zero if a failure.
1571          */
1572         int (*enable_vblank_callback)(emgd_vblank_callback_h callback_h);
1573
1574         /*!
1575          *  Disable delivering VBlank interrupts to the callback function for the
1576          *  registered function/port combination.
1577          *
1578          * @param callback_h (IN).  The handle that uniquely identifies which
1579          *  VBlank interrupt callback/port combination to disable.
1580          */
1581         void (*disable_vblank_callback)(
1582                 emgd_vblank_callback_h callback_h);
1583
1584         /*!
1585          * Shutdown MSVDX before the X exits.
1586          */
1587         void (*video_shutdown)(void);
1588
1589
1590         /*!
1591          * Query the hardware on for given 2D Caps.
1592          */
1593         void (*query_2d_caps_hwhint)(unsigned long caps_val,
1594                 unsigned long *status);
1595
1596         int (*dihclone_set_surface)(
1597         unsigned long display_number,
1598         unsigned long mode);
1599
1600         /*!
1601          *  Allows a user mode application to change pixel format of a display
1602          *  plane from XRGB to ARGB and vice versa.
1603          *
1604          * @param enable (IN). Whether to turn on transparency or not with the
1605          *  assumption that XRGB turns off transparency and ARGB turns it on.
1606          *  0 = disable
1607          *  1 = enable
1608          * @param display_plane (IN). Which display plane to change pixel_format of
1609          *  0 = Plane A
1610          *  1 = Plane B
1611          */
1612         int (*control_plane_format)(int enable, igd_display_h display_handle);
1613
1614         /*!
1615          * Overlay Plane assignment override.
1616          */
1617         int (*set_ovl_display)(igd_display_h ovl_displays[]);
1618
1619 /*!
1620          * Get MSVDX status.
1621          */
1622         int (*msvdx_status)(igd_driver_h driver_handle, unsigned long *queue_status, unsigned long *mtx_msg_status);
1623 } igd_dispatch_t;
1624
1625 #endif