FCL/sftools/depl/docscontent: comparison Symbian3/PDK/Source/GUID-6A4FE3A3-2E5D-51BB-8272-5995586291E9.dita

equal deleted inserted replaced

-:48780e181b38
+:578be2adaf3e
 Nokia Corporation - initial contribution.
 Contributors:
 -->
 <!DOCTYPE concept
 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
-<concept id="GUID-6A4FE3A3-2E5D-51BB-8272-5995586291E9" xml:lang="en"><title>LCD
+<concept id="GUID-6A4FE3A3-2E5D-51BB-8272-5995586291E9" xml:lang="en"><title>LCD Extension Implementation Tutorial</title><shortdesc>This topic describes how to create an LCD Extension.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
-Extension Implementation Tutorial</title><shortdesc/><prolog><metadata><keywords/></metadata></prolog><conbody>
+<p>The topic uses a reference board port named <filepath>template_variant</filepath> as an example implementation. </p>
-<p>This topic describes how to create an LCD Extension. </p>
+<section id="GUID-7DDD91D2-A69F-4940-AA58-74EB2A989E55"><title>Build
-<p>The topic uses a reference board port named <filepath>template_variant</filepath> as
+environment</title> <p>In the template reference board port, the <filepath>.mmp</filepath> file for the LCD Extension is <filepath>...\template_variant\lcdtemplate.mmp</filepath>. This is one of the <codeph>PRJ_MMPFILES</codeph> referenced in
-an example implementation. </p>
+the template variant's <filepath>bld.inf</filepath> file in the <filepath>...\template_variant\...</filepath> directory, and means that the
-<section id="GUID-7DDD91D2-A69F-4940-AA58-74EB2A989E55"><title>Build environment</title> <p>In the template reference board
+LCD Extension is built as part of the Variant. </p> <p>The source
-port, the <filepath>.mmp</filepath> file for the LCD Extension is <filepath>...\template_variant\lcdtemplate.mmp</filepath>.
+for the driver is contained entirely within <filepath>...\template_variant\specific\lcd.cpp</filepath>. </p> <p>The driver is defined as a kernel extension and is loaded
-This is one of the <codeph>PRJ_MMPFILES</codeph> referenced in the template
+early in the boot sequence. </p> </section>
-variant's <filepath>bld.inf</filepath> file in the <filepath>...\template_variant\...</filepath> directory,
+<section id="GUID-FC49B296-5DFA-4C19-BEDE-F641D70E5ED9"><title>Initialization</title> <p>The driver functionality is almost entirely encapsulated by the <codeph>DLcdPowerHandler</codeph> class. This is a power handler class derived
-and means that the LCD Extension is built as part of the Variant. </p> <p>The
+from <xref href="GUID-761AE02B-41A6-35EA-AA9F-0AEEFF67A6F7.dita"><apiname>DPowerHandler</apiname></xref>. An instance of <codeph>DLcdPowerHandler</codeph> is created when the extension is loaded. </p> <p> <codeph>DLcdPowerHandler</codeph> is defined within the source file itself <filepath>...\template_variant\specific\lcd.cpp</filepath>. </p> <p>As the driver is a kernel extension, it must have a <codeph>DECLARE_STANDARD_EXTENSION()</codeph> statement. In the template
-source for the driver is contained entirely within <filepath>...\template_variant\specific\lcd.cpp</filepath>. </p> <p>The
+port, this is implemented as follows: </p> <codeblock id="GUID-BB93E7E7-06DA-5A12-ABA1-D07AA246D6FC" xml:space="preserve">DECLARE_STANDARD_EXTENSION()
-driver is defined as a kernel extension and is loaded early in the boot sequence. </p> </section>
-<section id="GUID-FC49B296-5DFA-4C19-BEDE-F641D70E5ED9"><title>Initialization</title> <p>The driver functionality is almost
-entirely encapsulated by the <codeph>DLcdPowerHandler</codeph> class. This
-is a power handler class derived from <xref href="GUID-761AE02B-41A6-35EA-AA9F-0AEEFF67A6F7.dita"><apiname>DPowerHandler</apiname></xref>. An
-instance of <codeph>DLcdPowerHandler</codeph> is created when the extension
-is loaded. </p> <p> <codeph>DLcdPowerHandler</codeph> is defined within the
-source file itself <filepath>...\template_variant\specific\lcd.cpp</filepath>. </p> <p>As
-the driver is a kernel extension, it must have a <codeph>DECLARE_STANDARD_EXTENSION()</codeph> statement.
-In the template port, this is implemented as follows: </p> <codeblock id="GUID-BB93E7E7-06DA-5A12-ABA1-D07AA246D6FC" xml:space="preserve">DECLARE_STANDARD_EXTENSION()
 {
 __KTRACE_OPT(KPOWER,Kern::Printf("Starting LCD power manager"));
 // create LCD power handler
 TInt r=KErrNoMemory;
 r=pH-&gt;Create();
 __KTRACE_OPT(KPOWER,Kern::Printf("Returns %d",r));
 return r;
 }
