HAL Flat Display Driver Demystified

  • Article

 Posted by Oguz Sinanoglu

 

Let’s talk about display drivers, particularly HAL Flat ones. HAL stands for Hardware Abstraction Layer and is also known as OEM Adaptation Layer (OAL).

 

What is a HAL Flat display driver?

 

In brief, it is yet another implementation of a GPE (Graphics Primitive Engine) based display driver, but with a twist: The driver itself does not contain any hardware dependent code and therefore it is totally platform independent. The hardware dependent code is pushed down to OAL. It communicates with OAL through I/O control (IOCTL) messages.

 

As its name suggests it requires a flat (contiguous) frame buffer either on the display hardware or in memory.

 

The driver source is under %_WINCEROOT%\Public\Common\OAK\Drivers\Display\hflat.

 

Why care about writing a HAL Flat display driver?

 

A HAL Flat driver is a good choice to quickly make the display work on a new platform.

 

HAL Flat driver is based on GPE technology only and not on DirectDraw (DDGPE). Therefore, it is much simpler and easier to implement. Writing the hardware dependent code in OAL is straightforward: just right the basic hardware initialization code and data transfer routines for the frame buffer (if needed at all). You don’t need to write any DMA or HW acceleration code unless the HAL Flat driver will be the final display driver for your platform. Either way your efforts in developing the hardware routines won’t go wasted, you can put them into a DDGPE based driver if you choose to implement one later.

 

How do I implement a HAL Flat display driver?

 

Here are the steps to make the HAL Flat driver to work with your hardware:

 

1. Add the following line to into the IOCTL table in %_WINCEROOT%\Platform\%_TGTPLAT%\src\inc\ioctl_tab.h:

 

{ IOCTL_HAL_DDI, 0, OALIoCtlHalDDI },

 

IOCTL_HAL_DDI is the IOCTL message for HAL Flat services that enter OAL at OALIoCtlHalDDI function.

 

2. Add OALIoCtlHalDDI function to OAL code. Write the necessary hardware initialization and power management code and call it from OALIoCtlHalDDI.

 

Sample code for how to write OAL part of the HAL Flat display driver can be found under:

 

Windows CE 5.0:

%_WINCEROOT%\Platform\DBAu1100\src\kernel\oal\lcd.c

 

Windows CE 6.0:

%_WINCEROOT%\Platform\Aspen7750R\src\oal\oallib\ddi.c

 

Build OAL without any warnings or errors.

 

3. Add the following section to %_WINCEROOT%\Platform\%_TGTPLAT%\Files\Platform.bib:

 

Windows CE 5.0:

 

; @CESYSGEN IF CE_MODULES_DISPLAY

IF BSP_NODISPLAY !

IF BSP_DISPLAY_HFLAT

 

ddi_hflat.dll $(_FLATRELEASEDIR)\ddi_hflat.dll NK SH

 

ENDIF BSP_DISPLAY_HFLAT

ENDIF BSP_NODISPLAY !

; @CESYSGEN ENDIF CE_MODULES_DISPLAY

 

Windows CE 6.0:

 

; @CESYSGEN IF CE_MODULES_DISPLAY

IF BSP_NODISPLAY !

IF BSP_DISPLAY_HFLAT

 

ddi_hflat.dll $(_FLATRELEASEDIR)\ddi_hflat.dll NK SHK

 

ENDIF BSP_DISPLAY_HFLAT

ENDIF BSP_NODISPLAY !

; @CESYSGEN ENDIF CE_MODULES_DISPLAY

 

4. Add the following section to %_WINCEROOT%\Platform\%_TGTPLAT%\Files\Platform.reg:

 

Windows CE 5.0 and Windows CE 6.0:

 

; @CESYSGEN IF CE_MODULES_DISPLAY

IF BSP_NODISPLAY !

            IF BSP_DISPLAY_HFLAT

 

[HKEY_LOCAL_MACHINE\System\GDI\Drivers]

    "Display"="ddi_hflat.dll" ; HAL FLAT driver uses hard coded configuration values

 

ENDIF BSP_DISPLAY_HFLAT

ENDIF BSP_NODISPLAY !

; @CESYSGEN ENDIF CE_MODULES_DISPLAY

 

5. Build the image with BSP_DISPLAY_HFLAT flag set and BSP_DISPLAY_NOP flag cleared.