LCD Extension Implementation Tutorial

Build environment

In the template reference board port, the .mmp file for the LCD Extension is ...\template_variant\lcdtemplate.mmp. This is one of the PRJ_MMPFILES referenced in the template variant's bld.inf file in the ...\template_variant\... directory, and means that the LCD Extension is built as part of the Variant.

The source for the driver is contained entirely within ...\template_variant\specific\lcd.cpp.

The driver is defined as a kernel extension and is loaded early in the boot sequence.

Initialization

The driver functionality is almost entirely encapsulated by the DLcdPowerHandler class. This is a power handler class derived from DPowerHandler. An instance of DLcdPowerHandler is created when the extension is loaded.

DLcdPowerHandler is defined within the source file itself ...\template_variant\specific\lcd.cpp.

As the driver is a kernel extension, it must have a DECLARE_STANDARD_EXTENSION() statement. In the template port, this is implemented as follows:

DECLARE_STANDARD_EXTENSION()
    {
    __KTRACE_OPT(KPOWER,Kern::Printf("Starting LCD power manager"));
    
    // create LCD power handler
    TInt r=KErrNoMemory;
    DLcdPowerHandler* pH=new DLcdPowerHandler;
    if (pH)
        r=pH->Create();
    
    __KTRACE_OPT(KPOWER,Kern::Printf("Returns %d",r));
    return r;
    }

This simply creates an instance of the DLcdPowerHandler class and then calls its Create() function which implements the display setup. This function should do the following:

• map the video RAM

• setup the video info structure

• install the HAL handler

• install the power handler.

Map the video RAM

The frame buffer is a DPlatChunkHw object, and should be mapped as globally accessible, readable and writeable. It should not be mapped as writeback cached, it should be either not-cached or write-through. The advantage of write through is that it allows the use of the write buffer.

TInt DLcdPowerHandler::Create()
    {
    ...

    // map the video RAM
    TInt vSize = ((TemplateAssp*)Arch::TheAsic())->VideoRamSize();
    ivRamPhys = TTemplate::VideoRamPhys();                // EXAMPLE ONLY: assume TTemplate interface class
    TInt r = DPlatChunkHw::New(iChunk,ivRamPhys,vSize,EMapAttrUserRw|EMapAttrBufferedC);
    if ® != KErrNone)
        return r;
 ...

If the frame buffer resides in main RAM and there is no restriction on which physical addresses may be used for it, physical RAM for the frame buffer should be reserved by using Epoc::AllocPhysicalRam().

If the frame buffer does not reside in main RAM, there is no problem about reserving it.

If the frame buffer must reside at a specific address in main RAM, there are two strategies available for reserving it:

• If no conflicts are permitted between the frame buffer and memory allocations made during the kernel boot (for example, if the frame buffer must reside at the end of main memory), simply use Epoc::ClaimPhysicalRam(). This function just marks a region of physical RAM as allocated, returning an error if any part of the region has already been used.

• The required physical RAM region can be reserved in the bootstrap. The correct place to do this is in the implementation of the boot table function BTF_Reserve when writing platform-specific source code for the bootstrap. See the Bootstrap Port Implementation Tutorial for more detail and look at ...\template_variant\bootstrap\template.s for a concrete example.

Note that all Symbian platform base ports currently create a second frame buffer for a secure screen. However, as platform security is not yet implemented, this is wasteful of RAM and should be omitted.

Set up the video information structure

The video information structure is used to define several aspects of the display including display size, bits per pixel and address of the frame buffer. This structure is the class TVideoInfoV01 defined in the header file ...\eka\include\videodriver.h and exported to ...\epoc32\include.

TInt DLcdPowerHandler::Create()
    {
       ...
       // setup the video info structure, this will be used to remember the video settings
       iVideoInfo.iDisplayMode = KConfigLcdInitialDisplayMode;
       iVideoInfo.iOffsetToFirstPixel = Lcd_Mode_Config[KConfigLcdInitialDisplayMode].iOffsetToFirstVideoBuffer;
       iVideoInfo.iIsPalettized = Lcd_Mode_Config[KConfigLcdInitialDisplayMode].iIsPalettized;
       iVideoInfo.iOffsetBetweenLines = Lcd_Mode_Config[KConfigLcdInitialDisplayMode].iOffsetBetweenLines;
       iVideoInfo.iBitsPerPixel = Lcd_Mode_Config[KConfigLcdInitialDisplayMode].iBitsPerPixel;

       iVideoInfo.iSizeInPixels.iWidth = KConfigLcdWidth;
       iVideoInfo.iSizeInPixels.iHeight = KConfigLcdHeight;
       iVideoInfo.iSizeInTwips.iWidth = KConfigLcdWidthInTwips;
       iVideoInfo.iSizeInTwips.iHeight = KConfigLcdHeightInTwips;
       iVideoInfo.iIsMono = KConfigLcdIsMono;
       iVideoInfo.iVideoAddress=(TInt)pV;
       iVideoInfo.iIsPixelOrderLandscape = KConfigLcdPixelOrderLandscape;
       iVideoInfo.iIsPixelOrderRGB = KConfigLcdPixelOrderRGB;
    ...
    }

Install the HAL handler

Control of the display is done by using the HAL, the Hardware Abstraction Layer.

The DLcdPowerHandler class provides the implementation for the HAL handler for the HAL function group EHalGroupDisplay and this needs to be registered with the kernel by calling Kern::AddHalEntry().