-</codeblock> <p>This simply creates an instance of the <codeph>DLcdPowerHandler</codeph> class
+</codeblock> <p>This simply creates an instance of the <codeph>DLcdPowerHandler</codeph> class and then calls its <codeph>Create()</codeph> function which
-and then calls its <codeph>Create()</codeph> function which implements the
+implements the display setup. This function should do the following: </p> <ul>
-display setup. This function should do the following: </p> <ul>
+<li id="GUID-4D3B36C6-C782-5B3F-8244-7FD33B9976C6"><p>map the video
-<li id="GUID-4D3B36C6-C782-5B3F-8244-7FD33B9976C6"><p>map the video RAM </p> </li>
+RAM </p> </li>
-<li id="GUID-B693BD2B-50FF-554D-AF2B-1992A472F586"><p>setup the video info
+<li id="GUID-B693BD2B-50FF-554D-AF2B-1992A472F586"><p>setup the video
-structure </p> </li>
+info structure </p> </li>
-<li id="GUID-1DF67FC0-90FA-5853-88C2-6DBA5C60F377"><p>install the HAL handler </p> </li>
+<li id="GUID-1DF67FC0-90FA-5853-88C2-6DBA5C60F377"><p>install the
-<li id="GUID-2B8080C4-2A9F-5AA2-B609-3DC8F5759DDE"><p>install the power handler. </p> </li>
+HAL handler </p> </li>
-</ul> <p><b> Map
+<li id="GUID-2B8080C4-2A9F-5AA2-B609-3DC8F5759DDE"><p>install the
-the video RAM</b> </p> <p>The frame buffer is a <xref href="GUID-2A34A3DD-A7FE-34A0-B0B7-BB0A4F04B098.dita"><apiname>DPlatChunkHw</apiname></xref> object,
+power handler. </p> </li>
-and should be mapped as globally accessible, readable and writeable. It should <i>not</i> be
+</ul> <p><b> Map the video RAM</b> </p> <p>The frame buffer is a <xref href="GUID-2A34A3DD-A7FE-34A0-B0B7-BB0A4F04B098.dita"><apiname>DPlatChunkHw</apiname></xref> object, and should be mapped as globally accessible,
-mapped as writeback cached, it should be either not-cached or write-through.
+readable and writeable. It should <i>not</i> be mapped as writeback
-The advantage of write through is that it allows the use of the write buffer. </p> <codeblock id="GUID-148795D9-45A2-526B-A2F7-57B5B2AAC8AB" xml:space="preserve">TInt DLcdPowerHandler::Create()
+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. </p> <codeblock id="GUID-148795D9-45A2-526B-A2F7-57B5B2AAC8AB" xml:space="preserve">TInt DLcdPowerHandler::Create()
 {
 ...
 // map the video RAM
 TInt vSize = ((TemplateAssp*)Arch::TheAsic())-&gt;VideoRamSize();
 ivRamPhys = TTemplate::VideoRamPhys();                // EXAMPLE ONLY: assume TTemplate interface class
 TInt r = DPlatChunkHw::New(iChunk,ivRamPhys,vSize,EMapAttrUserRw|EMapAttrBufferedC);
 if ® != KErrNone)
 return r;
 ...
-</codeblock> <p>If the frame buffer resides in main RAM and there is no restriction
+</codeblock> <p>If the frame buffer resides in main RAM and there
-on which physical addresses may be used for it, physical RAM for the frame
+is no restriction on which physical addresses may be used for it,
-buffer should be reserved by using <xref href="GUID-3DC7B5F2-512E-3FF3-BC08-945DDE2AE680.dita#GUID-3DC7B5F2-512E-3FF3-BC08-945DDE2AE680/GUID-B506D835-505D-3D89-A840-475F291908DC"><apiname>Epoc::AllocPhysicalRam()</apiname></xref>. </p> <p>If
+physical RAM for the frame buffer should be reserved by using <xref href="GUID-3DC7B5F2-512E-3FF3-BC08-945DDE2AE680.dita#GUID-3DC7B5F2-512E-3FF3-BC08-945DDE2AE680/GUID-B506D835-505D-3D89-A840-475F291908DC"><apiname>Epoc::AllocPhysicalRam()</apiname></xref>. </p> <p>If the frame buffer does
-the frame buffer does not reside in main RAM, there is no problem about reserving
+not reside in main RAM, there is no problem about reserving it. </p> <p>If the frame buffer must reside at a specific address in main
-it. </p> <p>If the frame buffer must reside at a specific address in main
 RAM, there are two strategies available for reserving it: </p> <ul>
