Share via

IOCTL_HAL_DDI (Compact 2013)

  • Article

3/26/2014

This I/O control message retrieves information and sends commands to the Ddi_hflat display driver. The Ddi_hflat driver is a simple display driver that uses a flat framebuffer and the Graphics Primitive Engine (GPE) base class library. For more information, see GPE Base Classes. This I/O control allows you use some of the GPE capabilities within Ddi_hflat without having to work directly with the details of GPE. Send this message with KernelIoControl.

Syntax

BOOL KernelIoControl(
    DWORD dwIoControlCode,    // use IOCTL_HAL_DDI
    LPVOID lpInBuffer,        // pointer to input buffer
    DWORD nInBufferSize,      // input buffer size
    LPVOID lpOutBuffer,       // pointer to output buffer
    DWORD nOutBufferSize,     // output buffer size
    LPDWORD lpBytesReturned  // number of bytes returned
);

Parameters

  • dwIoControlCode
    [in] Control code for the operation. Use IOCTL_HAL_DDI for this operation.

  • lpInBuffer
    [in] A pointer to an array of ULONG values that describes the command to send to the driver. The following table shows the possible command values.

    Value

    Description

    DDHAL_COMMAND_GET_MODE_INFO

    Returns the size, in bytes, of a display mode, or it returns the data for the display mode. See the Remarks section.

    Set lpInBuffer to a two-element array, with this value as first element and the number of the display mode as the second element.

    DDHAL_COMMAND_GET_NUM_MODES

    Returns the number of display modes that the driver supports.

    Set lpInBuffer to a pointer to this value.

    DDHAL_COMMAND_POWER

    Turns the driver's power handler on or off.

    Set lpInBuffer to a two-element array with this value as the first element and the desired power handler state in the second element. Set the second element to TRUE to turn the power handler on, or FALSE to turn the power handler off.

    DDHAL_COMMAND_SET_MODE

    Sets the display driver's display mode.

    Set lpInBuffer to a two-element array with this value as the first element and the number of the new display mode as the second element.

    DDHAL_COMMAND_SET_PALETTE

    Sets the new palette for the display driver.

    Set lpInBuffer to a pointer to this value.
  • nInBufferSize
    [in] Set to the size, in bytes, of lpInBuffer.

  • lpOutBuffer
    [in, out] A pointer to a buffer used for either input or output data depending on the type of command passed in lpInBuffer. The following table shows the possible values for lpOutBuffer.

    Value

    lpOutBuffer

    DDHAL_COMMAND_GET_MODE_INFO

    [in] To obtain the size of a display mode, set lpOutBuffer to NULL.

    [out] To obtain the data describing a display mode, set lpOutBuffer to a pointer to a buffer of UINT8 values. The size of the buffer is the value returned when lpOutBuffer is set to NULL.

    DDHAL_COMMAND_GET_NUM_MODES

    [out] A pointer to an int value that will receive the number of display modes.

    DDHAL_COMMAND_POWER

    Set to NULL.

    DDHAL_COMMAND_SET_MODE

    Set to NULL.

    DDHAL_COMMAND_SET_PALETTE

    [in] A buffer of UINT8 values with the data formatted like a DDHAL_SET_PALETTE structure.
  • nOutBufferSize
    [in] Set to the size, in bytes, of lpOutBuffer.

  • lpBytesReturned
    [out] A pointer to a buffer that receives output data depending on the type of command passed in lpInBuffer. The following table shows the possible values for lpBytesReturned.

    Value

    lpBytesReturned

    DDHAL_COMMAND_GET_MODE_INFO

    If lpOutBuffer is NULL then this is the number of bytes required to describe a display mode.

    If lpOutBuffer is a pointer to a buffer that describes a display mode, then this is the size, in bytes, of the buffer.

    DDHAL_COMMAND_GET_NUM_MODES

    Set to NULL.

    DDHAL_COMMAND_POWER

    Set to NULL.

    DDHAL_COMMAND_SET_MODE

    Set to NULL.

    DDHAL_COMMAND_SET_PALETTE

    Set to NULL.

Return Values

Returns TRUE if successful; otherwise, returns FALSE.

Remarks

The following code shows how to use DDHAL_COMMAND_GET_MODE_INFO to query for the size of the buffer needed to store a display mode identified by the int value, modeNumber.

ULONG commands[2];
ULONG size;  // The size of the display mode buffer
// Ask HAL about mode, first call fails because output buffer is NULL
commands[0] = DDHAL_COMMAND_GET_MODE_INFO;
commands[1] = modeNumber;
rc = KernelIoControl(
  IOCTL_HAL_DDI, commands, sizeof(commands), NULL, 0, &size
);

The following code shows how to use DDHAL_COMMAND_GET_MODE_INFO to fill a buffer with the data that describes a display mode using the variables and data obtained from the previous code.

// Allocate buffer
UINT8 * pBuffer = new UINT8[size];
if (pBuffer == NULL) {
  DEBUGMSG(GPE_ZONE_ERROR, (L"FlatGPE::SetMode: "
    L"Failed allocate %d byte buffer\r\n", size));
  sc = E_FAIL;
  goto cleanUp;
}
// Call mode info second time
if (!KernelIoControl(
  IOCTL_HAL_DDI, commands, sizeof(commands), pBuffer, size, &size
)) {
  DEBUGMSG(GPE_ZONE_ERROR, (L"FlatGPE::SetMode: "
           L"IOCTL_HAL_DDI!GET_MODE_INFO failed for mode %d\r\n",
           modeNumber));
  sc = E_FAIL;
  goto cleanUp;
}

Requirements

Header

ddhal.h

See Also

Reference

Display Driver IOCTLs