TInt DLcdPowerHandler::Create()
    {
       ...
       // install the HAL function
       r=Kern::AddHalEntry(EHalGroupDisplay, halFunction, this);
       if (r!=KErrNone)
              return r;
    ...
    }

See User-Side Hardware Abstraction for more detailed information on the HAL.

Install the power handler

A call must be made to the Add() function, which is supplied by the DPowerHandler base class of DLcdPowerHandler, to register the handler with the power manager.

TInt DLcdPowerHandler::Create()
    {
       ...
        // install the power handler
        // power up the screen
        Add();
    ...
    }

HAL handler implementation

Requests to get and set hardware attributes are made through calls to HAL::Get() and HAL::Set(). These two HAL functions take a value that identifies a hardware attribute, one of the HALData::TAttribute values.

For the LCD Extension, the relevant hardware attributes are: EDisplayMode, EDisplayBitsPerPixel, EDisplayIsPalettized, EDisplayIsMono, EDisplayMemoryAddress, EDisplayMemoryHandle, EDisplayOffsetToFirstPixel, EDisplayOffsetBetweenLines, EDisplayXPixels, EDisplayYPixels, EDisplayPaletteEntry and EDisplayOffsetBetweenLines.

The HAL handler is registered with the kernel as the handler for the THalFunctionGroup::EHalGroupDisplay group. The HAL handler itself takes a function ID, which is one of the TDisplayHalFunction enumerators.

A call to HAL::Get() and HAL::Set() that takes one of the hardware attributes relevant to the LCD Extension is ultimately routed to a call to this HAL handler function passing an appropriate function ID. The association between the hardware attribute and the function ID is the responsibility of the accessor functions.

See User-Side Hardware Abstraction for more information on the way this works in general.

The HAL handler is implemented as a case statement, switching on the function ID. For example, the following code fragment taken from DLcdPowerHandler::HalFunction() gets and sets the brightness:

TInt DLcdPowerHandler::HalFunction(TInt aFunction, TAny* a1, TAny* a2)
    {
    TInt r=KErrNone;
    switch(aFunction)
        {
    
        ...
         case EDisplayHalSetDisplayBrightness:
             if(!Kern::CurrentThreadHasCapability(ECapabilityWriteDeviceData,
       __PLATSEC_DIAGNOSTIC_STRING("Checked by Hal function EDisplayHalSetDisplayBrightness")))
                       return KErrPermissionDenied;
             r=SetBrightness(TInt(a1));
             break;
            
         case EDisplayHalDisplayBrightness:
             kumemput32(a1,&iBrightness,sizeof(iBrightness));
             break;
        ...

where SetBrightness() is implemented as:

TInt DLcdPowerHandler::SetBrightness(TInt aValue)
    {
     __KTRACE_OPT(KEXTENSION,Kern::Printf("SetBrightness(%d)", aValue));

     if (aValue >= KConfigLcdMinDisplayBrightness && aValue <= KConfigLcdMaxDisplayBrightness)
         {
         iBrightness=aValue;
    
         // TO DO: (mandatory)
         // set the brightness
         //
         return KErrNone;
         }
    return KErrArgument;
    }

If an attribute does not have an implementation, the HAL handler function should return KErrNotSupported.

For platform security, the code only allows the attribute to be set if the current thread has been authorized to write system data. Otherwise, it returns KErrPermissionDenied.

Switch on and switch off operations

All of the HAL operations are seen to be synchronous by the user side. However there are some operations such as turning the display on and off which may need to be implemented asynchronously.

The display on/off code is implemented using synchronous kernel-side messages. There is only one message per thread and the thread always blocks while a message is outstanding. This means it is possible to make an asynchronous operation appear synchronous.

When turning on the screen the kernel-side message is queued and this thread is blocked until the message is completed, which happens when the display has been turned on.

If a display needs to be turned on and off truly asynchronously (for example, if millisecond timer waits are required during the process of turning on the display), the above functionality must be changed so that the complete occurs when the display is truly on.

Accessing the video information structure

When any part of the video information structure is read or written to, this must be done within a critical section to prevent potential collisions with other threads attempting to access the structure concurrently. A fast mutex is used to ensure that only one thread can access the video information at any one time, as the code segment below shows.

TInt DLcdPowerHandler::GetCurrentDisplayModeInfo(TVideoInfoV01& aInfo, TBool aSecure)
    {
     __KTRACE_OPT(KEXTENSION,Kern::Printf("GetCurrentDisplayModeInfo"));
     NKern::FMWait(&iLock);
     if (aSecure)
          aInfo = iSecureVideoInfo;
     else
         aInfo = iVideoInfo;
     NKern::FMSignal(&iLock);
     return KErrNone;
     }

Power handler implementation

The DPowerHandler class defines the interface that the driver must implement to provide power handling behaviour. For the template reference board, the LCD Extension defines and implements the DLcdPowerHandler class derived from DPowerHandler.

Note:

• DPowerHandler::PowerDown() and DPowerHandler::PowerUp()

  These functions are called in the context of the thread that initiates power down or power up, and synchronization is required, typically by means of power up and power down DFCs.

• DPowerHandler::PowerUpLcd() and DPowerHandler::PowerDownLcd()

  These functions generally queue DFCs which then call platform-specific functions to power the display up and down.

• DPowerHandler::PowerUpDone() and DPowerHandler::PowerDownDone()

  When power up or down is complete, the interface supplies a set of acknowledgment functions which must be called when the change of state has taken place.