-<li id="GUID-29D3BF5F-442B-5912-A8B9-4F1F76C1879E"><p>If no conflicts are
+<li id="GUID-29D3BF5F-442B-5912-A8B9-4F1F76C1879E"><p>If no conflicts
-permitted between the frame buffer and memory allocations made during the
+are permitted between the frame buffer and memory allocations made
-kernel boot (for example, if the frame buffer must reside at the end of main
+during the kernel boot (for example, if the frame buffer must reside
-memory), simply use <xref href="GUID-3DC7B5F2-512E-3FF3-BC08-945DDE2AE680.dita#GUID-3DC7B5F2-512E-3FF3-BC08-945DDE2AE680/GUID-78F136DC-023B-30AB-A1AB-34D6BC4F1B3E"><apiname>Epoc::ClaimPhysicalRam()</apiname></xref>. This function
+at the end of main memory), simply use <xref href="GUID-3DC7B5F2-512E-3FF3-BC08-945DDE2AE680.dita#GUID-3DC7B5F2-512E-3FF3-BC08-945DDE2AE680/GUID-78F136DC-023B-30AB-A1AB-34D6BC4F1B3E"><apiname>Epoc::ClaimPhysicalRam()</apiname></xref>. This function just marks a region of physical RAM as allocated,
-just marks a region of physical RAM as allocated, returning an error if any
+returning an error if any part of the region has already been used. </p> </li>
-part of the region has already been used. </p> </li>
+<li id="GUID-F2C5ED3A-767A-58CA-BDC6-78D3C1820C80"><p>The required
-<li id="GUID-F2C5ED3A-767A-58CA-BDC6-78D3C1820C80"><p>The required physical
+physical RAM region can be reserved in the bootstrap. The correct
-RAM region can be reserved in the bootstrap. The correct place to do this
+place to do this is in the implementation of the boot table function <xref href="GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE.dita#GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE/GUID-B3C6ACE9-A803-59D4-8EBD-314363905427">BTF_Reserve</xref> when writing platform-specific source code for
-is in the implementation of the boot table function <xref href="GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE.dita#GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE/GUID-B3C6ACE9-A803-59D4-8EBD-314363905427">BTF_Reserve</xref> when writing platform-specific source code for the bootstrap.
+the bootstrap. See the Bootstrap <xref href="GUID-5EB03086-A87D-5588-8927-7A7F8DB38366.dita">Port Implementation
-See the Bootstrap <xref href="GUID-5EB03086-A87D-5588-8927-7A7F8DB38366.dita">Port
+Tutorial</xref> for more detail and look at <filepath>...\template_variant\bootstrap\template.s</filepath> for a concrete example. </p> </li>
-Implementation Tutorial</xref> for more detail and look at <filepath>...\template_variant\bootstrap\template.s</filepath> for
+</ul> <p>Note that all Symbian platform base ports currently create
-a concrete example. </p> </li>
+a second frame buffer for a secure screen. However, as platform security
-</ul> <p>Note that all Symbian platform base ports currently create a second
+is not yet implemented, this is wasteful of RAM and should be omitted. </p> <p id="GUID-57223C8C-0381-51AC-8E8A-771434136A5C"><b> Set up the video
-frame buffer for a secure screen. However, as platform security is not yet
+information structure</b> </p> <p>The video information structure
-implemented, this is wasteful of RAM and should be omitted. </p> <p id="GUID-57223C8C-0381-51AC-8E8A-771434136A5C"><b> Set up the video information
+is used to define several aspects of the display including display
-structure</b> </p> <p>The video information structure is used to define several
+size, bits per pixel and address of the frame buffer. This structure
-aspects of the display including display size, bits per pixel and address
+is the class <xref href="GUID-C4712A78-6C58-39ED-AF84-11038DB8571D.dita"><apiname>TVideoInfoV01</apiname></xref> defined in the header
-of the frame buffer. This structure is the class <xref href="GUID-C4712A78-6C58-39ED-AF84-11038DB8571D.dita"><apiname>TVideoInfoV01</apiname></xref> defined
+file <filepath>...\eka\include\videodriver.h</filepath> and exported
-in the header file <filepath>...\eka\include\videodriver.h</filepath> and
+to <filepath>...\epoc32\include</filepath>. </p> <codeblock id="GUID-0680E467-9552-5FD6-BBDE-60AE95F0B941" xml:space="preserve">TInt DLcdPowerHandler::Create()
-exported to <filepath>...\epoc32\include</filepath>. </p> <codeblock id="GUID-0680E467-9552-5FD6-BBDE-60AE95F0B941" xml:space="preserve">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.iIsMono = KConfigLcdIsMono;
 iVideoInfo.iVideoAddress=(TInt)pV;
 iVideoInfo.iIsPixelOrderLandscape = KConfigLcdPixelOrderLandscape;
 iVideoInfo.iIsPixelOrderRGB = KConfigLcdPixelOrderRGB;
 ...
