IOCTL_HAL_DDI (Windows Embedded CE 6.0)

1/6/2010

This IOCTL is used in calls to KernelIoControl to retrieve information and send 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 IOCTL allows you use some of the GPE capabilities within Ddi_hflat without having to work directly with the details of GPE.

KernelIoControl Parameters

• dwIoControlCode
  [in] Set to IOCTL_HAL_DDI.

• lpInBuf
  [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 lpInBuf 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 lpInBuf to a pointer to this value.
  DDHAL_COMMAND_POWER	Turns the driver's power handler on or off. Set lpInBuf 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 lpInBuf 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 lpInBuf to a pointer to this value.

• nInBufSize
  [in] Set to the size, in bytes, of lpInBuf.

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

  Value	lpOutBuf
  DDHAL_COMMAND_GET_MODE_INFO	[in] To obtain the size of a display mode, set lpOutBuf to NULL. [out] To obtain the data describing a display mode, set lpOutBuf to a pointer to a buffer of UINT8 values. The size of the buffer is the value returned when lpOutBuf 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.

• nOutBufSize
  [in] Set to the size, in bytes, of lpOutBuf

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

  Value	lpBytesReturned
  DDHAL_COMMAND_GET_MODE_INFO	If lpOutBuf is NULL then this is the number of bytes required to describe a display mode. If lpOutBuf 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

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

See Also

Reference

Display Driver IOCTLs