-}</codeblock> <p><b> Install
+}</codeblock> <p><b> Install the HAL handler</b> </p> <p>Control of the display is
-the HAL handler</b> </p> <p>Control of the display is done by using the HAL,
+done by using the HAL, the Hardware Abstraction Layer. </p> <p>The <codeph>DLcdPowerHandler</codeph> class provides the implementation for the
-the Hardware Abstraction Layer. </p> <p>The <codeph>DLcdPowerHandler</codeph> class
+HAL handler for the HAL function group <xref href="GUID-7F299BFC-D8A5-3A5A-B8DA-39BF42C99DC6.dita"><apiname>EHalGroupDisplay</apiname></xref> and this needs to be registered with the kernel by calling <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-8C8DCE9D-0094-3909-8FDA-2F3134D0BC88"><apiname>Kern::AddHalEntry()</apiname></xref>. </p> <codeblock id="GUID-F9E86404-742D-5931-BA77-DA246A3975E5" xml:space="preserve">TInt DLcdPowerHandler::Create()
-provides the implementation for the HAL handler for the HAL function group <xref href="GUID-7F299BFC-D8A5-3A5A-B8DA-39BF42C99DC6.dita"><apiname>EHalGroupDisplay</apiname></xref> and
-this needs to be registered with the kernel by calling <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-8C8DCE9D-0094-3909-8FDA-2F3134D0BC88"><apiname>Kern::AddHalEntry()</apiname></xref>. </p> <codeblock id="GUID-F9E86404-742D-5931-BA77-DA246A3975E5" xml:space="preserve">TInt DLcdPowerHandler::Create()
 {
 ...
 // install the HAL function
 r=Kern::AddHalEntry(EHalGroupDisplay, halFunction, this);
 if (r!=KErrNone)
 return r;
 ...
-}</codeblock> <p>See <xref href="GUID-2D977A02-5928-5441-8AE7-42A722F2A4B8.dita#GUID-2D977A02-5928-5441-8AE7-42A722F2A4B8/GUID-4DA41221-40B9-5BC7-B2C6-7C6EB4522508">User-Side
+}</codeblock> <p>See <xref href="GUID-2D977A02-5928-5441-8AE7-42A722F2A4B8.dita#GUID-2D977A02-5928-5441-8AE7-42A722F2A4B8/GUID-4DA41221-40B9-5BC7-B2C6-7C6EB4522508">User-Side Hardware Abstraction</xref> for more detailed information
-Hardware Abstraction</xref> for more detailed information on the HAL. </p> <p><b> Install the power handler</b> </p> <p>A call must be made to the <codeph>Add()</codeph> function,
+on the HAL. </p> <p><b> Install the power handler</b> </p> <p>A call must be made to
-which is supplied by the <xref href="GUID-761AE02B-41A6-35EA-AA9F-0AEEFF67A6F7.dita"><apiname>DPowerHandler</apiname></xref> base class of <codeph>DLcdPowerHandler</codeph>,
+the <codeph>Add()</codeph> function, which is supplied by the <xref href="GUID-761AE02B-41A6-35EA-AA9F-0AEEFF67A6F7.dita"><apiname>DPowerHandler</apiname></xref> base class of <codeph>DLcdPowerHandler</codeph>, to register the handler with the power manager. </p> <codeblock id="GUID-9286C3A2-DC2B-54F1-9F28-4EBE085AEE84" xml:space="preserve">TInt DLcdPowerHandler::Create()
-to register the handler with the power manager. </p> <codeblock id="GUID-9286C3A2-DC2B-54F1-9F28-4EBE085AEE84" xml:space="preserve">TInt DLcdPowerHandler::Create()
 {
 ...
 // install the power handler
 // power up the screen
 Add();
 ...
 }</codeblock> </section>
-<section id="GUID-85B93308-2EDF-462C-8F64-6AE40B8B16B6"><title>HAL handler implementation</title> <p>Requests to get and
+<section id="GUID-85B93308-2EDF-462C-8F64-6AE40B8B16B6"><title>HAL
-set hardware attributes are made through calls to <xref href="GUID-BD00E7FC-C234-3111-87A5-10F79EB0F2B8.dita#GUID-BD00E7FC-C234-3111-87A5-10F79EB0F2B8/GUID-573C49D6-7763-37AE-B2B2-4C8FB1327E21"><apiname>HAL::Get()</apiname></xref> and <xref href="GUID-BD00E7FC-C234-3111-87A5-10F79EB0F2B8.dita#GUID-BD00E7FC-C234-3111-87A5-10F79EB0F2B8/GUID-9454F1B2-D525-3D6D-A872-C6457CACD4FC"><apiname>HAL::Set()</apiname></xref>.
+handler implementation</title> <p>Requests to get and set hardware
-These two HAL functions take a value that identifies a hardware attribute,
+attributes are made through calls to <xref href="GUID-BD00E7FC-C234-3111-87A5-10F79EB0F2B8.dita#GUID-BD00E7FC-C234-3111-87A5-10F79EB0F2B8/GUID-573C49D6-7763-37AE-B2B2-4C8FB1327E21"><apiname>HAL::Get()</apiname></xref> and <xref href="GUID-BD00E7FC-C234-3111-87A5-10F79EB0F2B8.dita#GUID-BD00E7FC-C234-3111-87A5-10F79EB0F2B8/GUID-9454F1B2-D525-3D6D-A872-C6457CACD4FC"><apiname>HAL::Set()</apiname></xref>. These two HAL functions take
-one of the <xref href="GUID-8BE90160-2C60-3582-82C8-4A108C7C0317.dita#GUID-8BE90160-2C60-3582-82C8-4A108C7C0317/GUID-1959915A-BA99-3F94-AFD4-FD1AA540BFBF"><apiname>HALData::TAttribute</apiname></xref> values. </p> <p>For the
+a value that identifies a hardware attribute, one of the <xref href="GUID-8BE90160-2C60-3582-82C8-4A108C7C0317.dita#GUID-8BE90160-2C60-3582-82C8-4A108C7C0317/GUID-1959915A-BA99-3F94-AFD4-FD1AA540BFBF"><apiname>HALData::TAttribute</apiname></xref> values. </p> <p>For the LCD Extension,
-LCD Extension, the relevant hardware attributes are: <codeph>EDisplayMode</codeph>, <codeph>EDisplayBitsPerPixel</codeph>, <codeph>EDisplayIsPalettized</codeph>, <codeph>EDisplayIsMono</codeph>, <codeph>EDisplayMemoryAddress</codeph>, <codeph>EDisplayMemoryHandle</codeph>, <codeph>EDisplayOffsetToFirstPixel</codeph>, <codeph>EDisplayOffsetBetweenLines</codeph>, <codeph>EDisplayXPixels</codeph>, <codeph>EDisplayYPixels</codeph>, <codeph>EDisplayPaletteEntry</codeph> and <codeph>EDisplayOffsetBetweenLines</codeph>. </p> <p>The HAL handler
+the relevant hardware attributes are: <codeph>EDisplayMode</codeph>, <codeph>EDisplayBitsPerPixel</codeph>, <codeph>EDisplayIsPalettized</codeph>, <codeph>EDisplayIsMono</codeph>, <codeph>EDisplayMemoryAddress</codeph>, <codeph>EDisplayMemoryHandle</codeph>, <codeph>EDisplayOffsetToFirstPixel</codeph>, <codeph>EDisplayOffsetBetweenLines</codeph>, <codeph>EDisplayXPixels</codeph>, <codeph>EDisplayYPixels</codeph>, <codeph>EDisplayPaletteEntry</codeph> and <codeph>EDisplayOffsetBetweenLines</codeph>. </p> <p>The HAL
-is registered with the kernel as the handler for the <xref href="GUID-66A851A0-2A0C-3624-AEC1-22F6629FABF7.dita#GUID-66A851A0-2A0C-3624-AEC1-22F6629FABF7/GUID-950EA0D3-747F-305E-92EA-1579023A111E"><apiname>THalFunctionGroup::EHalGroupDisplay</apiname></xref> group.
+handler is registered with the kernel as the handler for the <xref href="GUID-66A851A0-2A0C-3624-AEC1-22F6629FABF7.dita#GUID-66A851A0-2A0C-3624-AEC1-22F6629FABF7/GUID-950EA0D3-747F-305E-92EA-1579023A111E"><apiname>THalFunctionGroup::EHalGroupDisplay</apiname></xref> group. The HAL handler
-The HAL handler itself takes a function ID, which is one of the <xref href="GUID-BB011D9B-105F-345C-9FC0-39B0BA509394.dita"><apiname>TDisplayHalFunction</apiname></xref> enumerators. </p> <p>A
+itself takes a function ID, which is one of the <xref href="GUID-BB011D9B-105F-345C-9FC0-39B0BA509394.dita"><apiname>TDisplayHalFunction</apiname></xref> enumerators. </p> <p>A call to <xref href="GUID-BD00E7FC-C234-3111-87A5-10F79EB0F2B8.dita#GUID-BD00E7FC-C234-3111-87A5-10F79EB0F2B8/GUID-573C49D6-7763-37AE-B2B2-4C8FB1327E21"><apiname>HAL::Get()</apiname></xref> and <xref href="GUID-BD00E7FC-C234-3111-87A5-10F79EB0F2B8.dita#GUID-BD00E7FC-C234-3111-87A5-10F79EB0F2B8/GUID-9454F1B2-D525-3D6D-A872-C6457CACD4FC"><apiname>HAL::Set()</apiname></xref> that takes one of the hardware attributes relevant
-call to <xref href="GUID-BD00E7FC-C234-3111-87A5-10F79EB0F2B8.dita#GUID-BD00E7FC-C234-3111-87A5-10F79EB0F2B8/GUID-573C49D6-7763-37AE-B2B2-4C8FB1327E21"><apiname>HAL::Get()</apiname></xref> and <xref href="GUID-BD00E7FC-C234-3111-87A5-10F79EB0F2B8.dita#GUID-BD00E7FC-C234-3111-87A5-10F79EB0F2B8/GUID-9454F1B2-D525-3D6D-A872-C6457CACD4FC"><apiname>HAL::Set()</apiname></xref> that
+to the LCD Extension is ultimately routed to a call to this HAL handler
-takes one of the hardware attributes relevant to the LCD Extension is ultimately
+function passing an appropriate function ID. The association between
-routed to a call to this HAL handler function passing an appropriate function
+the hardware attribute and the function ID is the responsibility of
-ID. The association between the hardware attribute and the function ID is
+the accessor functions. </p> <p>See <xref href="GUID-2D977A02-5928-5441-8AE7-42A722F2A4B8.dita#GUID-2D977A02-5928-5441-8AE7-42A722F2A4B8/GUID-4DA41221-40B9-5BC7-B2C6-7C6EB4522508">User-Side Hardware Abstraction</xref> for more information on the
-the responsibility of the accessor functions. </p> <p>See <xref href="GUID-2D977A02-5928-5441-8AE7-42A722F2A4B8.dita#GUID-2D977A02-5928-5441-8AE7-42A722F2A4B8/GUID-4DA41221-40B9-5BC7-B2C6-7C6EB4522508">User-Side Hardware Abstraction</xref> for more information on the way this
+way this works in general. </p> <p>The HAL handler is implemented
-works in general. </p> <p>The HAL handler is implemented as a case statement,
+as a case statement, switching on the function ID. For example, the
-switching on the function ID. For example, the following code fragment taken
+following code fragment taken from <codeph>DLcdPowerHandler::HalFunction()</codeph> gets and sets the brightness: </p> <codeblock id="GUID-41D5153A-107A-5FCC-9E51-C6250857F3AC" xml:space="preserve">TInt DLcdPowerHandler::HalFunction(TInt aFunction, TAny* a1, TAny* a2)
-from <codeph>DLcdPowerHandler::HalFunction()</codeph> gets and sets the brightness: </p> <codeblock id="GUID-41D5153A-107A-5FCC-9E51-C6250857F3AC" xml:space="preserve">TInt DLcdPowerHandler::HalFunction(TInt aFunction, TAny* a1, TAny* a2)
 {
 TInt r=KErrNone;
 switch(aFunction)
 {
 case EDisplayHalDisplayBrightness:
 kumemput32(a1,&amp;iBrightness,sizeof(iBrightness));
 break;
 ...
-</codeblock> <p>where <codeph>SetBrightness()</codeph> is implemented as: </p> <codeblock id="GUID-82F38251-19A9-54BC-A066-80ED5AC549AF" xml:space="preserve">TInt DLcdPowerHandler::SetBrightness(TInt aValue)
+</codeblock> <p>where <codeph>SetBrightness()</codeph> is implemented
+as: </p> <codeblock id="GUID-82F38251-19A9-54BC-A066-80ED5AC549AF" xml:space="preserve">TInt DLcdPowerHandler::SetBrightness(TInt aValue)
 {
 __KTRACE_OPT(KEXTENSION,Kern::Printf("SetBrightness(%d)", aValue));
 if (aValue &gt;= KConfigLcdMinDisplayBrightness &amp;&amp; aValue &lt;= KConfigLcdMaxDisplayBrightness)
 {
 //
 return KErrNone;
 }
 return KErrArgument;
 }
-</codeblock> <p>If an attribute does not have an implementation, the HAL handler
+</codeblock> <p>If an attribute does not have an implementation, the
-function should return <xref href="GUID-F89DA3F0-2A48-3F9B-8F08-29350E92D0E4.dita"><apiname>KErrNotSupported</apiname></xref>. </p> <p>For platform
+HAL handler function should return <xref href="GUID-F89DA3F0-2A48-3F9B-8F08-29350E92D0E4.dita"><apiname>KErrNotSupported</apiname></xref>. </p> <p>For platform security, the code only allows the attribute
-security, the code only allows the attribute to be set if the current thread
+to be set if the current thread has been authorized to write system
-has been authorized to write system data. Otherwise, it returns <xref href="GUID-213DE05E-24F7-3E94-9B35-F4A72B3EBFD8.dita"><apiname>KErrPermissionDenied</apiname></xref>. </p> <p><b>Switch on and switch off operations</b> </p> <p>All of the HAL operations
+data. Otherwise, it returns <xref href="GUID-213DE05E-24F7-3E94-9B35-F4A72B3EBFD8.dita"><apiname>KErrPermissionDenied</apiname></xref>. </p> <p><b>Switch on and switch off operations</b> </p> <p>All of the HAL
-are seen to be synchronous by the user side. However there are some operations
+operations are seen to be synchronous by the user side. However there
-such as turning the display on and off which may need to be implemented asynchronously. </p> <p>The
+are some operations such as turning the display on and off which may
-display on/off code is implemented using synchronous kernel-side messages.
+need to be implemented asynchronously. </p> <p>The display on/off
-There is only one message per thread and the thread always blocks while a
+code is implemented using synchronous kernel-side messages. There
-message is outstanding. This means it is possible to make an asynchronous
+is only one message per thread and the thread always blocks while
-operation appear synchronous. </p> <p>When turning on the screen the kernel-side
+a message is outstanding. This means it is possible to make an asynchronous
-message is queued and this thread is blocked until the message is completed,
+operation appear synchronous. </p> <p>When turning on the screen the
-which happens when the display has been turned on. </p> <p>If a display needs
+kernel-side message is queued and this thread is blocked until the
-to be turned on and off truly asynchronously (for example, if millisecond
+message is completed, which happens when the display has been turned
-timer waits are required during the process of turning on the display), the
+on. </p> <p>If a display needs to be turned on and off truly asynchronously
-above functionality must be changed so that the complete occurs when the display
+(for example, if millisecond timer waits are required during the process
-is truly on. </p> <p><b>Accessing
+of turning on the display), the above functionality must be changed
-the video information structure</b> </p> <p>When any part of the <xref href="GUID-6A4FE3A3-2E5D-51BB-8272-5995586291E9.dita#GUID-6A4FE3A3-2E5D-51BB-8272-5995586291E9/GUID-57223C8C-0381-51AC-8E8A-771434136A5C">video information structure</xref> is read or written to, this must be done
+so that the complete occurs when the display is truly on. </p> <p><b>Accessing the video information structure</b> </p> <p>When any
-within a critical section to prevent potential collisions with other threads
+part of the <xref href="GUID-6A4FE3A3-2E5D-51BB-8272-5995586291E9.dita#GUID-6A4FE3A3-2E5D-51BB-8272-5995586291E9/GUID-57223C8C-0381-51AC-8E8A-771434136A5C">video information structure</xref> is read or written to, this must
-attempting to access the structure concurrently. A fast mutex is used to ensure
+be done within a critical section to prevent potential collisions
-that only one thread can access the video information at any one time, as
+with other threads attempting to access the structure concurrently.
-the code segment below shows. </p> <codeblock id="GUID-E30D9790-109C-541F-A534-C92CBD4E1706" xml:space="preserve">TInt DLcdPowerHandler::GetCurrentDisplayModeInfo(TVideoInfoV01&amp; aInfo, TBool aSecure)
+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. </p> <codeblock id="GUID-E30D9790-109C-541F-A534-C92CBD4E1706" xml:space="preserve">TInt DLcdPowerHandler::GetCurrentDisplayModeInfo(TVideoInfoV01&amp; aInfo, TBool aSecure)
 {
 __KTRACE_OPT(KEXTENSION,Kern::Printf("GetCurrentDisplayModeInfo"));
 NKern::FMWait(&amp;iLock);
 if (aSecure)
 aInfo = iSecureVideoInfo;
 aInfo = iVideoInfo;
 NKern::FMSignal(&amp;iLock);
 return KErrNone;
 }
 </codeblock> </section>
-<section id="GUID-04C06DAE-EE8E-4EE9-940F-807F82FBACD1"><title>Power handler implementation</title> <p>The <xref href="GUID-761AE02B-41A6-35EA-AA9F-0AEEFF67A6F7.dita"><apiname>DPowerHandler</apiname></xref> class
+<section id="GUID-04C06DAE-EE8E-4EE9-940F-807F82FBACD1"><title>Power
-defines the interface that the driver must implement to provide power handling
+handler implementation</title> <p>The <xref href="GUID-761AE02B-41A6-35EA-AA9F-0AEEFF67A6F7.dita"><apiname>DPowerHandler</apiname></xref> class defines the interface that the driver must implement to provide
-behaviour. For the template reference board, the LCD Extension defines and
+power handling behaviour. For the template reference board, the LCD
-implements the <codeph>DLcdPowerHandler</codeph> class derived from <xref href="GUID-761AE02B-41A6-35EA-AA9F-0AEEFF67A6F7.dita"><apiname>DPowerHandler</apiname></xref>. </p> <p> <b>Note</b>: </p> <ul>
+Extension defines and implements the <codeph>DLcdPowerHandler</codeph> class derived from <xref href="GUID-761AE02B-41A6-35EA-AA9F-0AEEFF67A6F7.dita"><apiname>DPowerHandler</apiname></xref>. </p> <p> <b>Note</b>: </p> <ul>
-<li id="GUID-32D95977-F46B-50E0-B575-BE7369C05F62"><p> <xref href="GUID-761AE02B-41A6-35EA-AA9F-0AEEFF67A6F7.dita#GUID-761AE02B-41A6-35EA-AA9F-0AEEFF67A6F7/GUID-578DB5FB-731D-36B2-A459-AAC7F250D726"><apiname>DPowerHandler::PowerDown()</apiname></xref> and <xref href="GUID-761AE02B-41A6-35EA-AA9F-0AEEFF67A6F7.dita#GUID-761AE02B-41A6-35EA-AA9F-0AEEFF67A6F7/GUID-DDC564B4-BD12-30E9-B04A-DBA6CFAF8743"><apiname>DPowerHandler::PowerUp()</apiname></xref>  </p> <p>These functions are called in the context of the thread that initiates
+<li id="GUID-32D95977-F46B-50E0-B575-BE7369C05F62"><p> <xref href="GUID-761AE02B-41A6-35EA-AA9F-0AEEFF67A6F7.dita#GUID-761AE02B-41A6-35EA-AA9F-0AEEFF67A6F7/GUID-578DB5FB-731D-36B2-A459-AAC7F250D726"><apiname>DPowerHandler::PowerDown()</apiname></xref> and <xref href="GUID-761AE02B-41A6-35EA-AA9F-0AEEFF67A6F7.dita#GUID-761AE02B-41A6-35EA-AA9F-0AEEFF67A6F7/GUID-DDC564B4-BD12-30E9-B04A-DBA6CFAF8743"><apiname>DPowerHandler::PowerUp()</apiname></xref>  </p> <p>These functions
-power down or power up, and synchronization is required, typically by means
+are called in the context of the thread that initiates power down
-of power up and power down DFCs. </p> </li>
+or power up, and synchronization is required, typically by means of
-<li id="GUID-7DC988A6-C60E-5951-9DD7-82DA129A8CB6"><p> <xref href="GUID-761AE02B-41A6-35EA-AA9F-0AEEFF67A6F7.dita#GUID-761AE02B-41A6-35EA-AA9F-0AEEFF67A6F7/GUID-038F9D7D-7DA0-3299-8AA2-85F175206887"><apiname>DPowerHandler::PowerUpLcd()</apiname></xref> and <xref href="GUID-761AE02B-41A6-35EA-AA9F-0AEEFF67A6F7.dita#GUID-761AE02B-41A6-35EA-AA9F-0AEEFF67A6F7/GUID-6EAF00D1-3CBA-3BC0-BAD9-7301EE5F9E12"><apiname>DPowerHandler::PowerDownLcd()</apiname></xref>  </p> <p>These functions generally queue DFCs which then call platform-specific
+power up and power down DFCs. </p> </li>
-functions to power the display up and down. </p> </li>
+<li id="GUID-7DC988A6-C60E-5951-9DD7-82DA129A8CB6"><p> <xref href="GUID-761AE02B-41A6-35EA-AA9F-0AEEFF67A6F7.dita#GUID-761AE02B-41A6-35EA-AA9F-0AEEFF67A6F7/GUID-038F9D7D-7DA0-3299-8AA2-85F175206887"><apiname>DPowerHandler::PowerUpLcd()</apiname></xref> and <xref href="GUID-761AE02B-41A6-35EA-AA9F-0AEEFF67A6F7.dita#GUID-761AE02B-41A6-35EA-AA9F-0AEEFF67A6F7/GUID-6EAF00D1-3CBA-3BC0-BAD9-7301EE5F9E12"><apiname>DPowerHandler::PowerDownLcd()</apiname></xref>  </p> <p>These
-<li id="GUID-51152EA7-C1A5-5AB3-8ACD-6FF6F16A255D"><p> <xref href="GUID-761AE02B-41A6-35EA-AA9F-0AEEFF67A6F7.dita#GUID-761AE02B-41A6-35EA-AA9F-0AEEFF67A6F7/GUID-BF62042B-FB7B-3D5B-8379-490FBA284A7A"><apiname>DPowerHandler::PowerUpDone()</apiname></xref> and <xref href="GUID-761AE02B-41A6-35EA-AA9F-0AEEFF67A6F7.dita#GUID-761AE02B-41A6-35EA-AA9F-0AEEFF67A6F7/GUID-EBE8CFF8-50BD-3AC3-A4C8-47094DA5674D"><apiname>DPowerHandler::PowerDownDone()</apiname></xref>  </p> <p>When power up or down is complete, the interface supplies a set
+functions generally queue DFCs which then call platform-specific functions
-of acknowledgment functions which must be called when the change of state
+to power the display up and down. </p> </li>
-has taken place. </p> </li>
+<li id="GUID-51152EA7-C1A5-5AB3-8ACD-6FF6F16A255D"><p> <xref href="GUID-761AE02B-41A6-35EA-AA9F-0AEEFF67A6F7.dita#GUID-761AE02B-41A6-35EA-AA9F-0AEEFF67A6F7/GUID-BF62042B-FB7B-3D5B-8379-490FBA284A7A"><apiname>DPowerHandler::PowerUpDone()</apiname></xref> and <xref href="GUID-761AE02B-41A6-35EA-AA9F-0AEEFF67A6F7.dita#GUID-761AE02B-41A6-35EA-AA9F-0AEEFF67A6F7/GUID-EBE8CFF8-50BD-3AC3-A4C8-47094DA5674D"><apiname>DPowerHandler::PowerDownDone()</apiname></xref>  </p> <p>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. </p> </li>
 </ul> </section>
 </conbody><related-links>
-<link href="GUID-0C3A4156-E5CF-55F9-91A0-A7961FDEE030.dita"><linktext>LCD Extension
+<link href="GUID-0C3A4156-E5CF-55F9-91A0-A7961FDEE030.dita"><linktext>LCD
-Architecture</linktext></link>
+Extension Architecture</linktext></link>
 <link href="GUID-8DF46A11-874A-52E5-9298-C083EA633BA0.dita"><linktext>Implementing
 Dynamic DSA                 Allocation</linktext></link>
 </related-links></concept>

changeset 14	578be2adaf3e
parent 5	f345bda72bc4