ROMBUILD

Capabilities

The +device driver framework provides a method to set and provide general information +to the user on the capabilities of the device driver. Typically, implementations +simply return the version number of the LDD. The device driver framework allows +both the LDD and PDD to set the device capabilities.

The user typically +calls the RDevice::GetCaps() function to retrieve the device +capabilities.

RDevice device; +r = device.Open(KDriverName); +if (r==KErrNone) + { + TPckgBuf<RExDriver::TUartCaps> caps; + device.GetCaps(caps); + ... + device.Close(); + }

Note: The device capabilities in this context +refer to the services that the driver can offer. Do not confuse this with +the idea of platform security capabilities, which are completely different.

HAL handlers

Symbian +platform provides a Hardware Abstraction Layer (HAL) interface that can be +used by device drivers and kernel extensions to provide information on device +specific attributes to user code. It comprises set and get interfaces used +by the Kernel and by user code. The attributes are divided into groups of +similar functionality, each of which is managed by a function called a HAL +handler.

Drivers must register any HAL handlers they provide, and +de-register them when unloading. Kernel extensions do not remove their HAL +handlers.

// Adds a HAL entry handling function for the specified group of +// HAL entries. +Kern::AddHalEntry(EHalGroupDisplay, &handler, this, 1); + +// Removes the HAL handler +TInt Kern::RemoveHalEntry(EHalGroupDisplay);

The arguments +to AddHalEntry() are the ID of a HAL group, a pointer to +the handler function and a pointer to a data structure that will be passed +to the handler function. The HAL handler function prototype is defined by THalFunc.

// Implementation of the kernel extension's exported function +EXPORT_C void TExClientInterface::MyExAPI() + { + … + ExController->MyExAPI(); + … + } + +LOCAL_C TInt halFunction(TAny* aPtr, TInt aFunction, TAny* a1, + TAny* a2) + { + DLcdPowerHandler* pH=(DLcdPowerHandler*)aPtr; + return pH->HalFunction(aFunction,a1,a2); + } + +TInt DLcdPowerHandler::HalFunction(TInt aFunction, TAny* a1, +TAny* a2) + { + ... + switch(aFunction) + { + ... + } + }

When the user calls HAL::Set() or HAL::Get(), +it invokes the corresponding halFunction() of the HAL function +group.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-2344B900-5EC5-4467-BEAD-AB55C88CE63E.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-2344B900-5EC5-4467-BEAD-AB55C88CE63E.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,134 @@ + + + + + +Stack +Implementation GuideHow to implement the platform-specific class for an SDIO stack +of an SDIO-based hardware component. +

The stack is provided by the DSDIOStack class. The developers +porting the SDIO Controller must derive the DSDIOStack class +and implement three platform-specific functions: IssueMMCCommandSM(), EnableSDIOInterrupt() and MaxBlockSize().

The following sections describe how to implement these functions in the DMySdioStack class +derived from DSIOStack.

Hardware registers

The DMySdioStack class +needs to have access to the values and offsets of the SDIO configuration registers. +Refer to the platform documentation and declare appropriate constants in the +header file of the stack class.

IssueMMCCommandSM()

If +you have not declared it already, declare the following function in the definition +of DMySdioStack:TMMCErr IssueMMCCommandSM();

DSDIOStack::IssueMMCCommandSM() handles the commands to the bus and must be extended to support the SDIO +protocol. See also DSDStack::IssueMMCCommandsSM().

Rely on the platform documentation to perform the operations and +update appropriate hardware registers when you intercept the following commands:

IO_OP_COND (CMD5)
IO_RW_DIRECT (CMD52)
IO_RW_EXTENDED (CMD53)

You should also handle the additional IO_SEND_OP_COND (R4) +and IO_RW_DIRECT (R5) responses.

In the following example, +the hypothetical hardware platform has two requirements, which are implemented +by the IssueMMCCommandSM() function. The function disables +the CRC7 check when receiving an R4 response to an CMD5 command, and disables +the SDIO interrupt before issuing a CMD52 command.void DMySdioStack::IssueMMCCommandSM() + { + TMMCCommandDesc& cmd = Command(); + ... + // CMD5 + // Disable the CRC7 check for R4 responses + if (cmd.iCommand == ECmd5) + { + // Clear the MMC_CRC7_R4_ENABLE bit + // MMC_SDIO_REG_SLOT0 is a 32-bit hardware register for SDIO in slot 0 + AsspRegister::Modify32(MMC_SDIO_REG_SLOT0, MMC_CRC7_R4_ENABLE, 0); + } + else + { + // Set the MMC_CRC7_R4_ENABLE bit + AsspRegister::Modify32(MMC_SDIO_REG_SLOT0, 0, MMC_CRC7_R4_ENABLE); + } + + // CMD52 + // Disable SDIO interrupts for CMD 52 + if (cmd.iCommand == ECmd52) + { + EnableSDIOInterrupt(EFalse); + } + ... + } +

As the SDIO Controller is instantiated at run-time, the +memory used to support the SDIO transfer mechanisms must be allocated dynamically. +Therefore, you can use two different types of memory and of data transfer:

Programmatic input/output using virtual memory
DMA using physically-allocated DChunk objects.

The KMMCCmdFlagDMARamValid flag of the TMMCCommandDesc object +indicates which kind of memory transfer to use.

If you use the Programmatic I/O method, you need to queue pending data transfers +while you handle hardware interrupts. Your platform's documentation specifies +which interrupts may be received during transfers.

EnableSDIOInterrupt()

Declare +the following function in the definition of DMySdioStack:virtual void EnableSDIOInterrupt(TBool aEnable);

DSDIOStack::EnableSDIOInterrupt() enables or disables +the SDIO interrupt.

The following example is a typical implementation +of EnableSDIOInterrupt():void DMySdioStack::EnableSDIOInterrupt(TBool aEnable) + { + if (aEnable) + { + // Set the Interrupt Enable Master Bit + // MMC_SDIO_REG_SLOT0 is a 32-bit hardware register for SDIO in slot 0 + AsspRegister:: Modify32(MMC_SDIO_REG_SLOT0, SDIO_IENM, 0); + } + else + { + // Set the Interrupt Enable Master Bit + AsspRegister:: Modify32(MMC_SDIO_REG_SLOT0, 0, SDIO_IENM); + } + } +

You must also ensure that your interrupt handler checks +the SDIO interrupt register and the card slot before forwarding the interrupt +to the stack. If checking the card slot is likely to take too long, +use a DFC (Delayed Function Call) for the interrupt handler to preserve real-time +performance.

The following example illustrates how to implement +this aspect of the interrupt handler:void DMySdioInterrupt::Service(TAny* aSelf) + { + ... + // Get access to the stack + DPlatMMCStack* stack = (reinterpret_cast<DMySdioInterrupt*>(aSelf))->Stack(); + + // MMC_SDIO_REG_SLOT0 is a 32-bit hardware register for SDIO in slot 0 + TInt32 sdioReg = AsspRegister::Read32(MMC_SDIO_REG_SLOT0); + // Test for the SDIO interrupt + if (sdioReg & KMMC_SDIO_IntPending) + { + // Trigger the PIL’s interrupt handler for slot 0 + stack->HandleSDIOInterrupt(0); + return; + } + + // MMC_SDIO_REG_SLOT1 is a 32-bit hardware register for SDIO in slot 1 + sdioReg = AsspRegister::Read32(MMC_SDIO_REG_SLOT1); + // Test for the SDIO interrupt + if (sdioReg & KMMC_SDIO_IntPending) + { + // Trigger the PIL’s interrupt handler for slot 1 + stack->HandleSDIOInterrupt(1); + return; + } + + ... + } +

MaxBlockSize()

Declare +the following function in the definition of DMySdioStack:virtual TUint32 MaxBlockSize() const;

DSDIOStack::MaxBlockSize() returns the maximum block size in bytes +that can be transferred on the SDIO bus. Extended read/write commands require +this information.

In the SD protocol, the block size must be a power +of two. SDIO does not have the same constraint and the block size can be anything +between 1 and 2048.

The following example is a typical implementation +of MaxBlockSize():TUint32 DMySdioStack::MaxBlockSize() const + { + return(512); + } +

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-2380FDDE-5489-5B1C-87BB-1FD882E385D2.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-2380FDDE-5489-5B1C-87BB-1FD882E385D2.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,238 @@ + + + + + +Migration +Tutorial: Direct Memory AddressingTo handle direct memory addressing, you must to make the following +changes to your code. +

If a media driver uses a data transfer mechanism like DMA, +data transfer can be faster if the media driver knows that an address passed +in an I/O request is a physical address. This is known as direct memory addressing.

Changes to registration
Changes to request handling
Issues about physical addresses

Changes to +registration

If the media driver code can handle physical addresses, +it must tell the local media subsystem. This process is called registration. +The media driver calls LocDrv::RegisterDmaDevice() to register +as part of the media +driver initialisation process. The media driver calls RegisterDmaDevice() after +the media driver has registered +with the local media subsystem.

After the call to LocDrv::RegisterDmaDevice(), +the local media subsystem will test if the address in an I/O request is a +physical address or a virtual address. The local media subsystem extracts +the information that the media driver requires. The media driver gets this +information through calls to the functions:

TLocDrvRequest::IsPhysicalAddress().
TLocDrvRequest::GetNextPhysicalAddress().

A TLocDrvRequest object represents an I/O request +and is passed to the media driver.

There are three pieces of information +that the local media subsystem needs from the media driver when the media +driver registers:

The minimum number +of bytes that the media device can transfer. For example, the architecture +of some memory card types requires data transfer in blocks of 512 bytes. The +local media subsystem can not support I/O requests for physical addresses +where the length of the data is smaller than this minimum number. This limit +prevents accidental access of the data outside the limits of the request.
The maximum number +of bytes that the media driver can transfer in one burst. This value depends +on the hardware. For eaxample,DMA +Framework has limits that depend on the DMA controller.
The alignment of +memory that the DMA controller requires. For example: a DMA controller +might require 2 byte (word or 16 bit) alignment or 4 byte (double word or +32 bit) alignment. For 2 byte alignment, specify 2; for 4 byte alignment specify +4 etc. The local media subsystem can not support I/O requests for physical +addresses that are not aligned according to this value.

You get all of this information from the documentation for the platform.

This +example code extends the code shown in the section Media +driver initialisation before the system is initialised. It adds a call +to LocDrv::RegisterDmaDevice(). This call follows registration +of the media driver with the local media subsystem.

DECLARE_STANDARD_EXTENSION() + { + TInt r=KErrNoMemory; + DPrimaryMediaBase* pM=new DPrimaryMediaBase; + if (pM) + {//…Required here for Asynchronous creation (if supported) + pM->iDfcQ = &MyDfcQ; + + // Perform registration here + r = LocDrv::RegisterMediaDevice(MEDIA_DEVICE_TYPE, + MEDIA_DRIVECOUNT, + &IMediaDriveNumbers[0], + pM,MEDIA_NUMMEDIA,KMediaDriveName + ); + if ® != KErrNone) + { + return r; + } + + // Register support for physical addressing. + // + // Note : in practice the values passed to RegisterDmaDevice() would be + // either symbolic constants or functions that return values. If the + // media driver is split into platform independent and platform dependent + // layers, and this code is in the independent layer, then you will need + // functions in the dependent layer to provide these values. + r = LocDrv::RegisterDmaDevice(pM, + 512, // Block Addressing 512 Bytes + 1024, // 1024 Byte address range + 2 ); // 2 Byte alignment + if ® != KErrNone) + { + return r; + } + ... + } + return®); + } +

Changes to +request handling

To use physical addreses, you need to make changes +to the code that deals with ERead and EWrite requests +in your implementation of the DMediaDriver::Request() function. This section discusses the issues with ERead requests, +but the principles apply to EWrite requests.

There +are a number of points to consider:

Check if the address is physical

Call TLocDrvRequest::IsPhysicalAddress() to +test if the address passed is a physical address. For example, for a ERead request:

... + // iReadReq points to a TLocDrvRequest object + ... + iMediaStartPos = iReadReq->Pos(); + iTotalLength = I64LOW(iReadReq->Length()); + iDoPhysicalAddress = iReadReq->IsPhysicalAddress(); + if(iDoPhysicalAddress) + { + ..< Physical address memory code >.. + } + else + { + ...< Virtual address memory code >...

Physical address code

If you want to use the physical address, +you need to get the physical address and the length of contiguous memory at +this location. Call TLocDrvRequest::GetNextPhysicalAddress() to +get the physical address and the length of physically contiguous memory. The +length of physically contiguous memory can be smaller than the length supplied +in the read request, because physical memory can be fragmented into a number +of small blocks. If the length is smaller than the length supplied in the +read or write request, you call TLocDrvRequest::GetNextPhysicalAddress() again +to get the address of the next physically contiguous block of memory. You +repeat this operation until the read request is complete. For example, for +a ERead request:

... + // iReadReq points to a TLocDrvRequest object + ... + TPhysAddr physAddr; + TInt physLength; + TInt err = KErrNone; + err = iReadReq->GetNextPhysicalAddress(physAddr, physLength); + if(err == KErrNone) + { + if (physLength < iTotalLength) + { + // Memory is fragmented, note remainder. You will need + // to use this code again using the remainder value. + iRemaining = iTotalLength – physLength; + iTotalLength -= physLength; + } + + // Start data transfer into the current physically + // contiguous block of physical memory. + DoDataTransfer(iMediaStartPos, physLength, physAddr); + ... + } +

If you do not want to deal with fragmented physical memory, +you can use your original code.

Virtual to physical address translation

Your code must not +perform a virtual to physical address translation when it deals with physical +memory. For example:

void DMMCRxDmaHelp::ChannelTransfer(const SDmaPseudoDes& aDes) + { + … + TPhysAddr dest; + + if (iCurrentReq->IsPhysicalAddress()) + dest = (TPhysAddr) aDes.iDest; + else + dest = Epoc::LinearToPhysical(aDes.iDest); + TPlatDma::SetDMARegister(KHoDMA_CDSA(iChno), dest); + … + }

Eliminate inter-process copy

You must change your code to +remove calls to TLocDrvRequest::WriteRemote(). For ERead requests, +data for transfer is already at the physical address. For example:

if (!iCurrentReq->IsPhysicalAddress()) + { + if( (id == DMediaPagingDevice::ERomPageInRequest)|| + (id == DMediaPagingDevice::ECodePageInRequest) ) + { + r = iCurrentReq->WriteToPageHandler((TUint8 *)(& iBufPtr [0]), len, usrOfst); + } + else if(id==DLocalDrive::ERead) + { + r = iCurrentReq->WriteRemote(&iBufPtr,usrOfst); + } + }

The same logic applies to EWrite requests. +You need to remove calls to TLocDrvRequest::ReadRemote().

Test your changes

You are recommended to run regression tests +on your changed code to makes sure that the media driver operates correctly.

Issues about +physical addresses

If the media driver can use physical addresses, +you need to be aware of a number of issues.

The address scheme used by the hardware

All media devices +have a minimum number of bytes that they can transfer. For example, the architecture +of some memory card types requires data transfer in blocks of 512 bytes. To +read one byte from this type of media device, the media driver must read a +block of 512 bytes and extract the byte from the block. To write one byte +to a media device, the media driver must read a block of 512 bytes, change +the content of the byte, and write the block to the media device.

Data transfer smaller than the minimum size

If the local +media subsystem receives a request to transfer data with a length smaller +than the minimum transfer size, the local media subsystem does not make a +physical address available to the media driver. A call to TLocDrvRequest::IsPhysicalAddress() returns +false. It is considered unsafe to give access to the physical data surrounding +the requested memory location.

Data transfer not aligned to the media device block boundary

If +the local media subsystem receives a request to transfer data, and the address +on the media device is not aligned to the media device block boundary, +you need to adopt the technique suggested below. The local media subsystem +will make the physical address available to the media driver. A call to TLocDrvRequest::IsPhysicalAddress() returns +true.

Consider the following case. A request has been made to read +1024 bytes from a media device that has a block size of 512 bytes. The 1024 +bytes start at offset +256 on the media device.

+ +

To get the first 256 bytes, you must read the first block of 512 +bytes from the media device. This can corrupt the physical memory passed in +the I/O request. The solution is to read the first block from the media device +into an intermediate buffer. Copy the 256 bytes from that buffer into the +physical memory passed in the I/O request.

To get the last 256 bytes, +you must read the third block of 512 bytes from the media device into the +intermediate buffer. Copy the 256 bytes from that buffer into the correct +position in the physical memory passed in the I/O request.

The middle +512 bytes are aligned on the media device block boundary. The media driver +can read this data into the correct position in the physical memory passed +in the I/O request.

Scatter/Gather DMA controllers

DMA controllers can support +the Scatter/Gather mode of operation. Each request in this mode of operation +consists of a set of smaller requests chained together. This chain of requests +is called the Scatter/Gather list. Each item in the list consists of a physical +address and a length.

Use TLocDrvRequest::GetNextPhysicalAddress() to +help you populate the Scatter/Gather list.

The following code fragment +shows how you do this. The example assumes that the DMA controller supports +a Scatter/Gather list with an unlimited number of entries. In practice, the +number of entries in the list is finite.

TPhysAddr physAddr; + TInt physLength; + TInt err = KErrNone; + + while (iRemaining > 0) + { + err = iCurrentReq->GetNextPhysicalAddress(physAddr, physLength); + if(err != KErrNone) + return err; + + iRemaining -= physLength; + PopulateScatterGatherList(physAddr, physLength); + } + + return DoDataTransfer(pos, length);

+MMC Porting +Implementation Tutorial +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-240EE926-BAFC-4A53-A8F8-D559BA7BB672.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-240EE926-BAFC-4A53-A8F8-D559BA7BB672.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,29 @@ + + + + + +DMA Client Interface Quick StartBasic steps to use the Client interface of the DMA framework. +

The DMA framework provides an interface for clients, such as device +drivers, to perform data transfers.

Basic steps

The following are the basic steps to +use the DMA framework:

The DMA Technology Guide describes the basic concepts of the DMA framework.
The DMA Device Driver +Guide explains the concepts of device driver guide.
The DMA Client Interface +Guide explains the interface and how to use it.
The DMA Testing Guide provides the location of the test application.

+DMA +Tutorials Overview +DMA +Hardware Interface +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-2490DA46-A57B-4DFD-AA9C-2004D58486E3.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-2490DA46-A57B-4DFD-AA9C-2004D58486E3.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,16 @@ + + + + + +Interrupt Testing GuideDescribes the test suites required to test the platform +service implementation. +

There is no specific test suite available for the Interrupt platform +service at the moment.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-2559E3F7-314B-5DCC-A7FE-A08162A89721.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-2559E3F7-314B-5DCC-A7FE-A08162A89721.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,56 @@ + + + + + +Local +Media Subsystem OverviewProvides the logical device driver for the internal and removable +storage media on a phone. +

Purpose

The local media sub-system allows the Symbian +platform file system and other programs to communicate with local media devices.

Required background

The local media sub-system +requires an understanding of the Symbian platform file system and local media +devices.

Key concepts and terms

local drive: A media drive mounted within the phone.

Architecture

The TBusLocalDrive class +provides an interface to the local media sub-system. Each instance of this +class represents a channel of communication with a local drive. To establish +a channel a client connects an instance of the class to a specified drive. +The file server contains 16 instances of TBusLocalDrive, +one for each local drive. Programs other than the file server may also create +instances to access a local drive. Drives are abstracted by the TDrive class.

Local Media Sub-system Summary

The local media +subsystem provides the following:

Local media LDD

elocd.ldd

The +kernel-side logical device driver which implements communication between physical +devices and applications which use them.

Typical uses

The TBusLocalDrive class +is used to connect to and disconnect from local drives, to read to and write +from them, to provide information about the capabilities of the drives, to +format them, and to mount and remount drives on specified media drivers.

Local +media subsystem:

Manages device connections
Manages data transfer
Handles notifications +and device configuration.

+ +File Server + +File Systems + +Media Drivers +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-25941CD2-D124-55DD-8716-ACC93E3F1D6C.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-25941CD2-D124-55DD-8716-ACC93E3F1D6C.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,285 @@ + + + + + +Bootstrap Source MacrosDescribes the macros used in source files. +

This set of macros is available for use in source files, but not in platform +specific configuration header files. Their definitions are obtained by including os/kernelhwsrv/kernel/eka/include/kernel/arm/bootcpu.inc.

General macros

GETCPSR

GETCPSR reg

Reads +the CPSR into the specified ARM general register reg.

This +macro should be used in preference to MRS instructions to avoid problems related +to syntax incompatibility between different assembler versions.

CGETCPSR

CGETCPSR reg, cc

Reads +the CPSR into the specified ARM general register reg. This +is conditionally executed using cc as the execution condition.

This +macro should be used in preference to MRS instructions to avoid problems related +to syntax incompatibility between different assembler versions.

GETSPSR

GETSPSR reg

Reads +the SPSR into the specified ARM general register reg.

This +macro should be used in preference to MRS instructions to avoid problems related +to syntax incompatibility between different assembler versions.

CGETSPSR

CGETSPSR reg, cc

Reads +the SPSR into the specified ARM general register reg. This +is conditionally executed using cc as the execution condition.

This +macro should be used in preference to MRS instructions to avoid problems related +to syntax incompatibility between different assembler versions.

SETCPSR

SETCPSR reg

Writes +the entire (all 32 bits) CPSR from the specified ARM general register reg.

This +macro should be used in preference to MRS instructions to avoid problems related +to syntax incompatibility between different assembler versions.

CSETCPSR

CSETCPSR reg, cc

Writes +the entire (all 32 bits) CPSR from the specified ARM general register reg. +This is conditionally executed using cc as the execution +condition.

This macro should be used in preference to MRS instructions +to avoid problems related to syntax incompatibility between different assembler +versions.

SETSPSR

SETSPSR reg

Writes +the entire (all 32 bits) SPSR from the specified ARM general register reg.

This +macro should be used in preference to MRS instructions to avoid problems related +to syntax incompatibility between different assembler versions.

CSETSPSR

CSETSPSR reg, cc

Writes +the entire (all 32 bits) SPSR from the specified ARM general register reg. +This is conditionally executed using cc as the execution +condition.

This macro should be used in preference to MRS instructions +to avoid problems related to syntax incompatibility between different assembler +versions.

BOOTCALL

BOOTCALL call_numbe

Calls +the specified function via the boot table. call_number should +be one of the BTF_* values in the TBootTableEntry enumeration, +defined in os/kernelhwsrv/kernel/eka/include/kernel/arm/bootdefs.h.

The +macro is transparent; the function is entered with all registers and flags +having the same values as immediately before the macro.

GETPARAM

GETPARAM pnum, default

Retrieves +the parameter with number pnum from the boot parameter table, +and returns its value in R0. If the parameter is not present +in the table, then R0 is loaded with value default.

See +the description of BTF_Params for +more information on the boot parameter table.

GETMPARAM

GETMPARAM pnum

Retrieves +the parameter with number pnum from the boot parameter table, +and returns its value in R0. If the parameter is not present +in the table, then the macro faults the system.

See the description +of BTF_Params for +more information on the boot parameter table.

FAULT

FAULT cc

Faults +the system if condition cc is true. The condition is a standard +ARM condition code.

BTP_ENTRY

Declares +MMU permissions and cache attributes. The macro takes a variable number of +arguments depending on the processor in use.

For ARM architecture 6 +CPUs:

BTP_ENTRY $domain, $perm, $cache, $execute, $global, $P, $S

For +XScale CPUs:

BTP_ENTRY $domain, $perm, $cache, $P

For +other CPUs:

BTP_ENTRY $domain, $perm, $cache + + + +

$domain

ARM domain number 0-15. In general only one memory-model-dependent +value is used here and the symbol CLIENT_DOMAIN specifies +this.

+ + +

$perm

Permissions for mapping.

For architecture 6 CPUs, use one +of PERM_NONO, PERM_RWNO, PERM_RWRO, PERM_RWRW, PERM_RONO, PERM_RORO.

For other CPUs, use one of PERM_RORO, PERM_RWNO, PERM_RWRO, PERM_RWRW.

In each of these names the first pair of letters +refers to supervisor, and the second pair to user access, so PERM_RWNO means +supervisor read/write, user no access.

+ + +

$cache

Cache attributes for mapping. These are processor dependent - see +the CACHE_* macros in os/kernelhwsrv/kernel/eka/include/kernel/arm/bootcpu.inc.

+ + +

$execute

ARM architecture 6 only. Determines whether code can be executed +from the mapped region; either BTPERM_EXECUTE or BTPERM_NO_EXECUTE.

+ + +

$global

ARM architecture 6 only. Determines whether the mapped region is +ASID specific (local) or non-ASID specific (global); either BTPERM_LOCAL or BTPERM_GLOBAL.

+ + +

ARM architecture 6 and XScale only. Determines whether or not ECC +should be used on the mapped region (assuming hardware supports ECC); either BTPERM_ECC or BTPERM_NON_ECC.

+ + +

ARM architecture 6 only. Determines whether the mapped region is +shared between multiple CPUs or not; either BTPERM_SHARED or BTPERM_NON_SHARED.

+ + + +

ROM_BANK

ROM_BANK PHYS, SIZE, LIN, WIDTH, TYPE, RAND, SEQ

Declares +an XIP ROM bank entry.

+ + + +

PHYS

The physical base address of the ROM bank.

+ + +

SIZE

The size of the ROM bank.

+ + +

LIN

Linear address override (usually 0).

+ + +

WIDTH

Bus width. One of: ROM_WIDTH_8, ROM_WIDTH_16 or ROM_WIDTH_32

+ + +

TYPE

The ROM type; see the TRomType enumeration.

+ + +

RAND

Random access speed.

+ + +

SEQ

Sequential access speed.

+ + + +

See also BTF_RomBanks in Boot Table Functions.

Macros for +declaring I/O mappings

HW_MAPPING

HW_MAPPING PHYS,SIZE,MULT

Defines +an I/O mapping using the standard permissions and cache attributes for I/O +mappings, i.e. those defined for the BTP_Hw boot table entry. +See Boot Table MMU +Permission and Cache Attribute Definitions.

+ + + +

PHYS

Physical base address.

+ + +

SIZE

Size of the mapping.

+ + +

MULT

Granularity +of the I/O mapping (below).

+ + + +

See also:

Determining the linear address (below).
BTF_HwBanks in Boot +Table Functions.

HW_MAPPING_EXT2

HW_MAPPING_EXT2 PHYS,SIZE,MULT,LIN

+ + + +

PHYS

Physical base address.

+ + +

SIZE

Size of the mapping.

+ + +

MULT

Granularity +of the I/O mapping (below).

+ + +

LIN

Linear address.

+ + + +

See also BTF_HwBanks in Boot Table Functions.

HW_MAPPING_EXT3

HW_MAPPING_EXT3 PHYS,SIZE,MULT,LIN

Defines +an I/O mapping using the permissions and cache attributes defined by a BTP_ENTRY macro +that immediately follows this macro. See Boot +Table MMU Permission and Cache Attribute Definitions.

+ + + +

PHYS

Physical base address.

+ + +

SIZE

Size of the mapping.

+ + +

MULT

Granularity +of the I/O mapping (below).

+ + +

LIN

Linear address.

+ + + +

See also BTF_HwBanks in Boot Table Functions..

Granularity of the I/O mapping

The +granularity of the I/O mapping is defined by the MULT parameter +of the I/O mapping macros: HW_MAPPING, HW_MAPPING_EXT, HW_MAPPING_EXT2 and HW_MAPPING_EXT3.

The MULT parameter specifies the granularity of the mapping. It takes one of the +following values:

HW_MULT_4K use +4K pages. The PHYS and LIN parameters must +be multiples of 4K.
HW_MULT_64K use +64K pages. The PHYS and LIN parameters must +be multiples of 64K.
HW_MULT_1M use +1M sections. The PHYS and LIN parameters +must be multiples of 1M.

In each case the unit in which the SIZE parameter +is specified is MULT, that is to say the actual mapping size +in bytes is SIZE*MULT. For example:

HW_MAPPING 0x80000000, 1, HW_MULT_4K +HW_MAPPING 0x80010000, 3, HW_MULT_64K

declares a mapping +of size 4K starting at physical address 0x80000000 followed +by a mapping of 192K in 64K pages starting at physical address 0x80010000.

Determining the linear address

For +those macros that don't specify a linear address: HW_MAPPING and HW_MAPPING_EXT, +it is determined as follows:

On the direct memory +model, it is equal to the physical address.
On the moving memory +model and the multiple memory model, the first such mapping is placed at KPrimaryIOBase (0x63000000 on +the moving model, 0xC3000000 on the multiple model). Each +mapping first rounds the linear address counter up to the next multiple of MULT before +making the mapping, then increments it by SIZE*MULT after +making it.

For example, on the moving memory model, the following mappings would +have linear addresses 0x63000000, 0x63002000, 0x63010000, 0x63020000 and 0x63100000 respectively:

HW_MAPPING 0x80000000, 2, HW_MULT_4K +HW_MAPPING 0x80010000, 1, HW_MULT_4K +HW_MAPPING 0x80100000, 1, HW_MULT_64K +HW_MAPPING 0x80200000, 1, HW_MULT_4K +HW_MAPPING 0x90000000, 1, HW_MULT_1M

For the direct memory +model, all I/O mappings required by the system must be listed here since it +is not possible to make further mappings once the kernel is running.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-2607CCFA-3D24-4716-A447-74304F861C44.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-2607CCFA-3D24-4716-A447-74304F861C44.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,490 @@ + + + + + +DSDIORegisterInterface +Class TutorialDescribes the DSDIORegisterInterface API class. +

Description

This +class provides the main client API between the SDIO implementation and the +rest of the system.

For portability reasons, it is recommended that +this class is allocated on behalf of the client by the appropriate function +class after the client has been registered with the SDIO function.

Unless +stated otherwise, all the register offsets are defined to be relative to offsets +within the SDIO function.

+ + + +

Header file

regifc.h

+ + +

Source code file

regifc.cpp

+ + +

Required libraries

EPBUSSDIO

+ + +

Class declaration

class DSDIORegisterInterface: public DSDIOSession

+ + + +

Read8()

The +function declaration for the Read8() method is:

IMPORT_C TInt Read8(TUint32 aReg, TUint8* aReadDataP);

Description

This method reads a single 8 bit value from the +specified register.

Parameters

+ + + +

TUint32 aReq

The Source register address.

+ + +

TUint8* aReadDataP

The location of the byte to read into.

+ + + +

Return value

+ + + +

TInt

The result of the operation. KErrNone if the operation was successful, +otherwise a system wide error code.

+ + + +

Write8()

The +function declaration for the Write8() method is:

IMPORT_C TInt Write8(TUint32 aReg, TUint8 aWriteVal);

Description

This method writes a single 8 bit value to the +register specified.

Parameters

+ + + +

TUint32 aReg

The destination register address.

+ + +

TUint8 aWriteVal

The 8 bit value to be written.

+ + + +

Return value

+ + + +

TInt

The result of the operation. KErrNone if the operation +was successful, otherwise a system wide error code.

+ + + +

Modify8()

The +function declaration for the Modify8() method is:

IMPORT_C TInt Modify8(TUint32 aReg, TUint8 aSet, TUint8 aClr); +

Description

This method performs a bitwise read-modify-write +operation on the specified register.

Parameters

+ + + +

TUint32 aReg

The destination register address.

+ + +

TUint8 aSet

A bitmask of the values to be set.

+ + +

TUint8 aClr

A bitmask of the values to be cleared.

+ + + +

Return value

+ + + +

TInt

The result of the operation. KErrNone if the operation +was successful, otherwise a system wide error code.

+ + + +

Modify8() with +read-after-write

The function declaration for the Modify8() with +read-after-write method is:

IMPORT_C TInt Modify8(TUint32 aReg, TUint8 aSet, TUint8 aClr, TUint8* aReadDataP);

Description

This method performs a bitwise read-modify-write operation on the +specified register.

Parameters

+ + + +

TUint32 aReg

The destination register address.

+ + +

TUint8 aSet

A bitmask of the values to be set.

+ + +

TUint8 aClr

A bitmask of the values to be cleared.

+ + +

TUint8* aReadDataP

The address of the byte to read into. The result of the operation +is stored in this buffer.

+ + + +

Return value

+ + + +

TInt

The result of the operation. KErrNone if the operation +was successful, otherwise a system wide error code.

+ + + +

ReadMultiple8()

The +function declaration for the ReadMultiple8() method is:

IMPORT_C TInt ReadMultiple8(TUint32 aReg, TUint8* aDataP, TUint32 aLen); +

Description

This method reads the specified number +of bytes starting at the specified register offset.

Parameters

+ + + +

TUint32 aReg

The source register address.

+ + +

TUint8* aDataP

The start address of the destination buffer.

+ + +

TUint32 aLen

The number of bytes to be read.

+ + + +

Return value

+ + + +

TInt

The result of the operation. KErrNone if the operation +was successful, otherwise a system wide error code.

+ + + +

ReadMultiple8() +with auto-increment

The function declaration for the ReadMultiple8() +method with auto-increment is:

IMPORT_C TInt ReadMultiple8(TUint32 aReg, TUint8* aDataP, TUint32 aLen, TBool aAutoInc); +

Description

This method reads the specified number +of bytes starting at the specified register offset.

Parameters

+ + + +

TUint32 aReg

The source register address.

+ + +

TUint8* aDataP

The start address of the destination buffer.

+ + +

TUint32 aLen

The number of bytes that are to be read.

+ + +

TBool aAutoInc

Enable or disable the auto-increment functionality.

+ + + +

Return value

+ + + +

TInt

The result of the operation. KErrNone if the operation +was successful, otherwise a system wide error code.

+ + + +

ReadMultiple8() +using shared chunks

The function declaration for the ReadMultiple8()method +using shared chunks is:

IMPORT_C TInt ReadMultiple8(TUint32 aReg, DChunk* aChunk, TUint32 aOffset, TUint32 aLen); +

Description

This method reads the specified number +of bytes starting at the specified register offset.

Parameters

+ + + +

TUint32 aReg

The source register address.

+ + +

DChunk* aChunk

The chunk that hosts the destination buffer.

+ + +

TUint32 aOffset

The offset from the start of the chunk to the start of the destination +buffer.

+ + +

TUint32 aLen

The number of bytes to be read.

+ + + +

Return value

+ + + +

TInt

The result of the operation. KErrNone if the operation +was successful, otherwise a system wide error code.

+ + + +

ReadMultiple8() +with auto-increment using shared chunks

The function declaration +for the ReadMultiple8() method with auto-increment using +shared chunks is:

IMPORT_C TInt ReadMultiple8(TUint32 aReg, DChunk* aChunk, TUint32 aOffset, TUint32 aLen, TBool aAutoInc);

Description

This method reads the specified number of bytes +starting at the specified register offset.

Parameters

+ + + +

TUint32 aReg

The source register address.

+ + +

DChunk* aChunk

The chunk that hosts the destination buffer.

+ + +

TUint32 aOffset

The offset from the start of the chunk to the start of the destination +buffer.

+ + +

TUint32 aLen

The number of bytes to be read.

+ + +

TBool aAutoInc

Enable or disable the auto-increment functionality.

+ + + +

Return value

+ + + +

TInt

The result of the operation. KErrNone if the operation +was successful, otherwise a system wide error code.

+ + + +

WriteMultiple8()

The +function declaration for the WriteMultiple8() method is:

IMPORT_C TInt WriteMultiple8(TUint32 aReg, TUint8* aDataP, TUint32 aLen); +

Description

This method writes the specified length +of bytes starting at the specified register.

Parameters

+ + + +

TUint32 aReg

The destination register address.

+ + +

TUint8* aDataP

The start address of the source buffer.

+ + +

TUint32 aLen

The number of bytes to be written.

+ + + +

Return value

+ + + +

TInt

The result of the operation. KErrNone if the operation +was successful, otherwise a system wide error code.

+ + + +

WriteMultiple8() +with auto-increment

The function declaration for the WriteMultiple8() method +with auto-increment is:

IMPORT_C TInt WriteMultiple8(TUint32 aReg, TUint8* aDataP, TUint32 aLen, TBool aAutoInc); +

Description

This method writes the specified length +of bytes starting at the specified register.

Parameters

+ + + +

TUint32 aReg

The destination register address.

+ + +

TUint8* aDataP

The start address of the source buffer.

+ + +

TUint32 aLen

The number of bytes to be written.

+ + +

TBool aAutoInc

Enable or disable the auto-increment functionality.

+ + + +

Return value

+ + + +

TInt

The result of the operation. KErrNone if the operation +was successful, otherwise a system wide error code.

+ + + +

WriteMultiple8() +using shared chunks

The function declaration for the WriteMultiple8() method +using shared chunks is:

IMPORT_C TInt WriteMultiple8(TUint32 aReg, DChunk* aChunk, TUint32 aOffset, TUint32 aLen); +

Description

This method writes the specified length +of bytes starting at the specified register.

Parameters

+ + + +

TUint32 aReg

The destination register address.

+ + +

DChunk* aChunk

The chunk that hosts the source buffer.

+ + +

TUint32 aOffset

The offset from the start of the chunk and the start address of +the source buffer.

+ + +

TUint32 aLen

The number of bytes to be written.

+ + + +

Return value

+ + + +

TInt

The result of the operation. KErrNone if the operation +was successful, otherwise a system wide error code.

+ + + +

WriteMultiple8( +) with auto-increment using shared chunks

The function declaration +for the WriteMultiple8() method with autoincrement using +shared chunks is:

IMPORT_C TInt WriteMultiple8(TUint32 aReg, DChunk* aChunk, TUint32 aOffset, TUint32 aLen, TBool aAutoInc);

Description

This method writes the specified length of bytes +starting at the specified register.

Parameters

+ + + +

TUint32 aReg

The destination register address.

+ + +

DChunk* aChunk

The chunk that hosts the source buffer.

+ + +

TUint32 aOffset

The offset from the start of the chunk and the start address of +the source buffer.

+ + +

TUint32 aLen

The number of bytes to be written.

+ + +

TBool aAutoInc

Enable or disable the auto-increment functionality.

+ + + +

Return value

+ + + +

TInt

The result of the operation. KErrNone if the operation +was successful, otherwise a system wide error code.

+ + + +

SetAsync()

The +function declaration for the SetAsync() method is:

IMPORT_C TBool SetAsync(TMMCCallBack& aCallback); +

Description

This function allows the user to disable +the synchronous nature of the DSDIORegInterface class, by using the specified +callback function to indicate the completion of an operation.

Parameters

+ + + +

TMMCCallback& aCallback

Reference to the callback function.

+ + + +

Return value

+ + + +

TBool

The result of the operation. KErrNone if the operation +was successful, otherwise a system wide error code.

+ + + +

SetSync()

The +function declaration for the SetSync() method is:

IMPORT_C TBool SetSync();

Description

Allows the synchronous nature of the DSDIORegInterface class to be enabled.

When +the synchronous nature of the DSDIORegInterface class is enabled, then completion +of an operation is specified by waiting on a semaphore.

Parameters

None

Return +value

+ + + +

TBool

The result of the operation. KErrNone if the operation +was successful, otherwise a system wide error code.

+ + + +

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-2622DE31-AA12-5FAD-86FB-B13259EFC6D9-master.png Binary file Adaptation/GUID-2622DE31-AA12-5FAD-86FB-B13259EFC6D9-master.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-2622DE31-AA12-5FAD-86FB-B13259EFC6D9_d0e9239_href.png Binary file Adaptation/GUID-2622DE31-AA12-5FAD-86FB-B13259EFC6D9_d0e9239_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-2648B61C-6EBD-4668-AACD-EA4B2C435BB2.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-2648B61C-6EBD-4668-AACD-EA4B2C435BB2.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,90 @@ + + + + + +Message +HandlingThis document describes message queues and message handling. +

Message queues

The +request handling kernel side DFC is managed by a message queue object of the TMessageQueue type. +The message queue consists of a DFC and a doubly linked list of received messages. +The messages are represented by TThreadMessage objects +and are owned by each user thread. Requests are queued as message objects +on the message queue.

The driver framework requires that the driver +sets a DFC queue to use with the message queue. This is done by calling DLogicalChannel::SetDfcQ(). +The message queue must also be enabled to receive incoming messages by calling TMessageQue::Receive().

// Logical Channel Second stage constructor +TInt DExDriverLogicalChannel::DoCreate(TInt /*aUnit*/, const TDesC8* + /*anInfo*/, const TVersion& aVer) + { + ... + // Set up the DFC queue for this driver. Here, the DFC + // queue is created by the PDD dedicated for this driver. + SetDfcQ(Pdd()->DfcQ()); + + // Start receiving the incoming requests on the message queue + iMsgQ.Receive(); + ... + }

The Kernel provides a standard DFC queue, which runs +on a dedicated kernel thread called DFCThread0, for general +use by drivers. However, it is recommended that the driver creates its own +DFC thread to process its requests. The following example shows how a PDD +can implement the DfcQ() function to return a newly created +DFC thread:

// DfcQ - Creates a DFC queue dedicated for the tutorial driver +TDynamicDfcQue* DExUartPhysicalChannelH4::DfcQ() + { + // Create a DFC queue dedicated to the driver with a specified + // priority + TInt r = Kern::DynamicDfcQCreate(pDfcQ,KExUartDfcPriority, + KExUartDfcName); + if (r!=KErrNone) + { + // DfcQ failed, return NULL + return NULL; + } + return iDfcQueue; + }

The DFC thread that is created for the driver must be +destroyed after use. To do this, the driver can create an Exit or Kill DFC +request and queue it to the thread to be destroyed in the logical channel +destructor. This exit DFC function cancels any other requests pending using TDfc::Cancel() and +calls Kern::Exit() to terminate the thread.

The TDynamicDfcQue has +a destroy method that can be run on the channel destructor. The destroy method +destroys the DFC queue, kills the DFC thread and deletes the TDynamicDfcQue object +itself. This avoids the possibilities of memory leaks in the DFC.

Message handling

All +synchronous and asynchronous requests are passed to the HandleMsg() function +by the framework, with the message as an argument. A driver should implement +the function to identify the message type and handle the messages accordingly.

The +client thread is blocked until the message is completed, as the request uses +the thread's message object. If the client thread was left free, it would +corrupt the message if another request was issued.

When the driver +has completed handling the message, it notifies the framework by calling TThreadMessage::Complete(). +The client thread is then unblocked, and can either block on the thread semaphore +or issue further requests before blocking.

For synchronous requests, +the message is not completed until the request itself is complete, and the +driver calls the TThreadMessage::Complete() function after +the actual completion of the request. However, for asynchronous requests, +the message is completed after the driver has accepted the request, but not +necessarily after the actual completion of the request, which can happen later. +This means that the driver calls TThreadMessage::Complete() as +soon as it has received the message and initiated the required processing +to complete the request.

void DExDriverLogicalChannel::HandleMsg(TMessageBase* aMsg) + { + TThreadMessage& m = *(TThreadMessage*)aMsg; + // obtain the function id value to determine the request nature + TInt id = m.iValue; + ... + if (id>=0) // Synchronous messages + { + // call synchronous message handler function, DoControl() + TInt r = DoControl(id,m.Ptr0(),m.Ptr1()); + m.Complete(r,ETrue); + return; + } + }

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-26621CA5-B686-53FB-AF3E-96CDD38C8520.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-26621CA5-B686-53FB-AF3E-96CDD38C8520.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,148 @@ + + + + + + Physical +RAM DefragmentationDescribes Symbian platform RAM defragmentation. +

Symbian platform physical RAM defragmentation is the process of moving +physical pages, used to back virtual allocations, in order to create empty +physical ranges. This enables the powering off of individual RAM banks or, +if required, the allocation of a large contiguous buffer, for example, for +a CCD image. This functionality allows a more efficient use of RAM in terms +of both memory and power consumption.

Symbian platform RAM defragmentation is used to create large areas +of contiguous RAM and/or allow the powering down of surplus RAM ICs: it does +not locate and consolidate fragmented files and folders. This functionality +enables more efficient use of physical RAM and may enable a lower Bill Of +Materials (BOM), or increase battery life.

There are two interrelated use cases for defragmenting physical RAM:

many device drivers +require physical RAM for use for buffers. For example, a camera driver may +require a physically contiguous buffer for holding the output of the CCD. +In releases 9.3 and before such memory was typically allocated at boot time. +This practice increases initial RAM consumption after boot. Total RAM consumption +can be reduced if memory for such buffers is only allocated as required, rather +than at boot time. It is not possible to provide an absolute guarantee that +the RAM will be available when needed, but it should succeed in all but exceptional +cases.
typically, memory consumption +of a phone while idle is less than the total memory available. Idle and active +power consumption can be decreased by powering down unused RAM chips or unused +RAM banks within a RAM chip. This may also involve cooperation with a higher +level component in the UI which can shut down unused applications to reclaim +more memory.

Defragmention +of RAM

TRamDefragRequest is the class used +by device drivers to perform all defragmentation operations. The three defragmentation +operations provided are:

TRamDefragRequest::DefragRam() – +Performs a general defragmentation.
TRamDefragRequest::ClaimRamZone() – +Attempts to claim a whole RAM zone.
TRamDefragRequest::EmptyRamZone() – +Removes allocated pages from a RAM zone.

There are three overloads for each of these TRamDefragRequest defragmentation +methods which behave differently:

The first overload is +synchronous and blocks the calling thread until the defragmentation is complete +(or is cancelled using TRamDefragRequest::Cancel). In this +case, the return value is the result of the defragmentation – an appropriate +system-wide error code.
The second overload +is asynchronous and takes a pointer to an NFastSemaphore. +The semaphore is signalled when the defragmentation is complete. The return +value is KErrNone unless there was a problem initializing +the request, in which case an appropriate system-wide error code is returned. +The result of the defragmentation can be obtained by calling TRamDefragRequest::Result() after +the semaphore has been signalled.
The third overload is +asynchronous and takes a DFC. The DFC is queued when the defragmentation is +complete. The return value is KErrNone unless there was +a problem initializing the request, in which case an appropriate system-wide +error code is returned. The result of the defragmentation can be obtained +by calling TRamDefragRequest::Result().

All TRamDefragRequest defragmentation operations +are placed onto a FIFO queue. Any currently running defragmentation operation +must complete or be cancelled before a new defragmentation operation can begin.

All +the TRamDefragRequest defragmentation methods have the +following parameter in common:

aPriority

aPriority specifies the priority +of the thread that performs the defragmentation. If aPriority = KInheritPriority, +the default, then the defragmentation thread will execute with the same priority +as thread that invokes the defragmentation operation.

Determining the result of +a defragmentation operation

For synchronous overloads of the defragmentation +methods the error code returned by the defragmentation method can be used +to determine the result of the defragmentation operation. KErrNone signifies +that the defragmentation operation was successful.

For asynchronous +overloads of the defragmentation methods the result of the defragmentation +operation is determined by invoking TRamDefragRequest::Result() after +it has signalled that it has completed. Again, KErrNone signifies +that the defragmentation operation was successful.

Cancelling a defragmentation +operation

A defragmentation operation can be cancelled by invoking +the TRamDefragRequest::Cancel() method. This method cancels +the defragmentation, if it is in progress or is in the queue, and causes it +to complete with KErrCancel. If the defragmentation operation +has already completed, this method has no effect and the result remains as +it was.

General defragmentation

TRamDefragRequest::DefragRam() initiates a general defragmentation. A general defragmentation attempts +to arrange the currently allocated pages so that only the minimum number and +the most preferable RAM zones required are powered and refreshed. Each time +the general defragmentation successfully empties a RAM zone the base port +invokes the RAM zone call back function with aOp = ERamZoneOp_PowerDown see RAM +zone call back function. This informs the base port that it can decide +to, not refresh or power down the empty RAM zone when it deems it to be appropriate.

Depending +on the current state of the system and the value of aMaxPages, +a general defragmentation may require a significant amount of time to complete. +Therefore, if a general defragmentation is performed too frequently the power +saving benefits achieved by powering down or not refreshing RAM zones, may +prove to be less than the power consumed while performing the general defragmentation. +It is recommended that a general defragmentation is only performed once the +device has been idle for a significant period of time.

aMaxPages

TRamDefragRequest::DefragRam() is +similar to the other defragmentation methods, except that it has an additional +parameter aMaxPages. aMaxPages specifies +a limit on the number of pages that can be moved during a general defragmentation +when set to zero there is no limit. This can be useful in limiting the amount +of processing a general defragmentation performs and therefore the power consumed +by the general defragmentation. However, setting aMaxPages too +low may prevent the general defragmentation from being able to empty a single +RAM zone despite there being enough free pages in the most preferable RAM +zones.

RAM defragmentation +of Physically contiguous allocations

Some devices may define RAM Zones for use +by particular applications or hardware peripherals requiring a block of physically +contiguous RAM. TRamDefragRequest::ClaimRamZone() is used +by the device driver when it requires use of the pre-determined RAM zone to +be used for the block of physically contiguous RAM.

TRamDefragRequest::ClaimRamZone() is +similar to the other defragmentation methods, except that it has two extra +parameters:

aId – +the ID of the RAM zone to be claimed.
aPhysAddr – +on successful completion of the claim operation this is loaded with the physical +base address of the claimed RAM zone.

Once a RAM zone has been successfully claimed its memory can be used +by the device driver after being mapped into a shared +chunk. When the claimed RAM zone is no longer required, the device +driver must use Epoc::FreePhysicalRam to release it for +use by the rest of the system.

Zone specific +allocations

A device driver may attempt to allocate memory from +a specific RAM zone using Epoc::ZoneAllocPhysicalRam(). +If the allocation fails then use TRamDefragRequest::EmptyRamZone() to +remove as many pages as is reasonable from the RAM zone.

TRamDefragRequest::EmptyRamZone() is +similar to the other defragmentation methods, as described in Defragmention of RAM, except that it has an extra parameter:

aId – the ID of the +RAM zone to be emptied.

Once the empty defragmentation operation has completed the RAM zone +specific allocation can be attempted again. However, the RAM zone specific +allocation may still fail in high RAM usage situations or if the RAM zone +has too many fixed pages allocated.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-26714A57-B6B4-5E81-B512-FB520718482B.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-26714A57-B6B4-5E81-B512-FB520718482B.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,28 @@ + + + + + +Debug Monitor +ToolDescribes how to get basic information about the system state when +problems occur on hardware to help you debug your software. +

Device drivers are typically run and debugged on target hardware rather +than on the Emulator. The tool that provides this information is called the debug +monitor or the crash debugger.

The debug monitor is used when the Kernel faults. This can happen because +there is a fault in a kernel-side component, such as a device driver, or because +a thread or process marked as system-critical crashes.

Note that the debug monitor is one of the basic ways of debugging software +problems on target hardware. Full interactive debugging on reference hardware +and some real phones is available through commercial IDEs.

+ +H4 in the Debug Monitor (or Why is the board flashing?) + +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-2700AAC8-A034-5E7D-B0E0-26B49E68BB18.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-2700AAC8-A034-5E7D-B0E0-26B49E68BB18.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,73 @@ + + + + + +Personality Layer for Real Time ApplicationsA base port can add a software layer called a personality +layer to the Kernel to provide an emulation of a real time operating +system (RTOS) +

. You can provide a personality layer so that a phone can run existing +protocol stacks, for example, mobile telephony signalling stacks, +or Bluetooth stacks, on the same CPU that runs the Symbian platform +applications.

Such protocol stacks, often referred to as Real Time Applications +(RTA), almost always run on an RTOS, and the aim of the personality +layer is to provide the same API as the RTOS, or at least as much +of it as is required by the RTA. The RTA can then run, using the Kernel +Architecture 2 Nanokernel layer as the underlying real time kernel.

The following diagram illustrates the point simply.

+ + + +

There is sample code at ...\e32\personality\... that you should refer to while reading this.

RTOS +environment features

As a basis for emulating an RTOS, +the RTOS is assumed to provide the following features:

Threads
Thread synchronisation/communication
Thread scheduling +following a hardware interrupt
Timer management +functionality
Memory management.

Threads

Threads are independent units of execution, +usually scheduled on a strict highest-priority-first basis. There +are generally a fixed number of priorities. Round robin scheduling +of equal priority threads may be available but is usually not used +in real time applications. Dynamic creation and destruction of threads +may or may not be possible.

Thread synchronisation/communication

Typical examples +of such thread synchronisation and communication mechanisms are semaphores, +message queues and event flags.

There is wide variation between +systems as to which primitives are provided and what features they +support. Again, dynamic creation and destruction of such synchronisation +and communication objects may or may not be supported. Mutual exclusion +protection is often achieved by simply disabling interrupts, or occasionally +by disabling rescheduling.

Thread scheduling following a hardware interrupt

This +is usually achieved by allowing interrupt service routines (ISRs) +to make system calls which perform operations such as signalling a +semaphore, posting a message to a queue or setting event flags, which +would cause a thread waiting on the semaphore, message queue or event +flag to run.

Some systems don't allow ISRs to perform these +operations directly but require them to queue some kind of deferred +function call. This is a function which runs at a lower priority than +hardware interrupts (i.e. with interrupts enabled) but at a higher +priority than any thread - for example a Nucleus Plus HISR. The deferred +function call then performs the operation which causes thread rescheduling.

Timer management functionality

A timer management +function is usually also provided, allowing several software timers +to be driven from a single hardware timer. On expiry, a software timer +may call a supplied timer handler, post a message to a queue or set +an event flag.

Memory management

An RTOS often provides memory management, +usually in the form of fixed size block management as that allows +real time allocation and deallocation. Some RTOSs may also support +full variable size block management. However most RTOSs do not support +use of a hardware MMU and, even if the RTOS supports it (for example +OSE does), the real time applications under consideration do not make +use of such support since they are generally written to run on hardware +without an MMU.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-28844FE0-AE0F-531C-826E-CDA8400A0581.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-28844FE0-AE0F-531C-826E-CDA8400A0581.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,104 @@ + + + + + +Sessions +and Request ManagementDescribes how the MultiMediaCard Controller manages the sessions +and sets the order of requests. +

When a number of drivers have a session with the MultiMediaCard Controller, +the MultiMediaCard Controller can have many requests to service.

Session queues

To +handle sessions, the MultiMediaCard controller implements a scheduler. The +MultiMediaCard stack has three internal queues:

an entry queue - this +is the queue onto which a session is initially added when a client submits +the session object by calling DMMCSession::Engage() on +it. This is anchored in the DMMCStack::iEntryQueue private +member.
a ready queue - this +is the queue into which a session is moved when it is ready to be handled; +the scheduler moves all the sessions from the entry queue into the ready queue +when it can. This is anchored in the DMMCStack::iReadyQueue private +member.
a working set queue +- this is the queue of sessions to be processed as chosen by the scheduler. +This queue is limited to eight sessions. The scheduler moves a session from +the ready queue to the working set queue if all current sessions in the working +set queue are blocked and there are less than eight sessions in it. This is +anchored in the DMMCStack::iWorkSet private member.

All three queues are circular queues as implemented using the internal +Symbian platform class TMMCSessionRing.

+ +

The scheduler

Every +time one of the following events occurs, the MultiMediaCard stack invokes +its scheduler to deal with that event:

a client submitting +a session to the MultiMediaCard controller
a client aborting a +session
a card interrupt occurring.

The stack invokes the scheduler by calling the internal function DMMCStack::Scheduler().

Blocking a +session

Sometimes, the MultiMediaCard controller has to perform +its processing in a DFC context. In those cases the Controller postpones operation +by queuing a DFC; the DFC call-back function then resumes the operation by +invoking the scheduler again. This means that the scheduler may be running +as part of a kernel executive call, a DFC or an interrupt service routine.

In +general, the MultiMediaCard controller processes a session in stages, issuing +commands, checking responses, reading or writing data etc. Each stage is usually +done asynchronously, first setting up the activity and then setting up a means +of being notified when that activity is complete, for whatever reason (e.g. +issuing a command and setting up an interrupt when a response has been received).

If +a session is waiting on an asynchronous operation, it is blocked. When one +session is blocked, the stack tries to process another session which isn’t +blocked.

The blocking of sessions is set up and implemented internally +to Symbian platform. However, the platform specific layer can block a session +by calling the DMMCStack::BlockCurrentSession() function +with the KMMCBlockOnASSPFunction bit set in the parameter +passed to that function.

Internally, the DMMCSession::iBlockOn private +data member is set when a session is blocked. This is a bit-mask variable +containing the reason that the session is blocked.

Scheduler algorithm

The +following flow-diagram shows the algorithm used by the scheduler.

+ +

The DMMCStack private members referenced in this +diagram have the following meaning:

+ + + +

DMMCStack::iAbortReq

Set to ETrue when there are sessions on the stack +that have been marked for abort by the client. This is set as a result of +a call to DMMCSession::Abort().

+ + +

DMMCStack::iAttention

Set to ETrue when there are sessions ready to +run. This is set when a session is submitted to the stack as a result of a +call to DMMCSession::Engage(), or when a session becomes +unblocked.

+ + +

DMMCStack::iCompReq

Set to ETrue when there are sessions on the stack +ready to complete. This is set internally by the controller through calls +to the private functions DMMCStack::MarkComplete() or DMMCStack::CompleteAll().

+ + +

DMMCStack::iInitialise

Set to ETrue when stack initialization (CIM_INIT_STACK) +has been forced. This is set when the controller needs to re-power the stack, +and to power up a card on client requests.

+ + + +

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-28F3F720-A2E0-59C9-8BB4-B6124CFC6C89-master.png Binary file Adaptation/GUID-28F3F720-A2E0-59C9-8BB4-B6124CFC6C89-master.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-28F3F720-A2E0-59C9-8BB4-B6124CFC6C89_d0e11050_href.png Binary file Adaptation/GUID-28F3F720-A2E0-59C9-8BB4-B6124CFC6C89_d0e11050_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-29B84A67-9DB7-5F4C-A4D1-A3BDC69015A8.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-29B84A67-9DB7-5F4C-A4D1-A3BDC69015A8.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,113 @@ + + + + + +Additional +System Wide Power StatesA base port can add new power states to improve power management +for phone hardware. +

The Kernel defines three system wide power states. A base port can add +new power states to improve power management for phone hardware.

The generic system wide power states that are defined are Active, Standby and Off. +Any additional sub-states of the Active power state must be wholly +managed by the base port. These states may not need to be declared explicitly +and may result from peripherals, or groups of peripherals, having moved to +their low power state (see also moving +to their low power state). The device will then “trickle“ into one +of these sub-states instead of transitioning into them as a result of a user +action or system policy decision.

Usually, the transition of the system into one of the additional low power +states happens when the CPU enters the idle mode. The transition may be automatic +and wholly managed by the ASSP hardware or may result from an action taken +by the software routine that prepares the CPU to go to idle mode.

Sleeping in idle mode

An example of this is when +the base port uses the idle mode to put the CPU and the device into hardware +“Sleep” mode similar to that which can be achieved with a transition to Standby mode +as described in the implementation issues for implementing +DPowerController::PowerDown()

When called, the power controller’s DPowerController::CpuIdle() implementation +could take the necessary steps to prepare the CPU and the platform to go to +“Sleep”.

There is a balance between the power savings obtained from +moving the CPU and platform into “Sleep” mode in Idle and the performance +hit resulting from spending time restoring the status after coming out of +“Sleep” mode. Usually the CpuIdle() routine investigates +the timer queue (using NTimerQ::IdleTime()) for the next +timer expiration and decides to move or not to move the CPU and platform into +“Sleep” mode based on how much time there is before the next timer expiration. +The threshold above which it is considered productive to move into “Sleep” +is dependent on the base port.

The decision to move into “Sleep” mode +may also be based on the current level of activity, or collected metrics on +the length of time spent in Idle, or other historical information. This can +be implemented entirely by the base port, or it may require the services of +an external component (such as, for example, Speed Management).

The +transition to a hardware “Sleep” mode may also depend on shared peripherals +being in a particular state, for example, no pending requests from other peripherals. +This means that the power controller may need to check with the peripheral +driver before initiating the change. The power controller could use the ASSP/Variant +method to access the resource manager and check the usage of a shared peripheral +using its GetCount() API.

The decision to move into +“Sleep” mode could be dependent on a number of peripherals (shared and not +shared) being in Standby and a number of controllable power resources being +turned off. Therefore the power controller may also need to check with the +resource manager (through the Variant or ASSP) for the state of a specific +set of controllable power resources (using the ResourceManager::GetResourceState() API).

On +going to “Sleep”, an action or set of actions might need to be taken that +would affect the whole platform. An example of this is when DRAM is put into +self-refresh mode on entering the CPU Idle mode after all peripherals that +might access it (including the LCD controller and DSP) are in low power state. +Unused DRAM banks may also be powered down.

The following diagram +exemplifies how the evolution of system power would look like on a system +when the most power saving “Sleep” mode can only be reached – from Idle - +when Peripherals A, B and C are already in their low power mode. On going +to the most power saving “Sleep” mode, additional actions can be taken to +lower the system power level:

+System power use over time + +

The system is active +when a request for service is made on peripheral A; the peripheral driver +for peripheral A requests its transition to operational state increasing the +system power requirement (a).
After a period of activity +related to servicing the request, the system enters the idle thread; in CpuIdle() the +time for the next timer expiration is investigated and is found to be long +enough to send the system to sleep, powering down peripherals A, B and C to +their low power state and other system resources (b).
The timer expires and +the system wakes up to the same power level as before (c).
The inactivity timer +implemented in the peripheral driver for peripheral A expires: the peripheral +is transitioned to the low power state (d).
At (e) the system enters +the idle thread again: the timer queue is investigated and then enters sleep +mode, waking up again when an interrupt occurs (f).
The inactivity timer +associated with the peripheral drive for peripheral B expires and the peripheral +is transitioned to its low power state (g).
On the next call to CpuIdle() the +time for the next timer expiration is not long enough to power off peripherals +and other system resources: only limited power savings can be made (h) until +the system wakes up again (i).
Finally, the inactivity +timer for peripheral C expires and the peripheral is transitioned to low power +state (j). On reaching another period of system idle all conditions are met +to send the system to the deepest sleep mode available accompanied by the +switching off other power resources (k).
On waking up (l) the +system resources are restored to the same power level as before.

Any transition to and from these low power states must be transparent +to the rest of the system. A transparent transition is one that can be instantly +reversed, perhaps automatically in hardware, and has no noticeable impact +on system performance. In other words, it should be possible to wake the processor +up and move the entire device to Active Mode as if coming from a “normal” +Idle Mode.

To perform a system wide power change which is not transparent, +peripherals that may be affected by the transition would need to be examined, +and interfaces would have to be provided so that the users of these peripherals +could query the peripheral and allow or disallow the system transition into +that state.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-2ADB873A-1580-476A-9642-AB47D13D4A98.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-2ADB873A-1580-476A-9642-AB47D13D4A98.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,102 @@ + + + + + +Driver +Source FilesThis document details the directory structure and file types of +logical device drivers and physical device drivers. +

Directory +structure

Device driver DLLs come in two types - the logical +device driver (LDD), and the physical device driver (PDD). Typically, a single +LDD supports functionality common to a class of hardware devices, whereas +a PDD supports a specific member of that class.

In Symbian platform +source code, PDDs are part of variant baseports, while LDDs are stored in +a shared location that is not specific to a particular variant:

PDD source files (.cpp, .h and .mmp) for peripherals for the H4 variant are in source directories named base\omap_hrp\h4\ <driver_pdd >.
PDD source files (.cpp, .h and .mmp) for peripherals for the Emulator variant are in source directories named base\wins\ <driver_pdd >.
LDD source files are +in source directories named base\e32\ <driver _ldd >, +which are shared for all variants.
Common test application +source files are in source directories named base\e32test\ <driver_test >.

For both types of driver, the source files are generally organised +in the following sub-directories:

<driver >\group – .mmp files
<driver >\inc – .h files
<driver >\src – .cpp files

File extensions

The +project files of a device driver that is part of the Kernel code are similar +to those for other components in Symbian platform. The following tables summarise +the source and binary file types you will see:

+ + + +

Source File Type

Description

+ + +

Include files

+ + +

.cpp

Source files

+ + +

.inl

Inline files

+ + +

.mmp

Project file, similar to a makefile in other operating systems

+ + +

.inf

Build file grouping multiple mmp files. Command line builds are +done from this file's directory.

+ + +

.iby

ROM include file. This file specifies the built files that need +to be included in a ROM image. This is not used in builds for the Emulator.

+ + + +

Binary File Type

Description

+ + +

.ldd

Logical Device Driver target. A LDD contains code that is common +to a class of hardware devices.

+ + +

.pdd

Physical Device Driver target. A PDD contains code that is specific +to one particular type of device.

+ + +

.exe

Application executable target.

+ + +

.ext

Kernel extension target, a driver that is started when the kernel +boots.

+ + + +

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-2AE438CC-F2E4-5FCB-971F-CFFAE5EF81E4-master.png Binary file Adaptation/GUID-2AE438CC-F2E4-5FCB-971F-CFFAE5EF81E4-master.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-2AE438CC-F2E4-5FCB-971F-CFFAE5EF81E4_d0e93636_href.png Binary file Adaptation/GUID-2AE438CC-F2E4-5FCB-971F-CFFAE5EF81E4_d0e93636_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-2B7D04D9-98DE-5284-836D-01DB4FA8949D.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-2B7D04D9-98DE-5284-836D-01DB4FA8949D.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,15 @@ + + + + + +Writable Data +Paging +

Describes writable data paging and how to use it.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-2BDDB4F8-3175-411B-A206-FAE27DEBF678.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-2BDDB4F8-3175-411B-A206-FAE27DEBF678.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,19 @@ + + + + + +DMA Tools GuideTools used to debug the DMA implementation. +

You implement DMA with the standard base porting tools (a compiler +and hardware-specific debugger). There are no tools specifically required +for DMA implementation.

+DMA +Implementation Overview +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-2C1B74C4-C80D-5EF9-B822-2DA2FCF9B006.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-2C1B74C4-C80D-5EF9-B822-2DA2FCF9B006.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,26 @@ + + + + + +General +MacrosDescribes macros that can be used in the platform-specific configuration +header and in bootstrap code. +

INIT_LOGICAL_SYMBOLINIT_LOGICAL_SYMBOL SYM, COUNT

Checks if the symbol SYM is defined. If so, it sets it to +a value which is logically TRUE and increments symbol COUNT by +one; COUNT may be omitted if not required.

If the +symbol SYM is not defined, then the macro defines it, and +sets it to a logically FALSE value.

INIT_NUMERIC_SYMBOLINIT_NUMERIC_SYMBOL SYM, DEFAULT

Checks if the symbol SYM is defined. If so, its value +is left unchanged.

If SYM is not defined, then the +macro defines it as a numeric variable and sets its value to DEFAULT.

INIT_NUMERIC_CONSTANTINIT_NUMERIC_CONSTANT SYM, DEFAULT

Checks if the symbol SYM is defined. If so, its value +is left unchanged.

If SYM is not defined, then the +macro defines it as a numeric constant and sets its value to DEFAULT.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-2C312536-2410-42D7-B976-F7CF99492DEA-master.png Binary file Adaptation/GUID-2C312536-2410-42D7-B976-F7CF99492DEA-master.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-2C312536-2410-42D7-B976-F7CF99492DEA_d0e344_href.png Binary file Adaptation/GUID-2C312536-2410-42D7-B976-F7CF99492DEA_d0e344_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-2C6B7D51-C201-453D-ABBA-C9EC6B3DBDB2.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-2C6B7D51-C201-453D-ABBA-C9EC6B3DBDB2.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,15 @@ + + + + + +Client InterfaceThe boundary between the generic implementation and any +part of the OS that uses the client interface. +

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-2C915A03-AD8C-5924-87BB-953AE323E0FA.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-2C915A03-AD8C-5924-87BB-953AE323E0FA.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,23 @@ + + + + + +Set +UpDescribes how to use the template port to start your port. +

The template port digitizer code can be found in ...\template\template_variant\specific\xyin.cpp.

The template .mmp file can be found in ...\template\template_variant\exxytemplate.mmp.

Following the general pattern, your implementation will be contained in +the directory: <path to your variant>\specific. Create +a copy of the template port implementation file xyin.cpp and +copy it into your variant specific directory.

Rename the class DTemplateDigitiser to reflect the name +of your device. You should also be prepared to add your own private data and +functions into it.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-2D8B8FF1-7A35-5E98-BDDB-2B0BD8DE6215.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-2D8B8FF1-7A35-5E98-BDDB-2B0BD8DE6215.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,16 @@ + + + + + +Writable Data +Paging Tutorial +

Contains the guides that describe various aspects of writable data paging +in more detail.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-2D977A02-5928-5441-8AE7-42A722F2A4B8.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-2D977A02-5928-5441-8AE7-42A722F2A4B8.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,26 @@ + + + + + +User-Side Hardware AbstractionThe User-Side Hardware Abstraction (HAL) component provides a simple +interface for programs to read and set hardware-specific settings, for example, +the display contrast. +

A base port must define the attributes that clients can use on a phone, +and implement any functions that are required to get and set the attributes.

To define attributes, you +must change the source of the hal.dll library and rebuild +it. Functions that get and set attributes are implemented as HAL handler functions +in kernel-side programs, for example, device drivers.

+LCD Extension + +Power HAL + Handler +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-2D98DB88-BA48-5EF8-A5F9-0CB8688B0B63-master.png Binary file Adaptation/GUID-2D98DB88-BA48-5EF8-A5F9-0CB8688B0B63-master.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-2D98DB88-BA48-5EF8-A5F9-0CB8688B0B63_d0e32099_href.png Binary file Adaptation/GUID-2D98DB88-BA48-5EF8-A5F9-0CB8688B0B63_d0e32099_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-2E402D4E-53A9-5BA6-9FBD-B2713DBC7858.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-2E402D4E-53A9-5BA6-9FBD-B2713DBC7858.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,101 @@ + + + + + +Peripheral +Power DomainsA peripheral power domain can be defined as being a peripheral, +or group of peripherals, whose power supply can be controlled independently +from the rest of the device, but not independently from other peripherals +within the same power domain. +

Power domains depend on the physical wiring of a device, and this must +be taken into account by the base port. They are usually manipulated when +peripherals or groups of peripherals transition between the Operational +Power and Off states.

The following diagram is an example of such an arrangement.

+ +Example of peripheral power domains + + +

To reduce power leakage, it may be useful to cut the power supply to an +area or a group of peripherals in the ASIC or the hardware platform, when +all peripherals on that peripheral power domain have moved to the Off state.

In the arrangement shown here, when all peripherals on a power domain have +been powered down, the power supply to that domain can be cut off, using the +RESn signal.

A suggested implementation would have peripheral power domains modelled +by a MPowerInput reference counted object, and controlled +using the MPowerInput::Use() and MPowerInput::Release() interfaces +that would enable the domain on request. The peripheral driver’s request on +that power resource would only be changed when entering the Operational +Power state from the Off state, or when entering or exiting the Off states. +In other words, a peripheral power domain should only be turned off when all +peripherals in that domain have transitioned to their Off state.

This is a suggested definition for a peripheral power domain class.

+class PeripheralPowerDomain : public MPowerInput + { +public: + void InitPowerDomain(); // (optional) handles any initialisation + void Use(); // implementation of pure virtual + void Release() // implementation of pure virtual + TUint GetCount(); +private: + TInt TurnSupplyOn(); // re-establishes power supply to this domain (asynch) + TInt TurnSupplyOff(); // cuts power supply to this domain + }; + +

The Use() and Release() functions implement +a usage count. Peripheral drivers for peripherals on that domain will call +these functions whenever their power handler’s PowerUp() and PowerDown() member +functions are called, respectively. If the usage count is 0 and Use() is +called, it should call TurnSupplyOn(). If Release() is +called and the usage count is decremented to 0, TurnSupplyOff() is +called.

Often, re-establishing the power supply to a power domain is a lengthy +operation and should be modelled by an asynchronous operation. In that case TurnSupplyOn() should +be able to sleep the thread in which this function is called until the power +supply is stable.

We recommend that peripheral power domains are defined as part of, and +accessed through, a resource manager object as suggested in the discussion +of Controllable Power +Resources. Extending the original A +suggested implementation of a resource manager would give us:

+class ResourceManager + { +public: + void InitResources(); // called by your Asic::Init3()/Asic::Init1() + void Modify(TUint aSetMask, TUint aClrMask); // only 32 simple Resources can be managed + TBool GetResourceState(TUint aResBitMask); // only 1 bit set on this mask, returns On/Off +public: + (MPowerInput-derived) iSharedResource1; // 1 per shared resource + (MPowerInput-derived) iSharedResource2; + ... + PeripheralPowerDomain iPeripheralPowerDomain1; + PeripheralPowerDomain iPeripheralPowerDomain2; + PeripheralPowerDomain iPeripheralPowerDomain3; + ... + }; + +

where InitResources() could call each PeripheralPowerDomain::InitPowerDomain().

Peripheral power domains may also be a useful concept when transitioning +peripherals to low power mode after peripheral inactivity detection. It is +only after all peripherals on a peripheral power domain have requested moving +the resource to the level corresponding to low power that the resource level +can be changed. This is exemplified again in the block diagram above: when +all peripherals in a domain have requested transitioning to low power (using +a ReleaseToLevel() -type call) the power supply level to +that power domain can be set to VLowPwr.

The following base port software architecture diagram could be used to +address control of the peripheral power domains shown in the hardware block +diagram above:

+ +Base port software architecture diagram + + + \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-2E42E7EA-FED8-522C-8A5F-F65D799476C9.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-2E42E7EA-FED8-522C-8A5F-F65D799476C9.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,131 @@ + + + + + +Keyboard Driver Implementation TutorialThis topic describes how to implement an interrupt driven +keyboard driver. +

The steps are:

Implement the +driver entry point function and initialisation code. This function +is called when the extension is loaded.

The initialisation +code binds the hardware interrupt to the Interrupt Service Routine +(ISR) and enables the interrupt.
Implement an +ISR to handle key events. The ISR queues a keyboard DFC.
Implement a +keyboard DFC. This function interrogates the keyboard, converts the +scancode to a keypress event, and places it onto the kernel's event +queue.

Set +Up

In the template reference board port, the .mmp file for the keyboard driver is ...\template_variant\exkey_inttemplate.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 keyboard driver is built as part of +the Variant.

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

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

Entry +point implementation

The driver functionality is encapsulated +by the DKeyboardTemplate class, and an instance of +this is created when the extension is loaded.

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

DECLARE_STANDARD_EXTENSION() + { + __KTRACE_OPT(KEXTENSION,Kern::Printf("Starting keyboard driver")); + + // create keyboard driver + TInt r=KErrNoMemory; + DKeyboardTemplate* pK=new DKeyboardTemplate; + if (pK) + r=pK->Create(); + + __KTRACE_OPT(KEXTENSION,Kern::Printf("Returns %d",r)); + return r; + } + +

It simply creates an instance of the DKeyboardTemplate class and then performs a second-phase initialisation, which is +a common pattern in Symbian platform and third party applications.

Initialisation on construction

The constructor +of the DKeyboardTemplate class has the following +signature:

DKeyboardTemplate::DKeyboardTemplate() + : DPowerHandler(KLitKeyboard), + iMsgQ(rxMsg,this,NULL,1), + iPowerUpDfc(PowerUpDfcFn,this,6), + iPowerDownDfc(PowerDownDfcFn,this,7), + iEventDfc(EventDfcFn,this,1) + { + } + +

See also Interrupt Dispatcher +Tutorial.

Interrupt +Service Routine (ISR) implementation

The ISR (Interrupt +Service Routine) just schedules the DFC that handles the keypress. +It can also optionally contribute the timing of key interrupts as +a source of random data for the Random Number Generator (see CSPRNG Implementation +in Kernel). On the template reference board, this is implemented +as:

void DKeyboardTemplate::Isr(TAny* aPtr) + { + Interrupt::Disable(KIntIdKeyboard); + + // Add the timing of key interrupts as entropy data for the RNG + Interrupt::AddTimingEntropy(); + + k.iEventDfc.Add(); + } +

The ISR disables the keyboard interrupt, as repeated +ISRs are not allowed to queue further DFC routines.

DFC +function implementation

The DFC is the function DKeyboardTemplate::EventDfcFn which is implemented as a +call to DKeyboardTemplate::EventDfc().

void DKeyboardTemplate::EventDfcFn(TAny* aPtr) + { + ((DKeyboardTemplate*)aPtr)->EventDfc(); + } + +void DKeyboardTemplate::EventDfc() + { + __KTRACE_OPT(KHARDWARE,Kern::Printf("DKeyboardTemplate::EventDfc")); + + TInt irq=NKern::DisableAllInterrupts(); + while (IsKeyReady()) // while there are keys in the controller's output buffer + { + NKern::RestoreInterrupts(irq); + TRawEvent e; + TUint keyCode=GetKeyCode(); // Read keycodes from controller + __KTRACE_OPT(KHARDWARE,Kern::Printf("#%02x",keyCode)); + + // + // TO DO: (mandatory) + // + // Convert from hardware scancode to EPOC scancode and send the scancode as an event (key pressed or released) + // as per below EXAMPLE ONLY: + // + TUint bareCode=keyCode&~KFlagKeyPressed; + TUint8 stdKey=convertCode[bareCode]; + if (keyCode&KFlagKeyPressed) + e.Set(TRawEvent::EKeyUp,stdKey,0); + else + e.Set(TRawEvent::EKeyDown,stdKey,0); + Kern::AddEvent(e); + NKern::Sleep(1); // pause before reading more keycodes + irq=NKern::DisableAllInterrupts(); + } + Interrupt::Enable(KIntIdKeyboard); + NKern::RestoreInterrupts(irq); + }

This:

reads the scan +code data by calling DKeyboardTemplate::GetKeyCode()
re-enables the +keyboard interrupt, now that the DFC has freed up the input data register
translates the +keypress event into a Symbian scancode
puts the translated +event on to the event queue.

See +also

Concepts

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-2E4F8732-F253-5E0D-9A37-9476541E6004.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-2E4F8732-F253-5E0D-9A37-9476541E6004.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,83 @@ + + + + + +Platform-Specific +Configuration HeaderDescribes how to write the file providing build-time configuration +options. +

The platform-specific configuration header is a file that provides the +configuration options that must be known at build time.

The configuration header is an include file written in assembler, and is +named config.inc.

Use the configuration header file in the Template port in os/kernelhwsrv/bsptemplate/asspandvariant/template_variant/config.inc as the basis of your own configuration header file.

The file consists of a number of global logical symbol definitions (GBLL statements), +including the following:

symbols that define +the CPU, listed below
a number of less commonly +used macros and symbols, which are documented in the template configuration +header file
a set of general bootstrap +macros described in the Reference section, +including the macros that define the presence of Level 2 cache (L210 cache +and L220 cache).

CPU +symbols

The CPU that the bootstrap runs on is indicated by defining one of +the following symbols:

CFG_CPU_ARM710T
CFG_CPU_ARM720T
CFG_CPU_SA1
CFG_CPU_ARM920T
CFG_CPU_ARM925T
CFG_CPU_ARM926J
CFG_CPU_XSCALE
CFG_CPU_ARM1136
CFG_CPU_GENERIC_ARM4

Note that CFG_CPU_GENERIC_ARM4 refers to an ARM +architecture 4, or later device, with no MMU.

The template file contains +all these symbol definitions; just move the comment symbol (;) +as appropriate for your platform.

Other symbols + + + +

CFG_DebugBootRom

Define this symbol to enable debug tracing in the bootstrap.

+ + +

CFG_BootLoader

Define this symbol if the bootstrap is a bootloader.

+ + + +

Derived +symbols

A number of commonly used symbols are derived from the +supplied configuration options, and may be used in your code.

Precisely one of +the following three logical symbols is true, indicating the memory model in +use:

CFG_MMDirect
CFG_MMMoving
CFG_MMMultiple

The following logical symbols are true or false depending on whether +the CPU in use has the corresponding property. The property represented by +the symbol is given by the symbol name.

CFG_ARMV6
CFG_MMUPresent
CFG_CachePresent
CFG_WriteBufferPresent
CFG_SplitCache
CFG_SplitTLB
CFG_AltDCachePresent
CFG_WriteBackCache

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-2E54DA7D-1094-41C6-AFB0-9999471991F8.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-2E54DA7D-1094-41C6-AFB0-9999471991F8.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,430 @@ + + + + + +Interrupt Implementation GuideDescribes how to implement the Interrupt class. +

Introduction

Interrupt handling is implemented by writing platform +specific versions of the structures and functions of the Interrupt +class. The details of the implementation depend on hardware and the +architecture of the device. This document describes a simple implementation +of the structures and functions and then discusses more elaborate +strategies required with the use of device specific interrupts , chained +interrupts and multiple interrupt sources. It also covers implementation +on unicore platforms only. The SMP version of the kernel now implements +support for the ARM Generic Interrupt Controller and relies on its +use.

Chained interrupts are interrupts which are output by one controller +and input to another. They need to be distinguished in the ISR table +and require extensions to the handler functions.
Multiple interrupt sources to the same ISR require the use +of pseudo-interrupts.
When a Symbian port is split into an ASSP and variant (common +and device specific) layer, the variant may include additional interrupt +sources. Their API is defined by the port. Device specific interrupts +are sometimes used to handle interrupts from peripherals: another +technique is to route peripheral interrupts to a GPIO pin. Peripheral +interrupts cannot be specified as part of the ASSP layer.

The Template Baseport provides a skeleton implementation for +developers to modify at kernelhwsrv/bsptemplate/asspandvariant/template_assp/interrupts.cpp.

The +ISR table

The ISR table is a data structure which pairs +each ISR with the interrupt source to which it will be bound. It must +have enough space for each interrupt source on the device. It is implemented +as an array of Interrupt::SInterruptHander of size KINterruptSourceCount in which the interrupt Id is used +as an index to the table. This example code assumes a size of 32.

... +const TInt KInterruptSourceCount = 32; +SInterruptHandler IsrHandlers[KInterruptSourceCount]; +...

DisableAndClearAll()

Interrupts must be disabled and cleared with a call to Interrupt::DisableAndClearAll() before the call to Interrupt::Init1() at the start of initialization. Implementation +of this function is entirely hardware dependent.

Init1()

The kernel is initialized in phases, interrupts being involved +in the first phase and sometimes the third. The Init1() function should +be implemented to

Initialize the ISR table, binding all ISRs to the spurious +interrupts handler.
Register the dispatcher functions.
Bind ISRs which handle chained or pseudo interrupts.

Interrupts must be disabled during first phase initialization.

This example code illustrates initialization of the ISR table.

... +const TInt KInterruptSourceCount = 32; +SInterruptHandler IsrHandlers[KInterruptSourceCount]; +... + +for( TInt i = 0; i < KInterruptSourceCount; ++i ) + { + IsrHandlers[i].iIsr = SpuriousHandler; + IsrHandlers[i].iPtr = (TAny*)i; + }

This example code illustrates an implementation +of Interrupt::Init1() after the point at which +the ISR table has been initialized.

void TemplateInterrupt::Init1() + { + // + // need to hook the ARM IRQ and FIQ handlers as early as possible + // and disable and clear all interrupt sources + // + ... + DisableAndClearAll(); + Arm::SetIrqHandler((TLinAddr)TemplateInterrupt::IrqDispatch); + Arm::SetFiqHandler((TLinAddr)TemplateInterrupt::FiqDispatch); + } +

Init3()

Third phase initialization involves initializing various interrupt +handlers and sources which can only be initialized when the kernel +is fully functional. This is done with a call to Interrupt::Init3().

It is important to remember that interrupts are enabled during +third phase initialization.

Spurious()

Interrupts not bound to a real ISR must be bound to a 'spurious' +handler function Interrupt::Spurious() which returns +an error with the number of the interrupt.

Bind()

The Interrupt::Bind() function binds ISRs to +interrupt sources.

The argument aId is the +Id of an interrupt source and is used to index an entry in the ISR +table. Set the iPtr and iIsr members +of that entry (ISR parameter and ISR pointer) to the passed in values aPtr and aIsr.

The implementation +should perform some preliminary checks.

The interrupt Id must be checked for validity
The ISR must not already be bound to a real interrupt. It should +have been bound to the spurious interrupt handler at initialization.

All interrupts must be disabled during binding.

This +example code provides a basic implementation.

EXPORT_C TInt Interrupt::Bind(TInt aId, TIsr aIsr, TAny* aPtr) + { + TInt r = KErrNone; + If(TUint(aId)>=TUint(KInterruptSourceCount)) + { + r = KErrArgument; // Illegal interrupt number + } + else + { + SInterruptHandler& h = IsrHandlers[aId]; + TInt irq = NKern::DisableAllInterrupts(); + if (h.iIsr != &SpuriousHandler) + { + r = KErrInUse; // Already bound to an ISR + } + else + { + h.iPtr = aPtr; // The ISR parameter + h.iIsr = aIsr; // Pointer to the ISR + } + NKern::RestoreInterrupts(irq); + } + return r; + } +

The implementation of Interrupt::Bind() can be more complicated in the case of chained interrupts, multiple +interrupt sources, pseudo interrupt sources and device interrupts: +see the discussion of those topics.

Unbind()

The Interrupt::Unbind() function unbinds ISRs +from interrupt sources.

The argument aId is +the Id of an interrupt source and is used to index an entry in the +ISR table. Reset the entry in the ISR table to reference the spurious +handler function.

The implementation should perform some preliminary +checks.

The interrupt Id must be checked for validity
The ISR must not already be unbound (that is, bound to the +spurious interrupt handler).

All interrupts must be disabled during unbinding.

This +example code provides a basic implementation.

EXPORT_C TInt Interrupt::Unbind(TInt aId) + { + TInt r = KErrNone; + if (TUint(aId) >= TUint(KInterruptSourceCount)) + { + r = KErrArgument; // Illegal interrupt number + } + else + { + SInterruptHandler& h = IsrHandlers[aId]; + TInt irq = NKern::DisableAllInterrupts(); + if (h.iIsr == &SpuriousHandler) + { + r = KErrGeneral; // Already unbound + } + else + { + h.iPtr =(TAny*)aId; + h.iIsr = SpuriousHandler; // Replace with spurious handler + // NOTE: at this point it may be wise to + // force the hardware interrupt source to disabled. + } + NKern::RestoreInterrupts(irq); + } + return r; + } +

The implementation of Interrupt::Unbind() can be more complicated in the case of chained interrupts, multiple +interrupt sources, pseudo interrupt sources and device interrupts: +see the discussion of those topics below.

Enable()

Device drivers call the Interrupt::Enable() function to enable the interrupt source identified by the argument anId in the interrupt controller hardware.

The implementation +is entirely hardware dependent.

This example involves a check +for chained interrupts, which are discussed in their own section below.

EXPORT_C TInt Interrupt::Enable(TInt anId) + { + TInt r=KErrNone; + // if ID indicates a chained interrupt, call variant... + if (anId<0 && ((((TUint)anId)>>16)&0x7fff)<(TUint)KNumTemplateInts) + r=TemplateAssp::Variant->InterruptEnable(anId); + else if ((TUint)anId>=(TUint)KNumTemplateInts) + r=KErrArgument; + else if (TemplateInterrupt::Handlers[anId].iIsr==TemplateInterrupt::Spurious) + r=KErrNotReady; + else + { + // + // TO DO: (mandatory) + // + // Enable the corresponding Hardware Interrupt source + // + } + return r; + } +

Disable()

Device drivers call the Interrupt::Disable() function to disable the interrupt source identified by the argument anId in the interrupt controller hardware. The implementation +is entirely hardware dependent.

Clear()

Device drivers call the Interrupt::Clear() function +to acknowledge that they have serviced the interrupt and cleared the +pending flag in the interrupt controller hardware. The implementation +is entirely hardware dependent.

Clear() is +a useful function in cases where an interrupt must be cleared explicitly +rather than as a side effect of I/O register access: for instance +in PC card and MMC controller code.

SetPriority()

The Interrupt::SetPriority() function associates +a priority value (passed as a TInt) with an interrupt +Id. The meaning of the priority value is entirely hardware dependent.

Priority is a property of interrupts on some hardware, an example +being OMAP. Where the hardware is of this type, Interrupt::SetPriority() can be used to modify priorities in hardware. A simple use is to +determine whether an interrupt generates an IRQ or an FIQ. If priority +adjustment is not supported or not specified, the function should +simply return KErrNotSupported.

The implementation +is entirely hardware dependent.

IrqDispatch() +and FiqDispatch()

The functions Interrupt::IrqDispatch() and Interrupt::FiqDispatch() dispatch an interrupt +by calling the associated ISR. Interrupts are either IRQ or FIQ interrupts +and separate dispatch functions must be provided for each type. What +follows refers to IRQs but applies equally to FIQs as the distinction only operates at the level of hardware and the two +dispatch functions look the same.

In the simplest implementation, +the interrupt Id is used as an index into the ISR table. The iIsr member of the entry is called as a function with the iPtr member as its argument. The interrupt Id is taken from +a list of pending IRQs as in this example code.

void IrqDispatch() + { + TUint32 pendingIrqs = TheAssp::IrqPendingRegister(); + // for the purposes of this example we assume that reading + // this register also clears the pending flags + + TInt index = 0; + while( pendingIrqs ) + { + // while there is at least one pending IRQ + if( pendingIrqs & 1 ) + { + // the next interrupt is pending - dispatch it + (IsrHandlers[index].iIsr)(IsrHandlers[index].iPtr); + } + ++index; + pendingIrqs >>= 1; + } + } +

This code is a simplified example which assumes that

The interrupt controller provides 32 interrupt sources and +has a 32 bit pending interrupt register where a 1 indicates a pending +interrupt and all ones are cleared when the register is read.
The interrupt source represented by the low order bit in the +pending interrupt register is represented by interrupt Id 0 and so +on.

Implementation will be more complex where chained interrupts +and multiple interrupt sources are involved, as discussed below.

Dispatch functions are time critical. You will probably write +an initial implementation in C++ to get them working and then rewrite +in assembler for maximum efficiency.

Chained +interrupts

A platform often has multiple interrupt controllers +of higher and lower priority (higher and lower level controllers), +organized so that the output of a lower level controller is one of +the inputs to a higher level controller. Interrupt sources organized +in this way are called chained interrupts.

In a system with +chained interrupts, the ISR table must be structured so that interrupts +from higher and lower level controllers can be distinguished by their +Ids.

The Interrupt::Bind() and Interrupt::Unbind() functions are the same whether interrupts are chained or not.

In a system with chained interrupts it can be desirable to write +the Interrupt::Enable() and Interrupt::Disable() functions so as to disable not the interrupt itself but a the higher +level interrupt on the controller to which it is the input.

The Interrupt::IrqDispatch() and Interrupt::FiqDispatch() functions need to be extended in a system with chained interrupts. +There are two techniques for doing this, both of which involve a separate +second level dispatch function, but which differ in the way it is +called.

In one technique, the main interrupt dispatcher calls the second +level dispatcher if the relevant condition is satisfied.
In the other technique, the second level dispatcher is bound +directly to an interrupt source as its ISR.

The first technique works well in cases where there is only +a main and a secondary interrupt controller. It does not scale well +in cases which make use of multiple controllers chained to substantial +depth.

You need to allocate locations in your ISR table for +the secondary controllers so that the interrupt Id identifies which +hardware controller the input is on. For example, if each interrupt +controller handles 32 interrupt sources, you could allocate the first +32 Ids to the highest level controller, the next 32 to a second level +controller and so on.

This example code illustrates a main dispatcher +which calls a second level dispatcher.

void IrqDispatch() + { + TUint32 pendingIrqs = TheAssp::IrqPendingRegister(); + + TInt index = 0; + while( pendingIrqs ) + { + if( pendingIrqs & 1 ) + { + if( index == EMainIntChainIrq ) + { + // second-level controller is signalling + SecondLevelIrqDispatch(); + } + else + { + // call ISR + (IsrHandlers[index].iIsr)(IsrHandlers[index].iPtr); + } + } + ++index; + pendingIrqs >>= 1; + } + } +

This example code illustrates a second level dispatcher +bound directly to an interrupt source.

void IrqDispatch() + // MAIN IRQ DISPATCHER, FIRST-LEVEL INTERRUPT + { + TUint32 pendingIrqs = TheAssp::IrqPendingRegister(); + + TInt index = 0; + while( pendingIrqs ) + { + if( pendingIrqs & 1 ) + { + (IsrHandlers[index].iIsr)(IsrHandlers[index].iPtr); + } + ++index; + pendingIrqs >>= 1; + } + } +void SecondLevelIrqDispatch( TAny* /* aParam */ ) + { + TUint32 pendingIrqs = TheAssp::SecondLevelIrqPendingRegister(); + + TInt index = EStartOfSecondLevelIntId; + while( pendingIrqs ) + { + if( pendingIrqs & 1 ) + { + (IsrHandlers[index].iIsr)(IsrHandlers[index].iPtr); + } + ++index; + pendingIrqs >>= 1; + } + } +void InitialiseSecondLevelDispatch() + // Bind and enable the second-level dispatcher + { + Interrupt::Bind(EMainIntChainIrq,SecondLevelIrqDispatch,NULL); + Interrupt::Enable( EMainIntChainIrq ); + } +

This example assumes an ISR table in which the second +level interrupt ISRs begin at location 32 (EStartOfSecondLevelIntId). EMainIntChainIrq is the interrupt Id of the chained +interrupt source to the main interrupt controller. The second level +dispatcher is itself an ISR with an argument TAny* which is not needed in this example (possible uses are to distinguish +between core and device specific ISR tables or to point to I/O addresses).

Multiple +interrupt sources

In cases where multiple peripherals are +connected to the same interrupt source, multiple sources may generate +the same interrupt which will then require a different ISR depending +on the specific source. However, EKA2 does not allow binding of multiple +ISRs to the same interrupt. There are two strategies for solving this +problem, both of which involve assigning the multiple ISRs not to +the real interrupt but to pseudo-interrupt Ids. In one strategy the +dispatcher examines the hardware to determine where the interrupt +originated and calls the appropriate ISR. In the other strategy, the +ISRs are written so that they examine their peripheral hardware and +only run if it is actually signalling an interrupt: in this strategy +the dispatcher calls all the ISRs bound to the real interrupt but +only one of them runs.

There is no requirement to extend the +implementation of Interrupt::Bind() and Interrupt::Unbind() where multiple interrupt sources are +involved.

Multiple interrupt sources require you to extend the +implementation of Interrupt::Enable() and Interrupt::Disable() to enable and disable the true interrupt +source.

The dispatch functions should be extended in the same +way as with chained interrupts, using one of the two techniques described +for that case.

The ISR table should be structured so that the +interrupt Id identifies the hardware controller the interrupt is on. +For instance the first 32 Ids might refer to the highest level controller, +the next 32 to a second level controller and so on.

Device +specific interrupts

Interrupts generated by peripherals +are sometimes routed to a GPIO pin and sometimes included in a variant +layer. Where they are part of the variant layer, they must be listed +in a separate ISR table which is part of the device implementation. +However, we want device drivers to be able to use the Interrupt class +functions on interrupts of either type. The solution is to write separate +device specific functions derived from those of the core class. Core +class functions are then written in such a way as to identify device +specific interrupts and pass them on to the derived functions.

A recommended way of labelling interrupts as being device specific +is to assign negative numbers as their Ids. The core functions can +then identify negative Ids as belonging to device specific interrupts +and pass them to the device specific derived functions. The device +specific functions can convert them to positive numbers which serve +as indexes to the device specific ISR table.

This example code +illustrates device specific interrupt handling.

EXPORT_C TInt Interrupt::Bind(TInt aId, TIsr aIsr, TAny* aPtr) + { + TInt r = KErrNone; + if(aId < 0 ) + { + return MyAsic->VariantBind( aId, aIsr, aPtr ); // Device specific ID, call variant + } + else if (aId >= KInterruptSourceCount) + { + r = KErrArgument; // Illegal interrupt number + } + else + { + SInterruptHandler& h = IsrHandlers[aId]; + TInt irq = NKern::DisableAllInterrupts(); + if (h.iIsr != SpuriousHandler) + { + r = KErrInUse; // Already bound to an ISR + } + else + { + h.iPtr = aPtr; + h.iIsr = anIsr; + } + NKern::RestoreInterrupts(irq); + } + return r; + } + +SInterruptHandler VariantHandlers[KNumVariantInts]; +EXPORT_C TInt TMyVariant::VariantBind(TInt aId, TIsr aIsr, TAny* aPtr) + { + TInt r = KErrNone; + aId = (-aId)-1; // convert to positive number >=0 + If (aId >= KInterruptSourceCount || aId < 0) + { + r = KErrArgument; // Illegal interrupt number + } + else + { + SInterruptHandler& h = VariantHandlers[aId]; + TInt irq = NKern::DisableAllInterrupts(); + if (h.iIsr != VariantSpuriousHandler) + { + r = KErrInUse; // Already bound to an ISR + } + else + { + h.iPtr = aPtr; + h.iIsr = anIsr; + } + NKern::RestoreInterrupts(irq); + } + return r; + }

The example provides a version of Interrupt::Bind() which calls a variant layer function VariantBind() to process device specific interrupts (here assigned negative Ids) +to ISRs held in the variant specific table VariantHandlers.

+Interrupt +Technology Guide +Interrupt +Client Interface Guide +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-2EC16C9C-7241-46B2-B569-B89751933C57.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-2EC16C9C-7241-46B2-B569-B89751933C57.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,13 @@ + + + + + +DMA Configuration OverviewHow to configure a DMA controller in the Platform Specific +Layer. \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-2ECF13A1-9D56-5740-A09F-8267E6A45DD9.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-2ECF13A1-9D56-5740-A09F-8267E6A45DD9.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,106 @@ + + + + + +Porting the Power Resource ManagerThis tutorial describes how to port the Platform Specific +Layer (PSL) of the Power Resource Manager (PRM) +and how to modify clients, such as device drivers, to use the PRM +framework. +

Purpose

The PRM is a framework for managing system power resources. This +framework improves portability across different platforms and reduces +device driver complexity.

The PRM framework is split into +two layers:

Platform Independent +Layer - the PIL is a generic software layer that is implemented by +Symbian. This is the base virtual class for the Power Resource Controller +(DPowerResourceController),
Platform Specific +Layer - the PSL is developed specifically to interface with the target +hardware by licensees. This is the class derived from DPowerResourceController.

Other acronyms used in this document set:

LDD - Logical +Device Driver. The higher layer of abstraction within the Symbian +platform device driver framework which implements common functionality +among differing pieces of hardware of one type,
PDD - Physical +Device Driver. The lower layer of abstraction within the Symbian platform +device driver framework which implements functionality that is specific +to a particular piece of hardware.

Intended audience

This document is intended +to be used by Symbian platform device creators.

Required +background

The reader of this document is assumed to have +knowledge of the Symbian platform device driver model and base port layering and components.

Device Driver Concepts,

Introduction

The PRM provides a unique place +where all the current power states for resources can be obtained at +any time. The sum of all internal and external power states defines +the current system-wide power state.

Setup and configuration +requirements

The PRM component is implemented as a kernel +extension with an exported public interface that is accessible to +kernel side components through statically linking against its export +library. The export library is built from the resource manager and +the resource manager libraries.

There are two versions available:

basic resource +manager - provides essential or required functionality for static +resources.

The basic version of the PIL layer is compiled +into resmanpsl.lib. This kernel library must +be included by the PSL to produce the kernel extension.
extended resource +manager - provides additional support for dynamic resources and resource +dependencies.

The extended version of the PIL layer is complied +into resmanextenedpsl.lib. This kernel library +must be included by the PSL to produce the kernel extension.

Device drivers that require the use of the PRM should link +against the appropriate library. resman.lib to +use the basic version and resmanextended.lib to +use the extended version of the PRM.

Building the PRM for +the target platform

The PRM is an early extension, so +the targettype in the mmp file +must be set to kext. If the PRM is implemented as +a PDD the targettype in the mmp file should be should +be pdd.

Boot sequence

The +PRM cannot be used to operate on power resources until later in the +boot sequence when the kernel allows the scheduling of other threads. +During this time it is not possible to read or change the state of +resources, but DPowerResourceController::PostBootLevel() can be used to specify the state of specific resources and the PRM +can change the state of resources to appropriate levels before the +PRM is fully initialised.

PostBootLevel() is used within the extension entry point, during this time PRM is +not fully initialised. Note: This function can only be used +for static resources and static resources with dependencies.

static TInt PostBootLevel(TUint aResId, TInt aLevel);

PostBootLevel() takes the resource ID and the +post boot level that the level a resource needs to be after it is +initialised. Typically the post boot level is only known to the PSL. +However kernel extensions (and the variant) may request a post boot +level.

If a kernel extension needs to know if certain resources +have reached the post boot state in order to complete its own initialisation +then the kernel extension should queue resource state change notifications +for the resource when first registering as clients with the PRM. Note: notification requests are accepted before the PRM is fully +initialised.

Variants or kernel extensions can register static +resources before the PRM is fully initialised with DPowerResourceController::RegisterStaticResource(). This API can only be used by static resources and not by static +resource that support dependency. See DoRegisterStaticResources().

Using +the Power Resource Manager

Porting the PRM consists of +implementing the PSL layer for a given hardware platform and modifying +clients, such as device drivers, to use the PRM framework.

The following tasks are covered in this tutorial:

Implement the controllable +power resources,
Implement the PSL +for the target,
Port the client +drivers to use the PRM (to control the implemented resources),
Debugging the PRM,
Testing the PRM +PSL.

+Power +Resource Manager (PRM) +Power +Management Tutorials +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-3046453A-AB3A-5491-87A0-00F3514D4768.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-3046453A-AB3A-5491-87A0-00F3514D4768.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,109 @@ + + + + + +Vector +Floating Point Implementation TutorialThis topic describes how to configure a base port to use the floating +point coprocessor. +

ARM provide a hardware floating point coprocessor that provides floating +point computation that is fully compliant with IEEE Std 754-1985.

To support a coprocessor, you need to:

Configure the Kernel +to use VFP through a macro setting in the Variant.
Configure the ROM to +include a Kernel extension to support IEEE-without-exceptions mode.
Configure the ROM to +include VFP support libraries.
Port the User Library +to implement its Math class functions to use VFP-enabled +functions. This is described in the Math +Class Port Tutorial.

Variant configuration

Define the macro __CPU_HAS_VFP in +the base port’s variant.mmh. This macro forces the inclusion +of VFP support when the kernel is re-compiled. As an example, see the Integrator +CM1136 base port, and specifically: ...\integrator\core\cm1136\variant.mmh. +When the kernel is re-compiled, VFP support is included.

HAL configuration

Add the HAL attribute for VFP +to your base port's config.hcf file, by adding the following +line to this file:

EHardwareFloatingPoint = GetHardwareFloatingPoint

As an example, see the Integrator CM1136 base port, and specifically: ...\integrator\core\cm920\hal\config.hcf

See +also Creating the Config +& Values files in the HAL Port +Implementation Tutorial for more information.

IEEE-without-exceptions +mode

Symbian platform supports two execution modes :

+ + + +

RunFast

In this mode, denormalised numbers, i.e. those outside the range +of normal floating point values, are treated as zero, and a default NaN (Not +a Number) value is used for all NaN situations regardless +of the inputs.

+ + +

IEEE-without-exceptions

In this mode, denormalised numbers are treated as their actual values, +and the IEEE754-mandated values for NaN s are used.

The +floating point model mandated by the Java specification is identical to this +mode, and means that this mode is sufficient to implement a VFP-accelerated +JVM.

+ + + +

NOTE: There may be some applications that depend on the correct +handling of calculations involving, or resulting in, very small numbers; for +such applications, RunFast mode may not be appropriate.

RunFast mode

For RunFast execution +mode, nothing else needs to be implemented, and no extra components need to +be added to the ROM.

IEEE-without-exceptions +mode

For IEEE-without-exceptions mode, you need +to include the kernel extension evfp.dll in the ROM image +by adding the following line into the .iby or .oby file +for your port:

extension[VARID]=KERNEL_DIR\DEBUG_DIR\evfp.dll \sys\bin\evfp.dll

As an example, see the Integrator CM1136 base port, and specifically: ...\integrator\core\cm1136\rom\base_integrator1136.iby

Note:

This is the default +execution mode.
It is possible to switch +between this execution mode and the RunFast execution mode.
evfp.dll is +built using ARM's VFP support code and can only be built using the RVCT tool +chain.

VFP-enabled +floating port support libraries

Symbian platform provides both +the VFP version and the non-VFP version of the floating point support functions. +You choose the VFP version when you build your ROM image by specifying the VFPHELPERS macro +to BUILDROM. +This causes the ROM building tool chain to replace the following three DLLs:

drtaeabi.dll
dfpaeabi.dll
dfprvct2_2.dll

There are two ways to specify the VFPHELPERS macro:

by adding the following +line into the header.iby file for your port:
#define VFPHELPERS
You +use this technique to permanently include the VFP versions in your ROM image.
by passing VFPHELPERS as +a pre-processor argument using the -D option when invoking BUILDROM, i.e. :

BUILDROM +-DVFPHELPERS ...

You use this technique if you only want +to include the VFP versions for a specific ROM image, for example, when testing.

If you use the first technique, you can still provide non-VFP versions +for a specific ROM image by passing NOVFPHELPERS as a pre-rpocessor +argument using the -D option when invoking BUILDROM, +i.e. :

BUILDROM -DNOVFPHELPERS ... +

In effect, you are overriding the definition in the header.iby file.

For +example, see the Integrator CM1136 base port, and specifically: ...\integrator\core\cm1136\rom\header.iby

+Math Class +Port Tutorial + +User-Side Hardware Abstraction +Vector Floating +Point (VFP) +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-306A0B41-94CD-534A-B3BA-FAECB858E9A9.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-306A0B41-94CD-534A-B3BA-FAECB858E9A9.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,29 @@ + + + + + +Platform-Specific +FunctionsExplains how bootstrap functions are organised. +

Platform-specific source code needs to implement a set of standard functions +that are called by the generic source code. It also needs to provide a set +of standard MMU permission and cache attribute definitions.

Standard functions are organised in the following way:

a set of public functions +that the Symbian platform generic source links to directly
a set of functions that +are contained in a table, known as the boot table.
a set of entries that +define MMU and cache attributes to be used for standard memory and I/O areas; +this set of entries is also contained in the boot table.

Refer to the Template bootstrap source code: os/kernelhwsrv/bsptemplate/asspandvariant/template_variant/bootstrap/template.s

+All bootstrap source code should be position independent. + \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-30978E00-D244-44CD-8F4E-9676DF172A52.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-30978E00-D244-44CD-8F4E-9676DF172A52.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,39 @@ + + + + + +Driver-side +HandlingThis document describes how device drivers handle asynchronous +requests. +

Drivers generally implement the DoRequest() function +in the LDD to handle the received asynchronous messages.

The implementation reads the request type and other passed arguments, and +initiates handling of the request appropriately.

The return value of this function only indicates the status of the message +reception to the driver. It does not actually indicate the request completion +result.

+TInt DExDriverLogicalChannel::DoRequest(TInt aReqNo, TRequestStatus* aStatus, + TAny* a1, TAny* a2) + { + switch (aReqNo) + { + case RExDriverChannel::ERequestTransmitData: + // Call TransmitData function + r = TransmitData ((const TDesC8*)a1); + // The status object is stored + // to be used when notifying the completion of the + // request at a later point. + // + iTxDataStatus = aStatus; + break; + } + return r; + } + \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-3102F778-DD2F-4C87-A0DF-7FA44C9709D8.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-3102F778-DD2F-4C87-A0DF-7FA44C9709D8.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,38 @@ + + + + + +Multiple +Client SupportThis document describes how multiple clients can access a driver +over a single logical channel. +

A single channel has a single handle which is shared by driver users. A +driver can allow or prevent the sharing of a handle to a logical channel between +multiple users. This policy is implemented by the DLogicalChannel::RequestUserHandle() function. +The default implementation does not restrict sharing of the channel, but a +driver can override the function to change this.

In the following example, the driver ensures that only the intended clients +can get the handle and access the driver. Any other client that tries to share +the handle gets a KErrAccessDenied error.

+TInt DExDriverLogicalChannel::RequestUserHandle(DThread* aThread, + TOwnerType aType) + { + // Handle should be provided only to the intended client. Any + // other clients that try to get a handle to the driver should get an access + // denied error. + if ( aType!=EOwnerThread || aThread!=iClient) + return KErrAccessDenied; + return KErrNone; + } +

DLogicalChannel::RequestUserHandle() only restricts +the user from sharing or duplicating an existing channel. It does not restrict +another process from opening its own separate channel on the same device.

More than one user can access the driver at the same time. It is +up to the driver to manage and provide correct and secure access to the driver.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-315DD62B-8669-471F-BDDC-BC4D700AEA60.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-315DD62B-8669-471F-BDDC-BC4D700AEA60.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,29 @@ + + + + + +Interrupt Client Interface Quick StartBasic steps to use the client interface of the Interrupt +platform service. +

The Interrupt platform service provides an interface that allows +clients to have access to interrupts.

Basic +steps

The following are the basic steps to use the Interrupt +platform service:

The Interrupt Technology +Guide describes the basic concepts of the Interrupt platform +service.
The Interrupt Client +Interface Guide explains the client interface and how to use +it.
The Interrupt Build Guide explains how to include the Interrupt platform service in a build.
The Interrupt Testing +Guide explains how to test the Interrupt platform service.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-31CE66F2-B36C-56ED-A399-BA9EFA179DED-master.png Binary file Adaptation/GUID-31CE66F2-B36C-56ED-A399-BA9EFA179DED-master.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-31CE66F2-B36C-56ED-A399-BA9EFA179DED_d0e75538_href.png Binary file Adaptation/GUID-31CE66F2-B36C-56ED-A399-BA9EFA179DED_d0e75538_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-31FFA810-129A-4E35-A47F-C6D3C1C71D5E.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-31FFA810-129A-4E35-A47F-C6D3C1C71D5E.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,15 @@ + + + + + +Register Access Tools GuideTools required for the Register Access platform service. +

There are no specific tools required to use or implement the Register +Access platform service.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-32B82E5C-FD53-48E6-9ABC-88F82ACF71BC.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-32B82E5C-FD53-48E6-9ABC-88F82ACF71BC.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,56 @@ + + + + + +The +LDD Entry Point and FactoryThis document describes how LDDs are created. +

An LDD +must define an entry point function using the macro DECLARE_STANDARD_LDD, +or DECLARE_EXTENSION_LDD in the case of kernel extensions. +This must create an LDD factory object derived from DLogicalDevice:

DECLARE_STANDARD_LDD() + { + return new DerivedLogicalDevice; + }

This factory object is created on the kernel heap. Its +purpose is to create the logical channel, the object through which all client +interaction with the driver will occur.

DLogicalDevice is +derived from DObject, and is, therefore a reference-counting +object. It also means that DLogicalDevice objects are given +a name, as these objects are always subsequently found by name. The user-side +specifies the name of the logical device through the first parameter in the +user-side call to RBusLogicalChannel::DoCreate().

The +file extension of a LDD DLL can be any permitted Symbian Platform name but, +by convention, the LDD DLL has the extension .LDD. Device +driver DLLs are polymorphic interface DLLs. When building LDDs, specify a +target type of ldd in the .mmp file.

An +LDD is loaded by calling User::LoadLogicalDevice(). This +static function:

loads the DLL into RAM, +if necessary
calls the exported function +at ordinal 1 to create the factory object, the DLogicalDevice derived +object
places the factory object +into the appropriate object container.

This only needs to be done once, not every time the driver is +used.

If an LDD needs to perform initialisation at boot time (before +the driver is loaded by User::LoadLogicalDevice()) then +specify the entry point macros DECLARE_STANDARD_EXTENSION and DECLARE_EXTENSION_LDD.

DECLARE_STANDARD_EXTENSION() + { + // initialise code here + } + +DECLARE_EXTENSION_LDD() + { + return new DMyLogicalFactory; + }

In order for the kernel to initialise the LDD extension +at boot time then the .oby file must specify the extension keyword. +Also note that initialisation of the extension will not load +the LDD: this still has to be done through a call to User::LoadLogicalDevice().

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-3335663A-BC11-556E-B5A6-F83622AE34C3.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-3335663A-BC11-556E-B5A6-F83622AE34C3.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,21 @@ + + + + + +Audio Driver Porting +Implementation TutorialDescribes the steps to implement a physical device driver (PDD) +for the Sound Driver. +

The audio device driver +implementation may provide for playback, recording, or both at the same time, +but there are design considerations for each option.

+ +Concepts +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-33A7D8D4-84D6-56EA-8EAB-2A3A3ACABF77.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-33A7D8D4-84D6-56EA-8EAB-2A3A3ACABF77.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,299 @@ + + + + + +ReferenceProvides a summary of related documentation for the MMC Controller +to which you can refer. +

API Reference

Peripheral bus layer + + + +

Item

Header

+ + +

DMediaChangeBase

pbus.h

+ + +

DPBusPowerHandler

pbus.h

+ + +

DPBusPrimaryMedia

pbusmedia.h

+ + +

DPBusPsuBase

pbus.h

+ + +

DPBusSocket

pbus.h

+ + +

TMediaState

pbus.h

+ + +

TPBusCallBack

pbus.h

+ + +

TPBusCallBackFn

pbus.h

+ + +

TPBusIsr

pbus.h

+ + +

TPBusPsuInfo

pbus.h

+ + +

TPBusPsuState

pbus.h

+ + +

TPBusPsuStatus

pbus.h

+ + +

TPBusState

pbus.h

+ + +

TPBusType

pbus.h

+ + +

TPsuVoltChkMethod

pbus.h

+ + + +

MultiMediaCard layer + + + +

Item

Header

+ + +

DMMCMediaChange

mmc.h

+ + +

DMMCPsu

mmc.h

+ + +

DMMCSession

mmc.h

+ + +

DMMCSocket

mmc.h

+ + +

DMMCStack

mmc.h

+ + +

SMF_BEGIN

mmc.h

+ + +

SMF_BPOINT

mmc.h

+ + +

SMF_CALL

mmc.h

+ + +

SMF_CALLMEWR

mmc.h

+ + +

SMF_CALLMYS

mmc.h

+ + +

SMF_CALLWAIT

mmc.h

+ + +

SMF_END

mmc.h

+ + +

SMF_EXIT

mmc.h

+ + +

SMF_EXITWAIT

mmc.h

+ + +

SMF_GOTONEXTS

mmc.h

+ + +

SMF_GOTOS

mmc.h

+ + +

SMF_INVOKES

mmc.h

+ + +

SMF_INVOKEWAITS

mmc.h

+ + +

SMF_JUMP

mmc.h

+ + +

SMF_JUMPWAIT

mmc.h

+ + +

SMF_NEXTS

mmc.h

+ + +

SMF_RETURN

mmc.h

+ + +

SMF_STATE

mmc.h

+ + +

SMF_WAIT

mmc.h

+ + +

SMF_WAITS

mmc.h

+ + +

TBusWidth

mmc.h

+ + +

TCID

mmc.h

+ + +

TCSD

mmc.h

+ + +

TExtendedCSD

mmc.h

+ + +

TMMCardControllerInterface

mmccd_ifc.h

+ + +

TMMCArgument

mmc.h

+ + +

TMMCBusConfig

mmc.h

+ + +

TMMCCallBack

mmc.h

+ + +

TMMC

mmc.h

+ + +

TMMCCmdDirEnum

mmc.h

+ + +

TMMCCommandDesc

mmc.h

+ + +

TMMCCommandEnum

mmc.h

+ + +

TMMCCommandSpec

mmc.h

+ + +

TMMCErrTypedef.xml

mmc.h

+ + +

TMMCMachineInfo

mmc.h

+ + +

TMMCMediaTypeEnum

mmc.h

+ + +

TMMCStackConfig

mmc.h

+ + +

TMMCStateMachine

mmc.h

+ + +

TMMCStatus

mmc.h

+ + + +

State machine function list

This is a list of state +machine functions defined for the MultiMediaCard controller.

Top level state machine functions

DMMCStack::CIMUpdateAcqSM()
DMMCStack::CIMInitStackSM()
DMMCStack::CIMCheckStackSM()
DMMCStack::CIMCheckStackSM()
DMMCStack::NakedSessionSM()
DMMCStack::CIMSetupCardSM()
DMMCStack::CIMReadWriteBlocksSM()
DMMCStack::CIMEraseSM()
DMMCStack::CIMReadWriteIOSM()
DMMCStack::NoSessionSM()

Child state machine functions

DMMCStack::AcquireStackSM()
DMMCStack::AttachCardSM()
DMMCStack::ExecCommandSM()
DMMCStack::IssueCommandCheckResponseSM()
DMMCStack::PollGapTimerSM()
DMMCStack::RetryGapTimerSM()
DMMCStack::DoPowerUpSM()
DMMCStack::InitClockOnSM()
DMMCStack::ProgramTimerSM()
DMMCStack::IssueMMCCommandSM()

Engineering +Specifications

No specifications are published.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-34D1D0BF-20DE-5677-A067-8FF9DD72E703.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-34D1D0BF-20DE-5677-A067-8FF9DD72E703.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,331 @@ + + + + + +Power Controller DPowerController Implementation TutorialThis topic describes how to implement the DPowerController class to provide the main power controller functionality in a base +port. +

DPowerController is defined as:

+class DPowerController : public DBase + { +public: + IMPORT_C DPowerController(); + IMPORT_C void Register(); + IMPORT_C void WakeupEvent(); + +#ifndef __X86__ + IMPORT_C TInt RegisterResourceController(DBase* aController, TInt aClientId); +private: + struct SResourceControllerData + { + DBase* iResourceController; + TInt iClientId; + } iResourceControllerData; +#endif + +public: + volatile TPowerState iTargetState; +public: + virtual void CpuIdle() = 0; + virtual void EnableWakeupEvents() = 0; + virtual void DisableWakeupEvents() = 0; + virtual void AbsoluteTimerExpired() = 0; + virtual void PowerDown(TTimeK aWakeupTime) = 0; + }; + +

The first three functions are exported from the kernel, EKERN.EXE, while the other five pure virtual functions +are implemented by your base port. You do not need to export any other +functions.

Initialising the power controller,
DPowerController::RegisterResourceController(),
DPowerController::EnableWakeupEvents(),
DPowerController::AbsoluteTimerExpired(),
DPowerController::PowerDown(),
CpuIdle().

Initialising +the power controller

Typically, you implement your derived +class in a power management kernel extension, which has the opportunity +to perform initialisation before the system itself is fully initialised. +This is done via the extension's DLL entry point. You use the DECLARE_STANDARD_EXTENSION() macro as a wrapper around +your initialisation code. There are at least three things to do here:

create an instance +of your power controller object
register your +power controller object with the Symbian platform power manager, by +calling DPowerController::Register(). Your power +controller cannot be used by the Symbian platform power manager until +it has been registered.
if you intend +to use a battery monitor, then you would create it and register it +as the HAL handler to deal with THalFunctionGroup::EHALGroupPower calls. See Battery Monitor Implementation Tutorialc and Power HAL Handler +Tutorial for more detail.

For example:

DECLARE_STANDARD_EXTENSION() + { + TInt r=KErrNoMemory; + + // Create the power controller object, and register it. + DPowerController* pC = new DYourPowerController; + if !(pC) + { + return (r); + } + pC->Register(); + + // Create the battery monitor. + DBatteryMonitor* pM = new DYourBatteryMonitor; + if !(pM) + { + return(r); + } + + r = KErrNone; + return(r); + }

DPowerController::RegisterResourceController()

The function DPowerController::RegisterResourceController() allows the Resource Controller to register itself with the Power +Controller. See registering with the resource controller in the PSL implementation +document.

To support idle power management the Power Controller's +PSL must override RegisterResourceController() to +include the registration of a list of resources whose states are of +interest to idle power management.

Idle power management

The Power Controller can assemble +a list of resources whose state it is interested in from a NULL thread +in an array of SIdleResourceInfo structures. Each +entry in the list contains the resource ID that the power controller +must enter before registering with the PRM. The resource list should +be created in the kernel heap or data section.

The example +below creates a buffer to capture the state of all static resources. +The PRM captures the information using DPowerResourceController::RegisterResourcesForIdle().

... +//Allocate buffer for Idle resource management + NKern::ThreadEnterCS(); + pBuf = HBuf::New(numResources * sizeof(SIdleResourceInfo)); + NKern::ThreadLeaveCS(); + if(!pBuf) + { + return KErrNoMemory; + } + SIdleResourceInfo* pI = (SIdleResourceInfo*)pBuf->Ptr(); + +//Update resource ID + for(TUint c = 0; c < numResources; c++) + { + pI[c].iResourceId = c+1; + } + r = (iResourceControllerData.iResourceController)->RegisterResourcesForIdle(iResourceControllerData.iClientId, numResources, (TPtr*)pI); + ...

The first parameter passed to RegisterResourcesForIdle() is the client Id generated for the power controller this is the +client ID passed by the PRM when calling RegisterResourceController.

Note: RegisterResourcesForIdle() is not exported and is only available for use by the Power Controller +to register resources for idle power management. Note: RegisterResourcesForIdle() can only be called by the Power +Controller once.

DPowerController::EnableWakeupEvents() virtual void EnableWakeupEvents() = 0;

The Symbian Power Model defines 3 generic system-wide power states: Active, Standby and Off, as defined in the Symbian platform +power model.

Each of the system-wide low power states: Standby and Off, has a defined set of wake-up events. +If a wake-up event occurs while the system is preparing to transition +into one of these low power states, or when the system is in the Standby state, then this can result in the system moving back +to the Active power state. Wake-up events may be different +for different target power states. Wake-up events are platform-specific +hardware events, and it is your base port that decides which events +count as wake-up events.

When is it called?

DPowerController::EnableWakeupEvents() is called called by the power manager as a result of a user side call to Power::EnableWakeupEvents(). The class Power is the user side interface to the power manager, and is used by +the user side entity that is responsible for moving the device into +a low power state.

Context

When the user side entity decides to move +the device to a low power state, it sends a notification to all of +the user side power domains registered with it, giving their applications +a chance to save their data and state. However, before doing this, +it calls Power::EnableWakeupEvents(). It also calls Power::RequestWakeupEventNotification() so that it can +be informed of a wake-up event. If it is notified of a wake-up event, +it can halt, and reverse the user side response to the power transition.

+ +

Before calling DPowerController::EnableWakeupEvents(), the power manager sets the iTargetState member +of DPowerController to the applicable TPowerState. This means that you can enable the appropriate set of wake-up events.

Once the user side transition is complete, it calls Power::PowerDown() in the user side interface to the power manager, which results in a call to DPowerController::PowerDown() in the power controller. This starts the transition of all power handlers to a low power state, a potentially long process. +This means that the power controller needs the ability to detect wake-up +events so that it can halt, and reverse the power transition.

Implementation issues

There are three possibilities +in dealing with wake-up events:

if wake-up events +are not handled by specific peripheral drivers, you could set up the +hardware so that wake-up events are recorded in a location accessible +by the software. Prior to completing the system power transition, +the Power controller would check the relevant hardware to see whether +a wakeup event had occurred. On detecting a wake-up event it would +tell the power manager by calling DPowerController::WakeupEvent().
if wake-up events +are not handled by specific peripheral drivers, you could arrange +for wake-up events to interrupt the CPU. The code that services those +interrupts would tell the power manager by calling DPowerController::WakepEvent().
if wakeup events +are intercepted, serviced and cleared by peripheral drivers, then +the following outline solution could be adopted:
- The power controller +would need to publish a list of wake-up events, preferably as a bit +mask, and export an API which peripheral drivers could use to notify +the power controller that a wake-up event has occurred. The following +interface class could be used for this purpose:
  class TPowerController + { +public: + inline static void SetPowerControllerPointer(DPowerController* apPowerController) + { iPowerControllerPointer = apPowerController; } + IMPORT_C static void WakeupEventOccurred(TUint aWakeupEvent); + … // other methods if required +private: + DPowerController* iPowerControllerPointer; + }; +
  The class would be implemented +as part of the power management kernel extension and SetPowerControllerPointer() would be called when initialising the power controller, but after creation of the +power controller object.
  
  Those peripheral drivers that intercept +wake-up events would need to link to the power controller DLL (i.e. +the power management kernel extension).
  
  On the occurrence +of a wake-up event, the peripheral driver software servicing that +event would notify the power controller by calling WakeupEventOccurred(), specifying the appropriate wake-up event bit(s).
  
  You might +implement WakeupEventOccurred() as follows:
  EXPORT_C void TPowerController::WakeupEventOccurred(TUint aWakeupEvent) + { + if(iPowerControllerPointer->iWakeupEvents & aWakeupEvent) + { + iPowerControllerPointer->WakeupEvent(); + } + }
  where iWakeupEvents is a data +member defined in your DPowerController -derived +class that contains the bitmask representing the wake-up events. The +bitmask groups wakeup events according to the target power state.

When the peripheral driver powers down, it should leave the +hardware that generates the wake-up event powered and enabled for +detection. Thus, if a wake-up event of the type handled by this peripheral +driver occurs, it will not be serviced in the normal way, but will +be left pending until the power controller services it.

When +the power controller’s DPowerController::PowerDown() function is called, the power controller must check the peripheral +hardware directly to see whether the wakeup event has happened, or +is happening right now, prior to transitioning the device to the target +system-wide low power state. If the wake-up event is found to have +happened then DPowerController::PowerDown() would +return immediately, instead of initiating the power handlers power down of the peripheral drivers.

DPowerController::AbsoluteTimerExpired() virtual void AbsoluteTimerExpired() = 0;

When is it called?

DPowerController::AbsoluteTimerExpired() is called by the power manager whenever an absolute timer expires. An absolute +timer is one that is set to complete at a specific time, as queued +by a call to RTimer::At().

Implementation issues

If absolute timer expiration +is one of your wake-up events, then your implementation of DPowerController::AbsoluteTimerExpired() should call DPowerController::WakeupEvent() to notify the power manager +that a wake-up event has happened.

It is recommended that +you track absolute timers.

DPowerController::PowerDown() virtual void PowerDown(TTimeK aWakeupTime) = 0;

When is it called?

DPowerController::PowerDown() is called by the power manager to move the device into one of the system-wide +low power states: Standby or Off.

Typically, +this is a result of the user side entity that is responsible for moving +the device into a low power state calling Power::PowerDown() in the user side interface to the power manager.

If physical RAM defragmentation is implemented you may wish to include calls to TRamDefragRequest::DefragRam() within this function to enable defragmentation of RAM zones that +can then be powered down.

Context

The target state is defined by the value of +the iTargetState member of DPowerController, as set by the power manager.

Implementation issues

Implementation depends on the +target state:

if the target +state is Standby, as implied by a value of TPowerState::EPwStandby in DPowerController::iTargetState, then the power +controller should put the hardware into a state corresponding to the Standby state.

If at least one wake-up event has been +detected and recorded since the last call to DPowerController::EnableWakeupEvents(), then PowerDown() should return immediately; otherwise, +it should continue with the process of putting the device into Standby; execution of the function will halt, and can only continue, +and return, when a wake-up event occurs.
if the target +state is Off, as implied by a value of TPowerState::EPwOff in DPowerController::iTargetState, then PowerDown() must never return. Typically, the power +controller turns the device off, but can choose to perform other device-specific +action such as a system reboot.

The TTimeK parameter passed to the function +is a system time value. If non-zero, it specifies the time when the +system should wakeup. The kernel calculates it as the time that the +next absolute timer expires. Typically, your implementation will use +the Real Time Clock module to generate an event at the specified time, +and this will cause a return to the Active state. This implies +that the base port should enable Real Time Clock event detection during Standby.

The Symbian definition of the Standby state usually translates into the hardware manufacturer’s CPU “Standby” +or “Sleep” modes of operation. Typically, the internal clocks associated +with the core and some of the core peripherals, or their power supply, +are suppressed, and their internal state is not preserved. In this +case, the state of the core and core peripherals should be saved before +going into Standby so that they can be restored when the system +wakes-up. Note the following:

for the core +state, save the current mode, the banked registers for each mode, +and the stack pointer for both the current mode and user mode
for the core +peripherals, save the state of the interrupt controller, the pin function +controller, the bus state controller, and the clock controller
for the MMU +state, save the control register, the translation table base address, +and the domain access control, if this is supported
flush the data +cache and drain the write buffer.

If all of this data is saved to a DRAM device, then this +should be put into self refresh mode.

Peripherals modules +involved in the detection of wake-up events should be left powered.

Tick timer events should be disabled, and the current count of +this and any other system timers should be saved; relevant wake-up +events should be left unmasked, and any others should be disabled.

DPowerController::CpuIdle() virtual void CpuIdle()=0;

When is it called?

DPowerController::CpuIdle() is called whenever the Null thread is scheduled to run. This can +happen as soon as the power model has been installed. It is the mechanism +through which your base port can increase power savings when the system +becomes inactive by moving the CPU or the system into a low power +mode.

If physical RAM defragmentation is implemented you may wish to +include calls to TRamDefragRequest::DefragRam() within this function to enable defragmentation while the device +is idle.

Implementation issues

The implementation can call +the Variant or ASSP implementation of Asic::Idle().

The idle state is usually implemented via a Wait-For-Interrupt +type instruction that will usually suspend execution of the CPU, possibly +triggering other ASIC power saving actions, and will resume execution +when any unmasked interrupt occurs.

Suppressing the system tick interrupt

To further increase +power savings during CPU Idle, a base port can choose to suppress +the system tick interrupt until the next nanokernel Timer (as implemented +by NTimer) is due to expire. Nanokernel timers +are the basic timing service and all Symbian platform tick-based timers +and time-of-day functions are derived from nanokernel timers.

In EKA2, timing services rely on a hardware timer, which is programmed +by the base port Variant code, to generate the system tick. We refer +to this as the system timer.

Typically, the platform-specific +ASSP or Variant object has a pointer to the nanokernel timer queue, +an NTimerQ object. The number of ticks before the +next NTimer is due to expire can be found by calling NTimerQ::IdleTime().

Before going into Idle mode, CpuIdle() disables the hardware timer used to generate the +system tick (i.e. the system timer) for the number of ticks to be +suppressed; i.e. the system timer is reset to go off and generate +an interrupt only when the NTimer expires. Note +that the clock supply to the hardware timer must be left enabled.

On returning from Idle mode, the software must examine the system +timer and decide whether the NTimer expiration +was responsible for waking up the processor, or whether it was due +to some other interrupt.

If waking up was due to the NTimer, the system timer must be reset to generate the +system tick at the frequency desired, and the tick count, NTimerQ::iMsCount, must be adjusted with the NTimer expiration time. As the expiration time is always an integer multiple +of the number of ticks, then the NTimerQ::Advance() function can be used for this purpose.

If waking up was +due to another interrupt, then the software must read the system timer +and calculate the time elapsed since going into Idle mode, and adjust +the system tick count with the elapsed time (which could be a fractional +number of ticks) and reprogram the system timer to continue generating +the tick after the correct interval, as above.

If the hardware +timer that is used to generate the system ticks does not use a Compare-Match +function, then some care has to be taken not to introduce skewing +when manipulating the timer value directly. If the timer needs to +be reloaded with the new value to give the next tick, then the software +usually “spins”, waiting for the hardware timer to change, and then +reloads it. This way the timer will always be reloaded on an edge +of its internal clock.

Waking up from “Sleep” modes with long wakeup latencies

Often, to further enhance power savings, the CPU and some peripherals +are moved into a hardware “sleep” mode when CpuIdle() is called. This could be of long latency, and waking up could take +longer than the system Tick period. There are two situations:

if the wakeup +time can be determined precisely, then CpuIdle() programs +the system timer to bring the CPU back from the “Sleep“ mode at a +time corresponding to the next NTimer expiration +(as a number of Ticks to suppress) minus the number of ticks +it takes to wake up from that mode. On waking up on the timer, the +System tick count should be adjusted with the total number of ticks +suppressed, i.e. the count corresponding to the time of the NTimer expiration.
If the wakeup +time cannot be known deterministically, then the above scheme must +be combined with another system to allow adjusting the system timer +from the hardware Real Time Clock (RTC).

Typically, the hardware +RTC is clocked with a 1Hz clock, and can be programmed to interrupt +the CPU on multiples of one second intervals. The clock supply to +the RTC must be left enabled on going into "sleep" mode.

To guarantee that timed events occur when they are due, the +CPU should only be allowed to go to into the long latency hardware +“sleep” mode if the RTC can be guaranteed to complete a second tick +before the CPU is due to wakeup.

Note that if waking up from +hardware “Sleep” mode takes a non-negligible amount of time, extreme +care should be taken when deciding to move the platform into that +mode. For example, if a receive request is pending on a data input +device and the CPU reaches the Idle mode and the platform +is transitioned into a “sleep” state and data arrives while +it is still in that state, then there is a possibility that +the system will not wake up on time to service the incoming data.

Validation

The e32test programs t_power, and t_timer will put the system into standby +and resume off a timer.

+Power +Management +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-3574BE12-9DA9-573D-8545-3B073005A139.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-3574BE12-9DA9-573D-8545-3B073005A139.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,67 @@ + + + + + +Configuration: +Timer ConstantsDescribes how to set the values of timer constants that change +the behaviour of the Digitizer Driver. +

The timing constants are defined near the beginning of the template port +implementation of the platform specific layer in ...\template\template_variant\specific\xyin.cpp.

The values and their meaning are as follows:

KInterSampleTime

This +constant determines the rate at which individual samples within a group are +collected.

A group of samples is collected when the pen is down, and, +in the template port, this is handled by DTemplateDigitiser::TakeSample().

Once +all the samples in a group have been collected, the function calls Digitiser::RawSampleValid() in +the platform independent layer, whose main purpose is to ensure the validity +of the samples by checking the spread. If the samples appear valid, it averages +the samples to obtain the current position.

The setting of the timer +constant depends on the sample resolution of the digitizer:

A high resolution can +lead to more jitter between samples, and therefore more smoothing is required +to obtain nice steady values. This argues for higher sampling rates, and a +smaller value of KInterSampleTime.
A low resolution means +that there is very little variation between consecutive samples, and therefore +fewer are required. This argues for lower sampling rates, and a larger value +of KInterSampleTime.

Another consideration when setting this constant is the speed of +the communications between the MPU and the digitizer.

In the Symbian +reference ports, this value varies between 1 and 3.

KPenDownDelayTime

This +value is used in the implementation of the pen +interrupt interrupt service routine (ISR). It represents a delay, measured +in nano-kernel ticks, between a pen down event and the start of the collection +of digitizer samples.

The value is optional. Choose a value of 0 if +no delay is required. Typically, a value of 2 is chosen.

KInterGroupTime

This +value is used in DTemplateDigitiser::WaitForPenUp() and DTemplateDigitiser::WaitForPenUpDebounce(). +After a group of samples has been collected, there is a delay, dictated by +the value of this constant, before the collection for the next group begins.

The +inverse of the sum of KInterSampleTime, +and KInterGroupTime will therefore determine the frequency +at which groups of samples are taken. This, in turn, dictates how often pen +movement events are issued, and, if no interrupt is used on pen up, how quickly +this situation is ascertained. The constant is optional. Typically it is set +at 1ms

The delay is optional, a value of zero meaning that there is +no delay. Typically, a value of 1 is chosen.

KPenUpDebounceTime

This +value is used in DTemplateDigitiser::TakeSample(). If, during +sample collection, the pen goes up, then the digitizer will wait for this +period of time before deciding whether the removal of the pen is momentary, +or whether it is an intentional removal - this is also referred to as debounce.

If, +after the delay, the pen is still up, then a pen-up event is issued; otherwise +the state of the digitizer reverts to collecting mode, resetting the sample +buffer

Typically, this value is set to around 30.

KPenUpPollTime

This +value is used in DTemplateDigitiser::TakeSample().

If +the pen is down when the system powers on, then the digitizer is sampled using +this delay until the pen is up.

Typically, this value is set at 30.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-360DEB3A-3E38-413A-9941-6C758BA01ADE.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-360DEB3A-3E38-413A-9941-6C758BA01ADE.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,169 @@ + + + + + +DSDIOSession +Class TutorialDescribes the DSDIOSession API class. +

Description

This +class is used for setting up a session to form specific SDIO specific command +sequences.

The stages involved in initializing a session are as follows:

The session is first +created with the required parameter values
The session is placed +on the stack.
On completion of initialization, +a callback is called.

It is intended that the DSDIORegInterface class +should be used for the majority of SDIO operations. This class should only +be used in more complex scenarios, for example where the asynchronous nature +of the stack could be an advantage. The same thing can also be achieved with +the DSDIORegInterface documented here .

Some +functions have an auto-increment parameter. If the hardware function requires +you to use the register as a pointer to an address, auto-increment automatically +increments the register to point to the next address after each call. If the +hardware function requires you to use the register as a FIFO, auto-increment +should be disabled.

+ + + +

Header file

sdio.h

+ + +

Source code file

sdiosession.cpp

+ + +

Required libraries

EPBUSSDIO

+ + +

Class declaration

class DSDIOSession : public DSessionBase

+ + + +

SetupCIMIoWrite()

The +function declaration for the SetupCIMIoWrite() method is:

IMPORT_C void SetupCIMIoWrite(TUint32 aAddr, TUint8 aWriteVal, TUint8* aReadDataP);

Description

Set the session to transfer a single byte of +data to the card, and optionally read the register after the write operation.

Parameters

+ + + +

TUint32 aAddr

Address of the destination register.

+ + +

TUint8 aWriteVal

The byte to be written

+ + +

TUint8* aReadDataP

Pointer to the start of the byte which is to be read into.

If +this parameter is NULL, then a read-after-write operation is not performed.

+ + + +

Return value

None

SetupCIMIoRead()

The +function declaration for the SetupCIMIoRead() method is:

IMPORT_C void SetupCIMIoRead(TUint32 aAddr, TUint8* aReadDataP);

Description

Set the session to perform a read of a single +byte of data from the card.

Parameters

+ + + +

TUint32 aAddr

Address of the source register.

+ + +

TUint8* aReadDataP

Pointer to the byte which is to be read into.

+ + + +

Return value

None

SetupCIMIoWriteMultiple()

The +function declaration for the SetupCIMIoWriteMultiple() method +is:

IMPORT_C void SetupCIMIoWriteMultiple(TUint32 aAddr, TUint32 aLen, TUint8* aDataP, TBool aInc);

Description

Sets the session to perform a multi-byte (or multi-block) transfer +of data to the card.

Parameters

+ + + +

TUint32 aAddr

Address of the destination register.

+ + +

TUint32 aLen

The number of bytes to be transferred.

+ + +

TUint8* aDataP

Pointer to the start of the source buffer.

+ + +

TBool aInc

Specifies whether the auto-increment feature is enabled or not.

+ + + +

Return value

None

SetupCIMIoReadMultiple()

The +function declaration for the SetupCIMIoReadMultiple() method +is:

IMPORT_C void SetupCIMIoReadMultiple(TUint32 aAddr, TUint32 aLen, TUint8* aDataP, TBool aInc);

Description

Sets the session to perform a multi-byte (or multi-block) transfer of +data from the card.

Parameters

+ + + +

TUint32 aAddr

Address of the source register.

+ + +

TUint32 aLen

The number of bytes to be transferred.

+ + +

TUint8* aDataP

Pointer to the start of the destination buffer.

+ + +

TBool aInc

Specifies whether the auto-increment feature is enabled or not.

+ + + +

Return value

None

SetupCIMIoModify()

The +function declaration for the SetupCIMIoModify() method +is:

IMPORT_C void SetupCIMIoModify(TUint32 aAddr, TUint8 aSet, TUint8 aClr, TUint8* aReadDataP);

Description

Sets the session to perform a safe read-modify-write operation on a single +byte of data on the card.

Parameters

+ + + +

TUint32 aAddr

Address of the destination register.

+ + +

TUint8 aSet

A bitmask of the values to be set: pass 1 where the bit is to be +set, otherwise pass 0.

+ + +

TUint8 aClr

A bitmask of the values to be cleared: pass 1 where the bit is to +be cleared, otherwise pass 0.

+ + +

TUint8* aReadDataP

If this value is not NULL, then the result of the modification is +returned in this parameter.

+ + + +

Return value

None

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-365283F1-54B4-519A-81EC-9B5018896DDE-master.png Binary file Adaptation/GUID-365283F1-54B4-519A-81EC-9B5018896DDE-master.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-365283F1-54B4-519A-81EC-9B5018896DDE_d0e35432_href.png Binary file Adaptation/GUID-365283F1-54B4-519A-81EC-9B5018896DDE_d0e35432_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-36CD752C-45FE-5BFE-A695-11DF085F301F.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-36CD752C-45FE-5BFE-A695-11DF085F301F.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,30 @@ + + + + + +Debug +MacrosDescribes the macros that can be used to debug the bootstrap. +

The macro have no effect in non-debug builds of the bootstrap, when CFG_DebugBootRom is +FALSE. These macros do not modify any registers, but they may modify flags. +See Platform-Specific +Configuration Header.

PRINTPRINT text

Sends +the quoted text string text to the debug port.

PRTLNPRTLN text

Appends +a new-line character to the quoted text string text, and +sends the resulting text to the debug port.

DWORDDWORD reg, text

Sends +the quoted text string text to the debug port followed by +the value of ARM general register reg as an 8 digit hexadecimal +number followed by a new-line character.

MEMDUMPMEMDUMP base, len

Dumps +an area of memory of length len starting at base, +specified in hexadecimal, and sends it to the debug port.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-3722B946-07CF-4AEA-B228-E50642D6B5BE.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-3722B946-07CF-4AEA-B228-E50642D6B5BE.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,85 @@ + + + + + +Register Access Implementation GuideDescribes the implementation of the Register Access platform +service. +

A ASSP hardware register is a physical interface to an item of +hardware which contains values, such as bit fields, for controlling +ASSP features.

ASSP

An ASSP (Application Specific Standard Product) is a class of +integrated circuit. Different ASSPs have different architectures and +instructions sets. The AsspRegister class provides device driver writers with a simple interface to +access ASSP registers. Hardware implementers must provide the specified +functionality on a given platform and ASSP by writing the appropriate +machine instructions.

Pre-requisites

Before the implementing a register access implementation, the +following must be decided:

The area in memory to which the registers are mapped. The start +of this memory region is known as the base address.
The location of each register in terms of an offset from the +base address.

The above information will be present in a specific header +file which is used by any device driver that uses this API. This header +file also contains other information required to access the registers, +such as:

constants for bit field offsets
bit field values

Implementation

To provide register access, hardware implementers need to implement +the AsspRegister class.

Generic access to a register is provided in the form of three +operations on a hardware register: read, write and modify. All these +functions can be called in any context.

Symbian platform provides +the class header and inline implementations of the 8, 16 and 32-bit +wide functions. You must implement all the register modify functions +and all functions to access 64-bit wide registers. You may also need +to replace the inline 8, 16 and 32-bit wide register read and write +functions if the ASSP contains write-only registers.

You must +implement these functions atomically so that there is no possibility +of another thread or interrupt service routine accessing the contents +of the register before the function returns. Where you cannot implement +the function with a single machine instruction you must disable interrupts +during the register operation (if you are working with a single core +architecture) or wrap a spinlock around the register operation (if +you are working with a multicore architecture).

There are +three cases in which you must enforce atomicity with interrupt disabled +or use of spinlocks.

The modify operations +involve reading the register, taking a local copy, changing the local +copy and writing it back to the register and cannot be performed with +a single machine instruction.
Operations on +write-only registers involve maintaining a copy of the current contents +of the register within the AsspRegister class. All write and modify operations therefore cannot be performed +with a single machine instruction.
Some architectures +contain 64-bit registers. In this case, 64-bit operations involve +at least two machine instructions.

Baseport implementations of the Register Access platform service +come in the form of a ASSP library (or DLL). To avoid the need for +each device driver which uses the ASSP register class having to specify +a baseport specific library file corresponding to the ASSP library, +the name of the baseport specific library file should instead be included +in a file used to define other variant specific settings such as the +CPU core type, the memory model and the name of the variant. Each +baseport will have a file called variant.mmh, +where variant is the name of the baseport to be used. +An example of this being used in a variant.mmh file is:

#if defined(__USING_BASPORT__) +library VariantTarget(basport_name,assp_library) +#endif +baseport_name is the name of the variant and assp_library +is the name of the ASSP specific library file.

In order to +specify which baseport assp register set up is to be used in the client +projects for this baseport, the following line is included in the +MMP file of those projects

#define __USING_BASEPORT___

+ +SMP - Locking +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-372D2B88-2035-44A5-82CF-57FF131DDEBE.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-372D2B88-2035-44A5-82CF-57FF131DDEBE.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,15 @@ + + + + + +Platform ServiceA service that is intended to be used by any part of the +OS. +

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-3773A78D-F491-52EB-AA1D-201636497F28.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-3773A78D-F491-52EB-AA1D-201636497F28.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,23 @@ + + + + + +Power Management +TutorialsThis topic describes how to implement a power controller in a base +port. +

A power controller is a kernel extension that manages the power management +hardware of a phone, for example on-chip power management controllers and +oscillators.

+Power Management + +Power States + +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-37B8243E-027A-49D0-A896-27946DAC9052.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-37B8243E-027A-49D0-A896-27946DAC9052.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,114 @@ + + + + + +Baseport Template Tools GuideDescribes the tools required needed to implement and test +the Baseport Template platform service. +

Build +tools

The following build tools are available:

+ + + +Name +Description + + + + +BUILDROM +BUILDROM is a unified ROM building front end. +It invokes ROMBUILD to build the ROM image and ROFSBUILD to build the ROFS image. + + +ROMBUILD +ROMBUILD is the Symbian platform binary XIP +(execute-in-place) ROM builder. It is normally invoked through BUILDROM. + + +ROFSBUILD +ROFSBUILD is the Symbian platform non-XIP +ROFS builder. It is normally invoked through BUILDROM. + + +iMaker +iMaker is a ROM-image creation tool that creates +a flash image from a set of Symbian binary and data files. iMaker mainly functions on top of BUILDROM. + + +SPITOOL +SPITOOL is a utility tool to create static +plug-in information (SPI) files. + + +InterpretSIS +InterpretSIS is a command-line tool used to +install SIS files. It can be invoked either through BUILDROM or directly. + + +READIMAGE +READIMAGE is a command-line tool that provides +readable data from a ROM, ROFS, or E32 image. + + +MAKSYM/MAKSYMROFS +MAKSYM/MAKSYMROFS is a tool to create a readable +symbol file listing the virtual addresses of the exported functions. + + +Obey +Files +OBEY files are standard text files containing +statements that are used to control the operation of the ROM building +tools. + + +Symbian Build System v2 +SBSv2 is a tool for building Symbian platform +and applications developed for Symbian platform. It helps you build +a set of components, or the complete Symbian platform, on Windows +and Linux platforms for the ARMv5, TOOLS2 and WINSCW target platforms. +They also provide a reference to the file formats used as input to +the build tools. For more information about SBSv2, see the Symbian +Build System v2 documentation that is provided with the Platform +Developer Toolkit. + + + +

Emulators

The following emulators are available:

+ + + +Name +Description + + + + +QEMU +QEMU is an open source emulator which can +be used to run and debug a Symbian ROM image on a PC. + + +Syborg + Syborg is a Symbian baseport for use with +QEMU. + + + +

+Base +Porting Guide +Baseport +Template Implementation Guide +Baseport +Template Testing Guide +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-388004AF-6F99-4BBB-A8E0-D75DC5B6790C.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-388004AF-6F99-4BBB-A8E0-D75DC5B6790C.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,134 @@ + + + + + +Test +ApplicationThis document describes a simple application which is used to load +a device driver and test its functionality. +

Testing +device drivers

Drivers, apart from kernel extensions, are +not automatically started by the Kernel, so they must be explicitly loaded +by application.

When testing an LDD-PDD model driver, it is a general +practice to write a simple test application that loads the LDD and PDD by +name, opens a logical channel, and calls the driver API to test the driver's +functionality.

The following shows a command line test application +that does this:

/** E32Main - Application, exe main entry point. */ +GLDEF_C TInt E32Main() + { + ... + // Load the PDD. This user API will load the PDD DLL by name + // and also enable the loader to search for the PDD object + // by name. + r = User::LoadPhysicalDevice(KExDriverPdd); + + // PDD loading is considered successful, if either it is + // loaded now or it is already loaded. + test((r==KErrNone)||(r==KErrAlreadyExists)); + + // Load the LDD. This user API loads the LDD DLL by name + // and also enable the loader to search for the LDD object + // by name. + r = User::LoadLogicalDevice(KExDriverLdd); + + // LDD loading is considered successful, if either it is + // loaded now or it is already loaded. + test((r==KErrNone)||(r==KErrAlreadyExists)); + ... + + // Get device capabilities + ... + + // Open the device with reference to the driver name. + r = device.Open(KDriverName); + if (r==KErrNone) + { + ... // do required operations + // Close the device. This handle is required only to + // get any device related information from the LDD factory + // object. + device.Close(); + } + + // RExDriverChannel is an RBusLogicalChannel derived class, which provides a user side + // handle to a logical channel. It defines the driver interface. + RExDriverChannel ldd; + + // Open the logical channel to the driver for unit 1. This is a + // user-side wrapper function for the + // RBusLogicalChannel::DoCreate() API. DoCreate() is + // called in Open() for unit 1. + // + r = ldd.Open(KUnit1); + test(r==KErrNone); + + // Call the driver API using the RExDriverChannel interface and + // test for the functionality + ... + + // Close the logical channel + ldd.Close(); + + // Free the logical device / LDD + r=User::FreeLogicalDevice (KDriverName); + test(r==KErrNone); + + // Instead of directly using the PDD name, get the PDD + // factory object name and append the extension name, to + // unload the PDD. + TName pddName(KDriverName); + _LIT(KVariantExtension, ".pdd"); + pddName.Append(KVariantExtension); + + // Free the PDD, resulting in freeing the PDD factory object + r=User::FreePhysicalDevice (pddName); + test(r==KErrNone); + + ... + }

If the driver is a kernel extension, then the Kernel +loads the driver when it boots, so an application does not need to load the +driver explicitly. Applications simply open a channel to the driver and call +the driver API as required.

The RTest class provides +macros and functions that can be used in test applications. It provides macros +to validate a return value against an expected value, and to leave giving +the line number where the error occurred. It also provides macros to print +debug messages, to group the test sets, and so on.

// Create RTest object (test framework) +LOCAL_D RTest test(_L("Tutorial Driver")); + +GLDEF_C TInt E32Main() + { + // Initialize the test object with a title + test.Title(); + + // RTest::Starts() starts a set of tests + test.Start(_L("Load Physical Device")); + ... + // RTest::Next() starts a new set of tests + test.Next(_L("Open Channel")); + ... + // Test if a condition is true. If not, the application leaves + // displaying the line number and error type + test(r==KErrNone) + ... + // Prints a string to the screen + test.Printf(_L(“<display string %d>”),r); + ... + // End the tests + test.End(); + }

The drivers developed and built can be tested on the +target hardware. The debug or release versions of the driver are built into +the ROM and downloaded to the target. This is done either by using a MMC card, +USB, Serial or JTAG interface, as supported by the particular hardware board. +Once the board is powered on or reset, Symbian platform boots and the text +shell is displayed (assuming a text shell ROM image). To test an LDD-PDD driver, +run the test application from the command line.

If debug messages +are enabled in the driver, by using KTRACE or BTRACE, +the messages can be viewed on the LCD screen, or through a connected COM port, +using the HyperTerminal application on a PC.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-38FD682F-656B-48F7-A553-50BC4F1FB4BB.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-38FD682F-656B-48F7-A553-50BC4F1FB4BB.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,17 @@ + + + + + +Base PortThe base code of the Symbian platform is structured so +that generic code is separated from hardware-specific code. This means +that porting Symbian to new hardware requires modification or creation +of hardware-specific code only. This is what is known as a base port. +

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-3A1BCF46-FFBB-4E4F-A73A-6E68254B23FF.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-3A1BCF46-FFBB-4E4F-A73A-6E68254B23FF.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,30 @@ + + + + + +SDIO +Implementation Quick StartProvides a collection of documents that describe SDIO (Secure Digital +Input Output) implementation. +

The implementation guide describes how SDIO is included in a build of the +Symbian platform.

SDIO Implementation +Guide

The testing guide describes techniques that can be used for testing the +SDIO functionality.

SDIO Implementation +Testing Guide

The tools guide describes the tools that can be used to test an implementation +of SDIO.

SDIO Implementation +Tools Guide

The build guide describes how to include the SDIO adaptation in a ROM image.

SDIO Implementation +Build Guide

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-3A30DA16-ECA8-5639-A9DC-6BE2AD55420B.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-3A30DA16-ECA8-5639-A9DC-6BE2AD55420B.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,69 @@ + + + + + +I2C Technology GuideThis topic describes the Inter Integrated Circuit (I2C) +bus technology. +

Introduction

The I2C is a serial bus technology invented by Philips. The I2C +is a multi master serial interface used by the low power peripherals +to exchange data. The I2C supports different modes of data transfer +and three commonly used modes are:

Standard mode supports 100Kbps data transfer
Fast mode supports 400Kbps data transfer
High speed mode supports 3.4Mbps data transfer

Architecture

The I2C bus contains 2 bi-directional lines, a serial clock (SCL) +and serial data (SDA) lines. In the I2C bus, more than one device +could act as Master device. There can be only one master device active +at a given time. The master device initiates the communication and +slave responds to the master. The master and slave devices can be +interchanged after a data STOP signal is sent from +the master. The master device can address more than one slave at a +time.

+ I2C Bus + +

The master device can read and write data to the slave device. +The I2C bus uses 7 or 10 bit address.

Features

The features of the I2C bus are:

the master device +can send and receive data from the slave device
the I2C bus +uses 7 or 10 bit address
only uses 2 +bi-directional lines for communication
multiple master +device can be connected to the same bus

Communication

The first byte from the master is used to address the slave device. +In the first byte the master sends the address and read/write signal +to the slave. There are three types of messages:

master just +reads data from the slave
master just +writes data to the slave
master reads +and writes data

The communication is initiated with a start signal and completed +with a stop bit. In the third type of message the master starts the +communication with a start signal with a read or write bit to the +slave. The process continues until the master has completed the read +and write tasks. The communication is terminated with a stop signal.

Typical +Uses

The typical uses of I2C bus are:

to read data +from various flash devices like EEPROM and SDRAM
to control LCD
to read real +time clock data

+ +I2C bus specification v2-1 Jun 2000 +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-3A625B23-354E-5CB4-98CF-FF53AD724FA0.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-3A625B23-354E-5CB4-98CF-FF53AD724FA0.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,66 @@ + + + + + +Dealing with Demand PagingWhen demand paging is used, the contents of memory are +available to a program when they are required (“on demand”). When +the contents are no longer required, the RAM can be used for other +content. +

Demand paging is a change to how the kernel can use RAM from Symbian +platform v9.3. This topic describes the possible results for base +port.

When demand paging is used, the contents of memory are available +to a program when they are required - that is, 'on demand'. When the +contents are no longer required, the RAM can be used for other content. +In this way, the total RAM required to store content is less than +if it were all permanently available.

The Device Driver Guide provides Suggested techniques for mitigating the effects of demand paging for writers of device drivers. These recommendations can result +in a more ‘multithreaded’ base-port. This may have the following impact +that needs to be considered:

A base-port +component may provide services to device drivers, exposing to them +a shared resource; either hardware or software:
- hardware - may +be a hardware controller whose non-instantaneous operation, once initiated, +cannot be disturbed until it completes
- software - may +be a list of requests for services.
A hardware component +has a control interface that can be used by a number of drivers. Operations +on the control interface although near instantaneous, are not atomic +and cannot be interrupted.

In the case of the base-port component, when the state of a resource +needs to be protected from the effects of pre-emption for a non-negligible +period of time, the recommended approach is to use mutual exclusion, +protecting the resource with a mutex: unless there is any chance that +the same driver may trigger the same operation before the previous +one completed. For example, when operations are non-blocking and happen +in a context different from the initiator’s, a NFastMutex should suffice.

An example of the hardware component situation is a set-clear control +interface, where a pair of registers (one containing the bits to be +set, the other the bits to be cleared) have to be written to produce +the desired change. If the operation is pre-empted after bits are +set but before they are cleared for a desired final output, and a +new set-clear operation is initiated, the final state of the interface +may be undetermined. Pre-emption protection in this case is achieved +by simply locking the Kernel using NKern::Lock() before the operation starts and unlocking it with NKern::Unlock() after it completes. If the interface is to be used from an interrupt +context disabling all interrupts is sufficient to protect against +thread concurrency.

+Migration + Tutorial: Demand Paging and Internal MMC Cards + +Migration +Tutorial: Demand Paging and Media Drivers + +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-3A785F02-F4AA-432C-9331-8827029BB384.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-3A785F02-F4AA-432C-9331-8827029BB384.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,25 @@ + + + + + +Status +QueryThis document describes how the status of an asynchronous request +is maintained and monitored. +

A TRequestStatus object is used to monitor the status +and result of the asynchronous request. This object maintains the status of +the request at various stages and finally contains the request result. The +driver uses the status object when performing operations on the request such +as cancelling, completing, or managing multiple similar requests.

Initially, when the request is made, the Kernel changes the status to KRequestPending. +After completion of the request, the status is changed to KRequestComplete to +indicate request completion. It also contains the result of the request, which +can indicate an error or failure of the request. TRequestStatus::Int() returns +the request result.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-3AFE0D8B-FB9B-5355-A63B-FB71DD13E7D0-master.png Binary file Adaptation/GUID-3AFE0D8B-FB9B-5355-A63B-FB71DD13E7D0-master.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-3AFE0D8B-FB9B-5355-A63B-FB71DD13E7D0_d0e73917_href.png Binary file Adaptation/GUID-3AFE0D8B-FB9B-5355-A63B-FB71DD13E7D0_d0e73917_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-3B6544CD-FA6E-5AB2-AA63-61186F52167D.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-3B6544CD-FA6E-5AB2-AA63-61186F52167D.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,231 @@ + + + + + +Controllable +Power ResourcesThis topic explains how power resources were controlled in older +releases of Symbian platform. For later releases see the Power Resource Manager +documentation. +

This documentation is retained for reference for those working with hardware +or software that is based on older versions of Symbian platform version (in +particular old release 9.5). For later releases see the Porting +the Power Resource Manager documentation.

Controllable power resources are defined as being any device resource, +such as voltages on power-lines or clocks, which can be independently enabled, +disabled or modified under software control.

The following hardware block diagram is an example of the way power resources +might be arranged:

+ +Example power resource arrangement + + +

There is no default support or default implementation for controllable +power resources in the generic layers of Symbian platform. They must be managed +by the base port.

We suggest that the management of controllable power resources (the resource +manager) be implemented in the Variant DLL or the ASSP DLL. This allows the +resource manager to be up and running by the time peripheral drivers, which +might also be kernel extensions, are loaded. See the ASSP/Variant Architecture and the ASSP/Variant +Tutorials.

A suggested implementation has the instance of the Asic derived +class owning a pointer to the resource manager object. The interface class +for the ASSP or Variant could then have an exported or an inline member function +to return a pointer to this resource manager object. Peripheral drivers are +expected to link against either the ASSP DLL, or the Variant DLL, or both.

For example, for a device that has a Variant and an ASSP:

+class MyVariant : public MyASSP + { +public: + Init1(); + Init3(); + // Other mandatory Asic-derived member functions + ... +public: + ResourceManager* myResMgrPtr; + ... + }; + +

where class MyASSP is derived from class Asic.

+GLREF_D MyVariant TheVariant; +class TMyVariant + { +public: + inline static ResourceManager* ResourceManager() + {return(TheVariant.myResMgrPtr);} + // other exported methods + ... + }; + +

where TMyvariant is the Variant interface class, and ResourceManager is +the resource manager class.

The resource manager can be declared as a global object at the Variant +(or ASSP) scope and can therefore be created when this component is first +loaded. In this case, the Asic::Init3() function would +initialise the ResourceManager object, and set up myResMgrPtr. +Alternatively, if the Variant (or ASSP) were to need the resource manager +up and running, then you would initialise ResourceManager in Asic::Init1().

In this implementation, the Variant would export a header file(s) publishing +a list of controllable power resources.

Shared controllable +power resources

Some controllable power resources can be shared +between groups of peripherals and therefore may require usage tracking.

We +recommend that shared power resources be represented by a class derived from MPowerInput. +This class offers the Use() and Release() interface +that encapsulates resource counting behaviour. This mechanism should turn +the resource on when the count becomes non-zero, and turn the resource off +when the count becomes zero.

We suggest that your MPowerInput derived +class defines and implements a GetCount() function that returns +the usage count on the shared resource.

A suggested +implementation of a resource manager

While we have implied that +a resource manager is a single class, which we have called ResourceManager, +the resource manager is a notional concept for controlling power resources. Symbian +neither mandates a format for a ResourceManager class, nor even its existence. +In practice, it may be more useful to embed resource manager functions and +data in the Variant interface class (or the ASSP interface class, if appropriate).

However, +for the purpose of explaining what a resource manager can do, it is easier +to assume that this behaviour is handled by a resource manager class. This +is the outline definition of such a class.

class ResourceManager + { +public: + void InitResources(); // called by your Asic::Init3()/Asic::Init1() + void Modify(TUint aSetMask, TUint aClrMask); // only 32 simple Resources can be managed + TBool GetResourceState(TUint aResBitMask); // only 1 bit set on this mask, returns On/Off +public: + (MPowerInput-derived) iSharedResource1; // 1 per shared resource + (MPowerInput-derived) iSharedResource2; + ... + }; +

The InitResources() function would +do at least two things:

enable an appropriate +set of simple resources at boot time
initialise the shared +power resource tracking objects, i.e. the instances of your MPowerInput derived +class(es).

The function would be called by the Variant or ASSP implementation +of Asic::Init3() or Asic:Init1().

The Modify() function +is an example of how to deal with power resources that are either on or off. +The function would take bit masks, where a bit represents a separate controllable +power resource. The first bit mask would represent the set of power resources +to be turned on, while the second would represent the set of power resources +to be turned off. This assumes that the function could behave synchronously. +Drivers for peripherals that use a set of these controllable power resources, +would call Modify() to turn the relevant controllable power +resources on or off.

As an example, the most common method of switching +clock resources on or off is by setting and clearing bits in a hardware register. +A base port could choose to implement common code for setting bits in registers.

A +shared power resource is further represented by a MPowerInput derived +class. The implementations of MPowerInput::Use() and MPowerInput::Release() would +call Modify() to turn on the shared resource when the usage +count becomes non zero, or turn it off when the usage count reaches zero. +Peripheral drivers would have access to shared resources, and also to the +member functions of the ResourceManager class, through the +ASSP or Variant Interface class function that returns a pointer to it.

The +resource manager, or its functions and members, could be offered as part of +a power controller interface class, the TPowerController class +suggested when we discussed the implementation of the Power +Controller's EnableWakeupEvents() function. +The class would provide an exported function that would give access to the +resource manager. The resource manager class would be made part of the power +controller kernel extension. Peripheral drivers needing access to shared power +resources would then link to the power controller DLL. If the Variant or ASSP +were also to need access to the resource manager, then the resource manager +would have to be initialised much earlier in the kernel start-up sequence. +In this case, we would suggest that the standard power controller kernel extension +entry point defined by DECLARE_STANDARD_EXTENSION() be +replaced with a custom entry point that might look like this:

GLDEF_C TInt KernelModuleEntry(TInt aReason) + { + if(aReason==KModuleEntryReasonVariantInit0) + { + ResourceManager* c = new ResourceManager (); // create Resource Manager + return c ? KErrNone : KErrNoMemory; + } + else if(aReason==KModuleEntryReasonExtensionInit0) + { + (create DPowerController and Battery Monitor and Power HAL handler) + } + return KErrNone; // gets here from calling with KModuleEntryReasonExtensionInit1 + } +

The Variant or ASSP would also need to link to the +power controller DLL.

The following base port software architecture +could be applied to the power supply arrangement as illustrated in the hardware +block diagram above (see the beginning of this section at Controllable +Power Resources):

+Base port software architecture + +

Multi-level, +composite and asynchronous power resources

Some power resources +may have more than one operational level. For example, it is possible that +an input clock to a peripheral can be operated at a nominal value corresponding +to the fully active state, and may be lowered to another level corresponding +to the power saving state.

The same could apply to the input voltages +that the peripheral can operate on. The control model suggested above for +simple resources may not be appropriate. A suggested alternative would have +these multi-Level resources implementing an interface that offers a public +enumeration to cover all possible usage levels at which the resource can be +used, and APIs such as:

class MultiLevelResource + { + enum TResourceLevel + { + EOperationalLevel1, + EOperationalLevel2, + . . . + ELowPowerLevel1, + ELowPowerLevel2, + . . . + }; + void UseToLevel(); + void ReleaseToLevel(); + TResourceLevel GetCurrentLevel(); + . . . + };

More importantly, it is possible that resources may +have to be operated in combination with other resources. For example, some +peripherals may have more than one input clock, and on transition between +power states, these clocks may have to be changed simultaneously.

If +the resources to be actuated simultaneously are simple resources, then the +model above with a Modify() call that takes a bit mask and +allows more than one resource to be changed at a time may be appropriate. +If the resources to be actuated are shared or multi-level, or have to be represented +individually, then another interface will have to be defined to allow modifying +more than one of them simultaneously.

Modifying some resources may +not be an instantaneous operation. For example, it may take a non-negligible +amount of time to stabilise an input clock that has just been modified.

The +nature of EKA2 strongly discourages actively waiting (or “spinning”) inside +drivers; instead it is suggested that the multithreading capabilities of EKA2 +kernel side code and the synchronisation mechanisms available be used to solve +the problem of having the driver code having to wait for a resource to stabilise +before proceeding with its use.

As an example, let us assume that +the multi-level resource mentioned above has a non-negligible delay associated +with any level changes:

If the length of time +to wait for a power resource to stabilise is known, and is the order of a +few milliseconds or less, or the driver executes on its unique kernel thread +(not used by any other kernel-side code), then the best solution would be +to sleep the driver thread, by calling NKern::Sleep(aTime) for +the specified length of time after issuing a call to UseToLevel() (or ReleaseToLevel()).
When the length of time +to wait for a power resource to stabilise increases, then sleeping the driver +thread may become a problem if the driver executes in a DFC queue used by +other drivers, which is often the case. This is because blocking that thread +means that no other drivers can run. Here, the best solution is for the driver +to create another thread and DFC queue, by calling Kern::DfcQInit(), +and whenever it needs to change the resource, queue a DFC on that queue, which +will issue the calls to UseToLevel() (or ReleaseToLevel()) +and then sleep the thread.
If the length of time +to change a power resource cannot be known in advance, but the hardware provides +an indication of completion of the change, for example, in the form of an +interrupt, then the solution may involve the driver code waiting on a Fast +Mutex, which is signalled by the completion event (in code belonging to the MultiLevelResource derived +object).

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-3C34724F-B476-5329-B0B1-6D5A34294979.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-3C34724F-B476-5329-B0B1-6D5A34294979.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,21 @@ + + + + + +Interrupt +Dispatcher TutorialDescribes how to implement the Interrupt Dispatcher part +of the ASSP/Variant.

+Interrupt +Dispatcher +Interrupt +Service Routines (ISR) +Symbian OS Internals - Chapter 6 Interrupts +and Exceptions +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-3CB74FE6-272E-4176-BC51-E36103CADB09-master.png Binary file Adaptation/GUID-3CB74FE6-272E-4176-BC51-E36103CADB09-master.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-3CB74FE6-272E-4176-BC51-E36103CADB09_d0e94075_href.png Binary file Adaptation/GUID-3CB74FE6-272E-4176-BC51-E36103CADB09_d0e94075_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-3E85C075-436F-5D2E-B1F7-0C9EC6D382E3.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-3E85C075-436F-5D2E-B1F7-0C9EC6D382E3.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,46 @@ + + + + + +Source +Code OrganisationDescribes the platform-independent files of the bootstrap. +

The generic files are stored in the os/kernelhwsrv/kernel/eka/ directory.

The files are:

kernel/bootstrap.mke - +Generic part of the makefile, written for GNU make. Works for both ARM and +X86 bootstrap builds.
include/e32rom.h - +C++ Header file describing the layout of the ROM header and the ROM file system.
include/kernel/kernboot.h - +C++ Header file describing the interface between the bootstrap and the kernel, +mainly the definition of super page fields. Applicable to both ARM and X86.
include/kernel/arm/bootcpu.inc - +Assembler include file giving CPU-specific definitions for ARM.
include/kernel/arm/bootdefs.h - +C++ Header file containing some internal bootstrap definitions for ARM.
include/kernel/arm/bootmacro.inc - +Assembler include file containing some general-purpose macro definitions for +ARM.
include/kernel/arm/bootstrap.lnk - +Linker script file for GNU linker; used when building ARM bootstrap using +GNU tools.
include/memmodel/epoc/<model>/arm/mmboot.h - +C++ Header file containing memory-model-specific definitions shared with bootstrap.
kernel/arm/bootcpu.s - +Source file containing routines which are specific to a particular ARM CPU +rather than generic to all ARM CPUs.
kernel/arm/bootutils.s - +Source file containing lots of useful subroutines such as memory copy, memory +fill, generic MMU mapping code, generic memory allocator, and so on.
kernel/arm/bootmain.s - +Source file containing top-level bootstrap code.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-3F0053A7-6EE2-5B59-81C2-27EC3CC7820A-master.png Binary file Adaptation/GUID-3F0053A7-6EE2-5B59-81C2-27EC3CC7820A-master.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-3F0053A7-6EE2-5B59-81C2-27EC3CC7820A_d0e9276_href.png Binary file Adaptation/GUID-3F0053A7-6EE2-5B59-81C2-27EC3CC7820A_d0e9276_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-3F47E907-975A-5739-9B03-042CB90D675D.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-3F47E907-975A-5739-9B03-042CB90D675D.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,16 @@ + + + + + +Port Implementation +TutorialDescribes the steps to implement a port of the DMA Framework.

+Concepts + +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-3FE9C184-1880-51E1-B045-3C2EA4BE204A-master.png Binary file Adaptation/GUID-3FE9C184-1880-51E1-B045-3C2EA4BE204A-master.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-3FE9C184-1880-51E1-B045-3C2EA4BE204A_d0e78117_href.png Binary file Adaptation/GUID-3FE9C184-1880-51E1-B045-3C2EA4BE204A_d0e78117_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-40880992-B177-4584-84B4-6F6CF096E423-master.png Binary file Adaptation/GUID-40880992-B177-4584-84B4-6F6CF096E423-master.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-40880992-B177-4584-84B4-6F6CF096E423_d0e96877_href.png Binary file Adaptation/GUID-40880992-B177-4584-84B4-6F6CF096E423_d0e96877_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-40F2BC43-5022-5F4E-B445-56FEF43FEB8B.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-40F2BC43-5022-5F4E-B445-56FEF43FEB8B.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,71 @@ + + + + + +Code +OrganizationDescribes the MultiMediaCard Controller source code provided by +Symbian platform +

Platform independent +layer

The location of the source code and the header files for +the platform independent layer of the MultiMediaCard +controller, i.e. the generic DLL, provided by Symbian platform called epbusm.dll, +is as follows:

+ + + +

Source location

Source files

+ + +

Peripheral bus layer source code.

...\e32\drivers\pbus\

spbus.cpp
pbusmedia.cpp

+ + +

Peripheral bus layer header files and inline functions.

...\e32\include\drivers\

pbus.h
pbus.inl
pbusmedia.h

+ + +

MultiMediaCard layer source code.

...\e32\drivers\pbus\mmc

session.cpp
stack.cpp

+ + +

MultiMediaCard layer header files and inline functions.

...\e32\include\drivers\

mmc.h
mmc.inl
mmc_ifc.h

+ + + +

Platform specific +layer

The suggested location of the source code and the header +files for the platform specific layer of the MultiMediaCard controller, i.e. the variant DLL, provided by you, +and usually called epbusmv.dll, is the variant specific +directory. This is the directory ...\<VAR>\specific\.

How +you organize source and header files within this directory is up to you.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-423537D5-2C8A-5C26-8D7B-60446E95F681.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-423537D5-2C8A-5C26-8D7B-60446E95F681.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,72 @@ + + + + + +Interrupt +Layer InitialisationThis topic describes how to implement the Asic::Init1() and Asic::Init3() functions +to initialise interrupts. +

In first phase +initialisation

During first phase initialisation of start-up, the +kernel calls the ASSP's implementation of Asic::Init1(). +For the template reference board, where the ASSP is split into a common, ASSP +layer and a device-specific (variant) layer, interrupt handling is initialised +in the ASSP layer, specifically in TemplateAssp::Init1(), +defined in ...\template_assp\template_assp_priv.h, and +implemented in ...\template_assp\assp.cpp.

Note +that interrupts are disabled during first phase initialisation.

Within +your implementation of Init1(), do the following:

Initialise the ISR table.

It is useful to initialise the ISR table so +that each interrupt is bound, by default, to the Spurious interrupts handler, with the 32-bit parameter taking the +interrupt number.

For example,
... +const TInt KInterruptSourceCount = 32; +SInterruptHandler IsrHandlers[KInterruptSourceCount]; +... + +for( TInt i = 0; i < KInterruptSourceCount; ++i ) + { + IsrHandlers[i].iIsr = SpuriousHandler; + IsrHandlers[i].iPtr = (TAny*)i; + }
where the spurious interrupt handler function might be +implemented as:
void SpuriousHandler(TAny* aId) + { + Kern::Fault("SpuriousInt", (TInt)aId); // handle unexpected interrupt. + } +
On the template reference board, the ISR table is initialised +by TemplateInterrupt::Init1() in ...\template_assp\interrupts.cpp, +and this is called by TemplateAssp::Init1().
Register the dispatcher +functions. The Symbian platform kernel needs to know the location of the IRQ +and FIQ dispatchers. It provides the two functions: Arm::SetIrqHandler() and Arm::SetFiqHandler(), +which the Variant layer must call, passing the addresses of the IRQ and FIQ +dispatchers.

On the template reference board, the registration is +done by TemplateInterrupt::Init1() in ...\template_assp\interrupts.cpp.
void TemplateInterrupt::Init1() + { + // + // need to hook the ARM IRQ and FIQ handlers as early as possible + // and disable and clear all interrupt sources + // + ... + DisableAndClearAll(); + Arm::SetIrqHandler((TLinAddr)TemplateInterrupt::IrqDispatch); + Arm::SetFiqHandler((TLinAddr)TemplateInterrupt::FiqDispatch); + } +
Bind any ISRs that handle +chained or pseudo interrupts

In third phase +initialisation

During third phase initialisation of start-up, the +kernel calls the ASSP's implementation of Asic::Init3().

Note +that interrupts are enabled during third phase initialisation.

Within +your implementation of Init3(), if you need to, call Interrupt::Enable() on +any of the interrupt sources that are bound to a chained or pseudo ISR dispatcher. +You don't need to do this if you are enabling and disabling the main interrupt +on demand as the chained or pseudo-interrupts are enabled and disabled.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-42F8FA5A-BBE4-50DE-917E-D05755019FEC.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-42F8FA5A-BBE4-50DE-917E-D05755019FEC.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,232 @@ + + + + + +Personality Layer DesignProvides some guidelines for the design of a personality +layer for real time Applications for the Kernel. +

Memory +management

The personality layer assumes that the RTA will +run in a single flat address space in which there is neither protection +between different parts of the application nor protection of any hardware +or CPU resource from any part of the application. For example, any +part of the application code can access any I/O port, and can disable +interrupts.

To get this behaviour under the Kernel Architecture +2, the RTA must run in supervisor mode in the kernel address space. +The obvious way to do this is to make the RTA together with the personality +layer a kernel extension. This also ensures that it is started automatically +early on in the boot process.

In general the RTA will have +its own memory management strategy and will not wish to use the standard +Symbian platform memory management system. To achieve this, the personality +layer will allocate a certain fixed amount of RAM for use by the real +time application at boot time. For a telephony stack this will be +around 128K - 256K. This can be done either by including it in the +kernel extension's .bss section, or by making +a one-time allocation on the kernel heap at boot time. Depending on +the RTA requirements, the personality layer can manage this area of +RAM (if the RTOS being emulated provides memory management primitives) +or the RTA can manage it.

Threads +and mapping thread priorities

A nanokernel thread will +be used for each RTOS thread

A priority mapping scheme will +be required to map RTOS priorities, of which there are typically 64 +to 256 distinct values, to nanokernel priorities. As long as the RTA +does not use more than 35 threads running simultaneously, which is +usually the case, it should be possible to produce a mapping scheme +that allows each thread to have a distinct priority, if needed. If +this limit is exceeded, it will be necessary to fold some priorities +together.

Note that any attempt to increase the number of +priorities supported by both the nanokernel and the Symbian platform +kernel would be prohibitively expensive in terms of RAM usage.

Communication +between Symbian platform and the RTOS Environments

To allow +the functionality of the RTA to be available to Symbian platform applications, +it is necessary that a mechanism exist by which Symbian platform code +and the RTA may communicate with each other. In practice this means:

it must be possible +for a Symbian platform thread to cause an RTOS thread to be scheduled +and vice-versa
it must be possible +for data to be transferred between Symbian platform and RTOS threads +in both directions.

It will usually be possible for a Symbian platform thread +to make standard personality layer calls (the same calls that RTOS +threads would make) in order to cause an RTOS thread to be scheduled. +This is because the nanokernel underlies both types of thread and +most 'signal' type operations (i.e. those that make threads ready +rather than blocking them) can be implemented using operations which +make no reference to the calling thread, and which are therefore not +sensitive to which type of thread they are called from.

The +standard personality layer calls will not work in the other direction, +since it will not be possible for a Symbian platform thread to wait +on a personality layer wait object. The most straightforward way for +RTOS threads to trigger scheduling of a Symbian platform thread would +be to enque a DFC on a queue operated by a Symbian platform thread. +Another possibility would be for the Symbian platform thread to wait +on a fast semaphore which could then be signalled by the RTOS thread. +However the DFC method fits better with the way device drivers are +generally written. A device driver will be necessary to mediate communication +between Symbian platform user mode processes and the RTA since the +latter runs kernel side.

All data transfer between the two +environments must occur kernel side. It will not be possible for any +RTOS thread to access normal user side memory since the functions +provided for doing so access parts of the DThread structure representing the Symbian platform calling thread, for +example to perform exception trapping. Some possibilities for the +data transfer mechanism are:

A fairly common +architecture for real time applications involves a fixed block size +memory manager and message queues for inter-thread communication. +The memory manager supports allocation and freeing of memory in constant +time. The sending thread allocates a memory block, places data in +it and posts it to the receiving thread's message queue. The receiving +thread then processes the data and frees the memory block, or possibly +passes the block to yet another thread. It would be a simple proposition +to produce such a system in which the memory manager could be used +by any thread. In that case a Symbian platform thread could pass messages +to RTOS threads in the same way as other RTOS threads. Passing data +back would involve a special type of message queue implemented in +the personality layer. When a message was sent to a Symbian platform +thread a DFC would be enqueued. That DFC would then process the message +data and free the memory block as usual. This scheme combines the +data transfer and scheduling aspects of communication.
Any standard +buffering arrangement could be used between the RTA and the device +driver (e.g. circular buffers). Contention between threads could be +prevented using nanokernel fast mutexes, on which any thread can wait, +or by the simpler means of disabling preemption or disabling interrupts. +It will also be possible for RTOS threads to make use of shared I/O +buffers for transfer direct to user mode clients, provided that these +buffers are set up by the Symbian platform device driver thread. This +may be useful as a way to reduce copying overhead if bulk data transfer +is necessary between the two domains.

Synchronisation/communication +primitives

The nanokernel does not support most of the +synchronisation and communication primitives provided by a standard +RTOS. Any such primitives required by the RTA will have to be implemented +in the personality layer. This means that the personality layer needs +to define new types of object on which threads can wait. This in turn +means that new nanokernel thread states (N-state) must be defined +to signify that a thread is waiting on an object of the new type. +In general, each new type of wait object requires an accompanying +new nanokernel thread state.

Blocking a thread on a wait object

To make a thread +block on a new type of wait object, call the nanokernel function Kern::NanoBlock(), passing the maximum time for which the +thread should block, the new N-state value, and a pointer to the wait +object.

Use the TPriListLink base class of NThreadBase to attach the thread to a list of threads waiting +on the object. Note that this must be done after calling Kern::NanoBlock(). As preemption is disabled before this +function is called, a reschedule will not occur immediately, but will +be deferred until preemption is reenabled.

State handler

Every thread that can use a new type of wait object, must +have a nanokernel state handler installed to handle operations on +that thread when it is waiting on that wait object. A nanokernel state +handler is a function that has the following signature:

void StateHandler(NThread* aThread, TInt aOp, TInt aParam);

aThread is a pointer to the thread involved.
aOp is one of the NThreadBase::NThreadOperation values +that indicates which operation is being performed on the thread.
aParam is a parameter that depends on aOp.

Note that the state handler is always called with preemption +disabled.

The possible values of aOp are:

+ + + +

aOp value

Description

+ + +

ESuspend

Called if the thread is suspended while not in a critical +section and not holding a fast mutex. Called in whichever context NThreadBase::Suspend() is called from.

aParam contains the requested suspension count.

+ + +

EResume

Called if the thread is resumed while actually suspended, +and the last suspension has been removed. Called in whichever context NThreadBase::Resume() is called from.

aParam contains no additional information.

+ + +

EForceResume

Called if the thread has all suspensions cancelled while +actually suspended. Called in whichever context NThreadBase::ForceResume() is called from.

aParam contains no additional +information.

+ + +

ERelease

Called if the thread is released from its wait. This call +should make the thread ready if necessary. Called in whichever context NThreadBase::Release() was called from.

aParam is the value passed into NThreadBase::Release() to be used as a return code.

If aParam is +non-negative, this indicates normal termination of the wait condition.

If aParam is negative, it indicates early or +abnormal termination of the wait; in this case the wait object should +be rolled back as if the wait had never occurred. For example, a semaphore's +count needs to be incremented if aParam is negative, +since in that case the waiting thread never acquired the semaphore.

+ + +

EChangePriority

Called if the thread's priority is changed. Called in whichever +context NThreadBase::SetPriority() is called from. +This function should set the iPriority field of the +thread, after doing any necessary priority queue manipulations.

aParam contains the new priority.

+ + +

ELeaveCS

Called in the context of the thread concerned if the thread +calls NKern::ThreadLeaveCS() with an unknown iCsFunction that is negative but not equal to ECsExitPending.

aParam contains the value of iCsFunction.

+ + +

ETimeout

Called if the thread's wait time-out expires and no time-out +handler is defined for that thread. Called in the context of the nanokernel +timer thread (DfcThread1). This should cancel the wait and arrange +for an appropriate error code to be returned. The handler for this +condition will usually do the same thing as the handler for ERelease with a parameter of KErrTimedOut.

aParam contains no additional information.

+ + + +

See the code in ...\e32\personality\example\... for practical examples.

Releasing the thread

When a thread's wait condition +is resolved, the nanokernel function NThreadBase::Release() should be called. This takes a single TInt parameter.

The parameter is usually KErrNone, if the +wait condition is resolved normally. A typical example is where the +semaphore on which the thread is waiting, is signalled. A negative +parameter value is used for an abnormal termination, and in this case, +the wait object may need to be rolled back.

NThreadBase::Release() should be called with preemption disabled. It performs the following +actions:

sets the NThreadBase::iWaitObj field to NULL
cancels the +wait timer if it is still running
stores the supplied +return code in NThreadBase::iReturnCode
calls the state handler passing ERelease and the return +code. If the return code is negative this should remove the thread +from any wait queues and roll back the state of the wait object. In +any case it should call NThreadBase::CheckSuspendThenReady() to make the thread ready again if necessary.

Thread +scheduling following a hardware interrupt

Most RTOS allow +interrupt service routines (ISRs) to perform operations such as semaphore +signal, queue post, set event flag directly, usually using the same +API as would be used in a thread context. The Kernel Architecture +2 nanokernel does not allow this; ISRs can only queue an IDFC or DFC.

The way to get round this limitation is to incorporate an IDFC +into each personality layer wait object. The personality layer API +involved then needs to check whether it is being invoked from an ISR +or a thread and, in the first case, it queues the IDFC. It may need +to save some other information for use by the IDFC, for example, it +may need to maintain a list of messages queued from ISRs, a count +of semaphore signals from ISRs or a bit mask of event flags set by +ISRs. Checking for invocation from an ISR can be done either by using NKern::CurrentContext(), or by checking the CPSR directly; +if doing the latter note that any mode other than USR or SVC on the +ARM counts as interrupt context.

Hardware interrupts serviced +by the RTA will need to conform to the same pattern as those serviced +by Symbian platform extensions or device drivers. This means that +the standard preamble must run before the actual service routine and +the nanokernel interrupt postamble must run after the service routine +to enable reschedules to occur if necessary. This can be done by calling Interrupt::Bind() as provided by the base port during RTA +initialisation (possibly via a personality layer call if it must be +called from C code). See also Interrupt Dispatcher +Tutorial.

+ +Personality Layer for Real Time Applications + +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-431A08D4-46DD-5A9D-B2A4-3D58C9B1E9E7-master.png Binary file Adaptation/GUID-431A08D4-46DD-5A9D-B2A4-3D58C9B1E9E7-master.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-431A08D4-46DD-5A9D-B2A4-3D58C9B1E9E7_d0e18839_href.png Binary file Adaptation/GUID-431A08D4-46DD-5A9D-B2A4-3D58C9B1E9E7_d0e18839_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-4353940E-C77B-4080-86AD-7DBE52B0A27B.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-4353940E-C77B-4080-86AD-7DBE52B0A27B.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,49 @@ + + + + + +SDIO +Interface Quick StartProvides a collection of documents that describe the SDIO client +interface API. +

SDIO tutorials

The +client interface guide describes the generic procedure for using SDIO in a +kernel-side device driver.

SDIO +Client Interface Guide

The Bluetooth example describes a reference +client driver using Bluetooth

SDIO +BT Example

The other tutorials describe the SDIO classes and commands +in more detail

DSDIOREGInterface +Class Tutorial
DSDIOSession +Class Tutorial
DSDIOStack Class +Tutorial
TSDIOCard Class +Tutorial
TSDIOFunction +Class Tutorial
TSDIOInterrupt +Class Tutorial
SDIO Commands +Tutorial

Purpose +

SDIO is an input/output protocol used to communicate with SDIO +(Secure Digital) cards and other media such as Bluetooth adapters and GPS +receivers.

Intended audience

This +document is intended to be used by device driver writers.

ArchitectureSymbian +platform implements SDIO as part of a larger framework involving SD cards, +which are a type of MMC (multimedia) card. For this reason, to use SDIO in +a device driver you will need to use classes representing SD and MMC cards +and the associated communications stack even if you only want the basic I/O +functionality.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-43782364-0865-43D0-BC89-D63BA9912FB6.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-43782364-0865-43D0-BC89-D63BA9912FB6.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,174 @@ + + + + + +Basic ManagementThis document describes how device drivers should manage shared +chunks. +

Creation

A +shared chunk is created in kernel space. The user is given a handle to the +shared chunk to access it, and can pass the handle to other process or other +drivers. Chunks are represented by DChunk objects on the +kernel side and by RChunk on the user side.

A shared +chunk is created by using Kern::ChunkCreate(), which takes +a TChunkCreateInfo argument that sets the chunk properties.

Chunk +creation should be done in a critical section, created using NKern::ThreadEnterCS() and NKern::ThreadLeaveCS(). The size of the chunk should be in multiples of MMU pages, which can be +calculated using Kern::RoundToSize(n), where n is +the actual size that needs to be rounded.

/** + Create a transmit shared chunk of specified size. + + @param aChunkSize + size of the chunk to be created + + @return KErrNone on success, standard error code on failure + */ +TInt DExUartPhysicalChannel::CreateTxChunk(TUint aChunkSize) + { + ... + // Round up the transmit chunk size to the page size. + // Kern::RoundToPageSize() rounds up the argument to the size + // of a MMU page. The size of one MMU page can be found out by + // calling Kern::RoundToPageSize(1). + + size=Kern::RoundToPageSize(aChunkSize); + + // Thread must be in critical section + NKern::ThreadEnterCS(); + ... + // Create the chunk. Example is given in next code snippet + ... + // Commit the chunk. Example is given in following sections + ... + // Thread can leave the critical section + NKern::ThreadLeaveCS(); + } + +TInt DExUartPhysicalChannel::CreateTxChunk(TUint aChunkSize) + { + ... + NKern::ThreadLeaveCS(); // Enter the critical section + + // TChunkCreateInfo holds the parameters required to create a + // chunk and is used by Kern::ChunkCreate() + TChunkCreateInfo info; + + // ESharedKernelMultiple specifies that a chunk which may be opened by + // any number of user side processes + info.iType=TChunkCreateInfo::ESharedKernelMultiple; + info.iMaxSize= size; // Chunk size + + // This specifies the caching attributes for the chunk. It can + // be no caching or fully caching (TMappingAttributes enum + // type). If the MMU does not support the requested attributes, + // then a lesser cached attribute will be used. The actual + // value used is returned in aMapAttr of Kern::ChunkCreate() + info.iMapAttr=EMapAttrFullyBlocking; // No Caching, suitable for DMA + + // Set to true if the chunk is to own its committed memory. + // In this case all memory committed to the chunk will come + // from the system's free pool and will be returned there when + // the chunk is destroyed. If the chunk will be committed to + // physical address, then EFalse can be set. + info.iOwnsMemory=ETrue; // using RAM pages + + // As chunk destruction is asynchronous we can have + // a DFC, if required, specifying a callback function to get + // the chunk destroy notification exactly. This is used if any + // follow up cleaning has to be done after chunk destruction. + info.iDestroyedDfc=NULL; // No chunk destroy DFC. + + DChunk* chunk; + TUint32 mapAttr; + // Creates a chunk that can be shared between a user thread and a + // kernel thread. This will be the initial step for a shared + // chunk. Once created, the chunk owns a region of linear + // address space of the requested size. This region is empty + // (uncommitted) so before it can be used either RAM or I/O + // devices must be mapped into it. This is achieved with the + // Commit functions. + // Here iTxChunkKernAddr returns the linear address of the + // chunk created. + // + TInt r=Kern::ChunkCreate(info,chunk,iTxChunkKernAddr, mapAttr); + if (r!=KErrNone) + { + // Thread can leave the critical section + NKern::ThreadLeaveCS(); + return r; + } + ... + }

Destruction

To allow a chunk to be properly cleaned +up, a driver should close the chunk when it is no longer required. When a +chunk is closed, the reference count is decremented by one. The chunk gets +destroyed when the reference count becomes zero. Closing the chunk should +be done within a critical section.

The destruction of the chunk happens +asynchronously, and a notification of this can be requested. This is done +using a DFC, by initialising TChunkCreateInfo::iDestroyDfc() with +the DFC object.

/** + Close the transmit chunk, that was already created. This is + called while closing the logical channel + */ +void DExUartPhysicalChannel::CloseTxChunk() + { + // Thread must be in critical section + NKern::ThreadEnterCS(); + + // Atomically get pointer to our chunk and NULL the iChunk + // member. Nkern::SafeSwap() atomically replaces the word + // referenced by aPtr with aNewValue, here NULL. + // + DChunk* chunk = (DChunk*)NKern::SafeSwap(NULL,(TAny*&)iTxChunk); + + if (chunk) + { + // Close the chunk that was created. This should be + // done in a critical section. This function decrements + // a chunk's access count, and, if the count reaches + // zero, the chunk is scheduled for destruction. + // ChunkClose() has to be called the same number of times + // as chunk creation. A mismatch in this will result + // in either a memory leak or a panic. + // + Kern::ChunkClose(chunk); + } + // Thread can leave the critical section + NKern::ThreadLeaveCS(); + }

Mapping

Shared chunks must be mapped to memory, +which means that either RAM or an I/O device must be committed to a shared +chunk before it can be used. This maps the chunk to a certain address. The +memory can be physical contiguous RAM pages, an arbitrary set of RAM pages, +a physical region, or a physical region with a list of physical addresses. +The Kernel provides the following APIs for committing these types of memory:

// Commit RAM to a shared chunk. The memory pages to commit are +// obtained from the system's free pool +TInt Kern::ChunkCommit(DChunk *aChunk, TInt aOffset, TInt aSize); + +// Commit RAM to a shared chunk. The memory pages to commit are +// obtained from the system's free pool and will have physically +// contiguous addresses. Used when TChunkCreateInfo::iOwnsMemory +// is ETrue +TInt Kern::ChunkCommitContiguous(DChunk *aChunk, TInt aOffset, + TInt aSize, TUint32 &aPhysicalAddress); + +// Commit memory to a shared chunk. The physical region committed +// is that which starts at the supplied physical address. +// Typically, this region either represents memory mapped I/O, or +// RAM that was set aside for special use at system boot time. +// This is used when TChunkCreateInfo::iOwnsMemory is EFalse. +TInt Kern::ChunkCommitPhysical(DChunk *aChunk, TInt aOffset, + TInt aSize, TUint32 aPhysicalAddress); + +// Commit memory to a shared chunk. The physical region committed +// is determined by the list of physical addresses supplied to +// this function +TInt Kern::ChunkCommitPhysical(DChunk *aChunk, TInt aOffset, + TInt aSize, const TUint32 *aPhysicalAddressList); +

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-43852F38-4841-5E6F-927B-A38ED4424F0C.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-43852F38-4841-5E6F-927B-A38ED4424F0C.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,467 @@ + + + + + +Keyword reference (P-R) +

This page lists the keywords starting from P to R.

pagedpaged

rombuild and rofsbuild

Use the paged keyword to specify that the executable +is code paged. If an executable is marked as code paged, the pages +are loaded into the RAM on demand one page after another. This can +reduce application startup time and memory usage.

This is the +same as specifying the pagedcode keyword for an executable.

pagedcodepagedcode

rombuild and rofsbuild

Same as paged.

pageddatapageddata

rombuild and rofsbuild

Use the pageddata keyword to specify that the +executable is data paged. This controls the paging of both +heap and stacks for an executable. For more fine-grained control of +memory usage, specify the paging of heap and stack data during the +creation of new threads and processes.

pagingoverride pagingoverride [NOPAGING | ALWAYSPAGE | DEFAULTUNPAGED | DEFAULTPAGED]

rombuild and rofsbuild

This overrides the code +and data paging settings for all the files, such as EXE and DLL in +an OBY file. It takes a single argument, which can be one of the following:

+ + + +Argument +Purpose + + + + +

NOPAGING

To mark all executables as unpaged, irrespective of whether +they are marked as paged or unpaged in the MMP file.

+ + +

ALWAYSPAGE

To mark all executables as paged, irrespective of whether +they are marked as paged or unpaged in the MMP file.

+ + +

DEFAULTUNPAGED

All executables, which are not marked as paged or unpaged +are marked as unpaged by default.

+ + +

DEFAULTPAGED

All executables, which are not marked as paged or unpaged +are marked as paged by default.

+ + + +

For example, the following entry in the Obey file marks +all the executables as unpaged:

pagingoverride NOPAGING

pagingpolicy pagingpolicy [NOPAGING | ALWAYSPAGE | DEFAULTUNPAGED | DEFAULTPAGED]

rombuild and rofsbuild

This overrides the default +settings for both code and data paging. It also overrides the settings +from all the previous levels. This keyword takes a single argument, which +can be one of the possible values listed in pagingoverride.

For example, the following entry in +the Obey file instructs the loader not to page the executables in +the default state:

pagingpolicy NOPAGING

payloaduid

payloaduid = <payloaduid>

Identifies +the payload of the SMR partition. This field allows kernel consumers +(such as HCR) at runtime to locate the memory regions that contain +their data.

payloadflags

payloadflags = <payloadflags>

Specifies the payload specific flags that are defined at runtime +by the the payload provider tools or user and payload consumer. This +field allows the provider to give metadata to the consumer of the +payload.

patchdata patchdata <binary_name> @ <symbolname> <newvalue> +

BUILDROM only

This keyword is introduced +since Symbian OS v9.3, and it enables you to change the value of a +constant that is exported by a binary while building the ROM image.

This means that the value of the constant can be changed without +rebuilding the binary. This is useful for quickly building ROM images +with different values for the constant, allowing you to make comparisons +in behaviour between the ROMs. This keyword must be placed before +or after the binary that it patches in the OBY file.

+ + + +

<binary_name>

The name of the binary on the PC and not the name in the +ROM image.

+ + +

The symbolic name of the constant exported by the binary.

+ + +

The replacement value. This can be specified either as an +integer or as a hexadecimal value.

It is assumed that the +exported constant is an integer that is either 1 byte, 2 bytes or +4 bytes in length, which means that the size of this replacement value +must not exceed the capacity of the constant to represent it.

+ + + +

For example, if a DLL named dllA.dll is created based on the header file dllA.h and +source file dllA.cpp:

//dllA.h +IMPORT_C int bar(); +... + //dllA.cpp +#include “dllA.h” +EXPORT_C extern const unsigned int foo = 0x1234; +EXPORT_C int bar () + { + return foo; + ... + } +

then an executable file can import this constant; +for example:

#include <e32cons.h> +#include <e32base.h> +#include “dllA.h” +... +int importValue = bar(); +... +

If you add the following statement to the .oby file to change the value of constant "foo" while +building the ROM, then the actual value of foo accessed +by the executable file is 0x100, and not 0x1234 as specified when DllA was originally +built.

patchdata dllA @ foo 0x100

Notes:

The value of +the constant in the source is not changed. It is only its value in +the copy of the binary incorporated into the ROM image that is changed.
Do not define +a patchable constant (exported data) in the source file in which it +is referred to, because the compiler may inline it. If a constant +is inlined, it cannot be patched. Hence, the constant must be defined +in a separate source file and must be referred to in other source +files by using the extern qualifier.

patched patched

rombuild only

This is used when sectioning a +ROM for language variants etc. If an executable is to be replaced, +make it patched in the first section of the ROM and include a replacement +in the top section of the ROM, after the section keyword.

This keyword appears at the point +in the obey file where the ROM is to be split. All files before this +line appear in the first (constant) section and files after appear +in the second (patch/language) section.

platsecdiagnostics platsecdiagnostics [on | off]

rombuild only

This is a keyword that affects +Symbian platform security when building a ROM.

It controls +whether or not diagnostic messages are emitted when a capability or +other platform security policy check fails. A diagnostic message takes +the general form:

*PlatSec* ERROR - xxxxx

if platform security is enforced

*PlatSec* WARNING - xxxxx

if platform security is NOT enforced.

The string +xxxxx represents the text of the message that describes the capability +being violated or the security policy check that is failing.

Specify on to enable diagnostic messages to be emitted.
Specify off to disable diagnostic messages from being emitted.
If neither on nor off is specified, then on is assumed as a default.

platsecdisabledcaps platsecdisabledcaps [+|-]cap1 [+|- cap2] [+|- cap3] ...[+|-capn]

rombuild only

This is a keyword that affects +Symbian platform security when building a ROM.

It allows capabilities +to be added to, or removed from, all executables in the ROM image.

Specify a list of capability names prefixed either by a + character or a - character. The first +capability name in the list does not need to prefixed by either of +these characters, but if it is omitted a + character +is assumed.

Capabilities preceded by a + character +are added to all executables, while those preceded by a - character are removed from all executables.

Any of the capabilities +listed in the left hand column in the table below can be specified; +follow the corresponding link in the right hand column for a description +of that capability. Note that you can also use:

+ALL

to add all capabilities, and

+NONE

to remove all capabilities.

Note, however, that the combinations -ALL and -NONE are not permitted

+ + + +

+ + + + +Capability + + + +

+ + + + +TCapability Enum value + + + +

+ + +

TCB

ECapabilityTCB

+ + +

CommDD

ECapabilityCommDD

+ + +

PowerMgmt

ECapabilityPowerMgmt

+ + +

MultimediaDD

ECapabilityMultimediaDD

+ + +

ReadDeviceData

ECapabilityReadDeviceData

+ + +

WriteDeviceData

ECapabilityWriteDeviceData

+ + +

DRM

ECapabilityDRM

+ + +

TrustedUI

ECapabilityTrustedUI

+ + +

ProtServ

ECapabilityProtServ

+ + +

DiskAdmin

ECapabilityDiskAdmin

+ + +

NetworkControl

ECapabilityNetworkControl

+ + +

AllFiles

ECapabilityAllFiles

+ + +

SwEvent

ECapabilitySwEvent

+ + +

NetworkServices

ECapabilityNetworkServices

+ + +

LocalServices

ECapabilityLocalServices

+ + +

ReadUserData

ECapabilityReadUserData

+ + +

WriteUserData

ECapabilityWriteUserData

+ + +

Location

ECapabilityLocation

+ + + +

For example:

PlatSecDisabledCaps LocalServices+ReadDeviceData+ReadUserData

platsecenforcement platsecenforcement [on | off]

rombuild only

This is a keyword that affects +Symbian platform security when building a ROM.

It controls +whether or not platform security is enforced.

Specify on to enable platform security enforcement. If enforcement +is enabled, and a capability or other platform security policy check +fails, then the appropriate action for a failed platform security +check occurs.
Specify off to disable platform security enforcement. If +enforcement is disabled, and a capability or other platform security +policy check fails, then the system continues as though the original +platform security check had in fact passed.
If neither on nor off is specified, then on is assumed as a default.

platsecenforcesysbin platsecenforcesysbin [on | off]

rombuild only

This is a keyword that affects +Symbian platform security when building a ROM.

It controls +whether or not to force the location of binary executables into the \Sys\Bin\ directory.

Specifying on has the following effects:
- rombuild places all executables into Z:\Sys\Bin\, and +overrides any file path specified in any of the .IBY files.
- the loader only +looks for files in the \Sys\Bin\ directory and +only loads files from the \Sys\Bin\ directory. +If a different path is specified this path is ignored and the \Sys\Bin\ directory is searched.
Specifying off causes rombuild to place files according +to the file path specified in the .IBY files +and permits the loader to load files from any specified path.
If neither on nor off is specified, then on is assumed as a default.

platsecprocessisolation platsecprocessisolation [on | off]

rombuild only

This is a keyword that affects +Symbian platform security when building a ROM.

It controls +whether or not insecure APIs inherited from EKA1 (Versions 8.1a, 8.0a, +7.0s, and earlier) are to be disabled. These are APIs whose use is +intended to be restricted. The kernel provides run-time checks for +their correct usage.

See the list of APIs affected +by the platsecprocessisolation keyword.

Specify on to disable insecure APIs. Incorrect use of this +set of restricted APIs results in diagnostic messages, if platsecdiagnostics is on, and raises panics +or causes errors if platsecenforcement is on.
Specify off to allow insecure APIs.
If neither on nor off is specified then on is assumed as a default.

preferredpreferred

rombuild only

This +keyword specifies that the major version of the executable binary +must be preferred over its minor versions. The minor version specifies +the revision of the executable. The major version enables you to identify +whether two versions of an executable are compatible. The two versions +of an executable can be compatible only if they have same major version.

The executable's header stores minor and major versions of the +executable.

primary[[HWVD]] primary[[HWVD]] = <source-file> <destination-image-file> [File-attribute-list] [Override-Attribute-list]

rombuild only

A standard executable file that +is loaded directly, bypassing the file server. The Boot program loads +and gives control to the primary; this is the Kernel.

As with +all standard executable files, this is loaded, relocated and stripped +of its relocation information.

Note that the HWVD is optional but, if specified, must be enclosed within square brackets.

priority priority = <hex-number> | <priority-keyword>

rombuild only

Sets the priority of the process. +The priority can be a hexadecimal number, or one of the keywords listed +below. The keywords correspond to the associated priority value.

+ + + +

Keyword

Process priority

+ + +

low

EPriorityLow

+ + +

background

EPriorityBackground

+ + +

foreground

EPriorityForeground

+ + +

high

EPriorityHigh

+ + +

windowserver

EPriorityWindowServer

+ + +

fileserver

EPriorityFileServer

+ + +

realtimeserver

EPriorityRealTimeServer

+ + +

supervisor

EPrioritySupervisor

+ + + +

processprocess = <file path of process being attached>

rombuild only

This keyword specifies the process +to which a DLL is attached.

reloc reloc = <hex-address>

rombuild only

Overrides the default stack size +for the executable.

rem rem <comment>

rombuild and rofsbuild

Defines a comment line. +Text that appears after the rem keyword is interpreted as a comment.

rename rename[[HWVD]]= <existing-file> <destination-file> [ full-attribute-list ]

rombuild and rofsbuild

Adding a file and then +renaming it is equivalent to adding it directly at the rename destination. +The existing and destination directories do not have to be the same.

RIGHT_NOW RIGHT_NOW

BUILDROM only

A pre-defined substitution. This +is replaced with the exact time in the format dd/mm/yy hh:mm:ss

Note that there is no UNDEFINE facility, and substitutions +are applied in an unspecified order.

rofsname rofsname = <filename>

rofsbuild only

Defines the name of the core +image.

rofssize rofssize = <size in bytes>

rofsbuild only

Specifies the maximum size of +the core image, or the maximum size of the extension.

romalign romalign = <hex-alignment>

rombuild only

The address alignment boundary +for files in the ROM.

This value should be greater than 4 +and a multiple of 4. The recommended value is 0x10. If no value is +specified, rombuild defaults to using a value of +0x1000. If the value specified is not a multiple of 4, it is rounded +off.

ROMBUILD_OPTION ROMBUILD_OPTION <command-line-option>

BUILDROM only

Adds additional command line parameters +to the eventual invocation of rombuild. +It is primarily used to specify the -no-header option +for platforms which don't want the 256-byte REPRO header. The ROMBUILD_OPTION keyword can be used multiple times if desired.

romchecksum romchecksum = <32 bit hex-number>

rombuild and rofsbuild

The checksum in the final +ROM image is made using the following algorithm:

checksum += romchecksum - sum of 32bit words in ROM image.

ROM_IMAGE ROM_IMAGE <id> <name> [size=<rom max size>] [xip | non-xip] [compress | no-compress] [extension]

BUILDROM only

Defines a ROM image.

This +is a ROM configuration feature; up to 8 ROM images can be defined +for a device.

+ + + +

A value in the range 0..7 to identify the ROM image.

+ + +

name

A name suitable as a suffix for the ROM image, IBY and logs.

+ + +

non-xip

Specifies a non-XIP ROM. If not specified, a XIP ROM is +the default

+ + +

size = <rom-max-size>

Defines the maximum size of the ROM. Not required for XIP +ROMs.

+ + +

compress

Compresses an XIP ROM. If not specified, no compression +is the default behaviour.

+ + +

extension

Defines this image as an extension to the previous image.

+ + + +

To mark a file for inclusion in a ROM it is prefixed with +the keyword ROM_IMAGE. For example:

ROM_IMAGE[2] data=\private\<process SID>\Apps\Calc\calc.INSTCOL_MBM \private\<process SID>\Apps\Calc\Calc.mbm

A Block of files can be included using '{' '}' +braces, for example:

ROM_IMAGE[2] + { + #include "calc.iby" + #include "word.iby" + } +

File blocks can be nested, for example:

ROM_IMAGE[2] + { + #include "calc.iby" + ROM_IMAGE[0] + { + #include "word.iby" + } + #include "video.iby" + } +

romlinearbase romlinearbase = <hex-address>

rombuild only

The virtual address of the start +of ROM, in hex.

This is the address at which the kernel expects +to find the start of the ROM. The recommended value depends on the +memory model:

For the Multiple +Memory Model, typically used on ARMV6 based hardware platforms, the +recommended value is 0x80000000.
For the Moving +Memory Model, typically used on ARMV5 based hardware platforms, the +recommended value is 0xF8000000.

romname romname = <rom-file-name>

rombuild only

This is the name of the output +file. It contains the ROM image that rombuild creates.

romnameeven romnameeven = <rom-file-name-even> +

rombuild only

rombuild can write two separate ROM images, one containing the odd bytes +of the image and the other the even. This is done if this keyword +and the romnameodd keyword are used to specify the output filenames +for the two half-images. A filename of "*" can be specified, which +means use the file name specified on the romname keyword and append .even.

romnameodd romnameodd = <rom-file-name-odd>

rombuild only

rombuild can +write two separate ROM images, one containing the odd bytes of the +image and the other the even. This is done if this keyword and the romnameeven keyword are used to specify the output filenames +for the two half-images. A filename of "*" can be specified, which +means use the file name specified on the romname keyword and append .odd.

romsize romsize = <hex-size>

rombuild and rofsbuild

The size of the entire ROM, +in hex, for example, 0x400000 for a 4MB ROM.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-44540C74-CD73-5D8E-A9E0-F90F46B4E7B1.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-44540C74-CD73-5D8E-A9E0-F90F46B4E7B1.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,54 @@ + + + + + +Preventing +And Recovering From Thrashing TutorialDescribes how to reduce the chance of thrashing occurring in demand +memory and how to recover from thrashing. +

Introduction

Thrashing +is a state where the vast majority of the processing time is spent paging +memory in and out of the system and very little is spent useful work. If this +situation persists, then the system performance rapidly becomes unacceptable +and will appear to the user to have hung.

Background information

The following is useful background +reading:

Thrashing

Thrashing features

When thrashing occurs the device +will appear to do nothing or 'hang' for period. Unlike a deadlock however, +the device can recover from thrashing.

Prevention of thrashing

The following can be used +reduce the chance of thrashing:

Compress pages in memory to decrease the amount of memory that has +to be paged in and out
Limit the maximum size of each process's paged memory to the minimum +size of the paging cache
Partition the page cache per-process and allocate pages to processes + based on the Working Set Size (WSS) of threads in that process
Swap out the oldest pages in advance to free up memory to cope with +spikes in paging demand
Don't let threads steal pages from other threads

Recovery from thrashing

The possible courses of +action to undertake, should thrashing occur, are :

Reboot the device
Kill a thread
Decrease the number +of paged threads running concurrently
Pick one thread with +a high page fault rate and stop other threads stealing pages from the thread's +associated process
Prompt the user-side +memory manager to close down applications.

+Thrashing +guide +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-450BF1D4-85D7-45D4-8893-57DA8F1640E9.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-450BF1D4-85D7-45D4-8893-57DA8F1640E9.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,12 @@ + + + + + +Baseport TemplateDescribes the Baseport Template platform service. \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-455ED16F-D288-42C9-AA7A-AE5822F7A5BC.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-455ED16F-D288-42C9-AA7A-AE5822F7A5BC.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,49 @@ + + + + + +Time QuickstartProvides a brief overview of the contents of the Time platform +service. +

Time platform service provides the state of the device +(mobile). It is controlled by a state machine that is SSM. These states +are defined by system state policies within a SSM plug-in and system +state changes are triggered by system-wide property changes or external +requests.

+ Concepts

MRtcAdaptation: An SPI that allows customizing +of the functionality of Real Time Clock (RTC) adaptation interface.
Alarm Server: manages all alarms on the device and enables +client UI applications to use the services provided by the Alarm Server. +It relies on the Alarm UI to notify, which includes displaying and +playing sounds.
Alarm Client and Alarm Shared: are the static interface DLLs. +Alarm client is the client side of the Alarm Server, which allows +other components to interact with the Alarm Server. The Alarm Shared +facilitates a common format shared across server and its clients for +providing definition for an alarm. It consists of shared objects such +as alarm class, IPC messages, repeat definitions, alarm states.
System State Manager (SSM): manages the state of a device throughout +its lifecycle. SSM extends the existing Generic Start-up Architecture +(GSA) and also manages the system state and the system-wide property.

+ Key uses for hardware implementators +

Including session alarms
Adding, updating and deleting alarms.
Performing alarm category-based operations such as retrieval +and deletion.

Key +uses for device creators

Activating an alarm on a specific date.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-4592D493-A47C-5622-8C03-F24FABB4381C-master.png Binary file Adaptation/GUID-4592D493-A47C-5622-8C03-F24FABB4381C-master.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-4592D493-A47C-5622-8C03-F24FABB4381C_d0e19271_href.png Binary file Adaptation/GUID-4592D493-A47C-5622-8C03-F24FABB4381C_d0e19271_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-463915EE-25DB-4ABD-AA80-1C10CD242072.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-463915EE-25DB-4ABD-AA80-1C10CD242072.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,16 @@ + + + + + +Register Access Build GuideDescribes how to build the Register Access platform service. +

There are no specific build instructions for Register Access platform +service. Register Access platform is a part of the ASSP layer. You +should use the ROMBUILD commands to build the baseport.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-465D1450-B1EF-568B-B518-34ACE8C1697C-master.png Binary file Adaptation/GUID-465D1450-B1EF-568B-B518-34ACE8C1697C-master.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-465D1450-B1EF-568B-B518-34ACE8C1697C_d0e9201_href.png Binary file Adaptation/GUID-465D1450-B1EF-568B-B518-34ACE8C1697C_d0e9201_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-4804B6E0-9199-5F3E-984A-4B00B3984E45.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-4804B6E0-9199-5F3E-984A-4B00B3984E45.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,18 @@ + + + + + +Porting the +Power Resource ManagerThis tutorial describes the steps needed to successfully port the +PRM for a particular device. +

The Power Resource Manager (PRM) is a framework for managing system power +resources. This framework improves portability across different platforms +and reduces device driver complexity.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-4862EA2E-6BFE-5E11-B527-7EBA94BB0EA2.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-4862EA2E-6BFE-5E11-B527-7EBA94BB0EA2.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,116 @@ + + + + + +OBY Tutorial Describes the new demand paging keywords available to the +OBY. file. +

Introduction

The new keywords that are available in the OBY file are used +to specify whether an object is paged, and if so what kind of demand +paging it supports.

With the addition of writable +data paging, the list of paging modifiers is shown below:

Procedure

With the addition of writable data +paging, the list of paging modifiers is shown below:

+ + + +

Keyword

Behaviour on Symbian platform

+ + +

paged

Enables code and data paging

+ + +

unpaged

Disables code and data paging

+ + +

pagedcode

Enables code paging

+ + +

unpagedcode

Disables code paging

+ + +

pageddata

Enables data paging

+ + +

unpageddata

Disables data paging

+ + + +

These modifiers appear in OBY files at the end of statements +relating to user-side ROM objects i.e. 'file=', 'dll=', 'data=' +and 'secondary='statements). For example:

file=ABI_DIR\DEBUG_DIR\MyLibrary.dll \sys\bin\MyLibrary.dll unpaged

The data paging keywords only make sense when applied to executable +binary files.

For an executable file, the use of one of the +above keywords in the oby file will override the paging settings in +the mmp file. However this will not be true, if the pagingoverride, codepagingoverride or datapagingoverride keywords are used in the MMP file, in the case of nopaging or alwayspage .

Executing +the buildrom command builds with no errors or warnings.

+OBY +file example

An example of an OBY file that uses the new +demand paging keywords is given below:

// +// MyDPConfig.oby +// +// The section below, is used to specify if XIP ROM paging is implemented. +#if !defined PAGED_ROM +#define PAGED_ROM +#endif + +// The sections below, is used to specify if code paging is implemented. +#if !defined USE_CODE_PAGING +// Comment out the next line if code paging is wanted +#define USE_CODE_PAGING +#endif + +#if !defined CODE_PAGING_FROM_ROFS +// Comment out the next line if code paging from primary rofs is wanted +#define CODE_PAGING_FROM_ROFS +#endif + +// The section below, is used to configure the writable data paging and to specify what the +// default paging behaviour is to be. +ROM_IMAGE[0] { +pagedrom +compress +// Min Max Young/Old +// Live Live Page +// Pages Pages Ratio +demandpagingconfig 256 512 3 +pagingoverride defaultpaged + +// This section specifies what the default paging behaviour is to be for code paging. +#if defined USE_CODE_PAGING && !defined USE_DATA_PAGING +codepagingpolicy defaultpaged +#endif + +#if defined USE_DATA_PAGING +#if defined USE_CODE_PAGING +codepagingpolicy defaultpaged +#endif + +datapagingpolicy defaultpaged +#endif +} + +#if defined CODE_PAGING_FROM_ROFS || defined USE_DATA_PAGING +ROM_IMAGE[1] { +pagingoverride defaultpaged +} +#endif + +// Now specify the files to be used +file=ABI_DIR\DEBUG_DIR\MyLibrary.dll \sys\bin\MyLibrary.dll unpaged + +

The next step is to Build the writable +data paging ROM

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-49379616-C235-598D-AE43-668998AD072B.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-49379616-C235-598D-AE43-668998AD072B.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,362 @@ + + + + + +Process, +Thread, Stack and Memory AttributesReference for users of the debug monitor tool to the attributes +of Kernel objects and memory structure. +

Process and thread priorities
Thread state summary
Thread and process exit information summary
Critical threads and processes
Kernel calls and thread context
Stacks
Virtual memory and run addresses

Process and +thread priorities

Internally the scheduler always deals with nanokernel +threads, NThread objects, and their associated priority between +0 (lowest) and 63 (highest). In general, a thread with a higher priority that +is ready to run will always run in preference to threads with a lower priority. +The only exception is where a higher priority thread waits on a nanokernel +fast mutex held by a lower priority thread. In this case, the higher priority +thread will yield to the lower priority thread holding the mutex.

A +Symbian platform thread, a DThread object, has an embedded NThread, +which enables it to be scheduled by the nanokernel.

There are two +ways of setting a priority for Symbian platform thread:

using the two-level +priority scheme
using an absolute priority.

The +two level priority scheme

In this scheme, a Symbian platform thread +priority is relative to the priority of its owning process. By default, Symbian +platform threads inherit the priority of their owning process when they are +created. This priority can be raised or lowered relative to the process priority +- this just sets the thread’s priority to the process priority plus or minus +a specified priority weighting. If the priority of the process is changed, +the priority of its threads will change relative to other threads in the system +but will remain the same relative to each other.

The default priority +of a process is EPriorityForgeround, which is an absolute +priority of 350. Threads by default are created with relative priority EPriorityNormal which +sets them to the same priority as the owning process. The window server lowers +the priority of background UI processes to EPriorityBackground (250).

The +NULL thread, also known as the idle thread, runs at priority 0, and means +that it will only run when there are no other threads ready to run.

Symbian +platform thread priorities map onto NThread priorities in +the range 1 to 31 as shown in the table below.

+ + + +

Thread priority

Idle

Much Less

Less

Normal

Much More

Real Time

+ + +

Process priority

+ + +

Low

+ + +

Background

+ + +

Foreground

+ + +

High

+ + +

SystemServer1

+ + +

SystemServer2

+ + +

SystemServer3

+ + +

RealTimeServer

+ + + +

where:

the process priority +values are defined by the internal Symbian platform enum TProcPriority, +defined in ...\e32\include\kernel\kern_priv.h. The symbols +in the table correspond to the symbols in the enum.
the thread priority +values are defined by the internal Symbian platform enum TThrdPriority, +defined in ...\e32\include\kernel\kern_priv.h. The symbols +in the table correspond to the symbols in the enum.

Absolute +priority scheme

It is possible to set an absolute priority that +is not relative to the process priority; it is not affected by changes in +the process priority.

Thread state +summary

This is a brief summary about nanokernel thread states +and Symbian platform thread states.

Nanokernel +thread states

The state of a nanokernel thread is referred to +as the NState (or N-state). This is to disambiguate it from any other state, +such as the state of a Symbian platform thread (referred to as the MState +or M-state).

The states of a nanokernel thread are defined by the +values of the NThreadBase::NThreadState enumeration.

Symbian platform thread states

The state of a Symbian platform +thread is referred to as the MState (or M_state). This is in addition to the +nanokernel N-state, and tracks threads waiting on Symbian platform synchronization +objects. The DThread class representing a Symbian platform +thread is internal to Symbian, but the following table defines its possible +states. The values in the left-hand column are the enumerators of the internal +enumeration DThread::TThreadState.

+ + + +

ECreated

The initial state of all Symbian platform threads. It is a transient +state; the thread starts in this state when the DThread object +is created, and stays in that state until it is ready to be resumed, typically +when DLL linkage and memory allocation is complete. At this point, the state +will change to EReady.

+ + +

EDead

This is the final state of a Symbian platform thread. A thread enters +this state when it reaches the end of its exit handler, just before the nanokernel +terminates it. In effect, the thread has exited but has not yet been deleted.

+ + +

EReady

This indicates that the thread is not waiting on, or attached to +any Symbian platform kernel wait object. It does not necessarily imply that +the thread is actually ready to run - this is indicated by the N-state. For +example, a thread that is explicitly suspended or waiting on a nanokernel +wait object (generally a fast semaphore) still has a READY M-state provided +that it is not attached to any Symbian platform wait object.

+ + +

EWaitSemaphore

This indicates that the thread is currently blocked waiting for +a Symbian platform semaphore, and is enqueued on the semaphore’s wait queue. +The thread’s DThread::iWaitObj field points to the semaphore.

For +example, this is the case if the thread calls User::WaitForRequest() or RSemaphore::Wait()

+ + +

EWaitSemaphoreSuspended

This indicates that the thread has been explicitly suspended after +blocking on a Symbian platform semaphore, and is enqueued on the semaphore’s +suspended queue. The thread’s DThread::iWaitObj field points +to the semaphore.

+ + +

EWaitMutex

This indicates that the thread is currently blocked waiting for +a Symbian platform mutex, and is enqueued on the mutex wait queue. The thread’s DThread::iWaitObj field +points to the mutex.

+ + +

EWaitMutexSuspended

This indicates that the thread has been explicitly suspended after +blocking on a Symbian platform mutex, and is enqueued on the mutex suspended +queue. The thread’s DThread::iWaitObj field points to the +mutex.

+ + +

EHoldMutexPending

This indicates that the thread has been woken up from the EWaitMutex +state but has not yet claimed the mutex. The thread is enqueued on the mutex +pending queue and the thread’s DThread::iWaitObj field points +to the mutex.

+ + +

EWaitCondVar

This indicates that the thread is waiting on a condition variable.

+ + +

EWaitCondVarSuspended

This indicates that the thread is suspended while waiting on a condition +variable.

+ + + +

Thread and +process exit information summary

User threads and processes have +“exit information”. When a thread or process terminates the reason for the +termination is found in the exit information. For example, a panic will store +the panic category and reason in the exit information. Exit information has +three parts: the exit type, exit reason and exit category.

Exit type +is defined by the TExitType enum.

When a thread +or process is created, its exit type is set to 3. An exit type of 3 indicates +that the thread is still active, though not necessarily running. If the thread +terminates for any reason, then the exit type is changed to reflect the cause +of the exit.

Once the thread or process has exited, the exit reason +and exit type fields will contain useful information. The contents depends +on the type of exit.

Note that if the main thread in a process exits, +then the process will exit with the same exit information as the thread.

Exit category: Terminate

if RThread::Terminate() or RProcess::Terminate() is +called, then the exit category is Terminate, and the exit +reason is the value of the aReason argument passed to these +functions.

Exit +category: Kill

If RThread::Kill() or RProcess::Kill() is +called, then the exit category is Kill, and the exit reason +is the value of the aReason argument passed to these functions.

Exit category: panic

If a thread panics, then the exit category +is panic, and the exit reason is the panic number. For example +a USER-19 panic would give the following exit information:

exit type = 2 +exit category = “USER” +exit reason = 19 +

Critical threads +and processes

Marking a thread or process as “system critical” +means that it is an integral and essential part of the system, for example, +the file server. In effect the thread or process is being declared necessary +for correct functioning of the device. If a system critical thread exits or +panics then the device will reboot; during development it will enter the debug +monitor. A thread can be set as process critical, which means that if it panics +the process will be panicked.

Kernel calls +and thread context

When a user thread makes a call into any kernel +code, the kernel code continues to run in the context of the user thread. +This applies to device driver code.

The stack is swapped to a kernel-side +stack and the permissions of the thread are increased to kernel privilege, +but otherwise the user thread is still running. Each thread has a small kernel +stack used to handle kernel calls – it would be dangerous to continue using +the normal thread stack in case it overflows. Some calls are handled in this +state, others – typically device drivers – will post a message to a kernel +side thread to carry out the request.

Stacks

When +a process is created, a chunk is allocated to hold the process executable's .data section +(initialised data) and .bss section (zero filled data). Sufficient +space (default 2Mb) is also reserved as user-side stack space for threads +that run in that process.

By default, each thread is allocated 8k +of user-side stack space. A guard of 8k is also allocated.

The stack +area follows the .data and .bss sections, +and each thread's user side stack follows. On ARM processors the stack is +descending, so that as items are added to the stack, the stack pointer is +decremented. This means that if the stack overflows, the stack pointer points +into the guard area and causes a processor exception, with the result that +the kernel panics the thread.

+ +

Return addresses are stored by pushing them on to the stack so at +any point you can trace through the stack looking at the saved return addresses +to see the chain of function calls up to the present function.

The +size of the user-side stack space has an indirect effect on the number of +threads that a process can have. There are other factors involved, but this +is an important one. The limit is a consequence of the fact that a process +can have a maximum of 16 chunks. This means that if threads within a process +can share a heap (allocated from a single chunk), then it is possible to have +a maximum of 128 threads per process [2Mb/(8K + 8K)]. More threads may be +possible if you allow only 4K of stack per thread.

Apart from the +kernel stack attached to each thread, the kernel also maintains stacks that +are used during processing of interrupts, exceptions and certain CPU states. +Interrupts and exceptions can occur at any time, with the system in any state, +and it would be dangerous to allow them to use the current stack which may +not even be valid or may overflow and panic the kernel. The kernel stacks +are guaranteed to be large enough for all interrupt and exception processing.

Virtual memory +and run addresses

Symbian platform devices have an MMU which is +used to map the addresses seen by running code to real addresses of memory +and I/O. The MMU in effect creates a virtual memory map, allowing scattered +blocks of RAM to appear contiguous, or for a section of memory to appear at +different addresses in different processes, or not at all.

Symbian +platform uses the MMU to provide memory protection between processes, to allow +sharing of memory, efficient allocation of RAM and to make all processes “see” +the same memory layout. Three different memory models are supported by Symbian +platform on ARM CPUs:

moving model: this is +the model familiar from EKA1 where processes are moved to a run-address in +low memory when executing and moved back to a home-address in high memory +when not running.
direct model: this is +used when the CPU does not have an MMU, or is emulating a system without an +MMU. Not normally used, but occasionally useful for development boards
multiple model: only +supported in ARM architecture V6 and above, each process has its own set of +MMU tables. A context switch changes the current MMU table to the new thread’s +table, instead of moving memory about in a single table as with moving model.

Fixed +processes

For ARM architectures with a virtually-tagged cache, +fixed processes avoid the need to flush the cache on context switches by keeping +all the code and data at a fixed address. This implies that there can only +ever be one instance of each fixed process because the data chunk address +cannot be changed.

Important servers such as the file server and window +server are fixed.

There is no limit to the number of fixed processes +that can be supported. The kernel will attempt to use ARM domains for fixed +process protection, but there are a limited number of domains so when they +are exhausted normal MMU techniques will be used. Domains are slightly faster +in a context switch but this is negligible compared to the real purpose of +the fixed process in avoiding the cache flush.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-4993AF8E-28C3-54BA-8D27-D86E05D39CFD.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-4993AF8E-28C3-54BA-8D27-D86E05D39CFD.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,61 @@ + + + + + +Crash +Logger TechnologyThe Crash Logger contains a logger program that stores system state +information when a crash occurs, and a reader application that can be used +later to get this information +

The +crash logger

When the kernel crashes, control is handed to the +crash logger. It tries to read as much state information as it can reasonably +find, and dumps it to a pre-reserved location in permanent storage flash storage).

Support +exists for dumping information to nor flash and nand flash. +The crash logger must have its own drivers to do this, as it cannot be assumed +that any specific part of the kernel is operating correctly in these circumstances. +These drivers are essentially simplified versions of the standard drivers.

All +monitoring functionality, crash logging and crash debugging is placed in kernel +extensions. Functionality can be enabled or disabled by placing the appropriate +kernel extensions into ROM at ROM build time.

To support both crash +logging and debugging without duplicating code, a common module, exmoncommon.dll, +has been created. This extension contains all of the generic monitoring code, +and supports features such as dumping registers, thread stacks and object +containers and is responsible for registering with the kernel’s crash monitor +entry point:

Epoc::SetMonitorEntryPoint()

This +extension must be placed in ROM before either of the two monitoring extensions, +as they both rely on its functionality. As exmoncommon.dll depends +on the underlying memory model, it is built from the Variant.

After +the common monitoring code registers itself with the kernel, further debugging +extensions may register with the common code. These extensions are called +when the kernel fails, in the order that they register. The maximum number +of extensions currently supported is nine though only two- the interactive +debugger, and the non-interactive crash logger are provided. However, this +is an arbitrary limit set by the macro definition MONITOR_MAXCOUNT in +the file E32\include\kernel\monitor.h, and can be increased +given sensible use cases.

exmondebug.dll is +the traditional interactive debugger.
exmonlog.dll is +the crash logger.

These DLLs are also built from the Variant. In the case of the crash +logger, two separate .mmp files exist:

one for NAND flash, +building exmonlognand.dll
one for NOR flash, building exmonlognor.dll

The rombuild scripts ensure that the crash logger for only one type +of flash is placed into the ROM, and named as exmonlog.dll.

The crash reader

At +the next system boot, the crash reader application uses the normal system +flash drivers to read the crash log from the reserved non-filesystem (non-uservisible) +flash area, and to write it into the user-visible file system.

The +output file from the crash reader is a text file, or a compressed GZIP-compatible file.

The +crash reader application is called crashread.exe, which +is built from e32utils\crashread\crashread.mmp.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-4A2E212E-BC1B-5965-9A62-6309CC7CAAAB-master.png Binary file Adaptation/GUID-4A2E212E-BC1B-5965-9A62-6309CC7CAAAB-master.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-4A2E212E-BC1B-5965-9A62-6309CC7CAAAB_d0e61647_href.png Binary file Adaptation/GUID-4A2E212E-BC1B-5965-9A62-6309CC7CAAAB_d0e61647_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-4A2E212E-BC1B-5965-9A62-6309CC7CAAAB_d0e65116_href.png Binary file Adaptation/GUID-4A2E212E-BC1B-5965-9A62-6309CC7CAAAB_d0e65116_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-4A910E9F-E881-51D7-A84A-CBC6AC343FD1.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-4A910E9F-E881-51D7-A84A-CBC6AC343FD1.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,21 @@ + + + + + +Level +2 Cache MacrosDescribes the macros that define if the phone uses Level 2 cache. +

The macros are used in the platform-specific configuration header file, config.inc, +described in Platform-Specific +Configuration Header.

CFG_HasL210CacheCFG_HasL210Cache

Includes +support for the L210 cache in the bootstrap.

CFG_HasL220CacheCFG_HasL220Cache

Includes +support for the L220 cache in the bootstrap.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-4AEF7595-17C0-513E-9568-B212E6194388.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-4AEF7595-17C0-513E-9568-B212E6194388.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,163 @@ + + + + + +Record +operationDescribes the operation of the Sound Driver for sound recording. +

Client functions

Many aspects regarding the way +that the Sound Driver recording operates are similar to the way it handles +playback. One difference is how the memory location in the Shared +Chunks for the transfer is determined. In play requests, the client +specifies the source location in the chunk for the transfer having arranged +for the data to be loaded there prior to the request. For record requests, +the client just requests a buffers worth of record data and allows the driver +to decide which buffer to use for the request.

The driver commences +recording when the client issues the first RSoundSc::RecordData() request. +However, unlike playback operation, once recording has commenced, the driver +continues to record data into its available record buffers until it is told +to stop. To stop the driver capturing record data, the client must either +issue RSoundSc::Pause() to temporarily suspend recording, RSoundSc::CancelRecordData() to +terminate record operation, or close the driver channel altogether.

The +client specifies the number and size of the record buffers available to the +driver within the shared chunk by calling either RSoundSc::SetBufferChunkCreate(), +to create a buffer, or RSoundSc::SetBufferChunkOpen() to +open an existing buffer.

When the driver starts recording, all the +buffers in the shared chunk are empty, and the driver can use all of these +available buffers. They are filled one by one, and if the client is slow to +request the recorded data, then once the driver has filled all of the available +empty buffers, it is forced to discard the earliest one filled and re-use +this to continue recording data.

Each time the client requests a buffers +worth of recorded data with RSoundSc::RecordData(), it +is given the earliest one filled. This buffer is now said to be in-use and +unavailable to the driver for capturing. This buffer remains in-use until +it is freed by the client with a call of RSoundSc::ReleaseBuffer().

When +buffers are in use by the client the number of buffers available to the driver +for capture is reduced. If the client is slow to release buffers and the number +of available buffers falls to two then further RSoundSc::RecordData() requests +fail with KErrInUse until the client has freed some buffers. +The driver always needs a working set of at least two buffers in order to +achieve uninterrupted data capture. The driver always has a current buffer +which is actively being filled and another queued in advance. If the client +fails to take buffers at full speed then they are discarded by the driver.

The +driver does not slow down if it runs out of empty buffers.

Buffers

The driver maintains three buffer lists:

free list
completed list
in-use list.

A record buffer can only exist in one of these lists at any time. +The free list contains buffers that are empty and not in use by the client. +Once a buffer has been filled with record data it is moved into the completed +buffer list. Here the buffer remains until it is passed back to the client +in response to a record request. When a client is using the buffer it is deemed +as in-use and is moved to the in-use list. Each time the client successfully +calls RSoundSc::ReleaseBuffer() to free up a buffer then +the driver moves this from the in-use list to the free list.

The driver +also maintains two record buffers which are excluded from any of the three +lists.

the current buffer, +the one actively being filled with record data
the next buffer which +becomes the active buffer once the current buffer is filled

During recording there may be DMA requests pending for both the current +buffer and the next buffers.

+ The record buffer cycle +

The numbers one to five show the buffer cycle under normal operation, +while the letters A to C show error induced operation.

+ +

When recording commences, the driver removes two buffers from the +free list making one the current buffer and the other the next buffer (4 and +5).

When the current buffer is set as filled, the LDD normally adds +this to the completed list (1). If a record error has occurred while recording +to this buffer and it is only partially filled, or even empty then the buffer +is still added to the completed list, as the client needs to be informed of +the error (1). The only exception is in handling record pause, where a record +buffer ends up being completed with no error and with no data added. In this +case the buffer is added straight into the free list (A).

Having added +the current buffer to one of these lists, the driver moves the next buffer +to the current buffer (5) and then obtains a new next buffer (4). In normal +operation this comes from the free list but if the client is slow, this list +may be empty and the buffer is taken from the completed list (B). This is +a buffer overflow situation which is reported to the client as a response +to its next RSoundSc::RecordData() request as KErrOverFlow.

Whenever +a buffer is filled, the driver checks if there is a record request pending +(1). Similarly, when the driver processes a new record request it checks if +a filled buffer is already available. In either case, if a request can be +completed to the client then the earliest buffer completed is returned. If +this buffer was filled successfully then it added to the in-use list (2). +However, if an error occurred whilst filling the buffer then it is returned +straight to the free list instead (C).

Each time the client successfully +calls RSoundSc::ReleaseBuffer() to free up a buffer then +the driver moves this from the in-use list to the free list (3).

Audio recording

RecordData()

If +the driver is not already recording data then the first RSoundSc::RecordData() request +is handled in the context of the driver DFC thread, as access to the audio +hardware is required to enable record operation. However, for efficiency, +subsequent record requests from the client are handled entirely in the context +of the calling thread, as access to the audio hardware is not required to +handle the request. The driver only has to check whether there is a filled +record buffer already available. If there is then the driver completes the +request straight away. If not, the driver saves the details of the request +until a filled buffer does become available.

Returning to the case +of a record request where the driver is not already in the process of recording +data, the LDD first checks whether the client has specified or supplied a +shared chunk to the driver channel and has set the audio configuration and +record level. If the buffer configuration has not been specified then the +driver cannot proceed and returns KErrNotReady. If the audio +configuration or record level has not been specified then the LDD applies +default settings to the audio hardware device for each instead by calling +the functions DSoundSc::SetConfig() and DSoundScPdd::SetVolume() on +the PDD.

StartTransfer()

Depending +on the mapping attributes of the shared chunk, the LDD may now need to purge +the region of the record chunk concerned. Next the LDD calls DSoundScPdd::StartTransfer() on +the PDD to allow it to prepare the audio hardware device for record data transfer.

TransferData()

The LDD may need to break down the record buffer +into memory fragments. These specify a physically contiguous region and are +manageable by the PDD as a single transfer. The LDD queues as many transfer +fragments of the current buffer on the PDD as it can accept with a call to DSoundScPdd::TransferData() for +each fragment. If all fragments from the current buffer are accepted by the +PDD then the LDD tries to queue fragments from the next buffer. As with playback, +to support uninterrupted transfer of audio data the PDD must be able to accept +multiple fragments simultaneously. As long as the LDD has transfer fragments +still to queue, it continues to call DSoundScPdd::TransferData() until +the PDD signals that it has temporarily reached its capacity by returning KErrNotReady.

RecordCallBack()

Each time the PDD completes the transfer +of a fragment from a record buffer, it must signal this event back to the +LDD by calling the function DSoundScLdd::RecordCallBack(). +This must always be called in the context of the driver DFC thread. In executing DSoundScLdd::RecordCallback(), +the LDD checks whether the entire transfer for the current buffer is now complete. +If so, depending on the mapping attributes of the shared chunk, the LDD may +need to purge the region of the record client. The LDD attempts to queue further +fragments on the PDD, by calling DSoundScPdd::TransferData(), +which should now have the capability to accept more transfers. So, the PDD +should be written to handle calls to DSoundScPdd::TransferData() within +its call back to DSoundScLdd::RecordCallback().

Pause and resume audio recording

The client can +temporarily halt the progress of audio record at any time by issuing DSoundScLdd::Pause(). +To configure the audio hardware device to halt recording, the LDD calls DSoundScPdd::PauseTransfer() on +the PDD. This time, any active transfer should be aborted by the PDD. If a +recording is halted the PDD must signal this event with a single call of the +LDD function DSOundScLdd::RecordCallback(), which reports +back any partial data already received. In this case, if transfer is resumed +later, the LDD issues a new DSoundScPdd::TransferData() request +to commence data transfer after calling DSoundScPdd::ResumeTransfer(). +As access to the hardware is required in both cases, pause and resume are +handled in the context of the driver DFC thread.

Error handling during recording

If the PDD reports +an error when setting up the audio hardware device for recording then the +LDD immediately completes the first record request back to the client returning +the error value as the result. It will not restart record data transfer unless +it receives a further record request from the client.

If the PDD reports +an error when commencing the transfer of a record fragment or as the result +of the transfer of a record fragment, then the LDD ceases transfer to that +record buffer and instead reports the error back to the client. The error +is returned in response to the record request which corresponds with that +buffer.

Unexpected errors from the PDD are returned to the LDD via +the functions DSoundScPdd::TransferData() and DSoundScLdd::RecordCallback().

The +LDD does not try to cancel the transfer of other fragments for the same buffer +that are already queued on the PDD, but it ignores their outcome. However, +the LDD does try to carry on with the transfer to other available record buffers.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-4AFDA3FF-38D1-5EFE-B18A-E3EAAA52EB75.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-4AFDA3FF-38D1-5EFE-B18A-E3EAAA52EB75.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,29 @@ + + + + + +Flash +Guide Flash memory is a class of memory that can retain its contents +even after the power has been switched off. +

Introduction

Unlike +ROM, the data in Flash memory can be changed by an application.

Flash memory features

Features of Flash memory +are:

Writing and erasing of memory has to be undertaken in blocks of memory
Memory contents are retained until erased (regardless of whether the +power has been turned on/off).

Flash memory limitations

The following are limitations +of FLASH memory:

There are a finite number of erase-write cycles (usually 100,000).
NAND Flash cannot be executed in place. Instead the contents have to +be loaded into RAM and then executed.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-4C4515EA-A5DD-56B4-94B0-EE48D66013F7.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-4C4515EA-A5DD-56B4-94B0-EE48D66013F7.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,40 @@ + + + + + +Read Data from USB using Shared Chunks This tutorial describes how to read shared chunk data from +a USB connection. +

Read data

To read data from the host to +the device (Out) call the function RDevUsbcScClient::ReadDataNotify() to make a request to wait for data in the specified buffer and wait +for it to complete.

If the buffer already has data in it, +it will return immediately with the code KErrCompletion. If there is no data in the buffer an asynchronous request is set +up that will complete when data is available. Note: check the +return code before attempting to wait for the request to complete.

TUsbcScHdrEndpointRecord* epInfo; +TRequestStatus status; + +TUsbcScChunkHeader chunkHeader(gChunk); + +chunkHeader.GetBuffer(0, 2, epInfo); +TInt outBuffNum = epInfo->iBufferNo; + +r = gPort.ReadDataNotify(outBuffNum,status);

The first +parameter required by ReadDataNotify() is the endpoint +buffer number. The endpoint buffer number can be found in the alternate +setting table in the chunk header. The location of the buffer can +be found by looking at the buffer offset table, which is also in the +chunk header.

When the request has completed, process the +data in the buffer that was read from the driver.

The transfer +buffer for an IN endpoint is always pointed to by the iTail member of the endpoint buffer struct SUsbcScBufferHeader. When finished processing the current chunk move iTail to point to the next transfer buffer.

iTransfer = (TUsbcScTransferHeader*) (iHeader->iTail + iBase); +... // Process data +iHeader->iTail = iTransfer->iNext;

If there is no more +data to be read then close the channel and unload the driver.

Next steps

When you have finished reading +and writing Close and Unload the Driver.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-4C5DB74E-41A5-53CB-A053-CBBEADD31AFF.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-4C5DB74E-41A5-53CB-A053-CBBEADD31AFF.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,31 @@ + + + + + +ArchitectureDescribes the architecture of the DMA Framework. +

The following diagram shows the main parts of the architecture:

+ + + +

The DMA Framework is implemented as a single DLL, which is split into two +layers:

a platform independent +layer that implements the behaviour that is common to all hardware
a platform specific +layer that implements the behaviour that is specific to a particular platform.

The DLL is called dma.dll, and is implemented as a +kernel extension, which means that it is loaded very early during system initialisation.

The platform specific layer interfaces to the DMA controller hardware via +the I/O port constants and functions exposed by the ASSP DLL and/or Variant +DLL.

The clients of the DMA Framework are physical device drivers (PDD).

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-4C8E40EE-8CC9-4737-A28E-A18E89356718.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-4C8E40EE-8CC9-4737-A28E-A18E89356718.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,12 @@ + + + + + +TimeDescribes the Time platform service. \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-4CB3C746-606F-4533-8BBB-4A1254A74772-master.png Binary file Adaptation/GUID-4CB3C746-606F-4533-8BBB-4A1254A74772-master.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-4CB3C746-606F-4533-8BBB-4A1254A74772_d0e94716_href.png Binary file Adaptation/GUID-4CB3C746-606F-4533-8BBB-4A1254A74772_d0e94716_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-4DAC39E0-2EC2-40F7-9AEF-4FDA09F1A151.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-4DAC39E0-2EC2-40F7-9AEF-4FDA09F1A151.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,21 @@ + + + + + +Asynchronous +RequestsThis document discusses the use of asynchronous requests by device +drivers. +

An asynchronous request is typically used to start an operation on a device +that completes at a later point of time. It returns immediately after starting +the operation on the device or making a request to the driver. The user side +thread is not blocked and can continue with other operations, including issuing +other requests (synchronous or asynchronous).

A driver lists the available asynchronous request types in an enumeration.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-4E3C086B-25BE-4DAC-9E21-CFC4F8B792A5.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-4E3C086B-25BE-4DAC-9E21-CFC4F8B792A5.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,121 @@ + + + + + +DMA Technology GuideDescribes the Direct Memory Access framework. +

Purpose

The DMA framework provides a generic simple interface for the +clients to access DMA resources in a device. The primary clients are +device drivers that will use the DMA framework to set up DMA transfers. +A device can have more than one DMA controller (DMAC).

Architectural +concepts

The key concepts related to DMA framework are:

+DMA Framework + +

DMA Client: A device driver or a kernel object that needs to use the resources +of the DMA framework. On the Symbian platform, the Physical Device +Drivers are the primary clients of the DMA framework.
DMA Platform Service API: The generic interface to provide DMA services to the clients.
DMA Import Library: The DMA clients link against the dma.lib file.
DMA Platform-Independent Layer (PIL): The platform-independent layer contains the generic framework +independent from the hardware.
DMA Platform-Specific Layer (PSL): The platform-specific layer is specific to the baseport and +the hardware used.
DMA Controller (DMAC): The DMAC is the DMA hardware implementation. The number of +DMAC in the implementation of the DMA Framework depends on the hardware. +The DMAC is a peripheral to the CPU and is programmed to control data +transfers without using the CPU.

DMA +functionality

The key concepts related to functionality +provided by the DMA framework are:

Scatter/Gather Mode: Some DMA controllers transfer data using scatter/gather mode. +In this mode, the operating system creates a DMA descriptor with source +and destination memory addresses and the configuration. The source +and destination data can be a list of scattered memory blocks. The +DMA controller uses this configuration to perform the data transfer.
DMA Descriptors: The data structure used by the DMA framework to store the configuration +of the data transfer. These will store details such as source address, +destination address, number of bytes and pointer to the next descriptor, +when the DMA is used to transfer disjoint blocks of data. This structure +is defined in the platform specific layer. The descriptors are always +used to store the configuration even if the DMA controller does not +support scatter/gather mode. When the scatter/gather mode is not supported +by the DMAC, the descriptors used to store the configuration are called +as pseudo-descriptors.
Descriptor Headers: The descriptor headers are used to store additional information +about the descriptors. The descriptors are accessed using the descriptor +headers which contain the pointer to the descriptor.
Transfer Request: The device drivers configure and initialize a data transfer +using the class DDmaRequest. The data can be transferred +between:
+
memory to memory
+
memory to peripheral
+
peripheral to memory
+
The transfer request stores the callback function of the clients. +The callback function is used to notify the success or failure of +a data transfer.
DMA Channel: The object which represents a single hardware, logical or a +virtual channel. In the DMA platform service API, each DMA channel +is referred to by a 32-bit value called a cookie. Each DMA transfer +is in the form of a description header and its associated DMA descriptor. +The queue of transfer requests (both being transferred and pending) +consists of a linked list of the DMA headers.
DMA Channel Allocator: The channel manager controls the opening and closing of DMA +channels. The channel manager functions are defined in the platform +independent layer and implemented in the platform specific layer.

Typical +Uses

The typical use cases of a DMA framework are:

programmable data transfer between hardware peripherals and +memory buffers
programmable data transfer of block of data between different +regions of memory

+ +ARM DMA Controller Reference Manual +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-4E6520E8-4BF1-55D1-B643-81B8D2816D1D-master.png Binary file Adaptation/GUID-4E6520E8-4BF1-55D1-B643-81B8D2816D1D-master.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-4E6520E8-4BF1-55D1-B643-81B8D2816D1D_d0e5246_href.png Binary file Adaptation/GUID-4E6520E8-4BF1-55D1-B643-81B8D2816D1D_d0e5246_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-4FDD1F7B-1A4E-5389-A0A4-22727CD42B5B-master.png Binary file Adaptation/GUID-4FDD1F7B-1A4E-5389-A0A4-22727CD42B5B-master.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-4FDD1F7B-1A4E-5389-A0A4-22727CD42B5B_d0e9110_href.png Binary file Adaptation/GUID-4FDD1F7B-1A4E-5389-A0A4-22727CD42B5B_d0e9110_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-50217E69-F4A9-4B9F-8608-419783046A1E.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-50217E69-F4A9-4B9F-8608-419783046A1E.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,38 @@ + + + + + +Register Access Quick Start GuideRegister Access is used to read/write/modify values on +only the ASSP hardware. +

The Register Access platform service is used by many of the other +platform services for either reading values from or setting the configuration +of hardware in the device.

Getting +started

The Register Access Technology Guide describes the key concepts +of the Register Access platform service.
The Register Access Client Interface Guide describes the Register +Access platform service API and its use by device drivers.
The Register Access Implementation section describes the implementation +of the Register Access PSL.
The Register Access Build Guide describes how to include the Register +Access platform service in a ROM image.
The Register Access Tools Guide describes the tools that are specific +to the Register Access platform service.
The Register Access Testing Guide explains how to test the functionality +of the Register Access platform service.

Users

Since this platform service is used by many of the other platform +services, it is of interest to both device driver developers and hardware +implementors.

+AsspRegister class diagram + +

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-51514A4B-0220-557B-9F7A-FB110CEFEF10.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-51514A4B-0220-557B-9F7A-FB110CEFEF10.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,722 @@ + + + + + +Shared +ChunksA shared chunk is a mechanism that kernel-side code uses to share +memory buffers safely with user-side code. +

A shared chunk is a mechanism that kernel-side code can use to share memory +buffers safely with user-side code. This topic describes this concept, and +explains how to use the shared chunk APIs.

What are shared chunks?
Creating a shared chunk
Opening a handle to the shared chunk for user-side access
Discarding a handle
Closing and destroying a shared chunk
Committing memory
Passing data from user-side code to another device driver
Passing data between user-side code
Direct peripheral access to shared chunks
Example code
- Example: Creating a shared chunk
- Example: Opening a handle to the shared chunk for user-side access
- Example: Using a DFC to notify destruction of chunk
- Example: Committing memory

You may find it useful to refer to the general sections : Device +Driver Concepts and Device +Driver Framework.

What are shared +chunks?

A shared chunk is a mechanism that kernel-side code uses +to share memory buffers safely with user-side code. References to kernel-side +code always mean device driver code.

The main points to note about +shared chunks are:

They can be created +and destroyed only by device drivers. It is typical behaviour for user-side +code, which in this context we refer to as the client of the device +driver, to pass a request to the device driver for a handle to a shared chunk. +This causes the device driver to open a handle to the chunk and return the +handle value to the client. Successful handle creation also causes +the chunk's memory to be mapped into the address space of the process to which +the client's thread belongs. Note, however, that the driver dictates when the +chunk needs to be created, and when memory needs to be committed.
Like all kernel-side +objects, a shared chunk is reference counted. This means that it remains in +existence for as long as the reference count is greater than zero. Once all +opened references to the shared chunk have been closed, regardless +of whether the references are user-side or kernel-side, it is destroyed.
User-side code that +has gained access to a shared chunk from one device driver can pass this to +a second device driver. The second device driver must open the chunk +before it can be used.
More than one user-side +application can access the data in a shared chunk. A handle to a shared chunk +can be passed from one process to another using standard handle passing mechanisms. +In practice, handles are almost always passed in a client-server context via +inter process communication (IPC).
Processes that share +the data inside a chunk should communicate the location of that data as an +offset from the start of the chunk, and not as an absolute address. +The shared chunk may appear at different addresses in the address spaces of +different user processes.

Creating a +shared chunk

A shared chunk can be created only by code running +on the kernel-side. This means that it is the device driver's responsibility +to create a chunk that is to be shared by user-side code. There is no user-side +API that allows user-side code to create shared chunks.

The device +driver creates a shared chunk using the Kern::ChunkCreate() function. +It passes to this function a TChunkCreateInfo object containing +the required attributes for that chunk. The most important attribute is the TChunkCreateInfo::ESharedKernelMultiple attribute +that states that a shared chunk is to be created.

Chunks are reference +counted kernel objects. When the chunk is created, the reference count is +set to one.

See Example: +Creating a shared chunk.

Opening a handle +to the shared chunk for user-side access

Before user-side code +can access the memory in a shared chunk, the device driver must create a handle +to the chunk and then pass the value back to the user-side. It does this by +calling the Kern::MakeHandleAndOpen() function, passing +the information:

a pointer to the user-side +code's thread (or NULL if referring to the current thread)
a pointer to the shared +chunk

Typically, the device driver does this in response to a request from +the user-side. Kern::MakeHandleAndOpen() also maps the +chunk's memory into the address space of the user-side code's thread.

If +the creation of the handle is successful, the device driver returns the handle value back +to the user-side. The user-side code then assigns the value to an RChunk object +using one of RChunk's base class functions:

RHandleBase::SetHandle()
RHandleBase::SetReturnedHandle()

The user-side code uses RHandleBase::SetReturnedHandle() if +the device driver returns either a positive handle value or a negative error +code. A negative error code means that handle creation has failed.

Opening +a handle to a shared chunk increases the reference count by one.

See Example: +Opening a handle to the shared chunk for user-side access.

Closing a handle

After +it has been opened, a device driver may need to perform further operations +before the handle can be returned to the user-side. If these operations fail, +the device driver code may want to unwind the processing it has done, including +discarding the handle it has just created. It does this using the function Kern::CloseHandle().

This +reverses the operation performed by Kern::MakeHandleAndOpen().

Closing and +destroying a shared chunk

There is no explicit method for deleting +or destroying shared chunks. Instead, because chunks are reference counted +kernel objects, a device driver can use the function Kern::ChunkClose(). +This function decrements a chunk's access count, and, if the count reaches +zero, the chunk is scheduled for destruction.

The chunk is not be +destroyed immediately. Instead it is done asynchronously. If the device driver +needs to know when the chunk has been destroyed, it must specify a DFC (Deferred +Function Call) at the time the chunk is created. The device driver specifies +the DFC through the TChunkCreateInfo::iDestroyedDfc member. +The DFC is queued to run only when the chunk has finally been destroyed. At +this point it is guaranteed that the memory mapped by the chunk can no longer +be accessed by any code. This is useful in cases where chunks are used to +map I/O devices or other special memory, and the program managing these needs +to know when they are free to be reused.

Note: For each call +to Kern::ChunkCreate() and Kern::OpenSharedChunk() there +should be exactly one call to Kern::ChunkClose(). +Calling Close() too few times can cause memory leaks. Calling Close() too +many times can cause the chunk to be destroyed while a program is still trying +to access the memory, which causes an application panic for user code and +a system crash for kernel code.

Committing +memory

After a shared chunk has been created it owns a region of +contiguous virtual addresses. This region is empty, which means that it is +not mapped to any physical RAM or memory mapped I/O devices.

Before +the chunk can be used, the virtual memory must be mapped to real physical +memory. This is known as committing memory.

Committing RAM +from the system free memory pool

You can commit RAM taken from +the system free memory pool using the following ways:

by committing an arbitrary +set of pages. Use the function Kern::ChunkCommit().
by committing a set +of pages with physically contiguous addresses. Use the function Kern::ChunkCommitContiguous().

Committing specified physical addresses

You can commit +specific physical addresses, but only if you set the data member TChunkCreateInfo::iOwnsMemory to EFalse when +you create the shared chunk - see Creating +a shared chunk.

You can use the following ways to do this:

by committing a region +of contiguous addresses. Use the function Kern::ChunkCommitPhysical() with +the signature:
TInt Kern::ChunkCommitPhysical(DChunk*, TInt, TInt, TUint32)
by committing an arbitrary +set of physical pages. Use the function Kern::ChunkCommitPhysical() with +the signature:
TInt Kern::ChunkCommitPhysical(DChunk*, TInt, TInt, const TUint32*)

Note: the same physical memory can be committed to two different RChunk s +or shared chunks at the same time, where each RChunk has +a different owner, as long as your turn OFF the caches.

Passing data +from user-side code to another device driver

User-side code that +has access to a shared chunk from one device driver may want to use this when +it communicates with another device driver. To enable this, the second device +driver needs to gain access to the chunk and the addresses used by the memory +it represents.

The second driver must open a handle on the shared +chunk before any of its code can safely access the memory represented by that +chunk. Once it has done this, the reference counted nature of chunks means +that the chunk, and the memory it represents, remains accessible until the +chunk is closed.

The general pattern is:

the first device driver +creates the shared chunk.

See Creating +a shared chunk.
the user-side gets the +handle value from the first device driver and calls SetHandle() or SetReturnedHandle() on +an RChunk object [the functions are members of RChunk's +base class RHandleBase (see RHandleBase::SetHandle() and RHandleBase::SetReturnedHandle()].

See Opening +a handle to the shared chunk for user-side access.
the user-side passes +the handle value to the second device driver. This value is obtained +by calling Handle() on the RChunk object. +[the function is a member of RChunk's base class RHandleBase (see RHandleBase::Handle()].
the second device driver +calls the variant of Kern::OpenSharedChunk() with the signature:
DChunk* Kern::OpenSharedChunk(DThread*,TInt,TBool)
to +open a handle to the shared chunk.

Note: there are situations +where the second device driver cannot use this variant of Kern::OpenSharedChunk() because:
- The user-side application +may have obtained data by using a library API that uses shared chunks internally, +but which only presents a descriptor based API to the user application. For +example, an image conversion library may perform JPEG decoding using a DSP, +which puts its output into a shared chunk, but that library supplies the user +application with only a descriptor for the decoded data, not a chunk handle.
- The communication channel +between the user-side application and the device driver supports descriptor +based APIs only, and does not have an API specifically for shared chunks. +The API items presented by the File Server are an example of this situation.
The second device driver will only have the address and size of the +data (usually a descriptor). If the driver needs to optimise the case where +it knows that this data resides in a shared chunk, it can use the variant +of Kern::OpenSharedChunk() with the signature:
DChunk* Kern::OpenSharedChunk(DThread*,const TAny*,TBool,TInt&)
to +speculatively open the chunk.

Getting the virtual address of data in a shared chunk

Before +device driver code can access a shared chunk that is has opened, it must get +the address of the data within it. Typically, user-side code will pass offset +and size values to the driver. The driver converts this information into an +address, using the function Kern::ChunkAddress().

Getting +the physical address of data in a shared chunk

Device driver +code can get the physical address of a region within a shared chunk from the +offset into the chunk and a size value. This is useful for DMA or any other +task that needs a physical address. Use the function Kern::ChunkPhysicalAddress() to +do this.

Getting chunk attributes and checking for uncommitted +memory

As a shared chunk may contain uncommitted regions of memory +(gaps), it is important that these gaps are detected. Any attempt to access +a bad address causes an exception. You can use the function Kern::ChunkPhysicalAddress() to +check for uncommitted regions of memory.

Passing data +between user-side code

User-side code can access data in a shared +chunk once it has opened a handle on that chunk. Handles can be passed between +user processes using the various handle passing functions. This most common +scenario is via client-server Inter Process Communication (IPC).

Passing +a handle from client to server

The client passes the handle to +the shared chunk as one of the four arguments in a TIpcArgs object. +The server opens this using the RChunk::Open() variant +with the signature:

RChunk::Open(RMessagePtr2 aMessage,TInt aParam,TBool isReadOnly, TOwnerType aType) +

Passing a handle from server to client

The +server completes the client message using the chunk handle:

RMessagePtr2::Complete(RHandleBase aHandle)

The +client then assigns the returned handle value to an RChunk by +calling:

RChunk::SetReturnedHandle(TInt aHandleOrError)

Note:

Processes that share +data within shared chunks must specify the address of that data as an offset from +the start of the chunk, and not as an absolute address. This is because the +chunk may appear at different addresses in the address spaces of different +user processes.
Once a chunk is no longer +needed for data sharing, user applications should close the handle they have +on it. If they do not, the memory mapped by the chunk can never be freed.

See Using +Client/Server.

Direct peripheral +access to shared chunks

When DMA or any other hardware device accesses +the physical memory represented by a shared chunk, the contents of CPU memory +cache(s) must be synchronised with that memory. Use these functions for this +purpose:

Cache::SyncMemoryBeforeDmaWrite()
Cache::SyncMemoryBeforeDmaRead()

Note: both these functions take a TUint32 type +parameter, identified in the function signatures as TUint32 aMapAttr. +This is the same TUint32 value set on return from calls to +either Kern::ChunkPhysicalAddress() or Kern::ChunkCreate().

Example code

This +section contains code snippets that show shared chunks in use. Most of the +code is intended to be part of a device driver. A few snippets show user-side +code and the interaction with device driver code.

Example: Creating a shared chunk
Example: Opening a handle to the shared chunk for user-side access
Example: using a DFC to notify destruction of chunk
Example: committing memory

Example: Creating +a shared chunk

This code snippet shows how a device driver creates +a shared chunk. The class DMyDevice has been given responsibility +for creating the chunk:

/** +The device or other object making use of shared chunks +*/ +class DMyDevice + { + ... + TInt CreateChunk(); + void CloseChunk(); +private: + void ChunkDestroyed(); +private: + TBool iMemoryInUse; + DChunk* iChunk + TUint32 iChunkMapAttr; + TLinAddr iChunkKernelAddr; + ... + } /* +Address and size of our device's memory +*/ +const TPhysAddr KMyDeviceAddress = 0xc1000000; // Physical address +const TInt KMyDeviceMemorySize = 0x10000; + +/** +Create a chunk which maps our device's memory +*/ +TInt DMyDevice::CreateChunk() + { + // Check if our device's memory is already in use + if(iMemoryInUse) + { + // Wait for short while (200ms) in case chunk is being deleted + NKern::Sleep(NKern::TimerTicks(200)); + // Check again + if(iMemoryInUse) + { + // Another part of the system is probably still using our memory, so... + return KErrInUse; + } + } + + // Enter critical section so we can't die and leak the objects we are creating + // I.e. the TChunkCleanup and DChunk (Shared Chunk) + NKern::ThreadEnterCS(); + + // Create chunk cleanup object + TChunkCleanup* cleanup = new iChunkCleanup(this); + if(!cleanup) + { + NKern::ThreadLeaveCS(); + return KErrNoMemory; + } + + // Create the chunk + TChunkCreateInfo info; + info.iType = TChunkCreateInfo::ESharedKernelMultiple; + info.iMaxSize = KMyDeviceMemorySize; + info.iMapAttr = EMapAttrFullyBlocking; // No caching + info.iOwnsMemory = EFalse; // We'll be using our own devices memory + info.iDestroyedDfc = cleanup; + DChunk* chunk; + TInt r = Kern::ChunkCreate(info, chunk, iChunkKernelAddr, iChunkMapAttr); + if(r!=KErrNone) + { + delete cleanup; + NKern::ThreadLeaveCS(); + return r; + } + + // Map our device's memory into the chunk (at offset 0) + + r = Kern::ChunkCommitPhysical(chunk,0,KMyDeviceMemorySize,KMyDeviceAddress); + if(r!=KErrNone) + { + // Commit failed so tidy-up... + + // We, can't delete 'cleanup' because it is now owned by the chunk and will + // get run when the chunk is destroyed. Instead, we have to Cancel it, which + // prevents it from doing anything when it does run. + cleanup->Cancel() + // Close chunk, which will then get deleted at some point + Kern::ChunkClose(chunk); + } + else + { + // Commit succeeded so flag memory in use and store chunk pointer + iMemoryInUse = ETrue; + iChunk = chunk; + } + + // Can leave critical section now that we have saved pointers to created objects + NKern::ThreadLeaveCS(); + + return r; + } + +/** +Close the chunk which maps our device's memory +*/ +TInt DMyDevice::CloseChunk() + { + // Enter critical section so we can't die whilst owning the chunk pointer + NKern::ThreadEnterCS(); + + // Atomically get pointer to our chunk and NULL the iChunk member + DChunk* chunk = (DChunk*)NKern::SafeSwap(NULL,(TAny*&)iChunk); + + // Close chunk + if(chunk) + Kern::CloseChunk(chunk); + + // Can leave critical section now + NKern::ThreadLeaveCS(); + } +

Implementation notes

a TChunkCreateInfo object +is created, populated and passed to Kern::ChunkCreate(). +This is information that Symbian platform needs to create the chunk. To create +a shared chunk, TChunkCreateInfo::iType must be +set to TChunkCreateInfo::ESharedKernelMultiple.
If the device architecture +allowed the device driver function DMyDevice::CreateChunk() to +be called in a re-entrant manner, you would need to protect this code using +a mutex. Such a situation might arise when a logical channel is shared between +two threads, or two logical channels are created on the same device. There +may also be other cases where a mutex is needed.

See also:
- The Symbian platform mutex
- Kern::MutexCreate()
- Kern::MutexWait()
- Kern::MutexSignal()
The line:
info.iDestroyedDfc = cleanup;
in +the function DMyDevice::CreateChunk() and code following +the comment
// Create chunk cleanup object
sets +the DFC that runs when the shared chunk is finally closed. See Example: using a DFC to notify destruction of chunk for the DFC code +itself.

Example: Opening +a handle to the shared chunk for user-side access

These code snippets +show user-side code making a request to a device driver to open handles on +two shared chunks.

The code snippets assume that the chunks have already +been created.

User-side

The user-side interface to +a device driver is always a class derived from RBusLogicalChannel, +and is provided by the device driver. Here, this is the RMyDevice class. +In real code, the class would offer much more functionality, but only the +relevant function members and data members are shown:

/** +Client (user-side) interface to the device driver. +*/ +class RMyDevice : public RBusLogicalChannel + { + ... +public: + TInt OpenIoChunks(RChunk& aInputChunk,RChunk& aOutputChunk); + ... +private: + /** Structure to hold information about the i/o buffers */ + class TIoChunkInfo + { + public: + TInt iInputChunkHandle; + TInt iOutputChunkHandle; + }; + // Kernel-side channel class is a friend... + friend class DMyDeviceChannel; + ... + }; +

You call the function OpenIoChunks() to:

issue a request to the +driver to create handles to two chunks
get handles to those +shared chunks so that they can be accessed by user-side code.

TInt RMyDevice::OpenIoChunks(RChunk& aInputChunk,RChunk& aOutputChunk) + { + // Send request to driver to create chunk handles. + TIoChunkInfo info; + TInt r=DoControl(EOpenIoChunks,(TAny*)&info); + // Set the handles for the chunks + aInputChunk.SetHandle(info.iInputChunkHandle); + aOutputChunk.SetHandle(info.iOutputChunkHandle); + + return r; + } +

Implementation notes

The request is passed +to the driver as a synchronous call; it calls the base class function RBusLogicalChannel::DoControl(). +This means that the call does not return until the driver has created (or +failed to create) the handles to the shared chunks. The call is synchronous +because the creation of the handles does not depend on the hardware controlled +by the driver, so there should be minimal delay in its execution.
The driver returns the +handle numbers in the TIoChunkInfo object; specifically +in its iInputChunkHandle and iOutputChunkHandle data +members.

To access the shared chunks, user-side code needs handles +to them. Handles to chunks are RChunk objects.

The +final step is to set the returned handle numbers into the RChunk objects +by calling SetHandle(). This function is provided by RChunk's +base class RHandleBase.

See handles for +background information.
In this example the +return value from RBusLogicalChannel::DoControl() is not +checked. In practice you need to do so.

+Shared chunks implementation + +

Device driver (kernel) side

This is example code +snippet shows the device driver side handling of the request made by the user-side +to open handles on two shared chunks.

The request is handled by the OpenIoChunks() function +in the device driver's logical channel. The logical channel is represented +by a class derived from DLogicalChannelBase. In this example, +this is the DMyDeviceChannel class.

Details of how +a user-side call to RMyDevice::OpenIoChunks() results in +a call to the driver's DMyDeviceChannel::OpenIoChunks() function +are not shown. Passing +requests from user-side to kernel-side in The +Logical Channel explains the principles.

/** + Kernel-side Logical Channel for 'MyDevice' +*/ +class DMyDeviceChannel : public DLogicalChannelBase + { + ... +private: + TInt OpenIoChunks(RMyDevice::TIoChunkInfo* aIoChunkInfoForClient); +private: + DChunk* iInputChunk; + TInt iInputChunkSize; + DChunk* iOutputChunk; + TInt iOutputChunkSize; + ... + }; +

The following code snippet is the implementation of DMyDeviceChannel::OpenIoChunks().

/** + Called by logical channel to service a client request for i/o chunk handles +*/ +TInt DMyDeviceChannel::OpenIoChunks(RMyDevice::TIoChunkInfo* aIoChunkInfo) + { + // Local info structure we will fill in + RMyDevice::TIoChunkInfo info; + + // Need to be in critical section whilst creating handles + NKern::ThreadEnterCS(); + + // Make handle to iInputChunk for current thread + TInt r = Kern::MakeHandleAndOpen(NULL, iInputChunk); + // r = +ve value for a handle, -ve value is error code + if(r>=0) + { + // Store InputChunk handle + info.iInputChunkHandle = r; + + // Make handle to iOutputChunk for current thread + r = Kern::MakeHandleAndOpen(NULL, iOutputChunk); + // r = +ve value for a handle, -ve value is error code + if(r>=0) + { + // Store OutputChunk handle + info.iOutputChunkHandle = r; + // Signal we succeeded... + r = KErrNone; + } + else + { + // Error, so cleanup the handle we created for iInputChunk + Kern::CloseHandle(NULL,info.iInputChunkHandle); + } + } + + // Leave critical section before writing info to client because throwing an + // exception whilst in a critical section is fatal to the system. + NKern::ThreadLeaveCS(); + + // If error, zero contents of info structure. + // (Zero is usually a safe value to return on error for most data types, + // and for object handles this is same as KNullHandle) + if(r!=KErrNone) + memclr(&info,sizeof(info)); + + // Write info to client memory + kumemput32(aIoChunkInfo,&info,sizeof(info)); + + return r; + } +

Implementation notes

The function calls Kern::MakeHandleAndOpen() twice, +once for each shared chunk. A NULL value is passed as the first parameter +in both calls to this function instead of an explicit DThread object. +This creates the handles for the current thread. Although this code is running +in kernel mode, the context remains the user thread.
The first handle created +is closed if the second handle cannot be created:
if(r>=0) + { + ... + } + else + { + // Error, so cleanup the handle we created for iInputChunk + Kern::CloseHandle(NULL,info.iInputChunkHandle); + }
The handle values are +written back into the TIoChunkInfo structure using the kumemput32() function. +See the EKA2 references in Accessing +User Memory in Migration +Tutorial: EKA1 Device Driver to Kernel Architecture 2.

Example: Using +a DFC to notify destruction of a chunk

This set of code snippets +shows how to set up a DFC that notifies a device driver when a shared chunk +has finally been destroyed.

/** +Example class suitable for use as a 'Chunk Destroyed DFC' when +creating Shared Chunks with Kern::ChunkCreate() +*/ +class TChunkCleanup : private TDfc + { +public: + TChunkCleanup(DMyDevice* aDevice); + void Cancel(); +private: + static void ChunkDestroyed(TChunkCleanup* aSelf); +private: + DMyDevice* iDevice; + }; + +/** +Contruct a Shared Chunk cleanup object which will signal the specified device +when a chunk is destroyed. +*/ +TChunkCleanup::TChunkCleanup(DMyDevice* aDevice) + : TDfc((TDfcFn)TChunkCleanup::ChunkDestroyed,this,Kern::SvMsgQue(),0) + , iDevice(aDevice) + {} + +/** +Cancel the action of the cleanup object. +*/ +void TChunkCleanup::Cancel() + { + // Clear iDevice which means that when the DFC gets queued on chunk destruction + // our ChunkDestroyed method will do nothing other than cleanup itself. + iDevice = NULL; + } + +/** +Callback function called when the DFC runs, i.e. when a chunk is destroyed. +*/ +void TChunkCleanup::ChunkDestroyed(TChunkCleanup* aSelf) + { + DMyDevice* device = aSelf->iDevice; + // If we haven't been Cancelled... + if(device) + { + // Perform any cleanup action required. In this example we call a method + // on 'MyDevice' which encapsulates this. + device->ChunkDestroyed(); + } + + // We've finished so now delete ourself + delete aSelf; + } +

Implementation notes

The DFC is an item of +information that is passed to Kern::ChunkCreate() when +the shared chunk is created. See Example: +Creating a shared chunk to see how the two sets of code connect.
Ensure that the code +implementing this DFC is still loaded when the DFC runs. As you cannot know +when a chunk will be destroyed, the code should reside in a kernel extension.

Example: committing +memory

This code snippet shows how memory is committed. It is +based on the implementation of the class DBuffers, which +represents a group of buffers hosted by a single chunk.

/** + Class representing a group of buffers in the same chunk +*/ +class DBuffers + { +public: + DBuffers(); + ~DBuffers(); + TInt Create(TInt aBufferSize,TInt aNumBuffers); +public: + DChunk* iChunk; /**< The chunk containing the buffers. */ + TLinAddr iChunkKernelAddr; /**< Address of chunk start in kernel process */ + TUint32 iChunkMapAttr; /**< MMU mapping attributes used for chunk */ + TInt iBufferSize; /**< Size of each buffer in bytes */ + TInt iOffsetToFirstBuffer; /**< Offset within chunk of the first buffer */ + TInt iOffsetBetweenBuffers; /**< Offset in bytes between consecutive buffers */ + }; /** Constructor */ +DBuffers::DBuffers() + : iChunk(NULL) + {} + +/** Destructor */ +DBuffers::~DBuffers() + { + if(iChunk) Kern::ChunkClose(iChunk); + } + +/** + Create the chunk and commit memory for all the buffers. + @param aBuffserSize Size in bytes of each buffer + @param aNumBuffers Number of buffers to create +*/ +TInt DBuffers::Create(TInt aBufferSize,TInt aNumBuffers) + { + // Round buffer size up to MMU page size + aBufferSize = Kern::RoundToPageSize(aBufferSize); + iBufferSize = aBufferSize; + + // Size of one MMU page + TInt pageSize = Kern::RoundToPageSize(1); + + // We will space our buffers with one empty MMU page between each. + // This helps detect buffer overflows... + + // First buffer starts one MMU page into chunk + iOffsetToFirstBuffer = pageSize; + + // Each buffer will be spaced apart by this much + iOffsetBetweenBuffers = aBufferSize+pageSize; + + // Calculate chunk size + TUint64 chunkSize = TUint64(iOffsetBetweenBuffers)*aNumBuffers+pageSize; + + // Check size is sensible + if(chunkSize>(TUint64)KMaxTInt) + return KErrNoMemory; // Need more than 2GB of memory! + + // Enter critical section whilst creating objects + NKern::ThreadEnterCS(); + + // Create the chunk + TChunkCreateInfo info; + info.iType = TChunkCreateInfo::ESharedKernelMultiple; + info.iMaxSize = (TInt)chunkSize; + info.iMapAttr = EMapAttrCachedMax; // Full caching + info.iOwnsMemory = ETrue; // Use memory from system's free pool + info.iDestroyedDfc = NULL; + TInt r = Kern::ChunkCreate(info, iChunk, iChunkKernelAddr, iChunkMapAttr); + if(r==KErrNone) + { + // Commit memory for each buffer... + + TInt offset = iOffsetToFirstBuffer; // Offset within chunk for first buffer + + // Repeat for each buffer required... + while(aNumBuffers--) + { + // Commit memory at 'offset' within chunk + r = Kern::ChunkCommit(iChunk,offset,aBufferSize); + if(r!=KErrNone) + break; + + // Move 'offset' on to next buffer + offset += iOffsetBetweenBuffers; + } + + if(r!=KErrNone) + { + // On error, throw away the chunk we have created + Kern::ChunkClose(iChunk); + iChunk = NULL; // To indicate that 'this' doesn't have any valid buffers + } + } + + // Finished + NKern::ThreadLeaveCS(); + return r; + } +

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-51C5DC6C-0CEE-5F44-8578-AEFBEF90FA4D.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-51C5DC6C-0CEE-5F44-8578-AEFBEF90FA4D.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,226 @@ + + + + + +READIMAGE +

READIMAGE is a command-line tool that provides readable data from +a ROM, ROFS, or E32 image. It can also generate an IBY file from a +SIS file which can be used to generate a data drive image.

Command +syntax

Run the following command to use the READIMAGE tool:

readimage [options] <image filename> or <SIS +filename>

where:

<image +filename> is an input image file
<sis +filename> is an input .sis file.

Reading ROM, ROFS and E32 images

Run the following +command to read a ROM, ROFS, or E32 image:

readimage +options <ROM/ROFS/E32 imagefile>

The command +line options are as follows:

+ + + +Options +Description + + + + +

-o

Indicates output file name.

+ + +

-d

Displays header information about the input image.

+ + +

-s

Displays the directory structure of the input image.

+ + +

-v

Displays image headers and the directory structure of the +input image.

+ + +

-e

Displays the E32 image from the input ROM or ROFS image.

+ + +

-h

Displays help information.

+ + +

-z <path>

Extracts all files from the given image to the specified +location.

+ + +

-l <logfile name>

Logs the image contents in a file.

+ + +

-x <pattern>

Extracts a single or a set of files from a ROM or ROFS image +into the current directory. The pattern contains set of file names. +For more information about <pattern>, see Extracting a set of files.

+ + +

-r

Recursively extracts the files from ROM or ROFS image. This +option is always used with the -x option.

+ + + +

Note: Options are not case-sensitive. READIMAGE +reports an error if an argument is not passed for the -x or -z option.

Extracting one file

The command below +extracts all the files from sample.img to the C:\test location.

readimage -z C:\test\ +sample.img

Extracting a set of files with +wildcard ?

The READIMAGE tool provides the -x option +to extract one or more files from a ROM or ROFS image, based on a +pattern that matches the name of the file. A question mark(?) indicates +to match one instance of any character in a file name, within the +directory.

The command below extracts all the .exe files from the \sys\bin directory present in +the sample.img file, whose file name consists +of two characters.

readimage -x \sys\bin\??.exe +sample.img

Extracting a set of files with +wildcard *

The READIMAGE tool provides the -x option +to extract one or more files from a ROM or ROFS image, based on a +pattern that matches the name of the file. A star sign(*) indicates +to match zero or more instances of any character in a file name, within +the directory.

The command below extracts all the .exe files from the \sys\bin directory present in the sample.img file, into the current directory.

readimage -x \sys\bin\*.exe sample.img

The command +below extracts all the .exe files from the \sys\bin +directory present in the sample.img file, into +the C:\test location.

readimage -x \sys\bin\*.exe +-z C:\test sample.img

The command below extracts +all the .dll files from the \sys\bin\ directory and its sub-directories +present in the sample.img file, into the current directory.

readimage -x \sys\bin\*.dll -r sample.img

Generating an IBY file from a SIS file

Run the +following command to generate an .iby file from +a .sis file:

readimage -sis2iby +[-tmpdir <path> -outdir <path>] <sisfile>

The following command-line options are supported when generating +an .iby file from a .sis file:

+ + + +Options +Description + + + + +

Input .sis file.

+ + +

-sis2iby

Used to generate .iby file for the +given .sis file.

+ + +

-tmpdir <path>

Extracts contents of the .sis file +to the specified directory.

+ + +

-outdir <path>

Generates .iby file in the specified +directory.

+ + + +

To generate an .iby file from the +given .sis file, READIMAGE performs the steps +as follows:

Reports an error +if the .sis file is invalid or missing.
Extracts the +contents of the .sis file into a specified directory, +or the current directory if the path is not specified. A .pkg script file is extracted from the sis file.
Creates an .iby file in the specified directory or the current directory +based on the .pkg file.

The .sis file is created using the package +(PKG) script file. A .pkg file is a text file +containing statements that define the information needed by the installation +(.sis ) file creation utility, MAKESIS.

For more information about creating .sis file, +see MakeSIS Installation file generator syntax. For more information on the +.pkg file format, see PKG File in +the Symbian +C++ Developer Library.

READIMAGE extracts the .pkg file from the .sis file. It +then uses the .pkg file as input to generate +the .iby file.

Languages and Package-header +section

The details of Languages and Package-header +sections are written in the .iby file as comments.

.pkg file
&EN +# {"HelloWorld application"}, (0xe8000091), 1, 0, 0, TYPE=SA
.iby file
// Generated IBY file for the package file: \dump\hwapp\hwapp.pkg +// Languages: EN +// Header: "HelloWorld application" (0xe8000091)

Install-file section

In the Install-file +section, the standard installation files, which are specified with +the installation option FF, are written using the FILE or DATA OBEY file keywords. The File keyword is used if the file is an E32 image, Otherwise, +the Data keyword is used.

.pkg file
"file0" - "!:\sys\bin\HelloWorld.exe", FF, VR +"file1" - "!:\private\<process SID>\Apps\AGENDA\Ericsson.txt", FF, VR
.iby file
file = "\test\dump\hwapp\file0" "\sys\bin\HelloWorld.exe" +data = "\test\dump\hwapp\sis0\file1" "\private\<process SID>\Apps\AGENDA\Ericsson.txt"

Embedded-SIS section

The details of +the Embedded-SIS section are written using #include pre-processor directive.

.pkg file
@"sis0.sis", (0x101f7771) +@"sis1.sis", (0x101f7773)
.iby file
#include "sis0.sis" +#include "sis1.sis"

Conditions-block section

In the Conditions-block +section, the IF statements are written using the #if - #else +- #endif pre-processor directive block.

The condition-primitives +and the functions in the .pkg file are written +as pre-processor macros.

The relational and logical operator +keywords are written using the appropriate operators.

.pkg file
;Display 2 options to the user +! ({"Option1", "Option1"}, {"Option2", "Option2"}) +;Conditional installation +IF option1 + "file0" - "!:\private\10000005\import\InstTest\option1.txt"; +ENDIF +IF option2 + "file0" - "!:\private\10000005\import\InstTest\option2.txt"; +ENDIF +;Conditional installation +IF (MANUFACTURER) = (1) + "file1" - "!:\sys\bin\HelloWorld.exe" +ELSEIF (MANUFACTURER) = (4) + "file1" - "!:\sys\bin\HelloWorld1.exe" +ELSE + "file1" - "!:\sys\bin\HelloWorld2.exe" +ENDIF + +
.iby file
//Install Options: "OPTION1" "OPTION1" "OPTION2" "OPTION2" +#if defined (option1) + data = "s:\test\hwapp\file0" +"\private\10000005\import\InstTest\option1.txt"; +#endif +#if defined (option2) + data = "s:\test\hwapp\file0" +"\private\10000005\import\InstTest\option2.txt"; +#endif + +#if (MANUFACTURER) = (1) + file = "s:\test\hwapp\file1" "\sys\bin\HelloWorld.exe" +#elseif (MANUFACTURER) = (4) + file = "s:\test\hwapp\file1" "\sys\bin\HelloWorld1.exe" +#else + file = "s:\test\hwapp\file1" "\sys\bin\HelloWorld2.exe" +#endif

Note: Using the .iby file with +the condition-block statements for the creation of ROM and ROFS images +needs appropriate macro definitions. For the preceding examples, the +macros are defined as follows:

#define option1 //selecting option1 block +#define MANUFACTURER 4 //selecting second conditional block

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-52583CC7-483E-54B5-8094-F0F61BD46B7F.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-52583CC7-483E-54B5-8094-F0F61BD46B7F.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,105 @@ + + + + + +Configuration: Attribute Definition FilesDescribes the format of configuration files. +

The attributes that can be used on a device are defined in two +configuration files. .

Config.hcf +file

The purpose of this file, config.hcf, is to define the attributes that have meaning on this hardware. It specifies +whether attributes:

are read-only
can be read +and written
are simply stored +by the HAL - the non-derived attributes
require calls +to other components to obtain or set their values - the derived attributes.

The file must be created in the ...\Variant\hal\... directory.

Note that:

all supported +attributes must have an entry in the Config file config.hcf
all non-derived +attributes also need an entry in theValues file values.hda.

The build system uses the Perl script halcfg.pl to convert text information in the Config file into a C++ source +file before the C++ compiler is invoked. The generated binary maps +to the data members defined in the HalInternal class. Note that this class is internal to Symbian.

After initial +implementation, any changes to the files will be picked up by the +supplied makefile, ...\hal\config.mke. The necessary +changes are made to the generated config.cpp file +when the HAL is built.

Any additional functions must be added +to the implementation file by hand, e.g. in a file called imp.cpp. However, this would be unusual because all likely +functions are already implemented in ...\hal\src\userhal.cpp.

The config file consists of a number of lines of text in +the form:

where the pair of square brackets indicates optional items.

<attrib>

This is one of the values of the enumeration HALData::TAttribute in the source file ...\hal\inc\hal_data.h

<prop1>, <prop2>,...

These are optional property +specifications defined by the enumeration HALData::TAttributeProperty in the source file ...\hal\inc\hal_data.h. +Where more than one property is specified, they are separated by commas. +If specified, the initial colon is required. Currently, only the two +properties EValid and ESettable are defined. Note that any substring which is not ambiguous within +the enumerated type is acceptable; matching is not case sensitive.

The property EValid is defined implicitly +for all attributes that appear in the Config file. It indicates that +the attribute is meaningful on this platform. Attributes that do not +appear in the Config file do not have this property, and calls to HAL::Get() or HAL::Set() which refer +to those attributes return KErrNotSupported.

The property ESettable, means that an attribute +is modifiable. Calls to HAL::Set() for attributes +without this property return KErrNotSupported.

<implementation>

Defines whether an attribute is derived. It can be:

0, which means +that the specified attribute is not derived, but is just a constant +stored by the HAL.
the name of +a function used to implement HAL::Get() and HAL::Set() for that specified attribute.

Comments

The order in which attributes are defined +is not important. Comments may be included by starting a line with +//. A comment must be on its own line and cannot be appended +to an attribute specification.

Values.hda +file

The purpose of this file, values.hda, is to specify the initial values of the non-derived attributes, those attributes which are simply stored in, and +retrieved from, the HAL. It must be created in the ...\variant\hal\... directory.

The build system uses the Perl script halcfg.pl to convert text information in the Values file +into a C++ source file before the C++ compiler is invoked.

After initial implementation, any changes to the file will be picked +up by the supplied makefile, ...\hal\config.mke. The necessary changes are made to the generated values.cpp file when the HAL is built.

Any additional functions must +be added to the implementation file by hand, e.g. in a file called imp.cpp. However, this would be unusual because all likely +functions are already implemented in ...\hal\src\userhal.cpp.

The values file consists of a number of lines of text in +the form:

<attrib>

This is one of the values of the enumeration HALData::TAttribute defined in the header file ...\hal\inc\hal_data.h.

<value>

This is the initial value of the attribute. +It may be specified in various ways, but depends on the attribute, +and may be one of the following:

a decimal integer +constant
a hexadecimal +integer constant, by prepending 0x
an enumerated +value for those attributes that have a corresponding enumeration in ...\hal\inc\hal_data.h. Note that any substring which +is not ambiguous within the enumerated type is acceptable; matching +is not case sensitive. For example, intel would be +an acceptable abbreviation for EManufacturer_Intel in the enumeration HALData::TManufacturer.
bit1 ++ bit2 + ... + bitn, for those attributes with corresponding +bitmask enumerations in ...\hal\inc\hal_data.h, and declared with the bitmask pseudo-keyword. bit1, bit2 etc. are values of the enumeration. +Any substring which is not ambiguous within the bitmask type is acceptable +and matching is not case sensitive.

Comments

Attributes EMachineUid and EManufacturer should be allocated UID values +in the normal way. These values should be placed in the values file +and in product specific header files, not in ...\hal\inc\hal_data.h.

Example +of a non-derived attribute

A line similar to the following +in the values.hda file defines the machine Uid +to the HAL, and shows how a value is paired to an attribute.

EMachineUid= 0x1000a682

A line similar to the following in the config.hcf file indicates that the value is not derived but is simply stored +by the HAL.

EMachineUid= 0

Example +(1) of a derived attribute

The following line in the config.hcf file shows how to configure the API for the +display contrast. This states that the display contrast is settable, +and that the function to do this is called ProcessDisplayContrast.

EDisplayContrast : set = ProcessDisplayContrast

Example +(2) of a derived attribute

The following lines in the config.hcf file shows how to configure the API for the +display size.

EDisplayXPixels=ProcessDisplayCurrentModeInfo +EDisplayYPixels=ProcessDisplayCurrentModeInfo

This +is read only information, so the entries do not contain the "set" +keyword. The values are derived via the API function ProcessDisplayCurrentModeInfo, and there is no corresponding entry in values.hda.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-52702561-DA37-5381-BA0D-76D9A41B2760.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-52702561-DA37-5381-BA0D-76D9A41B2760.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,274 @@ + + + + + +ROFSBUILD Obey File StructureA ROFSBUILD obey file consists of a number +of sections, each defining a ROFS image. +

A ROFS image is used to store code that is not part of the Core +OS section. The File Server uses ROFS (the Read-Only File System) +to access this, and ROFS uses a Media Driver to read the data from +the NAND Flash device and to load this into RAM for access or execution. +The Composite File System combines this media area with the Core OS +media area and presents the two as a single read-only drive Z:.

A ROFS image contain the following main sections:

a CoreImage section that specifies the existing core image to be used as the +base for generating the extension image.
an ExtensionRomSection that defines the ROM image that extends the core image.

The structure is defined as:

+ObeyFile : CoreImageStatement [ ExtensionRomSection ] +CoreImage : coreimage = <CoreImageFileName> +ExtensionRomSection : ObeyStatementList +ObeyStatementList : ObeyStatement | ObeyStatement ObeyStatementList +ObeyStatement : RomStatement | FileStatement +

See RomStatement
See FileStatement
See coreimage keyword

RomStatement

A RofsStatement is one of the following:

+ + + +

autosize =

<block-size>

+ + +

extensionrofs

+ + +

extensionrofsname =

+ + +

externaltool =

+ + +

rofsname =

+ + +

rofsize =

<size-in-bytes>

+ + +

version =

[ <major> ] [ .<minor> ] [ (<build>) + ]

+ + +

romsize =

<hex-size>

+ + +

romchecksum =

<base-checksum>

+ + +

time =

dd/mm/yyyy hh:mm:ss

+ + +

trace =

<32bit-hex-number>

+ + +

pagingoverride

[NOPAGING | ALWAYSPAGE | DEFAULTUNPAGED | + DEFAULTPAGED]

+ + +

pagingpolicy

[NOPAGING | ALWAYSPAGE | DEFAULTUNPAGED | + DEFAULTPAGED]

+ + +

patchdata =

+ + +codepagingpolicy +

[NOPAGING | ALWAYSPAGE | DEFAULTUNPAGED | DEFAULTPAGED]

+ + +datapagingpolicy +

[NOPAGING | ALWAYSPAGE | DEFAULTUNPAGED | DEFAULTPAGED]

+ + +codepagingoverride +

[NOPAGING | ALWAYSPAGE | DEFAULTUNPAGED | DEFAULTPAGED]

+ + +datapagingoverride +

[NOPAGING | ALWAYSPAGE | DEFAULTUNPAGED | DEFAULTPAGED]

+ + +dataimagename = +

+ + +dataimagefilesystem = +

+ + +dataimagesize = +

+ + +volume = +

+ + +sectorsize = +

+ + +fattable = +

+ + + +

FileStatement FileStatement : FileSpecificationStatement | ControlStatement | RomDirectoryStatement

A ControlStatement is one of the following:

+ + + +

rem

+ + +

stop

+ + + +

A FileSpecificationStatement is one of +the following:

+ + + +

data[[HWVD]] =

<Source-file> <destination-file> [ FileAttributeList ]

+ + +

file[[HWVD]] =

<Source-file> <destination-file> [ FileAttributeList] [OverrideAttributeList ] [paged | +unpaged]

+ + +

filecompress[[HWVD]] =

<source-file> <destination-image-file> [FileAttributeList][OverrideAttributeList]

+ + +

fileuncompress[[HWVD]] =

<source-file> <destination-image-file> [FileAttributeList][OverrideAttributeList]

+ + + +

A RomDirectoryStatement is one of the +following:

+ + + +

hide[[HWVD]] =

<existing-file>

+ + +

alias[[HWVD]] =

<existing-file> <destination-file> + [ FileAttributeList ]

+ + +

rename[[HWVD]] =

<existing-file> <destination-file> [ FileAttributeList ]

+ + + +

FileAttributeList FileAttributeList : FileAttribute | FileAttribute FileAttributeList

A FileAttribute is one of the following:

+ + + +

attrib =

[ s | S ][ h | H ][ r | R | w | W ] | hide

+ + +

exattrib =

+ + + +

OverrideAttributeList

OverrideAttributeList : OverrideAttribute | OverrideAttribute OverrideAttributeList

An overrideAttribute is one of the following:

+ + + +capability = +

+ + +paged + + + +unpaged + + + +pagedcode + + + +unpagedcode + + + +pageddata + + + +unpageddata + + + +

stack =

<hex-size>

+ + +

heapmin =

<hex-size>

+ + +

heapmax =

<hex-size>

+ + +

priority =

<hex-number> | <keyword>

+ + +

uid1 =

+ + +

uid2 =

+ + +

uid3 =

+ + + +

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-529757E6-ABF2-5C5C-A995-7DED6D298F52.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-529757E6-ABF2-5C5C-A995-7DED6D298F52.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,76 @@ + + + + + +DesignThis topic describes how to design the USB client controller +for different types of USB hardware. +

On most hardware platforms, the variant is split into a common, +or ASSP, layer and a device specific, or variant, layer; for example, +the Symbian port for the template board is split into a core layer +for the ASSP (in ...\template_assp\...) and code +specific to the template board (in ...\template_variant\...).

On some hardware configurations, the USB platform-specific layer +functionality is not only dependent on the USB device controller (in +the ASSP) but also on the variant. As an example, the USB cable connection/disconnection +notification mechanism is not defined in the USB specification. This +means that some USB device controllers have a mechanism for detecting +the status of a cable connection that is internal to the ASSP, while +for other controllers the mechanism is variant specific, and requires +software support in the variant layer.

In the template example port, the ASSP layer is implemented by +the TemplateAssp class defined in ...\template_assp\template_assp_priv.h. This class defines a number of pure virtual functions that act +as the interface to the cable connection status mechanism.

+class TemplateAssp : public Asic + { + + ... + /** + * USB client controller - Some example functions for the case that USB cable detection and + * UDC connect/disconnect functionality are part of the variant. + * Pure virtual functions called by the USB PSL, to be implemented by the variant (derived class). + * If this functionality is part of the ASSP then these functions can be removed and calls to them + * in the PSL (./pa_usbc.cpp) replaced by the appropriate internal operations. + */ + virtual TBool UsbClientConnectorDetectable()=0; + virtual TBool UsbClientConnectorInserted()=0; + virtual TInt RegisterUsbClientConnectorCallback(TInt (*aCallback)(TAny*), TAny* aPtr)=0; + virtual void UnregisterUsbClientConnectorCallback()=0; + virtual TBool UsbSoftwareConnectable()=0; + virtual TInt UsbConnect()=0; + virtual TInt UsbDisconnect()=0; + +

In the template example port, the variant layer is implemented +by the Template class defined in ...\template_variant\inc\variant.h. The variant layer provides the implementation for these USB pure +virtual functions.

+NONSHARABLE_CLASS(Template) : public TemplateAssp + { + + ... + /** + * USB client controller - Some example functions for the case that USB cable detection and + * UDC connect/disconnect functionality are part of the variant. + * These virtual functions are called by the USB PSL (pa_usbc.cpp). + * If this functionality is part of the ASSP then these functions can be removed as calls to them + * in the PSL will have been replaced by the appropriate internal operations. + */ + virtual TBool UsbClientConnectorDetectable(); + virtual TBool UsbClientConnectorInserted(); + virtual TInt RegisterUsbClientConnectorCallback(TInt (*aCallback)(TAny*), TAny* aPtr); + virtual void UnregisterUsbClientConnectorCallback(); + virtual TBool UsbSoftwareConnectable(); + virtual TInt UsbConnect(); + virtual TInt UsbDisconnect(); + +

The implementation for these functions can be found in ...\template_variant\specific\variant.cpp.

The USB port also needs interrupt handling code to deal with USB +external interrupts. See the Interrupt Dispatcher +Tutorial for details about how to do this.

+This may be done by others as a specialist porting activity. + \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-52B8098A-7695-5EA6-B58F-D730A445C583-master.png Binary file Adaptation/GUID-52B8098A-7695-5EA6-B58F-D730A445C583-master.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-52B8098A-7695-5EA6-B58F-D730A445C583_d0e77443_href.png Binary file Adaptation/GUID-52B8098A-7695-5EA6-B58F-D730A445C583_d0e77443_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-535C66C9-8B45-4DF3-8404-8ED03ABB4799-GENID-1-2-1-10-1-5-1-9-1-1-7-1-4-1-11-1.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-535C66C9-8B45-4DF3-8404-8ED03ABB4799-GENID-1-2-1-10-1-5-1-9-1-1-7-1-4-1-11-1.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,78 @@ + + + + + +TSDIOInterrupt +Class TutorialDescribes the TSDIOInterrupt API class. +

Description

The TSDIOInterrupt class +provides the client with the ability to enable, disable, bind and unbind to +an SDIO interrupt. There is no Clear() method provided as it is the responsibility +of the client device driver to clear the appropriate interrupt through its DSDIORegInterface class +documented here.

+ + + +

Header file

interrupt.h

+ + +

Source code file

interrupt.cpp

+ + +

Required libraries

epbussdio.lib

+ + +

Class declaration

class TSDIOInterrupt

+ + + +

Bind()

The +function declaration for the Bind() method is:

IMPORT_C TInt Bind(TSDIOIsr aIsr, TAny* aPtr);

Description

Binds the TSDIOIsr callback to the function's interrupt. +Once bound, the interrupt should be enabled for the function by a call to +Enable().

Parameters

+ + + +
TSDIOIsr aIsr
+The ISR used to handle the function's interrupt. + + +
TAny* aPtr
+User defined data for use within the ISR. + + + +

Return value

KErrNone if successful, KErrAlreadyExists if +an ISR already bound to the function's interrupt, or a standard Symbian platform +error code.

Unbind()

The +function declaration for the Unbind() method is:

IMPORT_C TInt Unbind();

Description

Unbinds +the callback from the interrupt controller, replacing the callback with a +dummy handler.

Parameters

None.

Return value

KErrNone if +successful, otherwise a standard Symbian platform error code.

Enable()

The +function declaration for the Enable() method is:

IMPORT_C TInt Enable();

Description

Enables +the function's interrupt by setting the appropriate IEN bit in the CCCR. Note +that this only unmasks the global function interrupt. It is the responsibility + of the client to perform any function-specific interrupt enabling that may +be required.

Parameters

None.

Return value

KErrNone if +successful, otherwise a standard Symbian platform error code.

Disable()

The +function declaration for the Disable() method is:

IMPORT_C TInt Disable();

Description

Disables the function's interrupt by clearing the appropriate IEN bit in +the CCCR. Note that this only masks the global function interrupt. It is +the responsibility of the client to perform any function-specific interrupt +disabling that may be required.

Parameters

None.

return +value

KErrNone if successful, otherwise a standard +Symbian platform error code.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-535C66C9-8B45-4DF3-8404-8ED03ABB4799-GENID-1-2-1-10-1-5-1-9-1-1-7-1-4-1-4-1.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-535C66C9-8B45-4DF3-8404-8ED03ABB4799-GENID-1-2-1-10-1-5-1-9-1-1-7-1-4-1-4-1.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,78 @@ + + + + + +TSDIOInterrupt +Class TutorialDescribes the TSDIOInterrupt API class. +

Description

+ + + +

Header file

interrupt.h

+ + +

Source code file

interrupt.cpp

+ + +

Required libraries

epbussdio.lib

+ + +

Class declaration

class TSDIOInterrupt

+ + + +

Bind()

The +function declaration for the Bind() method is:

IMPORT_C TInt Bind(TSDIOIsr aIsr, TAny* aPtr);

Description

Binds the TSDIOIsr callback to the function's interrupt. +Once bound, the interrupt should be enabled for the function by a call to +Enable().

Parameters

+ + + +
TSDIOIsr aIsr
+The ISR used to handle the function's interrupt. + + +
TAny* aPtr
+User defined data for use within the ISR. + + + +

Return value

KErrNone if successful, KErrAlreadyExists if +an ISR already bound to the function's interrupt, or a standard Symbian platform +error code.

Unbind()

The +function declaration for the Unbind() method is:

IMPORT_C TInt Unbind();

Description

Unbinds +the callback from the interrupt controller, replacing the callback with a +dummy handler.

Parameters

None.

Return value

KErrNone if +successful, otherwise a standard Symbian platform error code.

Enable()

The +function declaration for the Enable() method is:

IMPORT_C TInt Enable();

Description

Parameters

None.

Return value

KErrNone if +successful, otherwise a standard Symbian platform error code.

Disable()

The +function declaration for the Disable() method is:

IMPORT_C TInt Disable();

Description

Parameters

None.

return +value

KErrNone if successful, otherwise a standard +Symbian platform error code.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-535E5C2A-DCFD-4BCB-B26B-11E88BDB8A8A.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-535E5C2A-DCFD-4BCB-B26B-11E88BDB8A8A.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,295 @@ + + + + + +TDmac Derived Class ImplementationImplementing the hardware-specific DMA controller. +

The TDmac class is part of the PIL. It is a +container for the DMA controller's channels, descriptors and descriptor +headers. It also defines virtual functions for operations that require +a PSL implementation.

You need to derive TDmac for each distinct type +of DMA controller on your device, and implement these virtual functions.

+ + + +Function +Mandatory/Conditional +Description + + + + +Transfer() +Mandatory +For single buffer and scatter/gather, this starts the DMA transfer. +For double buffer, this prepares the next fragment to transfer while +a current transfer is in operation + + +StopTransfer() +Mandatory +Stop the specified channel synchronously. Must not return to +the PSL implementation until the channel has stopped. + + +IsIdle() +Mandatory +Returns ETrue if specified channel is idle, +otherwise EFalse + + +MaxTransferSize() +Optional +Takes the parameters and evaluates the maximum transfer size +in bytes. + + +MemAlignMask() +Optional +This applies to DMA v1 only. + + +InitHwDes() +Optional +For scatter-gather, initialise the array of memory areas and +set up the first block of data to be transferred. + + +ChainHwDes() +Optional +For scatter-gather, add additional blocks of data to transfer +to the list of memory areas. + + +AppendHwDes() +Optional +For scatter-gather, add to the array of memory areas while +the transfer is active. This is used in particular for streaming data +where new descriptors can be added to the end of the chain while data +earlier in the train is being transferred. E.g. video streaming. + + +UnlinkHwDes() +Optional +For scatter-gather, remove items from the array of memory areas. + + +FailNext() +Optional +For a sequence of memory transfers, tell the next one to fail. + + +MissNextInterrupts() +Optional +DMA transfers start on the next interrupt, but sometimes you +want to skip the next interrupt for synchronisation or other reasons. + + +Extension() +Optional +Pass a command from the application/client down to the DMA +chipset. Hardware dependent. + + + +

Implement +the mandatory controller virtual functions

The TDmac class contains several pure virtual functions that +must be implemented by the PSL implementation:

TDmac::Transfer()
TDmac::StopTransfer()
TDmac::IsIdle()

These functions start and stop transfers on a DMA channel +and are the main interface between the PIL and the PSL. The implementation +of these functions depends on the hardware available for performing +DMA, and on the characteristics used to specify a DMA transfer:

the source and +destination addresses
the burst size
the maximum transfer +size
the transfer width, +i.e. number of bits per memory access
the memory alignment +and endianness.

The DMA Framework manages the transfer descriptors according +to the descriptor parameter passed into the TDmac constructor by the derived class constructor; the descriptor parameter +is a TDmac::SCreateInfo structure. The per-request +transfer parameters are passed into the descriptors for each request +issued by a driver.

The +transfer function: Transfer()

This function initiates a +previously constructed request on a specific channel. This is the +template implementation:

+void TTemplateDmac::Transfer(const TDmaChannel& aChannel, const SDmaDesHdr& aHdr) +// +// Initiates a (previously constructed) request on a specific channel. +// + { + const TUint8 i = static_cast&<TUint8&>(aChannel.PslId()); + TDmaDesc* pD = HdrToHwDes(aHdr); + + __KTRACE_OPT(KDMA, Kern::Printf("&>TTemplateDmac::Transfer channel=%d des=0x%08X", i, pD)); + + // Load the first descriptor address into the DMAC and start it + // by setting the RUN bit. + (void) *pD, (void) i; + + } +

The +stop transfer function: StopTransfer()

This is the template +implementation:

void TTemplateDmac::StopTransfer(const TDmaChannel& aChannel) +// +// Stops a running channel. +// + { + const TUint8 i = static_cast&<TUint8&>(aChannel.PslId()); + + __KTRACE_OPT(KDMA, Kern::Printf("&>TTemplateDmac::StopTransfer channel=%d", i)); + + } +

The +function: IsIdle()

IsIdle() returns +the state of a given channel. This is the template implementation:

TBool TTemplateDmac::IsIdle(const TDmaChannel& aChannel) +// +// Returns the state of a given channel. +// + { + const TUint8 i = static_cast&<TUint8&>(aChannel.PslId()); + + __KTRACE_OPT(KDMA, Kern::Printf("&>TTemplateDmac::IsIdle channel=%d", i)); + + return ETrue; + } +

Implement +the non-mandatory controller virtual functions

The following +auxiliary functions are used to implement the scatter-gather transfer +mode behavior by creating and manipulating the linked list of transfer +fragment headers that describe a given scatter-gather transaction. +They are called by the TDmac base class functions +when the instance of the TDmac derived class reports +itself as being capable of scatter-gather operations.

TDmac::InitHwDes()
TDmac::ChainHwDes()
TDmac::AppendHwDes()

First +scatter-gather support function: InitHwDes()

This is a +function for creating a scatter-gather list. From the information +in the passed-in request, the function sets up the descriptor with +that fragment's:

source and destination +address
size
driver/DMA controller +specific transfer parameters: memory/peripheral, burst size, transfer +width.

This is the template implementation:

void TTemplateDmac::InitHwDes(const SDmaDesHdr& aHdr, TUint32 aSrc, TUint32 aDest, TInt aCount, + TUint aFlags, TUint32 aPslInfo, TUint32 /*aCookie*/) +// +// Sets up (from a passed in request) the descriptor with that fragment's source and destination address, +// the fragment size, and the (driver/DMA controller) specific transfer parameters (mem/peripheral, +// burst size, transfer width). +// + { + TDmaDesc* pD = HdrToHwDes(aHdr); + + __KTRACE_OPT(KDMA, Kern::Printf("TTemplateDmac::InitHwDes 0x%08X", pD)); + + // Unaligned descriptor? Error in generic layer! + __DMA_ASSERTD(IsHwDesAligned(pD)); + + pD-&>iSrcAddr = (aFlags & KDmaPhysAddrSrc) ? aSrc : Epoc::LinearToPhysical(aSrc); + pD-&>iDestAddr = (aFlags & KDmaPhysAddrDest) ? aDest : Epoc::LinearToPhysical(aDest); + pD-&>iCmd = DcmdReg(aCount, aFlags, aPslInfo); + pD-&>iDescAddr = TDmaDesc::KStopBitMask; + } +

Second +scatter-gather support function: ChainHwDes()

If the framework +needs to fragment the client’s request, either because of the transfer +size or because the memory is not a single contiguous block, then +the framework calls this function. It chains hardware descriptors +together by setting the next pointer of the original descriptor to +the physical address of the descriptor to be chained. It assumes that +the DMAC channel is quiescent when called.

This is the template +implementation:

void TTemplateDmac::ChainHwDes(const SDmaDesHdr& aHdr, const SDmaDesHdr& aNextHdr) +// +// Chains hardware descriptors together by setting the next pointer of the original descriptor +// to the physical address of the descriptor to be chained. +// + { + TDmaDesc* pD = HdrToHwDes(aHdr); + TDmaDesc* pN = HdrToHwDes(aNextHdr); + + __KTRACE_OPT(KDMA, Kern::Printf("TTemplateDmac::ChainHwDes des=0x%08X next des=0x%08X", pD, pN)); + + // Unaligned descriptor? Error in generic layer! + __DMA_ASSERTD(IsHwDesAligned(pD) && IsHwDesAligned(pN)); + + pD-&>iDescAddr = DesLinToPhys(pN); + } +

Third +scatter-gather support function: AppendHwDes()

This function +is called by the TDmac base class when a driver +request is called for a channel that is still active, i.e. where the +intent is to provide data streaming so that the target device is constantly +provided with data; for example, an audio device playing a track. +In this case, the function provided by the derived class must:

stop the DMAC to +prevent any corruption of the scatter-gather list while appending +the new fragment descriptor
append the new +descriptor
re-enable the channel, +ideally before the target has detected the gap in service.

This is the template implementation:

void TTemplateDmac::AppendHwDes(const TDmaChannel& aChannel, const SDmaDesHdr& aLastHdr, + const SDmaDesHdr& aNewHdr) +// +// Appends a descriptor to the chain while the channel is running. +// + { + const TUint8 i = static_cast&<TUint8&>(aChannel.PslId()); + + TDmaDesc* pL = HdrToHwDes(aLastHdr); + TDmaDesc* pN = HdrToHwDes(aNewHdr); + + __KTRACE_OPT(KDMA, Kern::Printf("&>TTemplateDmac::AppendHwDes channel=%d last des=0x%08X new des=0x%08X", + i, pL, pN)); + // Unaligned descriptor? Error in generic layer! + __DMA_ASSERTD(IsHwDesAligned(pL) && IsHwDesAligned(pN)); + + TPhysAddr newPhys = DesLinToPhys(pN); + + const TInt irq = NKern::DisableAllInterrupts(); + StopTransfer(aChannel); + + pL-&>iDescAddr = newPhys; + const TTemplateSgChannel& channel = static_cast&<const TTemplateSgChannel&&>(aChannel); + TDmaDesc* pD = channel.iTmpDes; + + (void) *pD, (void) i; + + NKern::RestoreInterrupts(irq); + + __KTRACE_OPT(KDMA, Kern::Printf("&<TTemplateDmac::AppendHwDes")); + } +

+DMA +Technology Guide +DMA +Implementation Guide +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-53649311-4465-48B5-8D07-A65515950040.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-53649311-4465-48B5-8D07-A65515950040.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,67 @@ + + + + + +Data +Transfer across Memory BoundariesThis document describes how to read from and write to user-side +memory from a kernel thread context or a user thread. +

When a driver reads or writes data from or to a user-side program, the +data must be copied between user address space and Kernel address space. The +Kernel provides a number of APIs that allow this to be done safely. The API +to use depends on whether the request is serviced in a user thread context, +or in a Kernel thread context.

From +kernel space

To read and write data to the user space from +a kernel thread context, use Kernel APIs such as Kern::ThreadDesRead(), Kern::ThreadRawRead(), Kern::ThreadDesWrite(), and Kern::ThreadRawWrite(). The data can be handled +as descriptors or as raw memory.

The Kernel also provides other APIs +to safely read the information about a descriptor in another thread's address +space. Kern::ThreadGetDesInfo() returns the length, maximum +length, and a pointer to the descriptor's buffer. The length and maximum length +can also be obtained specifically by using Kern::ThreadGetDesLength() and Kern::ThreadGetDesMaxLength().

TInt DExDriverLogicalChannel::DoControl(TInt aFunction, TAny* a1, TAny* /*a2*/) + { + ... + // To read the buffer descriptors from user space + r=Kern::ThreadDesRead(iClient,a1,iTxBuffer,0,0); + ... + // To write the buffer descriptors to user space + r=Kern::ThreadDesWrite(iClient,(TDes8*)a1,iRxBuffer,0); + ... + } // Read the descriptor maximum length from the user thread (iClient) +// using the kernel API Kern::ThreadGetDesMaxLength(). This API +// gets the maximum length of a descriptor in another thread's +// address space. Kern::ThreadGetDesInfo() can also be used to +// get length, maximum length and pointer to the descriptor's +// buffer. +// +iCount=Kern::ThreadGetDesMaxLength(iClient,aData);

From user space

When +executing a read or write operation in the context of a user thread, use the +following APIs:

kumemget()
kumemput()
umemget()
umemput()

Kernel APIs are also available to do copy operations using descriptors:

Kern::KUDesGet()
Kern::KUDesPut()
Kern::KUDesInfo()
Kern::KUdesSetLength()

Kern::InfoCopy() can be used to copy a descriptor +safely in a way that enables forward and backward compatibility. It is typically +used for copying capability packages.

void DExDriverLogicalDevice::GetCaps(TDes8& aCaps) const + { + // device capabilities are packaged to a buffer + TPckgBuf<RExDriver::TUartCaps> caps; + caps().iVersion=iVersion; + // Copy the device capabilities to the user thread using the + // Kernel API + Kern::InfoCopy(aCaps,caps); + }

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-5392507E-45FF-4B20-B257-E58E23685295-master.png Binary file Adaptation/GUID-5392507E-45FF-4B20-B257-E58E23685295-master.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-5392507E-45FF-4B20-B257-E58E23685295_d0e410_href.png Binary file Adaptation/GUID-5392507E-45FF-4B20-B257-E58E23685295_d0e410_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-53944506-5CA2-52BA-8D5A-9EE72092612B.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-53944506-5CA2-52BA-8D5A-9EE72092612B.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,28 @@ + + + + + +BootstrapDescribes what is the bootstrap and how to implement it for a specific +platform. +

The bootstrap is a program that the phone runs after a hardware reset. +The task of the bootstrap is to prepare a basic environment for the kernel +to run. If the phone uses NAND Flash, then the NAND Flash Core Loader loads +and starts the bootstrap.

Symbian platform divides the bootstrap into a platform-independent layer +that can be used with any ARM device, and a platform-specific layer that you +must implement when you create a new phone.

+Flash Translation +Layer Technology +Base Starter + +System Startup +Overview +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-54042C84-6216-5930-9CBF-BAF635CECD4D.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-54042C84-6216-5930-9CBF-BAF635CECD4D.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,62 @@ + + + + + +Power +HAL Handler TutorialUser-side programs can get and set a number of system attributes +about power using the HAL interface. +

The base port must provide and register a HAL handler to handle these attributes.

The power attributes are in the EHalGroupPower HAL group. +The handler provides a kernel-side implementation to deal with the user-side +calls to HAL::Get() and HAL::Set() when +one of the following parameters is passed:

HALData::EPowerGood
HALData::EPowerBatteryStatus
HALData::EAccessoryPower
HALData::EPowerBackup
HALData::EPowerBackupStatus
HALData::EPowerExternal
HALData::EPenDisplayOn
HALData::ECaseSwitchDisplayOn
HALData::ECaseSwitchDisplayOff

A typical application will have a user side monitor that periodically calls HAL::Get(), +passing HALData::EPowerBatteryStatus to get the charge +level of the battery.

Typically, the handler is implemented as part of a DPowerHal derived +object, which is created by the entry point of the base port power kernel +extension. The object is, therefore, part of the power controller kernel extension.

Implementation +notes

The DPowerHal derived +object constructor must register with the power manager by calling Register().
If there is some power-related +data that can be accessed via the HAL component and that persists through +power cycles (On/Off), it should be initialised here. Typically the TOnOffInfoV1 data +member of the Variant-specific TActualMachineConfig (usually +found in mconf.h file under the platform directory) contains +some of that persistent data.
The handler itself is +the function PowerHalFunction(), and must be fully implemented +in the base port.
The kernel hooks up +the handler to service the HAL functions at boot-time.
The power Hal functions +that the Handler can handle are enumerated by TPowerHalFunction. +Not all of these functions need to be handled. If not handled, the kernel +returns KErrNotSupported when the HAL function is called +with the relevant parameter. It is left to the base port to decide which functions +are relevant.

+ +User-Side Hardware Abstraction +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-552530EB-1287-542D-AED3-125387B485C1.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-552530EB-1287-542D-AED3-125387B485C1.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,59 @@ + + + + + +ArchitectureDescribes the architecture of the Digitizer Driver. +

The architecture has two layers:

+ + + + +

A platform-independent layer that:

processes digitiser +samples
issues pen movement +events to the kernel
maintains a buffer of +digitiser readings

This layer implements behaviour that can be expected to be the same +across all platforms.

Symbian provides this.

+ + +

A platform specific layer that is responsible for:

the conversion between +screen and digitiser coordinates
the implementation of +low level calibration
the gathering of raw +digitiser data samples
power management.

This layer implements behaviour that can vary between platforms and +therefore needs to be implemented by the port.

The bulk of the effort +here is the definition and implementation of a class derived from the Symbian +defined DDigitiser class; the derived class implements +the pure virtual functions defined by DDigitiser.

You +provide this.

+ + + +

The template port provides a framework for implementing the platform specific +part of the digitiser. The diagram below shows the overall relationship:

+ + + +

The standard Symbian platform ports all follow the same general pattern, +including the H2. However, the H2 board implementation has two levels in its +platform specific layer (an ASSP and a variant layer) and uses different source +file names (e.g. digitizer.cpp), but, nevertheless, the +same general pattern applies.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-5686E787-537F-5B32-B719-34EF5B7F0D37-master.png Binary file Adaptation/GUID-5686E787-537F-5B32-B719-34EF5B7F0D37-master.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-5686E787-537F-5B32-B719-34EF5B7F0D37_d0e18814_href.png Binary file Adaptation/GUID-5686E787-537F-5B32-B719-34EF5B7F0D37_d0e18814_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-57989FF8-5E8F-4C8A-9D38-169AFCA4C078.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-57989FF8-5E8F-4C8A-9D38-169AFCA4C078.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,116 @@ + + + + + +Baseport Template Implementation GuideDescribes the use of the Baseport Template in porting Symbian +platform. +

General +procedure

The Baseport Template is a minimal +baseport for the Symbian platform that implements the basic functionality +of a baseport without supplying any hardware specific code. It provides +a skeleton of a working baseport, which base porters can modify in +accordance with the instructions in the comments. Porting involves +abstraction from hardware and must be performed in a set sequence +(for example, the abstraction in the drivers depends on previous abstraction +in HAL which depends on previous abstraction in ASIC and so on). Many +of the header files are not in the Baseport Template files but are +held elsewhere in the code base, for example, ..\e32\include\kernel\arm\

File +structure

The files which make up the Baseport +Template are divided between two directories, ASSP and Variant containing +two classes of the same names. This division represents a fundamental +feature of the kernel architecture which you are recommended to retain +in your implementation of the port. The baseport involves implementing +functions to run on the target hardware, but it is useful to distinguish +between functionality specific to the CPU (ARM etc) and functionality +specific to peripherals with their own processors. ASSP functions +must be implemented in accordance with the device hardware, while +Variant functions correspond to off chip peripherals. The distinction +is not absolutely mandatory (it is possible just to provide a Variant +layer) but strongly recommended and assumed in many other areas of +the porting process.

A port with an ASSP/Variant architecture +is implemented with two C++ classes and two .mpp files.

...\template_assp\assp.cpp
...\template_assp\katemplate.mmp
...\template_variant\specific\variant.cpp
...\template_variant\vtemplate.mmp

For more information see the Base Porting Guide.

Bootstrap

The bootstrap is the code that runs after a hardware +reset, to initialize the basic system services that enable the kernel +to run. Parts of it must be written in assembler (either GNU or ARM) +and are specific to the device hardware, while others are written +in C++ and are automatically translated into assembler. Bootstrap +is implemented as the bootstrap/template.s file.

This is supplied as an example only: implementation is entirely +dependent on the target hardware.

For more information see the Base Porting Guide.

Interrupt +dispatcher

The Symbian platform is a real time +interrupt driven operating system. To port it you need to determine +the number and function of the interrupts in your port and implement +the interrupt dispatcher to handle them. Interrupt service routines +(ISRs) are held in an array of class SInterruptHandler as a member of the TemplateInterrupt class defined +in template_assp_priv.h. ISRs are associated +with individual interrupt sources defined in the ASSP layer by functions +of the Interrupt class such as Bind() and Unbind().

...\template_assp\template_assp_priv.h
...\template_assp\interrupts.cpp

For more information see the Base Porting Guide.

+ ASIC

The Asic class +contains initialization functions which must be called early in the +boot process. ASSP is derived from Asic and Variant from the ASSP derivation.

...\template_assp\template_assp.h
...\template_assp\template_assp.cpp

For more information see the Base Porting Guide.

+ HAL

The HAL class +abstracts items of hardware specific functionality. You must implement +functions to get and set hardware specific attributes in accordance +with the hardware used on the target device. The attributes are defined +in config.hcf and values.hda configuration files.

...\template_variant\hal\config.hcf
...\template_variant\hal\values.hda

The attributes are modified by get and set functions called +HAL handlers defined in the relevant hardware drivers.

For more +information see the Base Porting Guide.

+ Drivers

The rest of the work involves +porting drivers. A typical implementation would include these drivers:

DMA Framework
- ...\template_assp\dmapsl.cpp
- ...\template_assp\dma.mpp
Digitizer Driver
- ...\template_variant\specific\xyin.cpp
- ...\template_variant\exxytemplate.mmp
Keyboard Driver
- ...\template_variant\exkey_inttemplate.mmp
- ...\template_variant\specific\keyboard_interrupt.cpp
LCD Extension
- ...\template_variant\specific\lcd.cpp
- ...\template_variant\exlcdtemplate.mmp
Serial Port Driver
- ...\template_variant\specific\uart.cpp
- ...\template_variant\datxtemplate.mmp
Sound Driver
- ...\template\template_variant\specific\soundsc_rx.cpp
- ...\template\template_variant\specific\soundsc_tx.cpp
- ...\template\template_variant\soundsctemplate.mmp
USB Client Driver Technology
- ...\template_assp\pa_usbc.cpp
- ...\template_assp\usbcc.mmp

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-583F70B4-5C8C-54FA-A869-E6F073DE1FD6.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-583F70B4-5C8C-54FA-A869-E6F073DE1FD6.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,58 @@ + + + + + +Interrupt::Enable() +and Interrupt::Disable()The functions Interrupt::Enable() and Interrupt::Disable() are +used by device drivers to enable and disable the interrupt source in the interrupt +controller hardware. +

An Interrupt +ID is passed to the functions to identify the interrupt source. All +requests for enabling and disabling interrupts should go to these functions +in the Interrupt class so that device drivers should never +need to know where the interrupt is actually implemented. The general rule +is that the interrupt ID is tagged in some way to allow these functions to +decide whether the interrupt refers to the ASSP layer or to the Variant layer. +These functions are implemented in the ASSP layer.

The implementation of these functions is completely dependent on the interrupt +hardware. In the template port, Interrupt::Enable() is implemented +in ...\template_assp\interrupts.cpp. The relevant part +is:

+EXPORT_C TInt Interrupt::Enable(TInt anId) + { + __KTRACE_OPT(KEXTENSION,Kern::Printf("Interrupt::Enable id=%d",anId)); + TInt r=KErrNone; + // if ID indicates a chained interrupt, call variant... + if (anId<0 && ((((TUint)anId)>>16)&0x7fff)<(TUint)KNumTemplateInts) + r=TemplateAssp::Variant->InterruptEnable(anId); + else if ((TUint)anId>=(TUint)KNumTemplateInts) + r=KErrArgument; + else if (TemplateInterrupt::Handlers[anId].iIsr==TemplateInterrupt::Spurious) + r=KErrNotReady; + else + { + // + // TO DO: (mandatory) + // + // Enable the corresponding Hardware Interrupt source + // + } + return r; + } + +

Interrupts that 'belong' to the Variant Layer are passed to that layer +through the call to:

+r =TemplateAssp::Variant->InterruptEnable(anId); +

Interrupt::Disable() follows the same general pattern.

The Variant layer equivalent of this function, Template::InterruptEnable(), +in ...\template_variant\specific\variant.cpp, also follows +the same pattern.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-58AA7257-0951-42AB-9B6E-AAF63343FEFA-GENID-1-2-1-10-1-5-1-5-1-1-7-1-9-1-5-1.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-58AA7257-0951-42AB-9B6E-AAF63343FEFA-GENID-1-2-1-10-1-5-1-5-1-1-7-1-9-1-5-1.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,88 @@ + + + + + +DMA Channel OperationsDescribes how a device driver should open and close a DMA +channel. +

Open

To use a DMA channel it has to be opened. TDmaChannel::Open() must be called to open the channel, and the required information +provided in a TDmaChannel::SCreateInfo structure. +The actual DMA channel selection is done by the hardware specific +layer.

/** + Initializes the DMA for transmit. This function does all the + required generic initialization to use the DMA framework. This + function does not have any variant specific initialization. + + @return KErrNone on success, else standard error code on failure + */ +TInt DExDriverUartTxDma::Init() + { + ... + + // Initialize the channel information to select and configure the DMA + // channel + TDmaChannel::SCreateInfo info; + info.iCookie = (TUint); + info.iDesCount = 1; // For single buffered transfers + info.iDfcPriority = 4; // Set the priority of this DFC for DMA + info.iDfcQ = iUartComm->DfcQ(); // DFCQ onto which this request + // has to be queued + + // DMA channel has to be opened before doing any operations on + // the channel. TDmaChannel::Open() opens the DMA channel as + // set by info passed and selected by the hardware-specific layer. + + r = TDmaChannel::Open(info, iTxDmaChannel); + if (r!=KErrNone) + { + return r; + } + ... + }

A DMA channel has to be closed after completing all the DMA operations. +This releases the DMA channel for other resources and peripherals. +To close a previously opened channel, the channel should be idle, +with no pending requests. So, before closing, call TDmaChannel::CancelAll(), which cancels the current request and any pending DMA requests. +This should then be followed by closing the channel using TDmaChannel::Close().

/** + Destructor. Deinitializes the member variables, cancels any + requests, closes the channel, deletes the DMA requests, frees the + hardware chunks allocated. + */ + +DExDriverUartTxDma::~DExDriverUarttxDma() + { + ... + // if DMA channel is existing, cancel all requests on it. + // + if (iTxDmaChannel) + { + // TDmaChannel::CancelAll() cancels the current request and + // any pending requests on the DMA channel + // + iTxDmaChannel->CancelAll(); + } + ... + + if(iTxDmaChannel) + { + // Close the DMA channel. TDmaChannel::Close() closes a + // previously opened channel. All the requests on this + // channel should have been cancelled prior to this, i.e. + // TDmaChannel::CancelAll() should have been called before + // this call. + // + iTxDmaChannel->Close(); + } + ... + }

To stop DMA without closing the channel, simply +cancel the request.

+DMA +Channels +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-58AA7257-0951-42AB-9B6E-AAF63343FEFA-GENID-1-2-1-9-1-6-1-8-1-7-1-4-1.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-58AA7257-0951-42AB-9B6E-AAF63343FEFA-GENID-1-2-1-9-1-6-1-8-1-7-1-4-1.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,88 @@ + + + + + +DMA Channel OperationsDescribes how a device driver should open and close a DMA +channel. +

Open

To stop DMA without closing the channel, simply +cancel the request.

+DMA +Channels +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-592B6D20-4ABA-5C79-9734-D18E2CE4A86C.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-592B6D20-4ABA-5C79-9734-D18E2CE4A86C.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,166 @@ + + + + + +Writable +Data Paging OverviewOverview of data paging, the next phase in Symbian's implementation +of demand paging. +

Purpose

Writable +data paging allows the demand paging of any user-side data (for example thread +stacks and heaps). Writable data paging makes use of a fixed size backing +store to page out data. The backing store may use a NAND flash partition or +an embedded MMC (eMMC).

The aim of data paging is to enable more memory-hungry +use cases without increasing the amount of physical RAM present in the device.

For +example, data paging enables:

running applications +that are not designed with the memory constraints of embedded devices in mind, +for example applications ported from other environments with writable data +paging (such as a PC).
running multiple applications +at the same time where previously there would not have been enough memory.

Data paging offers no performance increase, unlike code paging +which can speed up application loading by reading only the necessary pages +into RAM.

However, writable data paging does have +the following limitations:

It is only possible +to page the following types of memory:
- user heaps,
- user thread stacks,
- private chunks,
- global chunks,
- static data.
A single memory object +(e.g. a heap, stack, DLL or chunk) is the smallest granularity at which paging +can be configured
No attempt will be made +to page kernel-side data
No attempt will be made +to implement memory mapped files (e.g. posix's mmap)
No attempt will be made +to implement any kind of paging on the emulator.

Required background

This +document assumes that the reader is familiar with the concept of Demand +Paging, and the existing implementation of ROM and code paging in Symbian +platform.

Key concepts +and terms

Page: Memory is managed in fixed size units called pages. The size of a page +is usually determined by the hardware, and for ARM architectures this is 4K.
Paged in or Paged out: If a given page of memory is present in RAM it is said to be paged +in (or just 'present'), as opposed to paged out.
Paging in: The process of moving a page of memory from being paged out to being +paged in.
Paging out: The process of moving a page of memory from being paged in to being +paged out.
backing store: The external media used to hold paged out pages is referred +to as the swap area. This area may be much larger than physical RAM, +although a factor of around twice as large is considered normal in existing +systems.
Working set: The term working set is defined as the memory accessed during +a given time period.
Pinning: Pinning pages refers to paging in demand-paged memory and forcing +it to remain in RAM until it is unpinned at a later time.

Classes

The +following classes are affected by the use of writable data demand paging:

The +following classes are involved in the use of threads and processes:

+ + + +

Class

Description

+ + +

RThread

This class is used to handle threads.

+ + +

RProcess

This class is used to handle processes.

+ + +

TThreadCreateInfo

Used to specify the attributes of a new thread.

+ + + +

These classes are used in handling memory:

+ + + +

Class

Description

+ + +

RChunk

Handle a chunk.

+ + +

TChunkCreateInfo

A structure that specifies the type and properties of the chunk +that is to be created.

+ + +

TChunkHeapCreateInfo

A structure that specifies the type and properties of a chunk with +a heap within it.

+ + +

UserHeap

A set of functions that are used to create heaps.

+ + + +

The following classes are used in client/server communication:

+ + + +

Class

Description

+ + +

CServer2

The abstract base class for servers.

+ + +

TIpcArgs

A client/server class that clients use to package arguments that +are to be sent to a sever.

+ + + +

+Flexible +Memory Model Overview +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-59322A4F-B9CB-5997-B843-C4A80F8D42F1.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-59322A4F-B9CB-5997-B843-C4A80F8D42F1.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,19 @@ + + + + + +AdaptationAdaptation is the software side of adding new hardware +to a device, including drivers and interfaces. +

This content is provided under our joint company non-disclosure +agreement. All content included in the documentation set is confidential +and can only be used for the limited purpose of viewing it as a potential +documentation solution. It cannot be redistributed or reused for any +purpose.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-59FF3BFE-21E2-554D-99EC-1A1D34AAEB7C-master.png Binary file Adaptation/GUID-59FF3BFE-21E2-554D-99EC-1A1D34AAEB7C-master.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-59FF3BFE-21E2-554D-99EC-1A1D34AAEB7C_d0e35295_href.png Binary file Adaptation/GUID-59FF3BFE-21E2-554D-99EC-1A1D34AAEB7C_d0e35295_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-5B24741C-7CE0-58E8-98C9-1D1CACCD476F.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-5B24741C-7CE0-58E8-98C9-1D1CACCD476F.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,106 @@ + + + + + +Fair Scheduling and File Caching BackgroundThis document describes the fair scheduling and file caching +features of the File Server. +

Fair +scheduling

The current design of the file server supports +the processing of client requests concurrently, as long as those requests +are made to different drives in the system. For example, a read operation +may take place on the NAND user area partition while a write operation +to the MMC card takes place concurrently.

However, requests +to the same drive are serialized on a first-come first-served basis, +which under some circumstances leads to bad user experience. For example:

An incoming +call arrives while a large video file is being written to the NAND +user area by an application that writes the file in very large chunks.
In order to +display the caller’s details, the phone needs to read from the contacts +database which is also stored on the NAND user area.
The write operation +takes a very long time to complete, so the call is lost.

This is one of many scenarios where the single threaded nature +of the file server may lead to unresponsive behavior. In order to +improve the responsiveness of the system, the Symbian platform implements +a fair scheduling policy that splits up large requests into more manageable +chunks, thus providing clients of the file server with a more responsive +system when the file server is under heavy load.

See Enabling fair scheduling.

Read +caching

Read caching aims to improve file server performance +by addressing the following use case:

A client (or multiple clients) issues repeated requests to +read data from the same locality within a file. Data that was previously +read (and is still in the cache) can be returned to the client without +continuously re-reading the data from the media.

Read caching is of little benefit for clients/files +that are typically accessed sequentially in large blocks and never +re-read.

There may be a small degradation in performance +on some media due to the overhead of copying the data from the media +into the file cache. To some extent this may be mitigated by the affects +of read-ahead, but this clearly does not affect large (>= 4K) reads +and/or non-sequential reads. It should also be noted that any degradation +may be more significant for media where the read is entirely synchronous, +because there is no scope for a read-ahead to be running in the file +server drive thread at the same time as reads are being satisfied +in the context of the file server’s main thread.

Demand +paging effects

When ROM paging is enabled, the kernel maintains +a live list of pages that are currently being used to store +demand paged content. It is important to realize that this list also +contains non-dirty pages belonging to the file cache. The implication +of this is that reading some data into the file cache, or reading +data already stored in the file cache, may result in code pages being +evicted from the live list.

Having a large number of clients +reading through or from the file cache can have an adverse effect +on performance. For this reason it is probably not a good idea to +set the FileCacheSize property to too large a value +– otherwise a single application reading a single large file through +the cache is more likely to cause code page evictions if the amount +of available RAM is restricted. See Migration Tutorial: +Demand Paging and Media Drivers.

Read-ahead +caching

Clients that read data sequentially (particularly +using small block lengths) impact system performance due to the overhead +in requesting data from the media. Read-ahead caching addresses this +issue by ensuring that subsequent small read operations may be satisfied +from the cache after issuing a large request to read ahead data from +the media.

Read-ahead caching builds on read caching by detecting +clients that are performing streaming operations and speculatively +reading ahead on the assumption that once the data is in the cache +it is likely to be accessed in the near future, thus improving performance.

The number of bytes requested by the read-ahead mechanism is initially +equal to double the client’s last read length or a page, for example, +4K (whichever is greater) and doubles each time the file server detects +that the client is due to read outside of the extents of the read-ahead +cache, up to a pre-defined maximum (128K).

Write +caching

Write caching is implemented to perform a small +level of write-back caching. This overcomes inefficiencies of clients +that perform small write operations, thus taking advantage of media +that is written on a block basis by consolidating multiple file updates +into a single larger write as well as minimizing the overhead of metadata +updates that the file system performs.

By implementing write +back at the file level, rather than at the level of the block device, +the possibility of file system corruption is removed as the robustness +features provided by rugged FAT and LFFS are still applicable.

Furthermore, by disabling write back by default, allowing the +licensee to specify the policy on a per drive basis, providing APIs +on a per session basis and respecting Flush and Close operations, +the risk of data corruption is minimized.

The possibility +of data loss increases, but the LFFS file system already implements +a simple write back cache of 4K in size so the impact of this should +be minimal.Write caching must be handled with care, as +this could potentially result in loss of user data.

Database +access needs special consideration as corruption may occur if the +database is written to expect write operations to be committed to +disk immediately or in a certain order (write caching may re-order +write requests).

For these reasons, it is probably safer to +leave write caching off by default and to consider enabling it on +a per-application basis. See Enabling read and write caching.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-5BD2D468-838A-49BC-BA92-F41102D37CBC.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-5BD2D468-838A-49BC-BA92-F41102D37CBC.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,16 @@ + + + + + +Generic ImplementationAdaptation software providing a realization of the Client +Interface. The Generic Implementation is also known as the Platform +Independent Layer (PIL). +

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-5C17A2E7-DE18-5CFB-A5D5-421D427CD5DD.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-5C17A2E7-DE18-5CFB-A5D5-421D427CD5DD.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,33 @@ + + + + + +Code OrganisationThis topic describes the source code for interrupt driven +keyboard drivers and related libraries. +

This topic describes the source code for interrupt driven keyboard +drivers and related libraries that Symbian platform provides.

Keyboard +driver

In a reference board port, the .mmp file for the keyboard driver is ...\template_variant\exkey_inttemplate.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 keyboard driver is built as part of +the Variant.

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

Key +translation DLL (ektran.dll)

This DLL is part of Symbian +platform generic code and is built as part of the Text Window Server +component.

The mmp file is located in Symbian platform generic +code in ...\e32\wserv\ektran.mmp, which defines +the location of the source files, header files and other dependencies.

Keyboard +mapping DLL (ekdata.dl)

The DLL is platform specific. It +is built as part of the Variant.

The mmp file has a name with +format cakd xx .mmp, where xx is the suffix that identifies the Variant in the +Variant specific .oby file. In the template port, +the mmp file has the name cakdtemplate.mmp.

The source code for the tables is located in keymap.cpp, and is located in the Variant specific directory. The template +port provides outline code.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-5C223AD5-4676-58B4-B3A5-066F6B69AA4D.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-5C223AD5-4676-58B4-B3A5-066F6B69AA4D.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,26 @@ + + + + + +Local Media +SubsystemProvides the logical device driver for the internal and removable +storage media on a phone. +

Local Media Subsystem uses +physical device drivers, called media drivers, that manage the storage media +hardware. A base port can implement new media drivers and implement ports +of the media drivers that are supplied in Symbian platform.

+ +File Server + +File Systems + +Media Drivers +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-5CCF303A-B7D5-570D-9BE8-29DFBE184995.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-5CCF303A-B7D5-570D-9BE8-29DFBE184995.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,79 @@ + + + + + +Porting OverviewThis topic describes the typical steps that you will need +to do to create a base port. +

The easiest way to create a base port is to take the supplied template +port and expand it to suit your own hardware configuration(s). The +template port, is an outline, but working, framework that you can +modify to suit your own hardware.

The template port can be found under the sf/os/kernelhwsrv/bsptemplate/ directory. For more information about the template port see Kernel & Hardware Quick Start Guide.

Set +up the environment

The first thing to do is to set up your +environment for building, downloading onto your hardware, and testing +that the port works.

Build, +download, and test the supplied template port

As supplied, +the template port is designed to boot on any hardware. It should boot +successfully, but clearly, the system can do nothing more at this +time. A successful boot shows that your build environment has been +set up correctly.

Copy +and rename the Template port

When porting the base to a +new platform, you will need to code and build the Variant. This provides +those hardware dependent services required by the kernel. In nearly +all ports, this is split into an ASSP DLL and a Variant DLL. We usually +refer to the ASSP layer and the Variant layer.

It is desirable +that code that depends only on the properties of the ASSP be segregated +from code that depends on details of the system outside the ASSP, +so that multiple systems that use the same ASSP can share common code.

For example, in the template reference port, the ..\template_assp\... directory contains source code that contains the ASSP code, whereas +the ...\template_variant\... directory contains +the code specific to the template board.

Code +the Bootstrap

The bootstrap consists of several generic +source and header files supplied as part of Symbian platform, and +a set of platform specific files. You need to create these platform +specific files as part of a base port.

For details, see Bootstrap.

The updated port can then be built, downloaded and tested.

Implement +the interrupt dispatcher

An interrupt is a condition that +causes the CPU to suspend normal execution, enter interrupt handling +state and jump to a section of code called an interrupt handler. The +ASSP/Variant part of the base port must implement an interrupt dispatcher +class to manage interrupts.

For details, see the Interrupt Dispatcher +Implementation Tutorial.

The updated port can then +be built, downloaded and tested.

Implement +the Asic class

The Kernel requires that the ASSP/Variant +part of the base port provides an implementation of the Asic interface. This defines a small number of hardware-specific functions +that are used by the Kernel.

For details, see the Asic Class Tutorial.

The updated port can then be +built, downloaded and tested.

Port +the User-Side Hardware Abstraction (HAL)

The User-Side +Hardware Abstraction (HAL) component provides a simple interface for +programs to read and set hardware-specific settings, for example, +the display contrast. A base port must define the attributes that +clients can use on a phone, and implement any functions that are required +to get and set the attributes.

For details, see User-Side Hardware Abstraction.

Port +the other drivers

The remaining drivers can now be ported. +Go and see:

DMA Framework
Digitizer Driver
Keyboard Driver
LCD Extension
Local Media Subsystem
Power Management
Serial Port Driver
Sound Driver
USB Client Driver +Technology

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-5CF162CA-4395-58AC-A318-2BF178276A57-master.png Binary file Adaptation/GUID-5CF162CA-4395-58AC-A318-2BF178276A57-master.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-5CF162CA-4395-58AC-A318-2BF178276A57_d0e69352_href.png Binary file Adaptation/GUID-5CF162CA-4395-58AC-A318-2BF178276A57_d0e69352_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-5E24CFFD-1F87-4B77-B7A0-59A419ADBC90.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-5E24CFFD-1F87-4B77-B7A0-59A419ADBC90.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,12 @@ + + + + + +IIC Describes the Inter-Integrated Circuit (IIC) platform service. \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-5E358AB4-03A7-5859-ABF2-A8B64B74AF56.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-5E358AB4-03A7-5859-ABF2-A8B64B74AF56.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,39 @@ + + + + + +Vector Floating Point Architecture (VFP)Describes the implementation of the ARM Vector Floating +Point Architecture (VFPv2) on Symbian platform. +

ARM provide a hardware floating point coprocessor that provides +floating point computation that is fully compliant with IEEE Std 754-1985.We +refer to the coprocessor as the VFP unit.

Symbian platform supports the use of VFPv2 on platforms where the +required hardware is present in both RunFast mode and in IEEE-without-exceptions mode. See ARM's Vector Floating-point +Coprocessor Technical reference Manual for more details on the coprocessor, +its architecture, and its execution modes.

You should read Floating point support in Symbian^3 Tools Guide +> Building. The guide contains information about applications +and user-side code, which is also applicable to code running on the +kernel side. However there are a number of restrictions that must +be observed:

You cannot use VFP instructions in any interrupt service routine.
You cannot use VFP instructions when the kernel is locked, for example, in +an IDFC or after calling NKern::Lock()
You cannot use VFP instructions in any section of code which runs with a fast +mutex held.

Using VFP instructions in these situations can lead to data being +corrupted, or the kernel panicking. If you rely on the compiler to +generate VFP instructions, rather than using inline assembler, it +is extremely important that you do not use any floating point values +in these situations. The compiler may generate VFP instructions for +the most trivial floating point operations and even for simple assignments.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-5EB03086-A87D-5588-8927-7A7F8DB38366.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-5EB03086-A87D-5588-8927-7A7F8DB38366.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,16 @@ + + + + + +Port Implementation +TutorialThis section describes how to implement a port of the bootstrap.

+Concepts + +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-5F35ED29-18A0-4764-B84D-B43BF23BF44F.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-5F35ED29-18A0-4764-B84D-B43BF23BF44F.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,72 @@ + + + + + +Time Testing GuideDescribes how to test a Time SHAI implementation. +

There is no conformance testing suite for the Time platform service. +So, this is a list of tests that have to be conducted to check that +the Time platform service is working correctly:

Time +Tests

The following table is a list of the tests that need +to be carried out in order to test the Time SHAI implementation.

+ + + + +

No.

Functionality To Test

Description

Correct Result

+ + + + +

The Real Time Clock (RTC) works correctly.

Check the output from the RTC with a reliable clock.

The date and time should be identical.

+ + +

Validating the RTC.

The function MRtcAdaptation::ValidateRtc() is called.

The KErrorNone should be returned in the +variable passed in the second argument.

+ + +

Setting the wake-up alarm.

The function MRtcAdaptation::SetWakeupAlarm()

The wake-up alarm should start at the set time.

+ + +

Un-set the wake-up alarm.

Set the wake-up +alarm to a known date and time.
Execute the +function MRtcAdaptation::UnsetWakeupAlarm() to +cancel the wake-up alarm.

The wake-up alarm will not go off at the original preset +time.

+ + +

Cancel a request.

As for the above, except that the function MRtcAdaptation::Cancel() is called instead ofMRtcAdaptation::UnsetWakeupAlarm().

The wake-up alarm will not go off at the original preset +time.

+ + + +

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-5F614B75-056D-5798-AE06-8DA6E9ED6834.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-5F614B75-056D-5798-AE06-8DA6E9ED6834.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,38 @@ + + + + + +Set the Interface Descriptors A short document that describes how to set the interface descriptors.

Introduction

Before setting the interface descriptors, get the device and endpoint capabilities of the USB Device Controller (UDC) hardware.

Get device capabilities,
Define the interface data,
Set the interface,
Finalise the interface.

Get device capabilities

Use RDevUsbcScClient::DeviceCaps() to get the device capabilities and RDevUsbcScClient::EndpointCaps() to get the endpoint capabilities.

TUsbDeviceCapsV01 is the structure used to return the device capabilities.

TUsbDeviceCaps d_caps; +TInt r = gPort.DeviceCaps(d_caps);

RDevUsbcScClient::EndpointCaps() returns the object TUsbEndpointData which contains a TUsbEndpointCaps object and a boolean variable that indicates whether the endpoint is in use. TUsbEndpointCaps contains the endpoint capabilities as reported by the driver.

TUsbcEndpointData data[KUsbcMaxEndpoints]; +TPtr8 dataptr(reinterpret_cast<TUint8*>(data), sizeof(data), sizeof(data)); +r = gPort.EndpointCaps(dataptr);

Note: Endpoint zero is only supported as a control endpoint. The capabilities of endpoint zero are not included in the list of endpoint cababilities returned.

Define the interface data

Before calling RDevUsbcScClient::SetInterface(), the class, subclass and protocol must be defined in the TUsbcScInterfaceInfo object. TUsbcScInterfaceInfo is in the TUsbcScInterfaceInfoBuf package buffer.

In the example below we set the interface data in the TUsbcScInterfaceInfo object.

TUsbcScInterfaceInfoBuf ifc; + +// Endpoint zero +ifc().iEndpointData[0].iType = KUsbEpTypeBulk; +ifc().iEndpointData[0].iDir = KUsbEpDirIn; +ifc().iEndpointData[0].iSize = KUsbEpSize64; + +//Endpoint 1 +ifc().iEndpointData[1].iType = KUsbEpTypeBulk; +ifc().iEndpointData[1].iDir = KUsbEpDirOut; +ifc().iEndpointData[1].iSize = KUsbEpSize64; + +_LIT16(string, "T_USBCSC Interface"); +ifc().iString = const_cast<TDesC16*>(&string); +ifc().iTotalEndpointsUsed = 2; +ifc().iClass.iClassNum = 0xff; +ifc().iClass.iSubClassNum = 0xff; +ifc().iClass.iProtocolNum = 0xff; + +// Tell the driver that this setting is interested in Ep0 requests: +ifc().iFeatureWord |= 0;

TUsbcScInterfaceInfo contains the following data members:

iEndpointData is is an array of n TUsbcScEndpointInfo elements where n = iTotalEndpointsUsed,

For each endpoint the TUsbcScEndpointInfo object must, at the very least, contain:
- The endpoint type (iType), direction (iDir) and maximum packet size (iSize) must be specified to claim each endpoint.
- The members iBufferSize and iReadSize help with performance tuning and memory optimisation. For example, a capture of 64KB may be an optimal size to pull off the bus without incurring timeout penalties in the PSL. Some classes may benefit from having multiple captures in the endpoint buffer, so iBufferSize would be some multiple of iReadSize.
- iExtra and iPairing allow for possible future support of classes that require pairing of endpoints by physical address and function. Note: This is not yet supported and any attempt to pair endpoints will result in failure to create the interface.
iString is a TDesC16,

A description string for the interface.
iTotalEndpointsUsed is a TUint,

This number is all the endpoints you wish to use excluding endpoint zero. For example, if you wish to use 4 endpoints and the control endpoint, this value is should be four.

Note: If you wish to implement a control-only interface then this value should be zero.
iClass is of type TUsbcClassInfo,

Sets the class type for this interface.
iFeatureWord is 32 flag bits used for specifying miscellaneous interface features.

See Allocate Resources for Endpoints.

Set the interface

To set the interface pass the initialised TUsbcScInterfaceInfoBuf to RDevUsbcScClient::SetInterface().

// Set up the interface. +r = gPort.SetInterface(0, ifc);

The interface number passed to SetInterface() along with TUsbcScInterfaceInfoBuf distinguishes between alternate interfaces. If alternate interfaces are not used then this value is always zero. When used, the value must be one greater than that of the proceeding alternate interface.

Note: The whole Setting interface descriptors section up to this point should be repeated for the number of alternative settings required.

Finalise the interface

RDevUsbcScClient::RealizeInterface() is called after SetInterface() has been called for all alternative settings.

On success, a chunk handle is created and passed back through aChunk.

RChunk gChunk; +r = gPort.RealizeInterface(gChunk);

If you are using the Buffer Interface Layer (BIL) then use FinalizeInterface() instead of RealizeInterface(). FinalizeInterface() has the same effect a calling RealizeInterface(), except that the BIL owns the RChunk handle. This function must be used if you want to use any other BIL method.

RChunk *tChunk = &gChunk; +gPort.FinalizeInterface(tChunk);

Note: Calling RealizeInterface() or FinalizeInterface() invalidates all further calls to SetInterface(). All alternative settings must have been initialised before calling these functions.

After you have set the interface descriptors you could optionally Allocate Resources for Endpoints or go straight to Re-Enumerate.

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-5FB6BEFD-579B-4139-B54D-9CDCF2198A14.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-5FB6BEFD-579B-4139-B54D-9CDCF2198A14.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,13 @@ + + + + + +Interrupt ImplementationDescribes the implementation of the Interrupt platform +service. \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-5FDAF564-6BE1-544A-B5C0-E0D6E25D82E7-master.png Binary file Adaptation/GUID-5FDAF564-6BE1-544A-B5C0-E0D6E25D82E7-master.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-5FDAF564-6BE1-544A-B5C0-E0D6E25D82E7_d0e15107_href.png Binary file Adaptation/GUID-5FDAF564-6BE1-544A-B5C0-E0D6E25D82E7_d0e15107_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-6060F138-CEB6-482A-B0E9-BBBE261568B0.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-6060F138-CEB6-482A-B0E9-BBBE261568B0.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,99 @@ + + + + + +Baseport Template OverviewThis section provides a summary of the Baseport Template +platform service. +

What +is the Baseport Template

The Baseport Template is a reference +board template, which provides a basic framework consisting of base +parts of the Symbian platform. This framework can be modified to suit +your hardware configurations.

The Baseport Template code is +categorized into Application Specific Standard Product (ASSP) layer +and variant layer. The ASSP layer provides the source code for hardware-specific +functions (for example, GPIO, DMA, IIC, USB Client Controller) that +are used by the kernel. This layer is implemented by the TemplateAssp class. The variant layer provides common peripheral +control functions such as power, bootstrap, keymap, keyboard and sound +that other extensions and device drivers can use. This layer is implemented +by the Template class.

ASSP and variant layers +provide control functions for hardware which is used by multiple devices. +This is done by placing Baseport Template code in a single DLL, called +the Variant DLL (ecust.dll). For hardware architectures +based on an ASSP, you can allow multiple phone types that use the +same ASSP to share the common code. To achieve this, implement the +common ASSP code in a kernel extension, and ecust.dll implements the code that is specific to each variant.

Purpose +of the Baseport Template

The Baseport Template is mostly +useful in creating a baseport and testing the software. The following +is a list of some of the key uses of the Baseport Template.

The Baseport Template is useful in handling:

data exchange between devices connected to the bus
data copy between memory locations or between memory location +and peripheral
communication interface between the microprocessor components
hardware events and registers
USB functions of the device
power resources
phone restart after a hardware reset
shared chunks of camera and sound physical device driver
CPU idle operations
HAL, interrupt and keyboard functions
data storage based on NOR type flash memory
variant specific initialization (not the same as ASSP specific +initialization).

Users +of Baseport TemplateThe Baseport Template documentation cover +users who:

manufacture devices and want to develop software and get an +early debug output.
develop baseport. See Base Porting Guide for base porting details

Baseport +Template details

The following table lists the Baseport +Template details:

+ + + +

DLL

Library

Description

+ + + + +

katemplate.dll

None

ASSP DLL. This DLL is made up of the following template +files and can be found under ...template\asspandvariant\template_assp\ directory:

template_assp.cpp
interrupts.cpp
assp.cpp
register.cpp
template_assp.cia
interrupts.cia
assp.cia

+ + +

ecust.dll

None

Variant DLL. This DLL is made up of the following template +files and can be found in ...template\asspandvariant\template_variant\ directory:

variant.cpp
variant.cia

+ + + +

+Base +Porting Guide +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-60949ACD-AAA9-540E-85AE-BB173382D548-master.png Binary file Adaptation/GUID-60949ACD-AAA9-540E-85AE-BB173382D548-master.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-60949ACD-AAA9-540E-85AE-BB173382D548_d0e13468_href.png Binary file Adaptation/GUID-60949ACD-AAA9-540E-85AE-BB173382D548_d0e13468_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-610E0C09-F014-4DA2-8411-D7A0CDAF5BBB-master.png Binary file Adaptation/GUID-610E0C09-F014-4DA2-8411-D7A0CDAF5BBB-master.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-610E0C09-F014-4DA2-8411-D7A0CDAF5BBB_d0e90471_href.png Binary file Adaptation/GUID-610E0C09-F014-4DA2-8411-D7A0CDAF5BBB_d0e90471_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-6114133F-E738-4DF1-8308-B09C02B9CEEA.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-6114133F-E738-4DF1-8308-B09C02B9CEEA.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,279 @@ + + + + + +DMAv2 Interface OverviewDescribes the interfaces provided by the DMAv2 platform +service. +

Client +functions

The clients that require to use the DMA framework +functionality use the DDmaRequest class functions +to request DMA transfers. The clients should not set any parameters +directly but use functions of the DDmaRequest class.

+ + + +API +Description + + + + +DDmaRequest::DDmaRequest(TDmaChannel& aChannel, +TCallback, TAny*, TInt) +The constructor for the DDmaRequest class. + + +DDmaRequest::Fragment(const TDmaTransferArgs& +aTransferArgs) +Split request into a list of fragments small enough to be fed +to the DMA Controller. The size of the fragment should be less than +or equal to the maximum transfer size supported by the DMA controller. + + +DDmaRequest::Queue() +Asynchronous transfer request. + + +DDmaRequest::ExpandDesList(TInt) +Add new descriptors to the existing list. The function is to +be used by the clients that require to build a custom descriptor list. + + +DDmaRequest::ExpandSrcDesList(TInt) +Add new descriptors to the existing source port descriptor +list. + + +DDmaRequest::ExpandDstDesList(TInt) +Add new descriptors to the existing destination port descriptor +list. + + +DDmaRequest::FreeDesList() +Free resources associated with this request. + + +DDmaRequest::FreeSrcDesList() +Free resources associated with this request from the source +port descriptor chain. + + +DDmaRequest::FreeDstDesList() +Free resources associated with this request from the destination +port descriptor chain. + + +DDmaRequest::EnableSrcElementCounting(TBool) +Enables the functionality for counting the transferred source +elements. + + +DDmaRequest::EnableDstElementCounting(TBool) +Enables the functionality for counting the transferred destination +elements. + + +DDmaRequest::DisableSrcElementCounting() +Disables the functionality for counting the transferred source +elements. + + +DDmaRequest::DisableDstElementCounting() +Disables the functionality for counting the transferred destination +elements. + + +DDmaRequest::TotalNumSrcElementsTransferred() +Get the number of transferred elements at the source port. +This function can only be used if the counting is enabled. + + +DDmaRequest::TotalNumDstElementsTransferred() +Get the number of transferred elements at the destination port. +This function can only be used if the counting is enabled. + + +DDmaRequest::FragmentCount() +Returns the number of fragments that are created by this transfer +request. + + +DDmaRequest::SrcFragmentCount() +Returns the number of source port fragments that are created +by this transfer request. + + +DDmaRequest::DstFragmentCount() +Returns the number of destination port fragments that are created +by this transfer request. + + +TDmaChannel::Open(const SCreateInfo& aInfo, TDmaChannel*& +aChannel) +Open a specified channel. + + +TDmaChannel::Close() +Close a previously opened channel. + + +TDmaChannel::LinkToChannel(TDmaChannel* aChannel) +Logically link a channel with the specified argument. When +the argument is NULL the channel is unlinked. + + +TDmaChannel::Pause() +Pause an active transfer. + + +TDmaChannel::Resume() +Resume transfer on this channel. + + +TDmaChannel::CancelAll() +Cancel current and all pending requests. + + +TDmaChannel::MaxTransferLength(TUint aSrcFlags, TUint +aDstFlags, TUint32 aPslInfo) +Get the maximum transfer length of the current channel. + + +TDmaChannel::AddressAlignMask(TUint aTargetFlags, +TUint aElementSize, TUint32 aPslInfo) +Get the address or memory alignment mask. + + +TDmaChannel::DmacCaps() +Get the reference to the structure that contains the features +and the capabilities of the DMAC associated with the current channel. + + +TDmaChannel::IsrRedoRequest(TUint32 aSrcAddr=KPhysAddrInvalid, +TUint32 aDstAddr=KPhysAddrInvalid, TUint aTransferCount=0, TUint32 +aPslRequestInfo=0, TBool aIsrCb=ETrue) +Repeat the current transfer request with modified parameters. + + +TDmaChannel::IsQueueEmpty() +Check if the current transfer queue is empty. + + +TDmaChannel::PslId() +Get the PSL specific ID of the current channel. This function +is used for debugging by the PIL. + + +TDmaChannel::FailNext(TInt) +Force to fail the next transfer request. This function is for +testing purpose only. + + +TDmaChannel::MissNextInterrupts(TInt) +Force the DMAC to miss one or more interrupts. + + +TDmaChannel::Extension(TInt aCmd, TAny* aArg) +Allows PSL to extend the DMA API with a channel specific functionality. + + +TDmaChannel::StaticExtension(TInt aCmd, TAny* aArg) +Allows PSL to extend the DMA API with a channel independent +functionality. + + + +

DMA +controller implementationThe TDmac class +provides the functions of a DMA controller: + + + +API +Description + + + + +TDmac::Transfer(const TDmaChannel& aChannel, const +SDmaDesHdr& aHdr) +Initiate a transfer request on a specified channel. + + +TDmac::StopTransfer(const TDmaChannel& aChannel) +Stop a data transfer on a specified channel. + + +TDmac::IsIdle(const TDmaChannel& aChannel) +Get the state of a specified channel. + + +TDmac::Extension() +Implement a platform specific functionality per channel. + + + +

Channel +manager implementation

The DmaChannelMgr class provides functions to open and close the channels by the PIL. +Implement the following functions in the PSL:

+ + + +API +Description + + + + +DmaChannelMgr::Open(TUint32 aOpenId, TBool aDynChannel, +TUint aPriority) +Open a channel with a specified channel ID. + + +DmaChannelMgr::Close() +Close a channel. + + + +

DMA +channel implementation

The TDmaChannel class provides the functions to implement a DMA channel. There are +three types of DMA channels that be can be implemented as described +below.

+ + + +Class +Description + + + + +TDmaSbChannel +Class to implement a single buffer channel. + + +TDmaDbChannel +Class to implement a double buffer channel. + + +TDmaSgChannel +Class to implement a scatter-gather channel. + + +TDmaAsymSgChannel +Channel class for controllers using asymmetric descriptor lists. + + + +

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-616C3426-A8C4-5653-912D-7150944E5836.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-616C3426-A8C4-5653-912D-7150944E5836.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,95 @@ + + + + + +Keyword reference (G-O) +

This page lists the keywords starting from G to O.

heapmax heapmax = <hex-size>

rombuild only

Overrides the default maximum +heap size for the executable.

heapmin heapmin = <hex-size>

rombuild only

Overrides the default minimum +heap size for the executable.

hide[[HWVD]] hide[[HWVD]] = <existing-file>

rombuild and rofsbuild

Marks the existing file +as hidden. The file is still available to resolve DLL static links.

_HIDE__ECOM_PLUGIN _HIDE__ECOM_PLUGIN(<local build directory>, <rom binary directory>, <local epoc32\data\Z directory>, <rom resources directory>, <DLL filename>, <resource filename>)

BUILDROM only

Specifies an ECom plug-in, consisting +of an implementation DLL and an ECom registration resource file, to +be hidden in the ROM and in the SPI file.

Symbian platform +code does not use this keyword directly. Instead, it uses the macro HIDE_ECOM_PLUGIN defined in \epoc32\rom\include\header.iby. This macro allows the plug-in to be specified more briefly in the +following form:

HIDE_ECOM_PLUGIN(<DLL name>,<resource file name>)

For example:

HIDE_ECOM_PLUGIN(foo.dll,12345abc.rsc)

This feature allows BUILDROM to hide the ECom +plug-ins. In particular, BUILDROM hides the DLL associated +with the specified plug-in. The resource registration files that are +passed using the macro are marked as hidden in the SPI file should +you choose to generate one. BUILDROM implements this +feature using the spidatahide keyword.

As part of the ROM building process, +it is possible to add support for multiple languages. This affects +how ECom resource files are specified by BUILDROM:

If an SPI file +is being created, the HIDE_ECOM_PLUGIN lines are +processed at an intermediate BUILDROM stage to produce:
spidatahide=MULTI_LINGUIFY( EXT sourcename ) <spi-id> <target-spi-dir>
During the BUILDROM localisation stage, these +lines become:
spidatahide = <source-file> <spi-id> <target-spi-dir>
If an SPI file +is not being created, the HIDE_COM_PLUGIN lines are +processed at an intermediate BUILDROM stage to produce:
hide=MULTI_LINGUIFY(EXT sourcename)
During the BUILDROM localisation stage, these +lines become:
hide=sourcename.EXT for the default extension +hide=sourcename.Enn for all the language codes nn

hcrdata

hcrdata = <hcrdata>

Specifies +the location of an HCR data file which is included in +the SMR partition image.

imagename

imagename = <imagename>

Creates +an SMR partition image.

<section id="GUID-178037D5-6040-4767-A185-0BC91B084770"><title>keepIAT</title +><codeblock>keepIAT</codeblock>rombuild onlyRetains +old-style Import Address Table.</section>

kerneldataaddress kerneldataaddress = <hex-address>

rombuild only

Kernel data/bss chunk base virtual +address.

The recommended value is 0x64000000.

kernelconfig kernelconfig <bit-of-kervel-config> <on | off>

rombuild only

This keyword sets the specified bit +of the kernel configuration flag to ON or OFF. The value of <bit-of-kervel-config> must be between 0 and 31.

kernelheapmax kernelheapmax = <hex-size>

rombuild only

Maximum size of the Kernel's heap.

The Kernel heap grows in virtual address space until this value +is reached: It can then grow no further. The value is rounded up to +a multiple of the virtual address space mapped by a single page directory +entry - on ARM CPUs this is 1MB. Usually 1 page directory entry's +worth of RAM is specified. The default value is 0x100000; this is +used if none is supplied.

kernelheapmin kernelheapmin = <hex-size>

rombuild only

Minimum size of the Kernel heap, +allocated immediately when the Kernel boots. Specify either a minimal +value or a working set size based on envisaged use.

The recommended +value is 0x10000, and is the default value if none is explicitly supplied.

kernelromname kernelromname = <rom-file-name>

rombuild only

ROM image on which an extension +ROM is based. This keyword is only valid for extension ROMs

kerneltrace kernelTrace = <32 bit hex-number | decimal number> [<32 bit hex-number | decimal number>]{0,7}

rombuild only

Initial value for the kernel trace +mask. You can supply upto eight separate 32 bit masks in order to +enable higher trace flags. The bit values are defined in nk_trace.h, and only apply to a debug Kernel.

To define kernel trace in an .oby file is optional. +The default value is set as 0x80000000 if kernel +trace is not defined. This default value allows the kernel to raise +a panic when an error occurs during runtime. If an invalid value is +set, Buildrom removes the invalid value. For example, if kernel trace +has only 1 invalid bit mask value, Buildrom removes it and resets +the default value.

LANGUAGE_CODE LANGUAGE_CODE NN

BUILDROM only

Localisation support. Specifies +the Symbian 2-digit codes for languages to be supported in this ROM. +The keyword may be used as many times as necessary.

maxunpagedsize maxunpagedsize <maximum_size_of_unpaged_data>

rombuild only

Sets the maximum value for the +size of uncompressed unpaged data for which you can flash the image. +If the size of the unpaged data is greater than maximum_size_of_unpaged_data, a warning message is displayed.

memmodel memmodel = moving | direct | multiple <chunk size> <page size>

rombuild only

Specifies the memory model to +be used at runtime together with the chunk size and the page size.

multikernel multikernel

rombuild only

Specifies that the ROM image has +multiple kernel executables. These kernels are specified with multiple +primary keywords in the files-section.

Note that this keyword +is mutually exclusive with singlekernel keyword.

MULTI_LINGUIFY <xxx>=MULTI_LINGUIFY(EXT <sourcename> <destname>)

BUILDROM only

Localisation support. During the +localisation pass, the MULTI_LINGUIFY lines are expanded into one +line per language code.

For example, the line:

data=MULTI_LINGUIFY( EXT sourcename destname )

is expanded to the lines:

data=sourcename.Enn destname.EXT +data=sourcename.Enn destname.Enn

The first line is +for the default language code; the remaining lines are for all other +language codes.

This provides support for the BaflUtils::NearestLanguageFile() function, which performs a similar mapping from language codes to +filenames.

nowrapper nowrapper

rombuild only

Specifies that no ROM wrapper +is required.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-622D6337-E60A-5252-8B2B-BA8232927453-master.png Binary file Adaptation/GUID-622D6337-E60A-5252-8B2B-BA8232927453-master.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-622D6337-E60A-5252-8B2B-BA8232927453_d0e29152_href.png Binary file Adaptation/GUID-622D6337-E60A-5252-8B2B-BA8232927453_d0e29152_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-627FC480-AF4F-4B23-8671-6E0A0DABA0EF.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-627FC480-AF4F-4B23-8671-6E0A0DABA0EF.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,44 @@ + + + + + +Baseport Template Testing GuideExplains how to test the Baseport Template implementation. +

There is no conformance testing suite available for Baseport Template. +However, Kernel testing (E32) and File system testing (F32) tests +should be run with 100% pass rate for any successful baseport. The +E32 and F32 tests are written to test the generic base code using +very minimal hardware services. As a result, if the baseport cannot +pass the minimal requirements of the base code, it is unlikely that +it will be suitable for running a production device.

Baseport +Template tests

The Baseport Template is designed to boot +on any hardware. It should boot successfully, but clearly, the system +can do nothing more at this time. A successful boot shows that your +build environment has been set up correctly.

You can conduct +a series of tests to check if the template works correctly. To test +different functionality of the template, see:

DMA +Testing Overview for information on DMA testing.
SDIO +Implementation Testing Guide for information on SDIO testing.
Kernel +API Validity Checks for information on testing the Kernel APIs.
Performance +Logging for information on writing trace logs and testing the +performance.
Validation for information on how to test a USB port.
Testing +the PRM PSL for information on how to test the Power Resource +Manager (PRM).
Platform +Specific Layer Validation for information on how to test a +port of the MMC Controller.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-63456B20-3A61-554A-BBA4-C23B176E39A8.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,433 @@ + + + + + +Pre-Conditions +and Post-Conditions for Kernel APIsReference documentation for kernel side function APIs, specifies +a wide variety of pre-conditions and post-conditions. +

A pre-condition is +something that must be true before using the function.
A post-condition is +something that is true on return from the function.

Such conditions are expressed using a standard phrase, wherever possible, +and this section explains what those conditions mean.

Where more than one pre-condition is stated for a given function, then +you can assume that all pre-conditions apply. In this sense, there is an implied +AND relation between conditions. For example, in the description of the function DObject::AppendFullName(), +the following pre-conditions apply:

+No fast mutex can be held. +Call in a thread context. +

Both conditions must be true before calling the functions.

There are exceptions to this rule, where a precondition applies only if +some other factor is true. For example, in the description of the function DObject::TraceAppendName(), +you will find the following pre-conditions:

+Call either in a thread or an IDFC context, if aLock=TRUE +Call in any context, if aLock=FALSE. +

Clearly, only one pre-condition will apply, depending on the supplied value +of the aLock argument.

A few conditions are self-explanatory, and these are not included in these +lists.

NOTE that some familiarity with kernel side programming is assumed.

Pre-conditions
Post-conditions

Pre-conditions

This +describes the meaning of each precondition, and tries to provide insight as +to why it needs to be satisfied, and explains what you need to do to ensure +that the preconditions are met.

Calling thread must be in a critical section
Calling thread must not be in a critical section
Calling thread can either be in a critical section or not
No fast mutex can be held
Kernel must be locked
Kernel must be unlocked
Kernel can be locked or unlocked
Kernel must be locked, with lock count 1
Interrupts must be enabled
Interrupts must be disabled
Interrupts can either be enabled or disabled
System lock must be held
System lock must not be held
Call in a thread context
Call in an IDFC contex
Call either in a thread or an IDFC context
Call in any context
Do not call from an ISR
The calling thread must own the semaphore
The calling thread must not be explicitly suspended
The calling thread must hold the mutex
Call only from ISR, IDFC or thread with the kernel locked
Call only from IDFC or thread with the kernel locked
Do not call from thread with the kernel unlocked
Do not call from ISR or thread with the kernel unlocked
Thread must not already be exiting
Property has not been opened
Property has been opened
Must be called under an XTRAP harness or calling thread must not be in a +critical section
DObject::Lock fast mutex held
DCodeSeg::CodeSegLock mutex held
Any kind of lock can be held
Call only from Init1() in base port
The various parameters must be valid. The PIL or PSL will fault the kernel +if not
The request is not being transferred or pending
Wait on TimerMutex before calling this
Message must be in ACCEPTED state
Queue must not be in asynchronous receive mode
Container mutex must be held
Thread container mutex must be held
Process container mutex must be held

Calling thread must be in +a critical section

Critical sections are sections of code that +leave the kernel in a compromised state if they cannot complete. A thread +enters a critical section by calling NKern::ThreadEnterCS() and +leaves it by calling NKern::ThreadLeaveCS().

While +in a critical section, the thread cannot be suspended or killed. These actions +are deferred until the end of the critical section. If a thread takes an exception +while inside a critical section, this is treated as fatal to the system, and +cause a Kern::Fault().

The described function must +be in a critical section when called.

Calling thread must not +be in a critical section

Critical sections are sections of code +that leave the kernel in a compromised state if they cannot complete. A thread +enters a critical section by calling NKern::ThreadEnterCS() and +leaves it by calling NKern::ThreadLeaveCS().

There are some functions winthin +the system that must NOT be in a critical section when called. This +applies to the described functions.

Calling thread can either +be in a critical section or not

Critical sections are sections +of code that leave the kernel in a compromised state if they cannot complete. +A thread enters a critical section by calling NKern::ThreadEnterCS() and +leaves it by calling NKern::ThreadLeaveCS().

When this pre-condition applies +to the described function, it means that it does not matter whether the code +is in a critical section or not.

No fast mutex can be held

A +thread can hold no more than one fast mutex at any given time. The described +function uses a fast mutex, which means that on entry to the function, the +calling thread must not hold another one.

Kernel must be locked

Many +kernel side functions run with interrupts enabled, including code that manipulates +global structures, such as the thread ready list. To prevent such code from +being reentered and potentially corrupting the structure concerned, a lock +known as the kernel lock (sometimes referred to as the preemption lock) is +used.

Sections of code that need to be protected against rescheduling +call NKern::Lock(). Interrupt Service Routines (ISRs) can +still run but no other thread (or IDFC) can run until the kernel is unlocked +by a call to NKern::Unlock().

The pre-condition +means that the kernel lock must be set before calling the described function.

Kernel must be unlocked

The pre-condition +means that the kernel lock must NOT be set when the described function +is called.

Kernel can be locked or +unlocked

Many kernel side functions run with interrupts enabled, +including code that manipulates global structures, such as the thread ready +list. To prevent such code from being reentered and potentially corrupting +the structure concerned, a lock known as the kernel lock (sometimes referred +to as the preemption lock) is used.

Sections of code that need to +be protected against rescheduling call NKern::Lock(). Interrupt +Service Routines (ISRs) can still run but no other thread (or IDFC) can run +until the kernel is unlocked by a call to NKern::Unlock().

The +pre-condition means that it does not matter whether the kernel lock is set +or unset when the described function is called.

Kernel must be locked, with +lock count 1

In +addition, calls to NKern::Lock() and NKern::Unlock() are +counted. The count value is zero when the kernel is unlocked; a call to NKern::Lock() adds +one to the count value, and a call to NKern::Unlock() subtracts +one from the count value.

The pre-condition means that there must +be exactly one call to Kern::Lock() that has not yet had +a matching call to Kern::Unlock().

See also:

DPhysicalDevice::Validate()
Kern::QueryVersionSupported()

Create()

Create() creates +and returns a pointer to the physical channel object through the DBase *& +type argument. In the case of serial device drivers, a physical channel is +an instance of a class derived from DComm, which is itself +derived from DBase.

Implementing this function +may involve:

setting up any port +related hardware; for example, defining GPIO pins as UART port I/O
initialising the UART +device itself; for example, enabling UART clock sources
binding any interrupt +resources to the UART Interrupt Service Routine (ISR).

The function sets a reference argument to point to the newly instantiated +physical channel object, but returns an error code if object allocation or +initialisation fails, i.e. the call to the physical channel object’s DoCreate() function +fails. Error codes are returned to the caller.

This code is typical, +and can be copied from any current source.

TInt DDriverComm::Create(DBase*& aChannel, TInt aUnit, const TDesC8* anInfo, const TVersion& aVer) + { + DCommXXX* pD=new DCommXXX; + aChannel=pD; + TInt r=KErrNoMemory; + if (pD) + r=pD->DoCreate(aUnit,anInfo); + return r; + } +

where DCommXXX is a DComm derived +class.

Customisation depends on the functions in the DCommXXX::DoCreate() function.

+Interrupt +Dispatcher Tutorial +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,609 @@ + + + + + +Power +Resource Manager (PRM)Describes the Power Resource Manager. +

Introduction
Concepts
User-side
Kernel-side

Introduction

The +Power Resource Manager (PRM) integrates the Symbian device driver with existing +power control and functions used for resource state changing and querying. +It defines an exported API that device drivers and other users of power resources +(represented by kernel-side components) can use to control the state of power +resources. The PRM assists the development of device drivers by removing the +need to understand the complexities of platform specific power resource management +by providing a simple to use generic framework.

The PRM also allows +user-side clients to gain access to the services. Clients of the PRM can:

request information +on the clients and resources registered with PRM
get the current state +of the resources
request changes to the +state of power resources
request notification +of changes (i.e. power-down or change clock frequency) to the power resources +that they depend on.

The following diagram shows the generic and customisable parts of +the framework:

exported kernel level +API (PowerResourceManager)
base virtual class for +Power Resource Controller (DPowerResourceController)
PDD required for user-side +proxy client
platform specific implementation +of resource control at the level of register interface to hardware resource +controller (DXXXPowerResourceController)

+ +

Concepts

Power resources
Clients

Power resources

A +power resource is anything that has an effect on power consumption. These +are typically platform specific and either physical or logical. Physical power +resources are provided by hardware: for example, clocks, outputs from voltage +regulators, switched power domains and performance levels. Logical power resources +do not directly map to hardware components, but their state has an effect +on overall power consumption. In this category we include, for example, shared +buses and devices that provide services to other components.

Power +resources can be further categorised based on:

Number of clients

A power resource can have a single user or it can +be shared. There is no limit to the number of clients sharing a resource. +If the resource is shared, then a request system is used. This comprises a +list of client +level objects, one for each client requesting a level on the resource. +The resource level is determined by a set of rules which govern whether a +request is accepted or declined.
States

The resource +state may be binary, multi-level or multi-property. A binary state +is either On or Off and a multi-level state can change either discretely or +continuously between a minimum (which could be Off) and a maximum value (which +could be fully On).

A multi-property resource has different properties +across different portions of the operating curve. For example, the level may +be controllable within the ‘operational’ part of that curve but have different +discrete fixed states for the ‘idle’ or ‘sleep’ modes of operation.
Execution time

The +execution time of a resource can be either instantaneous or long latency. +An instantaneous resource can be operated almost immediately (no longer than +a few system clock cycles, comparable to a CPU instruction execution time). +Operations on long latency resources take a significant time to complete (a +non-negligible amount of CPU clock cycles).

Power resources may be +long latency for state change operations and instantaneous for obtaining the +current state. This is typically the case of a PLL (Phase Locked Loop) device +(definition +from Wikipedia), which requires time to stabilise after a frequency +change is initiated but whose current output frequency can be read from a +register. Note: instantaneous operations may pre-empt operations on +long latency resources, and requests to get the state of a shared resource +may be issued while a state change is underway. If the read operation is instantaneous +and the change is long latency, care must be taken (at the PSL level) to not +return inconsistent values.

Other power resources may be long latency +on both state change and state read operations. This is typically the case +for any resources accessed through an inter-IC bus (even if their operation +is instantaneous).
Resource sense

Each +client sharing a resource may have a different requirement on its state. The +resource sense is used to determine whose requirement prevails.
+ + + +
Positive sense
+
Can have their value increased without affecting their sharers.

The +level is set to the highest level that is requested. The highest requirement +for binary resources is the On state.
+ + +
Negative sense
+
Can have their value decreased without affecting their sharers.

The +level is set to the lowest level that is requested. The lowest requirement +for binary resources is the Off state.
+ + +
Custom sense
+
May be increased or decreased freely by some privileged sharers +but not by others, which are bound by the requirement of the privileged sharers.

The +decision to change the prevailing level (or binary state) depends on the privileges +of the client and past usage of the resource. This decision is made by the +PSL custom +function implementation.
+ + + +
Static or Dynamic

Most +power resources are known at device creation time, so their control should +be addressed by such components as the Variant or ASSP. These resources are +registered during the creation of the Resource Controller; these are static +resources. Resources controlled by device drivers (internal or external) are +only registered at driver-creation time using the registration and deregistration +API provided by the PRM; these are known as dynamic resources.

Note: +Dynamic resources are only available when you use the extended library. See setup +and configuration.

Physical resources may belong to one or more of these categories, +for example, a multilevel resource may be shared between different clients +and take a significant time to change state (long latency).

External +devices may include and control their own power resources. In some cases, +an external device can function as a bus expander, allowing other devices +to be connected, and eventually share the power resources it controls.

Caching the prevailing level

The +PRM caches the prevailing level of each resource as well as the client that +requested it. The cached state is guaranteed to be the state that the resource +was in when the last request to change or read the state from its hardware +was issued.

On resource state read operations, the PRM allows clients +to select the cached state instead of the current state of the hardware resource. +A cached state read is always an instantaneous operation executed in the context +of the calling client thread (even for long latency resources).

However, +care must be taken as the cached state may not be the state the resource is +at that moment. For example, a resource can be non-sticky: when it is turned +on it stays on during an operation but then automatically switches itself +off.

The consistency of the cached state relies on all resource state +operations being requested through the Power +Resource Controller.

Dynamic +resources

A generic layer provides basic functionality for static +resources an extended version of the PRM provides APIs for dynamic resources +and resource dependencies. These dynamic resource and resource dependent APIs +are only available through the extended library resmanextended.lib.

A +dynamic resource is registered with the PRM using PowerResourceManager::RegisterDynamicResource(). +This function is also used to register a dynamic resource that supports dependencies +between resources.

TInt RegisterDynamicResource(TUint aClientId, DDynamicPowerResource* aResource, TUint& aResourceId)

Pass the ID of the client that requests the dynamic resource and the +dynamic resource (DDynamicPowerResource) to register. The +PRM sets aResourceId to the resource ID of this resource. +Dynamic resources that support dependencies are derived from the class DDynamicPowerResourceD.

Deregistering a dynamic resource

Use PowerResourceManager::DeRegisterDynamicResource() to +deregister a dynamic resource from the PRM. You can also use the function +to deregister a dynamic resource that supports a dependency.

TInt DeRegisterDynamicResource(TUint aClientId, TUint aResourceId, TInt* aState)

aState is a pointer to the final state that the resource is set +to before deregistration if this value is NULL the state of the resource is +changed to its default.

Changing resource state on a dynamic resource

Because a dynamic +resource can deregister from the PRM it is necessary to indicate to clients +that this has happened. Any remaining notification requests are completed +with a -2 in the client field of the callback function. This indicates that +this notification is because the resource has been deregistered and not because +the notification conditions have been met. When a client recieves a notification +of this type the request notification should be cancelled using CancelNotification().

Resource dependencies

A +resource may register a dependency on another resource. At least one of the +resources must be a dynamic resource. Request a dependency between resources +with PowerResourceManager::RegisterResourceDependency().

TInt RegisterResourceDependency(TUint aClientId, SResourceDependencyInfo* aResDependecyInfo1, SResourceDependencyInfo* aResDependencyInfo2)

This function is passed the ID of the client that sets the resource dependency +and the dependency information of the resource (SResourceDependencyInfo). SResourceDependencyInfo contains +the resource ID and the priority of the dependency.

The kernel will +panic if a closed loop dependency is found for the specified dependency or +if a resource with same dependency priority is already registered.

Use GetNumDependentsForResource() to +retrieve the number of resources that depend on the specified resource directly +and GetDependentsIdForResource() to return the IDs of all +the dependent resources.

Deregistering +resource dependencies

Use PowerResourceManager::DeRegisterResourceDependency() to +remove a dependency. This function takes the ID of the client that requests +the deregistration of the resource dependency and the IDs of the linked resources.

TInt DeRegisterResourceDependency(TUint aClientId, TUint aResourceId1, TUint aResourceId2)

Note: These functions are only available when you use the extended +library.

Changing +resource state on a dependent resource

A resource state can change +when the state of any of its dependent resources changes. A state change causes +a notification if the requested conditions are met. The client ID in the callback +function is updated with the ID of the resource that triggered this resource +change (bit 16 of the ID is set for dependency resource; this is used to distinguish +between a resource ID and a client ID).

Clients

The +PRM has both user and kernel-side clients. Kernel-side clients are:

device drivers
performance scaling +and/or performance monitoring and prediction components

User-side clients are:

user-side system-wide +power management framework
other power-aware servers +and power-aware applications

Clients register with the PRM by name. Clients can request to allocate +and reserve client level objects and request message objects after registering +with PRM.

Client level objects

Client +level objects represent a client requesting a level on a resource. They are +used by resources to set the current level of the resource and the current +owner of the resource level.

Each resource has a doubly linked list +on which client level objects are held. When a client requests a level for +the first time, a new client level object is added to the list; however, if +the client already has an object on the list, this object is adjusted to reflect +the change in the required level.

The following rules determine whether +the change is allowed on positive and negative sense resources:

If the requested change +is in the direction permitted by the resource sense and would result in exceeding +the prevailing level, the change is allowed.

The new prevailing level +is recorded, and the previous prevailing level and the requirements other +clients have on the resource remain on record.
If the requested change +is not in the direction permitted by the resource sense, but the client requesting +the change is the owner of the prevailing level, the resource state changes +up to next highest for a positive sense resource, or lowest for a negative +sense resource.

This value is now the prevailing level and the client +that requested it remains the owner of the prevailing level.
If the requested change +is not in the direction permitted by the resource sense, and the client requesting +the change is not the owner of the prevailing level, the change is not allowed.

Even +though the request was rejected, the client's existing requirement is adjusted +to reflect the request.

Prevailing levels are recorded by either adjusting the previous requirement +for the client that requested it or, if it is the first time this client requests +a level, a new requirement is created.

Notifications

A +client may request a state change notification from a resource. Notifications +can be conditional or unconditional; conditional notifications specify a threshold +on the resources state, which when crossed in the direction specified, triggers +the notification.

Notifications are always issued post resource change +and invoke callback functions executed in the context of the requesting client +thread. The process of notifying a client involves queuing a DFC in that clients' +thread. The notification object encapsulating the DFC must be created in kernel +heap and passed to the notification API by the client that requested the notification. +The client may share the same callback function between several notifications, +but a unique DFC must be created and queued per notification.

Because +notifications result in DFCs being queued, it is not possible to guarantee +that all changes of resource state are notified. If the resource state changes +again before the first DFC runs, a separate notification cannot be generated. +It is also not possible to guarantee that by the time the notification callback +runs, the resource state is still the same as the state that caused the notification +to be issued: it is the responsibility of the driver to read the resource +state after receiving a notification.

User-side

Introduction
Initialisation
Getting power resource information
Requesting notifications
Changing the state of power resources

Introduction

The RBusDevResManUs user-side +API makes relevant PRM functionality available to user-side applications that +have power-aware features.

RBusDevResManUs is derived +from RBusLogicalChannel, the user-side handle to a logical +channel base class, and presents the user-side interface to a kernel-side +LDD. The LDD is built as resman.ldd.

The API +enables concurrent access by multiple clients, with one channel supported +for each. Sharing of channels between threads is not supported.

To +open a channel on the user-side API a client must exhibit the PlatSec capability PowerMgt.

If a client wishes to access information +on kernel-side clients of the Resource Controller, it must also exhibit the ReadDeviceData capability.

Initialisation

Clients +do not need to explicitly load the kernel-side LDD, as this is a kernel extension +and so is loaded and initialised during kernel initialisation (attempts to +re-load it returns the error code KErrAlreadyExists but initialistation +otherwise appears successful).

Clients open a channel on the LDD by +calling the RBusDevResManUs::Open() method. The client +passes a name to the method - ideally, this is the client’s component name. +It is the client’s responsibility to ensure the name is unique even if multiple +channels are opened.

The client then needs to call the Initialise() method +specifying the number of request objects required. The numbers passed to Initialise() determine +the extent of memory allocation required (in part by the LDD and in addition +by request to the Resource Controller) and also the maximum number of concurrent +client requests supported.

The number of request objects created at +initialisation should be the maximum number of concurrent (asynchronous) requests +that the client expects to have outstanding at any time.

Getting power resource information

RBusDevResManUs::GetResourceInfo() is a method to retrieve the information for a specified resource, which +it returns in a TResourceInfo object. There is also a method +to get all the information for all the resources (GetAllResourcesInfo()). +This function requires the allocation of buffer memory in which the information +for all the resources is returned. GetNoOfResources() returns +the total number of resources available for access.

The example below +shows these functions in use. The amount of resources available are returned +by GetNoOfResources. This figure is used to calculate the +size of the buffer that is populated with the resource information by the GetAllResourcesInfo method.

TInt r = KErrNone; + TUint numResources=0; + if((r=gChannel.GetNoOfResources(numResources))!=KErrNone) + { + // Failed + return r; + } + + RBuf buffer; + if((buffer.Create(numResources*sizeof(TResourceInfo)))!=KErrNone) + { + // Failed + return KErrGeneral; + } + + buffer.SetLength(numResources*sizeof(TResourceInfo)); + + if((r=gChannel.GetAllResourcesInfo(buffer,numResources))!=KErrNone) + { + // Failed + return r; + }

Get the current resource state with GetResourceState(). +Passing ETrue results in the cached state being read rather +than the current hardware state. The cached state is guaranteed to be the +state that the resource was in when it was last changed or read from hardware. +This is why it is important that all change requests are carried out through +the Resource Controller. readValue returns the current prevailing +level and levelOwnerId the ID of the client that owns the +prevailing level. GetResourceState() can be cancelled using CancelGetResourceState() passing +the resource ID of the resource that the original request was on. Use the +method GetResourceIdByName() to get the ID of a resource +from the resource's name.

// Get initial state +TRequestStatus status; +TBool cached = EFalse; +TInt readValue; +TInt levelOwnerId = 0; + +gChannel.GetResourceState(status, gSharedResource, cached, &readValue, &levelOwnerId); +User::WaitForRequest(status);

GetNumClientsUsingResource() and GetNumResourcesInUseByClient() are used to retrieve the numbers of clients using a resource and the number +of resources in use by a client, respectively. GetInfoOnClientsUsingResource() and GetInfoOnResourcesInUseByClient() complement the last two methods by retrieving the resource information for +each resource that is in use by a specified client or retrieving the client +information for each client using the specified resource.

The API +supports receiving a number of concurrent (asynchronous) requests from a client; +the maximum number is determined by the number of resources that were specified +at initialisation. If a client issues a request that exceeds its allocation, +the error code KErrUnderflow is returned.

Some synchronous +methods take a binary value, aIncludeKern, which defaults +to EFalse. If this parameter is set to ETrue, +the API attempts to return information that includes kernel-side clients.

Requesting notifications

Clients +can request to be notified when a resource changes its state using the RBusDevResManUs::RequestNotification() method. +Clients can also request to be notified when a resource reaches a specified +threshold in a specified direction (positive or negative resource sense) using the same method but also passing it threshold +and direction values.

To cancel a notification, use CancelNotification() passing +the resource ID from which the notification was requested. Note: Any +notifications issued by a client must be cancelled before the client deregisters.

It +is not guaranteed that all changes of resource state result in a notification +– a resource may change state more than once before a notification request +is completed. In addition, it is not guaranteed that a resource is in the +same state as it was when the notification was generated. For these reasons, +it is the responsibility of the user-side client to read the state of a resource +after receiving a notification.

Changing the state of power +resources

To change a resource state call the asynchronous ChangeResourceState() method +passing the ID of the resource on which the change is being requested and +the requested state.

CancelChangeResourceState() cancels +all the ChangeResourceState() outstanding requests from the +client on the specified power resource. For each outstanding request, the +request object is removed from the doubly linked list within the Resource +Controller and returned to the request object pool.

Kernel-side

The Power Resource Manager component is implemented +as a kernel extension. It has an exported public interface accessible to kernel-side +components. Kernel components link to the resource manager kernel extension +DLL (resman.lib). Extended features are compiled and +exported in an additional library (resmanextended.lib). +The export library is built from the generic layer.

To ease the development +of the PRM including the functionality provided by the generic layer and the +mandatory PSL implementation, the generic layer is compiled into a kernel +library (klib) (resmanpsl.lib for the basic version and resmanextendedpsl.lib for +the extended version) which is included by the PSL to produce the kernel extension.

Concepts
Registration and initialisation
Deregistration
Requesting power resource information
Changing the state of power resources
Requesting notifications

Concepts

Requests
Callbacks

Request messages

Request +message objects represent a request for an operation on a resource by a client. +For example a request to change a resource's level or notification if a resource's +level changes.

The client may attempt to increase its quota by requesting +the allocation of request messages, but this may fail with KErrNoMemory. +A long latency resource request on may fail with KErrUnderflow if +the number of request messages pre-allocated by the client has been exceeded +and no more messages are left in the free pool to satisfy the request.

The +pre-allocation and reservation of client +levels and request messages is synchronously serviced in the context +of the calling client, although this may result in memory allocation that +is not time bound.

See Pre-allocating +client level and request message objects for implementation guidelines.

Callbacks

A +callback object is a customised DFC that is used to signal the completion +of notifications and the PRM's asynchronous APIs. Use the class TPowerResourceCb to +create a resource callback object that encapsulates callback functions.

The +resource callback object is initialised with a callback function TPowerResourceCbFn, +a pointer to data passed to the callback function, the priority of the DFC +within the queue (0 to 7, where 7 is highest) and optionally, a pointer to +the DFC queue that this DFC should use.

inline TPowerResourceCb(TPowerResourceCbFn aFn, TAny* aPtr, TInt aPriority)

This one specifies the DFC queue:

inline TPowerResourceCb(TPowerResourceCbFn aFn, TAny* aPtr, TDfcQue* aQue, TInt aPriority)

The user specified callback function is invoked with five arguments:

the ID of the client +is:
- the client that issued +an asynchronous operation - if the callback function is called as a result +of an asynchronous resource state read operation
- the client that is currently +holding the resource - if the callback function is called as a result of an +asynchronous resource state change operation or resource state change notification.
- Note:
  - If -1 is passed as the +client ID this specifies that no client is currently holding the resource.
  - In the extended version +of PRM (see Dynamic and Dependant resources) if -2 is passed as the client +ID in the callback function it signifies that the dynamic resource is deregistering. +With dependency resources, the ID of the dependent resource is passed as the +client ID if the state of the resource (specified in aResourceId) +changes as a result of the dependant resources stage changing (whose ID is +specified in aClientId).
- issued an asynchronous +API (state read or change) which leads to the callback function being called
- requested the resource +state change that leads to queuing a notification, which then leads to the +callback function being called.
the resource ID - a +client may have multiple notifications pending on different resources and +a single callback function. The resource ID can be used to specify which resource +change is being notified
the level of the resource +when either:
- the callback is called +as a result of a notification of state change
- when the callback is +called as a result of a non-blocking form of PowerResourceManager::GetResourceState().
- the requested level +for the resource when the callback is called as a result of a non-blocking +form of PowerResourceManager::ChangeResourceState()
the ID of the resource +level owner
the error code returned +when the callback is called as a result of an asynchronous request to change +the state of the resource. This is not relevant when the callback is called +as a result of a notification of state change
a user defined argument +that is passed to the constructor.

Cancel an asynchronous request, or its callback, by calling CancelAsyncRequestCallback().

Registration and initialisation

Clients +need to register with the PRM using PowerResourceManager::RegisterClient() before +they can request operations on resources.

Registration happens at +different times for different clients:

kernel extensions register +from their entry point during kernel boot
device drivers for internal +or external devices register on opening a channel.

When a client registers with the PRM, a client link object is removed +from the free pool, populated with the relevant information, and a pointer +to it is added to a container of clients within the PRM. If no free link exists +within the pool, a number of client links are created in kernel heap. As a +result, client registration may fail in out of memory situations. Client links +are never destroyed after the client deregisters, but are released back into +the free pool.

Clients are registered by name; the PRM does not check +that a name is unique unless the DEBUG_VERSION macro is enabled. +The component registering the client should check that the name is unique. +The ID returned is a handle to the client link object that represents the +client in the PRM.

On registration, a client also specifies the type +of ownership (TOwnerType) that applies. This is either:

EOwnerThread - +the client ID is only used by the thread that registered the client to call +the PRM APIs
EOwnerProcess - +the client ID is used by all threads in the process to call the PRM APIs.

The default is EOwnerProcess.

Pre-allocating client level +and request message objects

The controller has an initial pool +of free client levels and request messages whose size can be configured at +build time by the PSL. After registering with the PRM, a client can request +the pre-allocation of a number of client levels and request messages to guarantee +deterministic behaviour (to avoid out of memory failure) of the resource state +change operation using PowerResourceManager::AllocReserve(). +This allocation remains reserved to the specified client until the client +is deregistered from the PRM. The number of client level objects reserved +by a client depends on the number of resources on which a resource state change +will be requested.

A client may issue more than one request, possibly +to the same resource, before the previous one completes, it is therefore more +difficult to determine how many objects to pre-allocate.

It is recommended +that as many request messages as asynchronous long latency resources the client +expects to use are pre-allocated. The free pool should be relied on for the +situations when a resource is requested more than once before the first request +completes.

Deregistration

All +notifications and asynchronous requests must be cancelled before the client +is deregistered, otherwise the kernel will panic. Use the PowerResourceManager::CancelNotification() and CancelAsyncRequestCallback() methods to cancel all pending notifications and asynchronous requests. Notifications +that have been registered with the Controller should be deregistered before +they are deleted as the Controller may attempt to issue them. Deleting a notification +that is still registered with the Controller results in the kernel panicking.

Client +level objects and request objects reserved by the client remain reserved +for that client until it deregisters. When the client is deregistering these +objects are moved to free pool by the PRM.

Client deregistration can +result in a resource state change:

If the resource is shared +and the deregistering client owned the prevailing level, the resource state +is moved to the next level according to its sense. If it is a custom sense +resource, the resource state is changed as a result of calling a custom function.
If the resource is not +shared or if it is shared but the client is the only one using it at the time +of deregistration, the resource is moved to the default state. The +default state is only known by the PSL.

A deregistering client can have a number of active requirements on +a number of resources and more than one of these resources may need to change +state as a result of the client deregistering. The combined operation of deregistering +the client and adjusting the state of all resources it shares executes synchronously. +That is, the client thread is blocked throughout whether the resources whose +state needs to change is instantaneous or long latency.

Getting power resource information

The +resource information can be retrieved using the method PowerResourceManager::GetResourceInfo(), +information can also be retrieved for all of the resources used by the specified +client using GetInfoOnResourcesInUseByClient(). This function +takes a buffer that must be the size of the information structure multipled +by the number of resources in use by the client, this figure can be retrieved +using the method GetNumResourcesInUseByClient(). Specify +the resource ID as zero to retrieve all information from all the clients registered +with PRM.

To get information about clients using a resource, use the +method GetInfoOnClientsUsingResource(). Use the number +of clients using a resource using GetNumClientsUsingResource(). +Specify the client ID as zero to retrieve all information from all the resources +registered with PRM.

Use PowerResourceManager::GetResourceState() to +retrieve resource state information. This function can be called synchronously +or asynchronously. Asynchronous calls require the client to create a callback +object in the kernel heap or data section. The synchronous GetResourceState() call.

TInt GetResourceState(TUint aClientId, TUint aResourceId, TBool aCached, TInt& aState, TInt& aLevelOwnerId);

The asynchronous GetResourceState() call.

TInt GetResourceState(TUint aClientId, TUint aResourceId, TBool aCached, TPowerResourceCb& aCb);

If executing asynchronously, the callback function encapsulated in the +callback object (called in the client’s context) is invoked when the state +of the resource is available. The third argument of the callback function +carries the resource state. If this function is called with aCached set +as ETrue, then the callback function is called in the context +of the calling thread both for instantaneous and long latency resources, thus +blocking the calling thread throughout.

For instantaneous resources, GetResourceState() executes +in the context of the calling thread and, if specified, the callback function +is called after getting the state of the requested resource. The calling thread +is blocked throughout.

GetResourceState() takes +a boolean value that determines from where the requested resource state information +is retrieved:

ETrue - the resource +state is the cached value, this value is returned faster but is not guaranteed +to be correct
EFalse - the resource +state is read from the resource, this value takes longer to return, but is +much more likely to be correct.

Changing the state of power +resources

The PowerResourceManager::ChangeResourceState() method +is used to request a change on a resource. When a state change is requested +on a shared resource, only the minimum state change that satisfies the request +is guaranteed.

TInt ChangeResourceState(TUint aClientId, TUint aResourceId, TInt aNewState, TPowerResourceCb* aCb=NULL);

The values passed to the method are:

the ID of the client +requesting the change
the ID of the resource +that the change is to take place
the new state of the +resource
a pointer to the resource +callback object.

The requested state is either a binary value for a binary resource, +an integer level for a multilevel resource or some platform specific token +for a multi-property resource. The pointer to the callback object is defined +by the class TPowerResourceCb; its use is optional and +is treated by synchronous and asynchronous resources as described below.

Changing resource state on a long latency resource

If the +callback object is specified, then ChangeResourceState() is +executed asynchronously and returns immediately. The actual resource change +happens in the resource controller thread and the callback function encapsulated +in the callback object is called after the resource is changed.

If +the callback object is NULL, then ChangeResourceState() executes +synchronously, meaning the client thread is blocked until the resource state +has changed. The PRM panics if the synchronous version of this API for long +latency resources is called from DFC thread 0.

Changing resource state on an instantaneous resource

On an +instantaneous resource ChangeResourceState() always executes +synchronously.

If a callback object is specified, then the callback +function encapsulated in the callback object is called from the client thread +after the resource change and before returning from the function.

Use CancelAsyncRequestCallBack() to +cancel change requests on a resource. When the client no longer requires a +level on a resource use the method DeRegisterClientLevelFromResource() to +remove a client level object from a resource.

Requesting notifications

Clients +can request notification of a state change on a resource. Notifications are +issued post resource change and invoke the callback function encapsulated +in a notification object. The callback is executed in the context of the requesting +client thread.

The parameters passed to PowerResourceManager::RequestNotification() are:

the ID of the client +requesting the notification
the ID of the resource +for which notification of state changes is being requested
a reference to a notification +object encapsulating a callback function called whenever a resource state +change takes place.

A notification may be unconditional or conditional. An unconditional +notification request notifies the client each time the state changes. A conditional +notification request notifies the client when a threshold has been met in +the direction specified. A conditional notification has these additional parameters:

aThreshold - the level +of the resource state that triggers the notification
aDirection - the direction +the resource state change that triggers a notification:
- EFalse - the resource +state is equal to or below the threshold
- ETrue - the resource +state is equal to or above the threshold.

The client must create the notification object (DPowerResourceNotification) +in the kernel heap or data section. Note: The client may share the +same callback function between several notifications but a unique DFC must +be created and queued for each notification.

Because notifications +result in DFCs being queued, it is not possible to guarantee that all resource +state changes are notified. If the resource state changes again, before the +first DFC runs, it does not generate a separate notification. It is also not +possible to guarantee that by the time the notification callback runs the +resource state is still the same state that caused the notification to be +issued. The client should read the resource state after receiving a notification.

Use CancelRequestNotification() to +cancel a notification request. It takes a reference to the notification object +associated with the original notification request that is being cancelled.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-6E208C69-AC2C-4A7A-8203-2C4C3F2E54F5.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-6E208C69-AC2C-4A7A-8203-2C4C3F2E54F5.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,60 @@ + + + + + +Binding +and UnbindingThis document describes how device drivers bind and unbind interrupts. +

To handle events, the interrupt source and the ISR have to be registered +with the OS: this is called binding the interrupt. An interrupt +has to be unbound when its use is complete.

Binding

An +interrupt source ID is bound with the driver's interrupt service routine. +This is done using the function Interrupt::Bind() in the second +stage constructor of the physical channel. Interrupt binding can fail +if the source has been already used or bound.

TInt DExUartPhysicalChannelH4::DoCreate(TInt aUnit, const TDesC8* aInfo, const TVersion& aVer) + { + ... + // Bind the interrupt service routine (ISR) to a specific + // interrupt ID. When the ISR is called, the value aPtr, + // (here this object) is passed as the argument. The ISR + // must be a static void function, taking a single TAny* + // parameter: void Isr(TAny* aParam). Interrupt::Enable() + // must be called to start receiving interrupts. Bind() + // returns KErrInUse if the ISR is already bound. + // + TInt r = Interrupt::Bind(iIrqId,UartIsr,this); + if (r!=KErrNone) + { + KDBG(Kern::Printf("DExUartPhysicalChannel::Interrupt Binding + for UART failed")); + return r; + } + + return KErrNone; + }

Unbinding

An +interrupt is unbound by calling Interrupt::UnBind(), which +de-registers the interrupt source and routine. This must be done before or +during physical channel destruction. Unbinding an interrupt does not disable +its source. Interrupts have to be disabled explicitly before unbinding to +avoid spurious interrupts.

/** + Physical channel destructor. Delete and free any objects created and + allocated by the physical channel. This is called by the + framework while unloading the driver (PDD). + */ +DExUartPhysicalChannelH4::~DExUartPhysicalChannelH4() + { + // Unbind the UART interrupt. Interrupt::Unbind() frees the + // interrupt service routine (ISR) function from the specified + // interrupt ID. + // + Interrupt::Unbind (iIrqId); + }

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-6E89E787-749D-5AC5-957D-967B4B9ACD74.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-6E89E787-749D-5AC5-957D-967B4B9ACD74.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,121 @@ + + + + + +Using +the BIL InterfaceThis tutorial describes how to use the Buffer Interface Layer (BIL) +to read and write shared chunks form the client driver. +

The BIL +is a thin layer over the LDD APIs that removes the need for the class driver +to handle buffers directly. The BIL is consistent between different class +drivers and reduces the buffer related understanding needed to use the USBSc +LDD.

Using the BIL is optional to the class driver, but very highly +recommended.

Before completing these steps you must have followed +the procedure from + the beginning of the tutorial set through to +RDevUsbcScClient::FinalizeInterface()

+ + Open each endpoint +object. + +Use the function RDevUsbcScClient::OpenEndpoint() for +each endpoint object. +TEndpointBuffer iEpBuf; +const TUint KWriteEp = 1; + +gPort.OpenEndpoint(iEpBuf, KWriteEp); + OpenEndpoint() fills the provided endpoint buffer +(iEpBuf) for use with the given endpoint number (KWriteEp). +This endpoint will be opened on the current alternate interface setting. + + + Reading with an OUT endpoint. +To read with an endpoint call TEndpointBuffer::GetBuffer() to +request data from the BIL. +r = iEpBuf.GetBuffer(scReadData, readSize, readZlp, aStatus); +The first parameter passed to GetBuffer() can be either +a pointer to the transfer buffer or the offset of the transfer data within +the shared chunk. +This function allows the BIL to expire any previously retrieved transfer +on this endpoint so that it can be used again for new transfers. If the transfer +or the LDD are not ready then aStatus is set to pending. +If no transfer is available then the variable passed in the first parameter +is set to NULL or 0 depending on the API. Call this function again on completion, +to wait for data again. +The function GetBuffer() returns: + + + + KErrCompletion if data could be retrieved without +a pending request, + + + KErrNone if an asynchronous request was queued. This +function should be called again on completion, + + + KErrEof if the end of the data in the endpoint has +been reached, + + + KErrNotSupported if the endpoint is an IN endpoint. + + +If the host has changed to an alternate setting and you wish to continue +reading and writing data then you must Close() all endpoints +and go to step five Process the next alternate set of endpoints. Otherwise, +if you have finished then go to step four Close each endpoint object. + + + Writing with an IN endpoint. +After filling a shared chunk buffer with some data call TEndpointBuffer::WriteBuffer() to +write the data to endpoint hardware. + WriteBuffer() transmits the provided buffer on the +given endpoint asynchronously. More than one request may be outstanding at +any time. This reduces the time between buffer transfers. +r = iEpBuf.WriteBuffer(buffer, length, ETrue, aStatus); +The first parameter passed to WriteBuffer() can be +either a pointer to the transfer buffer or the offset of the transfer data +within the shared chunk. +If the host has changed to an alternate setting and you wish to continue +reading and writing data then you must Close() all endpoints +and go to step five Process the next alternate set of endpoints. Otherwise, +if you have finished then go to step four Close each endpoint object. + + + Close each endpoint object. +Each endpoint object opened with OpenEndpoint() must +be closed with TEndpointBuffer::Close(). +iEpBuf.Close(); +If the host has changed to an alternate setting and you wish to continue +reading and writing data then you must Close() all endpoints +and go to step five Process the next alternate set of endpoints. Otherwise, +if you have finished data transfer then Close +and Unload the Driver. +If you wish to continue reading and writing data but on an alternate +setting then call RDevUsbcScClient::StartNextOutAlternateSetting(). +Otherwise if you have finished then Close and Unload the Driver. + + + Process the next alternate set of endpoints. +Use the function RDevUsbcScClient::StartNextOutAlternateSetting() to +switch to the next set of endpoints. The alternate interfaces were initialised +with SetInterface(). See Set +the Interface Descriptors. +TInt r = StartNextOutAlternateSetting(ETrue); +Pass ETrue to the function to purge the buffers of any data unread for +the previous setting. + Note: All open endpoints (except EP0) must be closed before this is +called. + + +

When you have finished reading and writing Close +and Unload the Driver.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-6EB38F10-849D-5763-96A0-A0A108982D67-master.png Binary file Adaptation/GUID-6EB38F10-849D-5763-96A0-A0A108982D67-master.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-6EB38F10-849D-5763-96A0-A0A108982D67_d0e63496_href.png Binary file Adaptation/GUID-6EB38F10-849D-5763-96A0-A0A108982D67_d0e63496_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-6EF762B8-DE93-51C0-8A5D-89FC5289B7D0.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-6EF762B8-DE93-51C0-8A5D-89FC5289B7D0.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,29 @@ + + + + + +MMP Tutorial This tutorial describes how to set the paging options for an individual executable.

The paging options are:

code paging
data paging
both code and data paging

Making executables (either exe or dll) paged is the finest level of control of paging at runtime. In the order of precedence for paging keywords, the values in this file will be overridden by those in the oby file.

The following keywords are used to indicate whether the executable is + unpaged or paged. If the executable is paged then the keywords indicate if code + paging, data paging or both are to be used.

Keyword

Behaviour on Symbion OS v9.6 and later

paged

Enables code and data paging

unpaged

Disables code and data paging

pagedcode

Enables code paging

unpagedcode

Disables code paging

pageddata

Enables data paging

unpageddata

Disables data paging

When using the above keywords, the following points must be considered.

The keywords pageddata and unpageddata do not make sense for files that are not executable binaries, and will be ignored.
The use of the paged, unpaged, pagedcode and unpagedcode keywords only states the default paging behaviour of the data that is to paged by the executable. The behaviour can be overridden by using the TChunkCreateInfo, RChunk and TChunkHeapCreateInfo API.
The keywords in the table above, should appear on a separate line on their own and with no arguments
If the build tools are configured to compress executables while building them (this is the default behaviour), then executables marked with paged or the pagedcode keyword will be implicitly byte-pair compressed.
If a ROM/ROFS partition defines a pagingoverride, codepagingoverride or datapagingoverride as defaultpaged or defaultunpaged, then the pagability specified in the mmp file will be implemented.
If a ROM/ROFS partition has defines pagingoverride, codepagingoverride or datapagingoverride as nopaging or alwayspage, then the pagability specified in the mmp file will be ignored.

Building the executable with the new keyword does not produce any errors or warnings.

mmp file example

Below is an example mmp file with paging:

TARGET dummy.dll +TARGETTYPE DLL + +UID 0x10003d3a +VENDORID 0x12345678 + +SOURCEPATH ../dummy +SOURCE dummy1.cpp dummy2.cpp + +SYSTEMINCLUDE /epoc32/include + +LIBRARY euser.lib + +CAPABILITY PowerMgmt ReadDeviceData WriteDeviceData LocalServices ReadUserData WriteUserData + +UNPAGED

The above mmp file, specifies that the dummy.dll file is not going to use demand paging.

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-6F82A35E-9F11-591D-AA5C-8F60734A2827.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-6F82A35E-9F11-591D-AA5C-8F60734A2827.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,16 @@ + + + + + +Demand Paging +Guides +

Contains guides that describe various aspects of demand paging in more +detail.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-70041B11-4C03-42C6-9EC2-307E5FF0F626.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-70041B11-4C03-42C6-9EC2-307E5FF0F626.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,165 @@ + + + + + +IIC Interface OverviewProvides a summary of IIC interface. +

The IIC platform service provides APIs for a master channel and +a slave channel. The PIL provides the generic platform independent +functionality.

+ Master channel

You must derive a +class from DIicBusChannelMaster and implement certain +pure virtual functions.

+ + + +API +Description + + + + +DIicBusChannelMaster::DoRequest(TIicBusTransaction* +aTransaction) +Gateway function for the PSL implementation. This function +allows the client to request a new channel. + + +DIicBusChannelMaster::DoCreate() +Second phase constructor to create a new channel. + + +DIicBusChannelMaster::HandleSlaveTimeout() +Function to be called in the event of slave time out. Implement +this function to stop the transmission, disable the hardware or call +PIL function CompleteRequest(). + + +DIicBusChannelMaster::CheckHdr() +Function to check if the header of the transaction is valid. + + + +

PIL +functions for master channelThe following functions can be +used by the platform specific implementation of the IIC platform services. + + + +API +Description + + + + + DIicBusChannelMaster::Init() +Initialise the child class DIicBusChannelMaster. + + +DIicBusChannelMaster::SetDfcQ() +To set the IIC driver's DFC queue to be used by the DFC of +PIL. + + +DIicBusChannelMaster::StartSlaveTimeOutTimer() +To start a timer to wait for the slave class functions, if +the time expires the HandleSlaveTimeout() call +up function is invoked by the clients. + + +DIicBusChannelMaster::CancelTimeOut() +To cancel the timer monitoring the transactions. + + +DIicBusChannelMaster::CompleteRequest() +To notify the PIL of a completed transaction + + + +

Slave +channelYou must derive a class from DIicBusChannelSlave and implement the following pure virtual functions: + + + +API +Description + + + + + DIicBusChannelSlave::DoRequest() +The gateway function to the SHAI implementation layer. + + + DIicBusChannelSlave::DoCreate() +The second phase constructor function to create a new channel. + + + DIicBusChannelSlave::ProcessData() + Called by the PIL in response to the DIicBusChannelSlave::NotifyClient() function. + + + DIicBusChannelSlave::ChechHdr() +The function to validate a configuration. + + + +

PIL +function for slave channelThe following are the generic functions +provided by the PIL of the IIC platform service: + + + +API +Description + + + + +DIicBusChannelSlave::DIicBusChannelSlave() +Constructor function for PIL. + + +DIicBusChannelSlave::Init() +Initialise the slave channel. + + +DIicBusChannelSlave::SetMasterWaitTime() +Set the timer to wait for the master channel to respond after +a transmission is started. + + +DIicBusChannelSlave::GetMasterWaitTime() +Get the current delay to wait for the master channel to respond +after a transmission is started. + + +DIicBusChannelSlave::SetClientWaitTime() +Set the timer of the client to respond for the next operation. + + +DIicBusChannelSlave::GetClientWaitTime() +Get the current delay of the client to respond for the next +operation. + + +DIicBusChannelSlave::NotifyClient() +Notify clients of the slave channel events. + + + +

The header file for the IIC can be found here

+IIC +Implementation Guide +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-71271D1C-C385-5687-8A90-46E8B590BB1E-master.png Binary file Adaptation/GUID-71271D1C-C385-5687-8A90-46E8B590BB1E-master.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-71271D1C-C385-5687-8A90-46E8B590BB1E_d0e1517_href.png Binary file Adaptation/GUID-71271D1C-C385-5687-8A90-46E8B590BB1E_d0e1517_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-73B853D5-13E6-54E7-AA8B-C41EEDB5EA7F.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-73B853D5-13E6-54E7-AA8B-C41EEDB5EA7F.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,32 @@ + + + + + + RMdaDevSound-Based +Driver MigrationExplains how to convert an RMdaDevSound -based +sound driver to the current Sound Driver architecture. +

Symbian converted the PDD of the RMdaDevSound based driver +to an RSoundSc version of the PDD. The same procedure was +used for this on all three platforms.

PDDs for the RMdaDevSound based driver have a significant +amount of code that is dedicated to creating and managing a circular buffer, DSoundBuffer, +for storing playback or record audio. In the RSoundSc version +of the driver, this is taken care of by the shared chunk and this code can +be discarded.

For the remaining PDD code, although the LDD to PDD interface for the RMdaDevSound based +version is similar to the RSoundSc version, it is best +to start by taking a copy of the template port as described in Set +Up , then fill in the sections marked TODO in the template code by +cutting and pasting the relevant code coming from a single function, this +is often called the same in each version of the driver.

One complication comes if the RSoundSc version is to +support both record and playback driver channels, as this requires some of +the functionality to be moved to the shared PDD factory object.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-73D9E2F2-5965-479E-97DB-C3773DA0D90C.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-73D9E2F2-5965-479E-97DB-C3773DA0D90C.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,39 @@ + + + + + +Device Driver Quick StartA quick introduction to the device driver documentation. +

Device drivers provide a mechanism for applications and other operating +system functions to access hardware devices without needing to know +how each specific piece of hardware works. In addition device drivers +may be written so that part of the device driver is user-side space +and the rest is kernel-side so that the device driver can access shared +memory and resources that belong to the Kernel.

Who +this documentation is for

There are two main sets of users +for device drivers:

Application developers that want to use device drivers
Developers that need to create or amend device drivers.

This documentation set is aimed at the second category +of users. If you are an application developer and want to use a particular +device driver, then you should search for, and read the documentation +for that specific device driver.

Device driver framework

The device driver guide explains +the concepts of device driver framework and how to implement a device +driver.

For the basic concepts of device driver, see Device Driver Concepts
To write a device driver, see Device Driver Writing +Guide
To use the kernel services in a device driver, see Kernel-Side Services
To debug your device driver implementation, see Debug Monitor Tool
It is important to understand how memory is paged in the system, +so you should also read Demand Paging.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-73F220EA-F41F-56A5-BAEB-4A37174CFD1F.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-73F220EA-F41F-56A5-BAEB-4A37174CFD1F.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,117 @@ + + + + + +Power +ManagementDescribes the power management policies. +

The MMC Controller manages the power to the MultiMediaCard hardware.

Normal power +up and power down handling

Before card commands can be issued to +a card, three operations are required:

power must be applied +to the card, i.e. VDD must be turned on
any requirement from +the power model must be set, e.g. requesting a necessary system clock
the clock to the card +interface must be switched on.

All three operations are performed as part of the DMMCStack::CIMInitStackSM() state +machine function which then issues the sequence of commands involved in performing +the CIM_UPDATE_ACQ macro to initialize a card stack.

There +are two cases:

Local drive requests, +i.e. those originating from a media driver - if the card is not fully powered +up when such a request is received, then the local media device driver automatically +precedes the request with an instruction to the controller to power up the +card. This results in DMMCSocket::InitiatePowerUpSequence() being +called, which in turn invokes the DMMCStack::CIMInitStackSM() state +machine function.

Once the MultiMediaCard stack has been initialized, +the MultiMediaCard controller calls DPBusSocket::PowerUpSequenceComplete() to +signal the completion of initialization back to the local media driver, and +this can then continue to open a media driver and continue with the original +request.

This automatic re-powering of the card applies in all situations +which can lead to the card not being powered: media change, machine power +down, card inactivity timeout, VDD power problem etc. In most cases, the process +of restoring power results in the closure of any existing media driver and +a new one opened. As the kernel thread used to perform controller requests +is able to block, this means that no special mechanism is necessary to allow +for this potential long-running power up sequence prior to a request on the +device.
Requests not originating +via a local media device driver, for example device drivers for I/O cards +- if the MultiMediaCard stack is not initialized when the client submits a +session, then the MultiMediaCard controller automatically precedes the request +with a call to the DMMCStack::CIMInitStackSM() state machine +function.

The MultiMediaCard controller will normally be configured with an +inactivity timer. If a given period elapses where there is no bus activity, +then the controller automatically turns off the card clock, removes any power +requirements on the power model, and then removes power from the cards. This +is the bus power down sequence. The length of this inactivity timeout period +is set in the platform specific layer as part of porting the controller, and +can be disabled completely if required; see the reference to porting the PsuInfo() function +as part of implementing the DMMCPsu +derived class.

Clients of the controller do not need to worry +about re-initializing the stack following such a power down as the controller +does this automatically.

In the event of a PSU voltage check failure, +the controller performs the bus power down sequence. It will not re-power +the problem card and will expect it to be removed.

The power model +calls DPBusSocket::DoPowerDown() when the machine is about +to be normally turned off (due to the off key being pressed or keyboard/touch +screen inactivity). This leads to the function DMMCStack::PowerDownStack() being +called resulting in the bus power down sequence.

When the machine +is powered back up after a normal power off, the power model calls DPBusSocket::DoPowerUp(). +However, the controller normally does not power up the bus, but waits for +the next request from one of its clients before doing so. The only exception +is where a card power up sequence was interrupted by the machine being turned +off.

Emergency +power down

In an emergency power down situation, for example, where +a battery is in a critically low power state, the MultiMediaCard controller +performs the normal bus power down sequence as this is not a lengthy operation. +The power model calls DPBusSocket::DoEmergencyPowerDown(), +which results in a call to DMMCStack::PowerDownStack().

However, +there is always a risk that a block being written to a card may become corrupt. +The solution to this problem lies in the hardware architecture. Two possible +solutions are:

to provide enough early +warning of power being removed before the battery level becomes too low for +card operation. For example, a catch mechanism on a battery door, making it +slow to remove. This would provide sufficient time for any write operation +in progress to be terminated at the next block boundary before the power supply +is lost.

Note, however, that the media driver fails any operations +involving write operations to a card when the battery level is becoming dangerously +low, so in general, we are only talking about unexpected battery removal.
to provide a backup +battery so that the failing write operation can be re-retried once a good +battery level has been restored.

Even with such mechanisms in place, if power is removed in the middle +of a multi-block write operation, then some blocks will contain new data while +others will still contain old data.

Media change

When +a door open event is detected by the MultiMediaCard controller, it attempts +to remove power from a card as soon as possible. Power is not removed immediately +if a bus operation is in progress as powering down a card in the middle of +writing a block could leave the block corrupted.

Power is only removed +from a card immediately a door open event occurs if there are no sessions +queued by clients on the controller. If one or more sessions are queued then +these are allowed to complete, with power being removed once the last session +has completed. Any attempt to engage a new session while the door is open +fails with KErrNotReady.

To prevent a card becoming +corrupt because of attempted removal during a write operation, then it is +important that the door mechanism and circuitry gives enough early warning +of a potential card removal before the card is actually removed. This is to +provide sufficient time for any write operation in progress to proceed to +the next block boundary before the card is removed.

Once the door +is closed again, then new sessions can be engaged and power can be re-applied +to the card by the controller. However, power is only restored by the controller +in response to a client request. The Controller does not automatically re-power +a card to resume an operation interrupted by a door open event, no matter +what operation was in progress when the door opened.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-746BD53F-F637-4BC9-91AC-E53BA182B823-master.png Binary file Adaptation/GUID-746BD53F-F637-4BC9-91AC-E53BA182B823-master.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-746BD53F-F637-4BC9-91AC-E53BA182B823_d0e87730_href.png Binary file Adaptation/GUID-746BD53F-F637-4BC9-91AC-E53BA182B823_d0e87730_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-76A30EC4-4B99-5471-9E80-F853C91485BC.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-76A30EC4-4B99-5471-9E80-F853C91485BC.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,198 @@ + + + + + +Interrupt DispatcherThe ASSP/Variant part of the base port must implement an +interrupt dispatcher to manage interrupts. +

An interrupt source is a hardware device or software action that +can force the CPU to suspend normal execution, enter interrupt handling +state and jump to a section of code called an interrupt handler.

Typically, a number of interrupt sources are monitored by an interrupt +controller. This is hardware that generates a single interrupt notification +to the CPU, and provides information about which interrupts are pending, +i.e. which interrupts require action to be taken.

ISR

An interrupt service routine, or ISR, is code that deals with +a pending interrupt. The Symbian platform kernel responds to an interrupt +notification by calling an ISR for each pending interrupt. The process +of calling ISRs is called interrupt dispatch.

The ISR is a +single bare function. It is not a class member.

Each ISR takes +a single 32-bit parameter that is, typically, a pointer to an owning +class, although it can be any value that is appropriate. The parameter +is defined as a TAny * type, so a cast is almost +always necessary.

ISRs are usually kept in an ISR table.

Interrupt +ID

An interrupt source is identified by number, defined +as a TInt type. Typically, the ASSP layer defines +this number for each interrupt in a header file and exports it so +that it can be included and used by device drivers.

Where +the ASSP layer is split into a common layer and a variant (device +specific) layer, then the variant layer may also define its own set +of interrupt IDs.

This number is usually referred to as the +interrupt ID.

Binding +and unbinding

Only one ISR can be associated with each +possible interrupt source. Making this association is known as binding. +ISRs can be bound and unbound during normal operation, but only one +ISR can be bound to an interrupt source at any one time.

A +device driver binds an ISR by calling Interrupt::Bind(), passing the interrupt source ID; similarly, the device driver can +unbind the ISR by calling Interrupt::Unbind(), +also passing the interrupt ID.

Dispatching +interrupts

At its simplest, this is the process of deciding +which interrupts are pending and calling the ISR for each.

The following pseudo code shows the general principle:

+ { + FOREVER + { + Get next pending interrupt; + if None + { + return; + } + call ISR for the pending interrupt; + } + } +

In practice the dispatcher may have to do some more +work to communicate with the interrupt controller hardware.

Chained +interrupts

A system may have multiple interrupt controllers +to handle a large number of interrupt sources. These are usually prioritised +by connecting the interrupt output of a lower-priority controller +to an interrupt input of a higher-priority controller. This is called +chaining.

+Chained interrupts + +

An interrupt from a lower priority controller will appear +as an interrupt on the highest-priority controller.

When the +interrupt dispatcher of the higher-priority controller detects that +it is the chained interrupt that is pending, the usual way of dealing +with this is to run a secondary dispatcher to determine which interrupt +on the chained controller is pending.

There may be further +levels of chaining before the true source of the interrupt has been +identified.

Multiple +interrupt sources and pseudo interrupt sources

It is possible +that a single input to an interrupt controller is shared by several +interrupt sources.

+Multiple interrupt sources + +

It appears necessary to bind multiple ISRs to the same interrupt. +However, this is not possible. There are two ways of dealing with +this:

Maintain a list +of all ISRs that are bound to this single interrupt source, and call +all the ISRs in the list when the interrupt is dispatched. This is +most conveniently implemented by binding a single ISR to the interrupt, +which then calls all the real ISRs bound to this interrupt
Create pseudo +interrupts. These are extra interrupt IDs that do not exist in the +interrupt controller, but represent each of the interrupt sources +connected to the single shared interrupt source. An ISR can then be +bound to each pseudo interrupt. The interrupt dispatcher can then +determine which of the sources are actually signalling and call the +appropriate ISR via that pseudo interrupt ID. This is effectively +an implementation of a chained interrupt, and assumes that the interrupt dispatcher +can identify which of the sources is signalling.

Interrupts +in the split ASSP/Variant Configuration

When a common ASSP +extension is used, a device may have additional peripherals external +to the ASSP, and there needs to be a way of allowing extra interrupt +binding and dispatch functions to be added later by the variant layer. +This must be handled by the port as Symbian platform does not provide +any additional API to support this.

Device drivers should +be able to use the Interrupt class functions without +having to know where the interrupt is actually implemented. This implies +that all requests should go to the core implementation of functions +like Interrupt::Bind(), Interrupt::Enable() etc.

To enable the core implementation of these functions +to decide whether an interrupt ID refers to a core interrupt or device +specific interrupt, a common technique is to "tag" the interrupt ID. +A simple way is to use positive numbers to identify core interrupts +and negative numbers to identify device specific interrupts. The ISRs +for device specific interrupts are not stored in the core ISR table, +instead the device specific layer provides its own ISR table.

The general pattern for creating the core-device specific split +is that the core derives an implementation from class Asic, and the device specific part further derives from this core implementation. +The usual technique is to add a set of virtual functions to the core +class that can be derived by the device specific part. The core can +provide default implementations for these functions that would just +return KErrArgument to trap illegal ID numbers. +This API would need functions equivalent to each of the functions +defined by the Interrupt class.

As an example, +the core layer for the template reference board defines a class TemplateAssp that is derived from Asic. TemplateAssp defines the pure virtual functions: InterruptBind(), InterruptUnbind(), InterruptEnable() etc, all with signatures that are the +same for the comparable functions defined by Interrupt, and which are implemented by the Template class.

+Interrupt binding + +

Spurious +interrupts

In the Kernel Architecture 2, it is a convention +that unbound interrupts should be bound to a "spurious" interrupt +handler, i.e. an interrupt handler that faults the system indicating +the number of the interrupt. This aids debugging by identifying interrupts +that are enabled without corresponding ISRs.

Interrupt +priority

The interrupt architecture supports the concept +of adjustable interrupt priorities. Symbian platform defines the Interrupt::SetPriority() function that can implement this. +The function is passed the ID of the interrupt source to be adjusted +together with a priority value. The meaning of the priority value +is hardware and implementation dependent, and is defined by the port.

The +ISR table

The Variant must provide a table where each entry +defines which ISR is bound to which interrupt source. The table must have +enough space for entries for each interrupt source that is known to +the Variant.

When the Variant is split into an ASSP layer +and a Variant layer, the ISR table is put in the ASSP layer and will +not normally include ISRs for the Variant interrupt sources - these +will be handled by separate chained dispatchers in the Variant layer.

Symbian platform provides the SInterruptHandler structure, defined in the header file ...\e32\include\kernel\arm\assp.h to encapsulate the entry for an ISR. The ISR table is, therefore, +just an array of SInterruptHandler items. For example, +if a system has 32 possible interrupt sources, then the ISR table +would be defined as:

... +const TInt KInterruptSourceCount = 32; +SInterruptHandler IsrHandlers[KInterruptSourceCount]; +...

Interrupts are identified in the system by their +interrupt ID number, which is used to index into the ISR table. You +are free to allocate these numbers any way that is convenient for +you.

On the template reference board, for example, the ISR +table is defined as a static data member of the VariantASSPInterrupt class, which is derived from TemplateInterrupt. The class is defined in ...\template_assp\template_assp_priv.h.

class TemplateInterrupt : public Interrupt + { + ... // functions +public: + static SInterruptHandler Handlers[KNumTemplateInts]; + ... + };

where KNumTemplateInts is defined in the same +header file.

Factors that decide the size of the ISR table

The number of entries to be reserved in the ISR table depends +on the following factors:

Where the ASSP +is targeted at only a single device, the number of possible interrupts +is usually known, and the table can include an entry for each one.
If any pseudo sources exist, they should be included in the main +table for efficiency, but note that this is not strictly necessary.

Other factors affecting the ISR table

IRQs +and FIQs may need to be distinguished, although the exact requirement +is hardware dependent. Although the table has one entry for each possible +interrupt source, a possible scheme may be to group IRQs at the start +of the table, and FIQs at the end of the table. If the hardware has +separate interrupt controller hardware for IRQs and FIQs (or at least, +different registers) then you will need to arrange the table so that +you can determine from the interrupt ID whether the interrupt is an IRQ or FIQ.

For example:

+ISR table + +

Location +of interrupt handling code

Most of the interrupt dispatching +code is implemented in the ASSP layer. This includes a list of ISRs, +code for adding and removing ISRs, enabling and disabling interrupt +sources, and dispatching ISRs. The kernel only provides a pre-amble +and post-amble.

The kernel defines, but does not implement, +a class called Interrupt that exports interrupt +functionality to device drivers and other kernel code. The class provides +the public API for using interrupts (but not for dispatching them). +The port must provide an implementation for each function defined +by the class.

The class is defined in the header files ...\e32\include\kernel\arm\assp.h, which is exported to ...\epoc32\include\kernel\arm.

See Symbian OS +Internals Book, Chapter 6 - Interrupts and Exceptions

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-772C2721-DD84-54A6-ACE0-ECACC6432B95.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-772C2721-DD84-54A6-ACE0-ECACC6432B95.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,81 @@ + + + + + +Kernel +Objects and Containers Information CommandsDescribes how to use the c and o commands +to get information about kernel objects. +

Kernel objects

Kernel +objects such as DProcess, DThread, DSemaphore, DChunk are +all instances of classes derived from DObject.

To +show basic information about a DObject, use the o command.

To show more detail, use the O command.

As an example, use these commands to show information +about a DProcess object whose address is shown using the i command:

... +TheCurrentDataSectionProcess=6403bb4c +...

o 6403bb4c

This gives:

.o 6403bb4c +PROCESS at 6403bb4c VPTR=f8046c78 AccessCount=6 Owner=00000000 +Full name crash +

All objects derived from DBase have a virtual +table pointer, access count, owner and name. Using the O command on this address would you give you the full process information.

You +can use o to +examine other types of objects, for example chunks. The thread information +for the current data section process shows two chunks:

NumChunks=2 +0: Chunk 6403c044, run 00400000, access count 1 +1: Chunk 64039688, run 00600000, access count 1 +

Using the o command +on the first of these chunk objects gives you the basic information:

.o 6403c044 +CHUNK at 6403c044 VPTR=f8046b50 AccessCount=1 Owner=6403bb4c +Full name crash::$DAT +

Using the O command +gives you more detailed information:

.q 6403c044 +CHUNK at 6403c044 VPTR=f8046b50 AccessCount=1 Owner=6403bb4c +Full name crash::$DAT +Owning Process 6403bb4c +Size 2000, MaxSize 200000, Base 00400000 +Attrib 6, StartPos 0 +Type 6, State 2, Home Base 68900000 +Home Region Offset 00000000 +Home Region Base 68900000 +Home Region Size 00100000 +PTE: 0000055e, PDE: 00000021 00000001 00000001 +NumPdes=1, iPdes=61000010, iHomePdes=61001a24 +PdeBitMap=00000001, PageBitMap=6403c0c8 +Domain -1 +

The information displayed is memory model dependent. +It is shown here for the moving memory model.

Notes:

Size 2000, MaxSize 200000, Base 00400000
The Size field shows the current size of the chunk, +in bytes.

The MaxSize field shows the maximum size +of the chunk, in bytes.

The Base field shows the +base address in the run region.
Attrib 6, StartPos 0
The Attrib field shows the attributes of the chunk.

The StartPos field +shows the offset, in bytes, between the base address and the start of the +committed area. This is non-zero for double-ended chunks only.
Type 6, State 2, Home Base 68900000
The Type field shows the type of chunk. This corresponds +to a TChunkType enum value.

The State field +shows the current state of the chunk. This corresponds to a TChunkState enum +value, which is itself defined within the scope of the Symbian platform internal +class DMemModelChunk.

The Home Base field +is the base address of the chunk in the home region.
Home Region Offset 00000000 +Home Region Base 68900000 +Home Region Size 00100000 +
These three lines show the offset, base address and size (the +reserved size) of the chunk in the home region.

Kernel containers

Internally, +the kernel maintains lists of all current objects, organized by type. Each +list is a container, a DObjectCon object, with one for each +object type.

The c command +will walk through all objects in a given list. The type of object is identified +by appending a number after the command. For example, DProcess objects +are identified by the number 1, so to walk through all current DProcess objects +type:

The command effectively executes +a O command +on each object in the "processes" container.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-775901A4-0262-4E14-9E9C-C4E37DFCCF2E.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-775901A4-0262-4E14-9E9C-C4E37DFCCF2E.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,12 @@ + + + + + +OS Base Services Describes the platform services related to OS Base Services. \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-782E8D92-0431-50F5-95A0-5B231EBDF391-master.png Binary file Adaptation/GUID-782E8D92-0431-50F5-95A0-5B231EBDF391-master.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-782E8D92-0431-50F5-95A0-5B231EBDF391_d0e25767_href.png Binary file Adaptation/GUID-782E8D92-0431-50F5-95A0-5B231EBDF391_d0e25767_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-788ECC4B-36B9-493C-A86E-E6C8007074B1.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-788ECC4B-36B9-493C-A86E-E6C8007074B1.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,13 @@ + + + + + +SDIO Describes the Secure Digital Input/Output (SDIO) platform +service. \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-78963104-C2B0-4E19-99E5-FEAEB7EA307A.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-78963104-C2B0-4E19-99E5-FEAEB7EA307A.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,12 @@ + + + + + +IIC SHAI Implementation LayerDescribes how to use the IIC SHAI implementation layer. \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-795B8649-B6C3-5540-B52A-9B460F35A5B5.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-795B8649-B6C3-5540-B52A-9B460F35A5B5.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,12 @@ + + + + + +ROM PagingDemand Paging documentation related to ROM demand paging. \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-79620372-BADC-4826-A3AC-7FDBCFF98DA9.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-79620372-BADC-4826-A3AC-7FDBCFF98DA9.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,12 @@ + + + + + +Device Driver ConceptsThis section describes the Device Driver concepts. \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-796CB42C-29AC-5ECC-AC6E-35FC6B8CC84E.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-796CB42C-29AC-5ECC-AC6E-35FC6B8CC84E.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,16 @@ + + + + + +ConceptsThis section describes the technology and architecture +of the USB Client Driver.

+Port + Implementation Tutorial +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-79B2CF91-FB95-5E7C-81CC-235A6A660D88.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-79B2CF91-FB95-5E7C-81CC-235A6A660D88.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,24 @@ + + + + + +MMC ControllerThe MMC Controller provides kernel extensions that manages access +to the MultiMediaCard hardware on behalf of media drivers or any other device +driver. +

This section describes how to create a port of it for your phone hardware. Symbian +platform provides a generic Platform-Independent part of the Controller. You +must provide a Platform-Specific part to implement the interface to the MMC +hardware on your phone.

+File Systems + +Local Media +Subsystem +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-7A50630B-2B44-5D27-AA18-3BEEE1453020.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-7A50630B-2B44-5D27-AA18-3BEEE1453020.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,82 @@ + + + + + + The +Paging Algorithm Technology GuideDescribes the paging algorithm used in demand paging. +

Purpose

Kernel +side developers will sometimes need to know the algorithm used to move data +in and out of paged memory.

Intended +Audience:

This document is intended to be read by kernel side +developers.

The algorithm

Terminology

Paged memory (virtual addresses and their contents) +is called either:

'live', meaning present +in the cache of physical RAM, or
'dead', meaning stored +elsewhere in the backing store.

Physical RAM not being used to hold paged memory is called the free +pool.

Items of paged memory can be reassigned from 'live' to 'dead' +and vice versa. 'Live' items are classed as either 'old' or 'young' for this +purpose.

Paging +out memory

When more RAM is needed and the pool of free memory +is empty then RAM is freed up. This means changing an item of paged memory +from live to dead. The process is called paging out and it involves these +tasks.

The oldest virtual page +is removed from the cache and physically stored elsewhere
The MMU marks the virtual +page as inaccessible.
The associated page +of RAM cache is returned to the free pool.

Paging +in memory

When a program attempts to access dead paged memory, +the MMU generates a page fault and the executing thread is diverted to the +Symbian platform exception handler. This performs the following +tasks.

Obtain a page of RAM +from the free pool. If the free pool is empty, free up some memory by paging +out the oldest live page.
Read the contents of +the dead paged memory from its actual location (e.g. NAND flash) and write +them to the page of RAM.
Update the live list +described in the next section.
The MMU maps the linear +address of the dead paged memory on to the page of RAM.
Resume program execution.

The +paging cache

The paging cache is only useful if it is used to +hold the pages most likely to be required. The paging subsystem provides for +this by selecting the oldest pages to be paged out making space for new ones +to be paged in.

All live pages are stored in a list called the 'live +page list'. Live pages are labelled 'young' or 'old' and are stored in two +sub-lists, one for each type: the item at the start of the young list is the +youngest item and the one at the end of the old list is the oldest item. The +MMU makes young pages accessible to programs and old pages inaccessible. However, +old pages are different from dead pages because their contents are still held +in RAM.

The young and old lists are maintained in accordance with +these four rules.

When a dead page is +paged in (made live) it is added to the start of the young list, becoming +the youngest item.
When a live page must +be paged out (made dead) to free up RAM, the oldest page is selected.
If an old page is accessed +by a program a page fault results because old pages are marked inaccessible. +The paging system handles the fault by turning the page into a young page +('rejuvenating' it). To compensate, the oldest young page is then turned into +an old page ('aging' it).
Efficient operation +requires a stable ratio of young to old pages. If the number of young pages +exceeds a specified ratio of old pages, the oldest young page is turned into +the youngest old page ('aging' it).

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-7AB0C7E2-8B7C-5CC3-BAA5-15AA59F31181.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-7AB0C7E2-8B7C-5CC3-BAA5-15AA59F31181.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,66 @@ + + + + + +InterpretSIS +

InterpretSIS is a command-line tool used to install SIS files to +a data drive image that can be flashed onto a device's system +drive. It is either invoked through BUILDROM while +creating a data drive image or can be invoked directly.

For more information on system drive refer to, +> Symbian Guide > Kernel and Hardware Services Guide > User Library +and File Server > File Server > File Server Client Side > The System +Drive.

Command-line +syntax

The syntax for using InterpretSIS is as follows:

InterpretSIS [-v] [-h] [-w off|error|warn|info [-l <logfile>]] [-d <systemdrive>] -c <dir> -z <dir> -s <filename.sis>[,<filename2.sis>, <dir>, ...]

or:

InterpretSIS -p <filename> + + + +

-v

Displays verbose output.

+ + +

-h

Displays help.

+ + +

-w

The warning level to report; error by default.

+ + +

-l

The log file to write to; standard error by default.

+ + +

-d

The drive letter of the system drive on the target device; C: by default.

+ + +

-c

A directory on the PC representing the drive on the target +device to which files are installed.

+ + +

-z

A directory on the PC representing the contents of the ROM +(the Z: drive). This needs to be specified so +that InterpretSIS can check any dependencies are +met and to prevent invalid eclipsing.

+ + +

-s

The SIS file(s) to install. Any directory specified will +be searched for SIS files.

+ + + +

For example:

interpretsis -d c -c c:\epoc32\winscw\c -z C:\epoc32\release\WINSCW\udeb\Z -s sisfile1.sis, directory1, sisfile2.sis -w info

Alternatively, the parameters can be placed in a file, which +is passed to InterpretSIS using the -p option:

InterpretSIS -p <filename>

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-7AB51180-7A1A-40C7-B28F-EA46314A6E5B-GENID-1-2-1-9-1-5-1-4-1.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-7AB51180-7A1A-40C7-B28F-EA46314A6E5B-GENID-1-2-1-9-1-5-1-4-1.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,54 @@ + + + + + +Synchronous +RequestsThis document describes the use of synchronous requests by device +drivers. +

Synchronous +requests

Synchronous requests are typically used to set +or retrieve some information for the device driver. These requests almost +never need to access the hardware itself, and usually complete relatively +quickly. They return only after the completion of the request and the user +side thread is blocked till completion. Synchronous requests are usuallly +initiated by a call to RBusLogicalChannel::DoControl(). +The request is most likely to be executed in the context of the client user-side +thread.

A driver lists its available synchronous requests +in an enumeration, for example:

// Synchronous control messages used with DoControl() +enum TControl + { + EControlConfigure, // Configure the device (UART) + EControlTransmitData, // Transmit data over the device (UART) + EControlReceiveData, // Receive the data from the device + ENumRequests, // Number of synchronous control requests + AllRequests = (1<<ENumRequests)-1 + };

Implementation

Drivers +generally implement the DoControl() function in the LDD +to handle the received synchronous messages. The implementation reads the +request type and other passed arguments, and handles the request appropriately. +For example, the following handles RExDriver::EControlConfigure requests:

TInt DExDriverLogicalChannel::DoControl(TInt aFunction, TAny* a1, TAny* /*a2*/) + { + switch (aFunction) + { + case RExDriver::EControlConfigure: + memclr(&c, sizeof(c))); + TPtr8 cfg((TUint8*)&c, 0, sizeof(c))); + r = Kern::ThreadDesRead(iClient,a1,cfg,0,0); + if (r==KErrNone) + Pdd()->Configure(&c); + break; + ... + default: + r = KErrNotSupported; + } + return r; + }

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-7AB51180-7A1A-40C7-B28F-EA46314A6E5B-GENID-1-2-1-9-1-6-1-9-1-5-1.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-7AB51180-7A1A-40C7-B28F-EA46314A6E5B-GENID-1-2-1-9-1-6-1-9-1-5-1.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,54 @@ + + + + + +Synchronous +RequestsThis document describes the use of synchronous requests by device +drivers. +

Synchronous +requests

A driver lists its available synchronous requests +in an enumeration, for example:

Implementation

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-7B0BA327-54A0-4908-B8E3-0C82112EB957-master.png Binary file Adaptation/GUID-7B0BA327-54A0-4908-B8E3-0C82112EB957-master.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-7B0BA327-54A0-4908-B8E3-0C82112EB957_d0e93167_href.png Binary file Adaptation/GUID-7B0BA327-54A0-4908-B8E3-0C82112EB957_d0e93167_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-7B9D4E46-6AF9-5B77-9BE3-8B1DFAC588BD.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-7B9D4E46-6AF9-5B77-9BE3-8B1DFAC588BD.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,40 @@ + + + + + +Set UpSet up the source code and project files for an implementation +of the USB client controller. +

This topic describes how to set up the source code and project +files for an implementation of the USB client controller.

Another more complicated example is implemented in the OMAP/H4 +platform. This platform has two USB device controllers. The code shows +how two UDCs can be supported in the same source and build tree. The +second controller (Fibula) is a High speed USB 2.0 compatible device +controller, the code demonstrates how to support a USB 2.0 UDC and +one or more USB 2.0 Client Devices. See the code in ...\omap-hrp\....

The suggested steps are as follows:

Decide where +to put the source and header files for the platform-specific layer +. Normally the USB device controller is part of the ASSP, and you +would put the source files in the ASSP directory. For an external +USB device controller, you would use the Variant directory instead.
Implement the +platform-specific Layer within your chosen source and header files.

If you have a header file with a name in the shape of ASSP.h, then you will put USB Device Controller register +definitions and register bit definitions here.
Define the .mmp file for the USB client controller (the PDD), and +put this into your chosen directory. Remember that the platform-specific +layer is just part of the USB client controller, and the .mmp file needs to contain a list of all source +files that need to be compiled.
Add the name +of the .mmp file (without the file extension) +to your ASSP's .inf file in the PRJ_MMPFILES section. This must be in the same directory. This tells the abld tool about the existence of the .mmp file.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-7BB36477-0FE2-51D5-B4C0-86F7265C1B94.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-7BB36477-0FE2-51D5-B4C0-86F7265C1B94.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,16 @@ + + + + + +ReferenceThis topic provides a summary of related documentation for the +Base Starter to which you can refer. +

API +Reference

No published APIs.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-7BCC0EFA-0DD5-4879-BECF-C32D04BC8A39.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-7BCC0EFA-0DD5-4879-BECF-C32D04BC8A39.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,16 @@ + + + + + +SHAI ServiceA service that it intended to be used only by adaptation +code, for example, as part of a SHAI implementation. SHAI services +are rare. +

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-7BCDDA55-1460-5411-AFCF-C4640BEB9DE4.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-7BCDDA55-1460-5411-AFCF-C4640BEB9DE4.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,38 @@ + + + + + +Configuration: +HAL (Hardware Abstraction Layer)HAL contains a number of attributes that are related to the Digitizer +Driver. +

These attributes must be appropriately described in the HAL config.hcf file +for your variant. Follow the links to these attribute items for their meaning +and values.

HALData::EPen
HALData::EPenX
HALData::EPenY
HALData::EPenState
HALData::EPenDisplayOn
HALData::EPenClick
HALData::EPenClickState
HALData::EPenClickVolume
HALData::EPenClickVolumeMax

+ +User Side +Hardware Abstraction +HAL Attributes +and Function IDs +Configuration +Attribute Definition Files + +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-7C064328-8368-4259-9CE1-B8DFE2DF4AAC.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-7C064328-8368-4259-9CE1-B8DFE2DF4AAC.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,12 @@ + + + + + +Fair Scheduling and File CachingThis section shows how to enable and configure file caching. \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-7C533836-0D27-5519-BC1D-7153AC8BE4C0.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-7C533836-0D27-5519-BC1D-7153AC8BE4C0.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,47 @@ + + + + + +Media +Driver GuideDescribes the issues that need to be considered, when writing a +media device driver for a writable data demand paging environment. +

Purpose

This +document explains the points that have to be considered when writing a media +driver in an environment that uses writable data paging.

Issues to consider

The +main issue to consider when writing a media device driver for a writable demand +paging environment is to avoid page faults from occurring in DFCs, since this +can lead to a deadlock condition between the driver and the client process.

This +can be avoided using the following methods:

Use shared chunks.

Shared +chunks are memory areas that are accessible by both kernel-side and user-side +and they are never paged.

This is the best solution for drivers that +involve fast throughput such as media drivers.
Use synchronous rather +than asynchronous data transfer

This could be done by implementing +the following steps:
1. The client requests +a notification when data is available.
2. The data arrives.
3. The driver writes data +into an internal buffer and completes the client request.
4. The client makes a read +request.
5. The driver writes the +data back to the client in the client thread context.
This approach is easy to implement, however it requires the buffering +of data.
Use the flexible +memory model

This provides the ability for the memory to be +mapped into a drive's address space as unpaged.

This is an alternative +to the use of shared chunks.

However, this is not supported on the +moving or multiple memory models.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-7D535B68-CA7F-4796-80FB-AE7A27642A88.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-7D535B68-CA7F-4796-80FB-AE7A27642A88.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,117 @@ + + + + + +SDIO +OverviewSDIO is an Input/Output interface based on the SD card standard. +

The intent behind SDIO is to allow the use of an SD slot for more than +memory cards. SDIO allows I/O devices such as GPS, camera, Wi-Fi, FM radio, +Ethernet, barcode readers and Bluetooth to be plugged into such a slot.

However, with space being limited in modern mobile phones, memory card +slots are usually microSD slots - which are too small to accept SDIO or miniSDIO +cards. Also, memory card slots are often internal to the phone which prohibits the +insertion of SDIO cards. Therefore in Symbian devices, SDIO is typically used +only as an internal peripheral bus on all but hardware reference platforms. +Because of its ability to provide high-speed data I/O with low power consumption, +SDIO can be used to connect components such as Wi-Fi and FM radio peripheral +chips to the main processor.

Required background

You +must have an understanding of SD card before using SDIO.

Architecture +SDIO Architecture + +

Description

The +SDIO is divided into key modules described below.

Memory card performs the SD or the MMC card operations. It registers +the card driver, initializes the card, and sets permissions for the read and +write operations

SDIO Host controller is the most important module in the SDIO +architecture. It has a driver that allows card initialization, bus width settings, +clock frequency setting, sending and receiving of commands and SDIO interrupt +handling.

General Card Functions contains functions that are useful during +the development of other card drivers. The module supplies the read/write +SDIO/SD/MMC card register operations as well as select/deselect card, read +card status and reset card procedures.

Key Concepts

SDIO Interrupts: SDIO Interrupts are level-sensitive interrupts. +They communicate with the host through the SDIO line. The signal is held +active until the host acknowledges the interrupt through some function unique +I/O operation.

SDIO Class Driver: SDIO Driver supports the SDIO Host Controller. +The driver includes functions such as initialization, bus settings, clock +frequency setting, sending and receiving of commands, and SDIO interrupt handling.

SDIO card controller: SDIO card protocol is a super-set of the +SD card protocol. The SDIO Card Controller shares some of its functionality +with the SD controller. The Symbian platform SDIO card controller is implemented +as a set of SDIO card classes, each of which is derived from the corresponding +SD card classes. The SDIO card controller provides support for SDIO cards +within the E32 kernel. It manages access to the SDIO card hardware interface +and provides an API for class drivers to access SDIO card functions.

API summary

This +API is used by the implementers of the class drivers.

+ + + +

API names

Description

+ + + + +

DSDIOSTACK

The stack can handle multiple outstanding requests simultaneously. + It schedules these requests onto the bus, thereby putting the appropriate +card into transfer state automatically and running the appropriate state machine +function.

+ + +

TSDIOCARD

This class owns the I/O function objects. It provides access to +an I/O function object provided through the IOFunction(), +which returns a pointer to the object concerned.

+ + +

DSDIOSESSION

This contains functions for setting up a session object to perform +SDIO specific command sequences such as initialization, scheduling, invoking +and submitting the session.

+ + +

DSDIOREGINTERFACE

This contains the APIs that are used most frequently +during the implementation of the SDIO class drivers. It contains member functions +that allow single-byte read or write operations to a given register address +together with the corresponding ones for multi-byte access

+ + +

TSDIOFUNCTION

This contains member functions for access and control of function-specific +features such as function enable, function ready. It also has the member functions +for access and control of FBR features such as CSA access and function block +size.

+ + +

TSDIOINTERRUPT

This contains the usual interrupt object member functions. It provides +the abstraction of a per-function interrupt even though each function actually +shares a single interrupt request signal on the card.

+ + + +

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-7DDF052C-2520-428D-932D-BDB476344575.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-7DDF052C-2520-428D-932D-BDB476344575.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,27 @@ + + + + + +Generated +EventsThis document describes how kernel events are used in communication +with the kernel. +

Drives +can communicate with the Window Server, and through that to user programs, +using events.

Kern::AddEvent() adds an event +to the kernel event queue. This is used typically in drivers such as the keyboard +driver, which raises key events.

TRawEvent event; +event.Set(TRawEvent::EKeyDown, EStdKeyBackspace); +Kern::AddEvent(event);

The kernel event queue maintains a circular +buffer of TRawEvent objects allocated at system initialization. +The Windows Server calls UserSvr::CaptureEventHook() to +register itself to receive such events. The Kernel does not permit any process +other than the Windows Server to register to receive events.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-7E357DA2-67AD-403A-B4E1-7CB83E75136F.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-7E357DA2-67AD-403A-B4E1-7CB83E75136F.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,37 @@ + + + + + +SDIO Build GuideDescribes what is needed to include the SDIO adaptation +in a ROM image. +

When building a ROM image, all the processes and data needed to +execute a build are included in a single file. This file is executed +by the platform when the hardware is powered up.

Requirements

The SDIO hardware must conform to the SDIO standards and that +the hardware must work correctly.
You must be familiar with building a ROM for the Symbian platform.

Build +time implementation details

None

Building +the ROM with SDIO included

To include the SDIO PIL libraries +in the final ROM image, the USE_SDIO_SD_MMC flag +must be included in the list of buildrom parameters.

An example +of the use of this new parameter is:

buildrom h4hrp techview -DUSE_SDIO_SD_MMC

This example produces a ROM.

The iby file that specifies +the SDIO's PSL, must be included in the oby file for the ROM image.

For more information, refer to BUILDROM .

Run-time +configuration

Not required

+ROM +Tools Overview +BUILDROM + +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-7E3BBB18-3113-4312-AD91-897DE87C58BF.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-7E3BBB18-3113-4312-AD91-897DE87C58BF.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,32 @@ + + + + + +SDIO +PSU Implementation TutorialHow to implement the platform-specific class for the Power Supply +Unit of an SDIO-based hardware component. +

The Power Supply Unit (PSU) functionality is provided by the DSDIOPsu class. +To enable power control in the SDIO Controller, you must implement the PsuInfo() function +in the derived class of the DSDIOPsu class.

The iNotLockedTimeOut variable +is used by the "card not locked" functionality and the value is tied to the +reference board inactivity time-out. The iInactivityTimeOut variable +is used to set a time-out value for the sleep mode of the SDIO cards.

void DMySdioPsu::PsuInfo(TPBusPsuInfo& anInfo) + { + ... + // Only for SDIO + anInfo.iNotLockedTimeOut = 5; // Power down after 5 seconds of non-use (no clients registered) + anInfo.iInactivityTimeOut = 1; // Enter Sleep mode within 1 Second of inactivity (clients registered) + ... + return; + } +

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-7ECDCF7B-3B2A-561F-9136-04BC4DAE46E4.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-7ECDCF7B-3B2A-561F-9136-04BC4DAE46E4.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,161 @@ + + + + + +ARM +Exception Types, Fault Status Register Values, and Processor Mode ValuesReference for users of the debug monitor tool to ARM exception +types, fault status register values, and processor mode values. +

ARM exception +types

The numeric value in the left hand column is the value of +the ExcId field displayed as a result of entering an f command +in the debug monitor.

+ + + +

00000000

Prefetch abort

+ + +

00000001

Data abort

+ + +

00000002

Undefined instruction

+ + + +

Fault status +register values (FSR register)

The lowest 4-bits of the FSR register +indicates the fault generated by the MMU. The FSR register value is displayed +as a result of entering an f command +in the debug monitor.

+ + + +

Vector exception

+ + +

Alignment fault

+ + +

Terminal exception

+ + +

Alignment fault

+ + +

External abort on linefetch for section translation

+ + +

Section translation fault (unmapped virtual address)

+ + +

External abort on linefetch for page translation

+ + +

Page translation fault (unmapped virtual address)

+ + +

External abort on non-linefetch for section translation

+ + +

Domain fault on section translation (i.e. accessing invalid domain)

+ + +

External abort on non-linefetch for page translation

+ + +

Domain fault on page translation (i.e. accessing invalid domain)

+ + +

External abort on first level translation

+ + +

Permission fault on section (i.e. no permission to access virtual +address)

+ + +

External abort on second level translation

+ + +

Permission fault on page (i.e. no permission to access virtual address)

+ + + +

ARM processor +modes (CPSR register)

The 5 least-significant bits of the CPSR +register indicate the ARM processor mode. The CPSR register value is displayed +as a result of entering an f command +in the debug monitor.

+ + + +

CPSR[4:0]

Mode

Register set

+ + +

10000

User

PC, R14..R0, CPSR

+ + +

10001

FIQ

PC, R14_fiq..R8_fiq, R7-R0, CPSR, SPSR_fiq

+ + +

10010

IRQ

PC, R14_irq, R13_irq, R12-R0, CPSR, SPSR_irq

+ + +

10011

SVC

PC, R14_svc, R13_svc, R12-R0, CPSR, SPSR_sv

+ + +

10111

Abort

PC, R14_abt, R13_abt, R12-R0, CPSR, SPSR_abt

+ + +

11011

Undef

PC, R14_und, R13_und, R12-R0, CPSR, SPSR_und

+ + +

11111

System

PC, R14..R0, CPSR

+ + + +

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-80698E62-E310-59CA-A524-5CF44C437BE4.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-80698E62-E310-59CA-A524-5CF44C437BE4.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,23 @@ + + + + + +Base StarterThe Base Starter is a program that runs when the system starts. +

The program completes the initialization of the File Server, then starts +the System Starter process. You must customize the Base Starter when you create +a port of Symbian platform to a phone. To customize the Base Starter, you +change the configuration files and the Base Starter source code.

The Base Starter has often also been called EStart.

+ +File Server +System +Starter +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-80E0DB93-A96A-54A8-A201-E11935418BE7.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-80E0DB93-A96A-54A8-A201-E11935418BE7.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,236 @@ + + + + + +State +MachinesDescription of the structure and operation of state machines. +

The MultiMediaCard Controller uses state machines to manage the interactions +with the MultiMediaCard hardware.

State machines allows the controller to maintain the state of each submitted +session – allowing it to schedule a second session when the first becomes +blocked, for example.

To handle the complex sequence of bus operations involved, the controller +implements a state machine stack, allowing a parent state machine function +to invoke a child state machine function. The state machine stack allows nesting +of children down to a depth of 10 levels.

Each session object has its own individual state machine stack because +each session runs its own sequence of bus operations, with the controller +managing these multiple sequences. This means that each session object has +a state machine object, an instance of the TMMCStateMachine class.

+ + + +

The state machine remembers the next state and child function name, and +moves to that state as soon as control returns to the session.

The stack chooses the next session to be handled and manages the state +machine through the state machine dispatcher.

Structure of the state machine stack
Structure of a state machine function
Example of a state machine calling sequence

Structure of +the state machine stack

The stack itself is represented as an array +of TMMCMachineStackEntry objects contained within the state +machine object TMMCStateMachine.

The state machine +maintains a "pointer", TMMCStateMachine::iSP, to the current +state entry. This is not a true pointer, but just a value that indexes into +the array. However, for all practical purposes it has the effect of a pointer. +Each state entry in the stack is thought of as having a parent-child relationship +with the other.

Each state entry maintains three pieces of information:

A pointer to the state +machine function.
A variable containing +the current state; the value and meaning of the state is defined by the state +machine function.
A bitmask of TMMCErr defined +error conditions; these are set by the parent state machine function so that +it gets the chance to trap those errors if the child state machine function +returns those errors. Errors are propagated up the stack, and any error conditions +not trapped at any level in the state machine hierarchy leads to the state +machine terminating with that error value.

+ +

In general, the overall state of the state machine reflects the +state of the current state entry; for example, TMMCStatemachine::State() returns +the state held in the current state entry.

While the flow of control +through a stack can be complex, the following diagram shows a short example +snapshot. Here, the current state in the current stack entry is Sn and +is handled by the function PF(). The code decides to pass +control to the child function CF(), but ensures that, on +completion, the next state in the current stack entry will be Sn+1.

+ +

For example, the DMMCStack::CIMUpdateAcqSM() function +implements the CIM_UPDATE_ACQ macro as defined by the MultiMediaCard System +Specification, and is a typical state machine function.

Most commands +and macros involve one or more asynchronous operations and while such operations +are outstanding, a session is blocked. While a session is blocked, its state +machine dispatch function is not called. As soon an asynchronous event removes +the blocking condition, control returns to the state machine.

Structure of +a state machine function

State machine functions are defined and +implemented in the DMMCStack class in pairs: one as a static +function, and the other as a member function. The static variant takes a TAny* pointer +that is cast to a DMMCStack pointer, and the DMMCStack member +function is then called:

TMMCErr DMMCStack::FunctionNameSMST( TAny* aPtr ) + { + return( STATIC_CAST(DMMCStack*,aPtr)->FunctionNameSM() ); + } + TMMCErr DMMCStack::FunctionNameSM() + { + enum states {EStBegin=0, EStNext,…, EStEnd }; // Enumeration of states for this state machine + DMMCSession& s = Session(); + + SMF_BEGIN + // State EStBegin + // Actions for state EStBegin + + SMF_STATE( EStNext ) + // State EStNext + // Actions for state EStNext + + SMF_END + } +

A state machine function can release control and wait to be +re-entered by returning zero. If its session is not blocked then that will +happen immediately. If the state machine function returns non-zero, the session +will be completed with that error code unless the parent state machine function +has explicitly intercepted such an error by setting the trap mask.

Important points to note
Blocking on an asynchronous request

Important points to note

Each +state machine function must define a list of states that can exist. States +are defined as an enumeration whose first and last values must be labelled EStBegin and EStEnd, +respectively. EStBegin must have the value zero. Any other +intermediate states are program defined.

To make the state machine +functions more readable, a number of macros exist to help with the layout +of the function code, and to control program flow. The most basic macros are SMF_BEGIN, SMF_STATE and SMF_END that expand into a switch statement. The above code expands +to:

TMMCErr DMMCStack::FunctionNameSM() +{ +enum states {EStBegin=0, EStNext,…, EStEnd }; // Enumeration of states for this state machine +DMMCSession& s = Session(); + +TMMCStateMachine& m = Machine(); //SMF_BEGIN +const TMMCErr err = m.SetExitCode( 0 ); //SMF_BEGIN +for(;;) //SMF_BEGIN + { //SMF_BEGIN + switch(m.State()) //SMF_BEGIN + { //SMF_BEGIN + case EStBegin: //SMF_BEGIN + { //SMF_BEGIN + if(err) (void)0; //SMF_BEGIN + // State EStBegin + // Actions for state EStBegin + + } //SMF_STATE + case EStNext: //SMF_STATE + { //SMF_STATE + // State EStNext + // Actions for state EStNext + + case EStEnd: //SMF_END + break; //SMF_END + default: //SMF_END + DMMCController::Panic(DMMCController::EMMCMachineState);//SMF_END + } //SMF_END + break; //SMF_END + } //SMF_END +return(m.Pop()); //SMF_END +}

Notes:

be aware that SMF_BEGIN +generates an open curly bracket while SMF_STATE generates a corresponding +close bracket, and SMF_END closes the switch statement.

You need to be aware of the code that is generated by these macros. +In particular, some such as SMF_BEGIN generate an opening curly brace, while +others such as SMF_STATE generate a corresponding close curly brace. Also, +you need to know whether a macro generates a break; or a return; statement. +Lack of awareness here may cause code to be generated that flows from one +case statement to another, which may not be your intent.

SMF_BEGIN
SMF_END
SMF_NEXTS
SMF_CALL
SMF_CALLWAIT
SMF_CALLMYS
SMF_CALLMEWR
SMF_INVOKES
SMF_INVOKEWAITS
SMF_WAIT
SMF_WAITS
SMF_RETURN
SMF_EXIT
SMF_EXITWAIT
SMF_JUMP
SMF_JUMPWAIT
SMF_GOTONEXTS
SMF_GOTOS
SMF_STATE
SMF_BPOINT

Blocking on an asynchronous +request

The state machine can be made to block. This is done so +that you can wait for an asynchronous operation to complete. When the operation +completes, it unblocks the state machine. There are two stages to blocking +a state machine:

Call DMMCStack::BlockCurrentSession() to +indicate that the state machine associated with the current session is to +be blocked
Execute one of the SMF_xxxWAIT +macros to return from the current state machine function and wait.

Note that the state machine function must return by calling +one of the SMF_xxxWAIT macros. It must not poll or sit in a loop! The state +machines are not threaded, and this means that CPU time can only be given +to other tasks if the function returns.

DMMCStack::BlockCurrentSession() takes +an argument describing the type of block. The state machine will only unblock +when an unblock request with the matching argument is called. In the platform +specific layer of the MultiMediaCard controller, you should always set the KMMCBlockOnASSPFunction bit +in the argument passed to BlockCurrentSession().

To +unblock the state machine, call DMMCStack::UnBlockCurrentSession() setting +the KMMCBlockOnASSPFunction bit in the flags argument passed +to the function, and also an error code. This will invoke the state machine +scheduler, which will re-start the state machine.

Note that further +state machine processing must take place in a DFC rather than within the interrupt +service routine (ISR), and this can be forced by ORing the session status, DMMCSession::iState, +with the KMMCSessStateDoDFC bit before unblocking +the session. The bit has the effect of queueing a DFC to resume the state +machine at some later stage, before returning to the ISR.

The following +code shows the idea:

TMMCErr DMMCStackAssp::DoSomethingSM() + { + enum states {EStBegin=0, EStDone,EStEnd }; // enumeration of states for this state machine + + SMF_BEGIN + // start the asynchronous operation + BlockCurrentSession( KMMCBlockOnASSPFunction ); + StartAsynchronousOp(); + + // block and wait. Go to state EStDone when the asynchronous op is complete + SMF_WAITS( EStDone ); + + SMF_STATE( EStDone ) + // operation is complete, check for errors and return from state machine + TInt errors = CheckForHardwareErrors(); + SMF_RETURN( errors ); + + SMF_END + } + void TMMCInterrupt::Service( TAny* aParam ) + { + Session().iState |= KMMCSessStateDoDFC; + UnBlockCurrentSession(KMMCBlockOnASSPFunction, KMMCErrNone); + } +

Example of +a state machine calling sequence

This shows the state machine calling +sequence that implements the reading of a single block on a MultiMediaCard, +where the card is not yet selected. Note that the lowest level state machine +function called is IssueMMCCommandSM(), which is implemented +by the base port.

+ +

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-812DEBEB-84D0-5BD4-A5BB-5AF6B8384CCF.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-812DEBEB-84D0-5BD4-A5BB-5AF6B8384CCF.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,47 @@ + + + + + +Entry +Point ImplementationDescribes how to implement the entry point function. +

The DMA Framework implements its entry point function in the platform-specific +layer.

The entry point for a kernel extension is declared by a

+DECLARE_STANDARD_EXTENSION() +

statement, followed by the block of code that runs on entry to the DLL. +The following code is typical for a port of the DMA Framework , and is taken +from the port for the template reference platform:

+DECLARE_STANDARD_EXTENSION() +// +// Creates and initializes a new DMA controller object on the kernel heap. +// + { + __KTRACE_OPT2(KBOOT, KDMA, Kern::Printf("Starting DMA Extension")); + + return Controller.Create(); + } + +

where Controller is declared as writable static data:

+static TTemplateDmac Controller; +

Create() is a second-phase constructor defined in, and implemented by, +the concrete class derived from TDmac. DMA channels are +attributes of this concrete class because only the platform specific layer +knows what kind of channel to use. This platform specific layer second phase +constructor must call the platform independent layer second phase constructor, TDmac::Create(), +before doing anything else.

TDmac::Create() allocates the arrays containing the +descriptors and descriptor headers using the information passed to it by the +platform specific layer in the SCreateInfo struct. This +includes information such as the number of descriptors to be allocated, whether +hardware descriptors are supported and their size etc.

Note that if hardware-specific descriptors are used, they are allocated +in a hardware chunk. If pseudo-descriptors are used, they are allocated on +the kernel heap.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-817E0561-6165-5BB1-97F9-AD53CFCDAA56.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-817E0561-6165-5BB1-97F9-AD53CFCDAA56.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,117 @@ + + + + + +Impact +of Data Paging on Kernel-side Code GuideDescribes the kernel-side issues that must be considered when writing +device drivers. +

Purpose

This document explains the impact of data +paging on kernel side code.

Intended +Audience:

This document is intended for device driver writers.

Access to user memory

New restrictions on access +to user memory.

Access to current thread's address space

Certain +exported and internal APIs access the address space of the current thread +and are subject to restrictions on their use enforced by assertions in the +code. The restrictions are these:

The APIs may only be +called from thread context.
They may not be called +while any mutexes are held. There are two particularly important cases when +mutexes are often held:
- When publish and subscribe +is writing large binary properties to user space, and
  - When the multiple memory +model writes code segments' export directories to user space.
The APIs may not be +called when the system lock is held. There are two particularly important +cases when the system lock is often held:
- When publish and subscribe +is writing large binary properties to user space, and
- When the multiple memory +model uses DThread::FastWrite to write to user space.

The APIs concerned are these:

Kern::KUDesInfo
Kern::KUDesGet
Kern::KUDesPut
Kern::KUDesSetLength
Kern::InfoCopy
umemget(), kumemget(), umemget32(), kumemget32()
umemput(), kumemput(), umemput32(), kumemput32()
umemset(), kumemset()
SafeRead(), KUSafeRead()
SafeWrite(), KUSafeWrite()
KUSafeInc()
KUSafeDec()

Access to another thread's address space

Certain +exported and internal APIs access the address space of another thread and +are subject to restrictions on their use enforced by assertions in the code. +The restrictions are these:

The APIs may not be +called when any mutexes are held. One particularly important case of this +is when undertakers are completed and handles written to user space.

The APIs concerned are these:

Kern::ThreadRawRead()
Kern::ThreadRawWrite()
Kern::ThreadDesRead()
Kern::ThreadDesWrite()
Kern::ThreadGetDesLength()
Kern::ThreadGetDesMaxLength()
Kern::ThreadGetDesInfo()
DThread::FastWrite()

Client request completion

In non-paged code it +is usual for a thread to have an asynchronous request outstanding and to complete +it by calling Kern::RequestComplete(). This technique is +not safe in data paged code as it involves writing a status value back into +the thread's address space, but this memory might be paged out and violate +the thread's performance guarantees or cause a mutex order violation.

Instead, +you should use the TClientRequest object to write the request +status within the context of the client thread in the following way.

Create a TClientRequest object +by calling Kern::CreateClientRequest().
Call the SetStatus() function +of the TClientRequest object to set the client's request +status.
Call Kern::QueueRequestComplete() to +signal the client thread that the request has been queued for completion.
When the client thread +next runs, the TRequestStatus value is written back to +it.
The TRequestStatus can +now be reused, or destroyed by a call to Kern::DestroyRequest().

IPC message delivery

In non-paged code it is common +for a client thread to send a message to a server and write it into the address +space of the server. When data paging is enabled, this creates the same risk +of page faults as the completion of asynchronous requests and can be mitigated +by the same techniques as above. In addition, descriptor information (type, +length and maximum length) is read by temporarily switching to the client's +address space, creating additional risk of page faults.

When data +paging is enabled, messages to servers must be pre-parsed and their type, +length and maximum length stored in the message structure. This involves change +to the kernel code but does not impact on user-side code.

Kernel event queue

The kernel maintains a queue +of user-input events which is read by the window server. The introduction +of data paging involved a change to the kernel code which responds to the +user-side API UserSver::RequestEvent(). No change to user-side +code is involved.

+Code Paging +Overview +Code Paging +Guide +Demand Paging +Overview +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-81C69779-27AE-55E0-ACCF-E4F3E6657427.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-81C69779-27AE-55E0-ACCF-E4F3E6657427.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,16 @@ + + + + + +Concepts describes the technology, architecture, and behaviour of the DMA +Framework.

+Port Implementation + Tutorial +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-81DD805C-90B5-5227-B62B-F2413855BD9A.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-81DD805C-90B5-5227-B62B-F2413855BD9A.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,46 @@ + + + + + +LCD Extension ReferenceThis topic provides a summary of related documentation +for the LCD Extension to which you can refer. +

API +Reference

Kernel Architecture

+ + + +

Item

Header

+ + +

SRectOpInfo

videodriver.h

+ + +

TVideoInfoV01

videodriver.h

+ + +

TVideoInfoV01Buf

videodriver.h

+ + +

TDisplayHalFunction

u32hal.h

+ + + +

+LCD +Extension Architecture +Implementing +Dynamic DSA Allocation +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-834781AF-D202-5752-B81A-A51D12A4D1EC.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-834781AF-D202-5752-B81A-A51D12A4D1EC.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,28 @@ + + + + + + Code OrganisationThis topic describes the USB Client Driver code. +

This topic describes the USB Client Driver code that Symbian platform +provides.

USB client driver LDD:

is implemented +in USBC.LDD
has its source +code located in ...\e32\drivers\usbc\d_usbc.cpp
has its project +file located in ...\e32\drivers\usbc\usbc.mmp.

USB client controller PDD:

The interface DUsbClientController is defined in ...\e32\include\drivers\usbc.h.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-84D56A30-1E97-40AE-BFB0-E33495E95AAC.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-84D56A30-1E97-40AE-BFB0-E33495E95AAC.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,17 @@ + + + + + +Base Porting DetailsDescribes the base port implementation. +

This is a section that contains the detail for specific porting +activities. You will normally access this material via links from +the section on the Porting Overview. However, this is a good place +to look if you need to review specific activities.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-85332468-292D-589B-891B-0E7ACBADC7BA-master.png Binary file Adaptation/GUID-85332468-292D-589B-891B-0E7ACBADC7BA-master.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-85332468-292D-589B-891B-0E7ACBADC7BA_d0e11000_href.png Binary file Adaptation/GUID-85332468-292D-589B-891B-0E7ACBADC7BA_d0e11000_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-8552E66E-73D6-51DA-8F53-DDF437186CD6.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-8552E66E-73D6-51DA-8F53-DDF437186CD6.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,63 @@ + + + + + +ValidationDescribes the DMA test code to validate the port of DMA framework. +

The same set of source code is used to build two different DMA test harnesses:

It builds: T_DMASIM.EXE, D_DMASIM.LDD, +and DMASIM.DLL. This is a software-simulated implementation +of DMA. This harness is used mainly for debugging and validating the PIL (platform-independent +layer) as it simulates every kind of DMA controller. The DMA simulator and +associated PSL (platform-specific layer) is in ...\e32test\dma\dmasim.cpp.
It builds: T_DMA.EXE, D_DMA.LDD. +The source code for building these executables is in ...\e32test\dma\t_dma.cpp and ...\e32test\dma\d_dma.cpp respectively

T_DMA.EXE is a user-side harness, and is an automatic +test included in the E32TEST suite. It assumes that the underlying DMA controller +supports memory to memory transfers. This executable delegates most of the +work to D_DMA.LDD (built from base\e32test\dma\d_dma.cpp), a logical device +driver that acts as a client for the DMA Framework. D_DMA.LDD links statically +against DMA.DLL, the DMA Framework kernel extension and as such must be built +from the variant.

T_DMA.EXE delegates most of the work to D_DMA.LDD, +which is a logical device driver that acts as a client for the DMA Framework. D_DMA.LDD links +statically against DMA.DLL, the DMA Framework kernel +extension, and as such must be built from the variant. In practice, this means +that D_DMA.LDD must be specified in the test bld.inf for +the variant being ported. See ...\template_variant\test\bld.inf for +an example.

D_DMA.LDD calls the DmaTestInfo() function +in the PSL to discover the capacities of the PSL: number of channels, maximum +transfer size, etc. This is the template implementation:

+TDmaTestInfo TestInfo = + { + 0, + 0, + 0, + 0, + NULL, + 0, + NULL, + 0, + NULL + }; + + +EXPORT_C const TDmaTestInfo& DmaTestInfo() +// +// +// + { + return TestInfo; + } + + + \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-857F981E-711B-5CA8-AB37-5C700A6140FA.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-857F981E-711B-5CA8-AB37-5C700A6140FA.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,93 @@ + + + + + +HAL Groups +and Handlers List of HAL groups and the location of their associated handlers. +

Some of the handlers are part of Symbian platform generic code and do not +require porting.

+ + + + +

HAL group

Location

Customizable?

Explicit registration required?

+ + +

EHalGroupVariant

Variant

Yes. It needs to be implemented as the Asic::VariantHal() function +defined by the Asic class.

See the template port: ...\template\template_variant\specific\variant.cpp

No. It is done automatically as part of the kernel initialization.

+ + +

EHalGroupPower

Power model

Yes. It needs to be implemented when implementing the power model.

See +the template port: ...\template\template_variant\specific\power.cpp

No. It is done automatically as part of the kernel initialization.

+ + +

EHalGroupDisplay

LCD driver

Yes, when porting the LCD driver.

See the template port: ...\template\template_variant\specific\lcd.cpp.

Yes, during initialization of the driver.

+ + +

EHalGroupDigitiser

Digitiser

Yes, when porting the digitiser.

See the template port: ...\template\template_variant\specific\xyin.cpp.

Yes, during initialization of the driver.

+ + +

EHalGroupKeyboard

Keyboard driver

Yes, when porting the keyboard driver.

See the template +port: ...\template\template_variant\specific\keyboard.cpp.

Yes, during initialization of the driver.

+ + +

EHalGroupKernel

Kernel

No. It is part of Symbian platform generic code.

No. It is done automatically as part of the kernel initialization.

+ + +

EHalGroupMedia

Media Driver

No. This is in the media driver LDD; this is a kernel extension +and is implemented by Symbian platform.

Yes, during initialization of the driver/extension.

+ + +

EHalGroupEmulator

Emulator

No. The emulator is a port of Symbian platform maintained by Symbian.

Yes, during 3rd phase initialization of the emulator variant.

+ + +

EHalGroupSound

Sound driver

Unlikely—the only example is in the sound driver maintained for +backwards compatibility with pre-Symbian hardware.

Yes

+ + +

EHalGroupMouse

Emulator

Unlikely—the only example is in the emulator, which is a port of +Symbian platform maintained by Symbian.

Yes

+ + + +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-85C18DAF-DB76-51C6-B38D-A802E314F4D1.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-85C18DAF-DB76-51C6-B38D-A802E314F4D1.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,159 @@ + + + + + +Performance +Guarantee Tutorial Describes how to maintain performance guarantees when writing a +software package on a data paged platform. +

Data paging can +affect performance guarantees. When writing software for a data paged platform, +you need to perform an impact assessment on the components of your application. +To do so, you perform the following analyses and implement the appropriate +mitigation for the impacts you discover:

Static analysis,
Use case analysis, and
IPC analysis.

+ +Perform a static +analysis of the impact of data paging on your code. + + +List all the executables in your package, indicating their size and +pageability. + + +For each item in the list identify its static dependencies, indicating +their size and pageability. + + +For each item in the list identify its dynamic dependencies, indicating +their size and pageability. +For instance, note whether the component is a plug-in to a framework +or is itself a framework. + + +The purpose of collecting this information is to identify which +executables are most likely to be impacted by data paging. + +Perform a use case +analysis of the impact of data paging on your code. It is good practice to +distinguish between use cases involving real time and performance critical +performance guarantees. You do not need to cover use cases which do not involve +guarantees of this kind. + +List all the +use cases for the component which involve real time performance guarantees. +Real time use cases are those having very strict response time guarantees +and also those involving an acceptable user perception of behaviour. +

Video playback,
VoIP phone calls, and
File download over USB.

+Examples of use cases involving acceptable user perception are: + +List all the +use cases for the component which involve performance critical guarantees. +This means the bench-marked use cases by which the performance of the operating +system is measure. +Examples of use cases having a strict response time are: +

Standard boot time,
Application start-up +time, and
Camera image capture +time.

+ +Identify compound +cases involving both real time and performance critical guarantees. +An example of a compound case is receiving a text message while playing +MP3 audio. + + + +Perform an IPC analysis +of the impact of data paging on your code. + +Identify all +performance critical or real time servers which the component interacts with. + +List each case +where these servers read paged data from a client's address space. In this +case, paged data includes: +

Paged heaps and stacks,
RAM-loaded code, and
Read only XIP data structures +including
- bitmaps,
- constant descriptors,
- constant data arrays +in code,
- data files accessed +through a pointer, and
- exported DLL data.

+ +Identify all +cases of custom architectures where one thread reads from another thread's +address space. + + + +Take steps to mitigate +the impacts of data paging which you have identified, as appropriate to each +case. + + +Protect the real +time and performance critical code paths. These paths will have been identified +in the static analysis of the component. There are two ways of protecting +them. +

For all use cases, ensure +that the minimum paging cache size is large enough to accommodate both the +protected code path and any other paged data required at the same time.

This +method of protection may not always be practical, because compound use cases +may involve unpredictable amounts of data which exceed the size of the paging +cache.
Make the protected code +path unpaged. Mark the code itself as unpaged, and either mark whole regions +of memory as unpaged or pin memory to ensure that it is unpaged.

+ +Redesign the +component architecture to isolate areas where data paging impacts on performance. +Examples of this are: +

Separating the data +plane and the control plane, and
Splitting a monolithic +library into paged and unpaged parts.

+ +Use code paging +or XIP ROM paging to mitigate the impact of paging. + +For instance, a monolithic library with static dependences may only +need to be partially loaded, and some dependencies may not need to be loaded +at all. + + +Mitigate the impact of data paging on IPC using the techniques set out +in the document Device +Driver Writing Technology Tutorial + + + + + \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-86082C0C-B0EE-5E7C-85B4-4A509066012F.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-86082C0C-B0EE-5E7C-85B4-4A509066012F.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,16 @@ + + + + + +MMC Porting +Implementation TutorialDescribes the steps to implement a port of the MMC Controller.

+Concepts + +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-862CA4C4-C6E8-4D60-8DD0-F3590C92E15D.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-862CA4C4-C6E8-4D60-8DD0-F3590C92E15D.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,13 @@ + + + + + +Interrupt Client InterfaceDescribes the client interface of the Interrupt platform +service. \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-86737CAB-2A4A-4424-8856-67E0804BCD60.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-86737CAB-2A4A-4424-8856-67E0804BCD60.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,28 @@ + + + + + +Time OverviewProvides a basic idea about the Time platform service. +

What +is Time platform service

Time platform service +starts during device start up. It is responsible for maintaining a +queue of all system-wide alarms. It allows clients to query the status +of alarms, set alarms, remove alarms and perform other utility functions.

Need +for Time platform service

Time platform service +is required to manage the alarm in the system and system +state manager utility plug-in specifically RTC adaptation plug-in.

For +whom does Time platform service matter to?

Time platform service matters to all the Real time clock and alarm +implementations to fulfill the requirements set by the RTC adaptation +plug-in interface that is introduced beside of a System State Manager. +The SSM Adaptation Server contains a RTC Adaptation plug-in.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-86C21C9B-9F08-579F-84E9-CBE46F756373-master.png Binary file Adaptation/GUID-86C21C9B-9F08-579F-84E9-CBE46F756373-master.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-86C21C9B-9F08-579F-84E9-CBE46F756373_d0e10964_href.png Binary file Adaptation/GUID-86C21C9B-9F08-579F-84E9-CBE46F756373_d0e10964_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-877EEB52-40C8-4880-87A0-9736A625F85F.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-877EEB52-40C8-4880-87A0-9736A625F85F.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,76 @@ + + + + + +TDmaChannel Derived Class ImplementationDescribes how to write a class describing a DMA channel. +

The TDmaChannel class is part of the PSL implementation. +It is an abstract class with pure virtual functions which you must +derive in order to implement it. The implementation of a DMA channel +involves hardware-specific decisions such as the choice of DMA mode

The purpose of DMA is to transfer data such as streaming audio +produced by a client application. A typical transfer involves passing +the data from user side to kernel side via a shared chunk and then +a transfer from one memory location to another by DMA over a buffer. +If the amount of data to be transferred exceeds the maximum transfer +size supported by the controller or involves non-contiguous physical +memory, the data is fragmented and transmitted in a sequence of transfers +in one of three modes.

In single buffer mode the hardware controller provides a single +set of transfer registers used alternately to perform an active transfer +and to set up a pending one: however this mode incurs overhead in +the form of significant periods of time when the driver is idle during +the pending phase.
In double buffer mode the hardware controller provides two +sets of transfer registers, one set for the active transfer and one +for the pending transfer..
In scatter-gather mode, a single procedure call sequentially +writes data from multiple buffers to a single data stream or from +a data stream to multiple buffers.

The PIL supplies three derived classes corresponding to the DMA +modes:

TDmaSbChannel
for a single-buffer channel,
TDmaDbChannel
for a double-buffer channel, +and
TDmaSgChannel
for a scatter-gather channel.

These three classes are defined in dma_v1.h.

You may simply use one of these classes or derive further classes +from them and implement those. For example, the template scatter-gather +implementation defines a TTemplateSgChannel class +derived from TDmaSgChannel for storing data when +appending new descriptors to a running channel:

+class TTemplateSgChannel : public TDmaSgChannel + { +public: + TDmaDesc* iTmpDes; + TPhysAddr iTmpDesPhysAddr; + }; + +

In general, design decisions are made at the level of implementation +in hardware and are subsequently reflected in the structure of the +derived classes.

There are two ways of extending the DMA Framework:

to provide platform-specific functionality on a per-channel +basis, and
to provide platform-specific functionality on a channel independent +basis

In the first case, TDmaChannel::Extension() calls TDmac::Extension() and the PSL provides an implementation +of the virtual function TDmac::Extension(). The +default implementation just returns KErrNotSupported. In the second case, TDmaChannel::StaticExtension() calls DmaChannelMgr::StaticExtension() and the +PSL provides an implementation of the static function DmaChannelMgr::StaticExtension(). The template PSL implementation just returns KErrNotSupported.

+DMA +Channels +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-8798F896-E0CB-4B9B-8F88-3C8B58574213.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-8798F896-E0CB-4B9B-8F88-3C8B58574213.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,26 @@ + + + + + +The +Physical ChannelThis document describes how a logical device communicates with +a physical device over a physical channel. +

The +physical channel defines the interface between the logical device and the +physical device. Typically, this interface is different for each device family +and, therefore, the device driver framework does not require a particular +type of interface. The only requirement is that the physical channel class +is derived from DBase. It is up to the driver writer to +define the physical channel class.

+ Device driver physical channel classes + + +

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-892931C3-E560-54AA-A9CB-2820BF025E52.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-892931C3-E560-54AA-A9CB-2820BF025E52.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,70 @@ + + + + + +Fault +Information CommandsDescribes how to use the f command to get information +about the fault type. +

There are two possibilities:

an unhandled exception has occurred
a panic has occurred

To start, use the f command. +You will see something like this:

+Fault Category: Exception Fault Reason: 10000000 +ExcId 00000001 CodeAddr f800415c DataAddr 00000000 Extra 00000005 +Exc 1 Cpsr=60000013 FAR=00000000 FSR=00000005 + R0=64007328 R1=00000000 R2=00000000 R3=00000001 + R4=64007328 R5=640074c0 R6=00000000 R7=f8047ba4 + R8=64006f80 R9=64006fec R10=00000013 R11=64006ec4 +R12=00000001 R13=000029b4 R14=0000016c R15=f800415c +R13Svc=64006ea8 R14Svc=f8002b2c SpsrSvc=600000ff + +

The Fault Category field shows the type of fault, in this case an +exception.

Unhandled +exceptions

If the Fault Category is Exception, then +the fault is caused by an unhandled processor exception. You can get further +information on the type of exception by looking at the first three lines of +the generated output:

Fault Category: Exception Fault Reason: 10000000 +ExcId 00000001 CodeAddr f800415c DataAddr 00000000 Extra 00000005 +Exc 1 Cpsr=60000013 FAR=00000000 FSR=00000005

The CodeAddr and DataAddr fields +show the address of the instruction that caused the exception and, depending +on the type of exception and instruction, the address of the data the instruction +was trying to access. You can use the CodeAddr value to find +the function which was being executed by using +the MAKSYM tool.

The number after ExcId is +the type of exception, in hexadecimal, and is one of the ARM exception types. The meaning of the numbers depends on the type +of processor.

If the exception is +a prefetch abort, then the code address is invalid.
A data abort means that +the code address is invalid.

The number after FAR is the fault address register; +this is the address that caused the fault.

The number after FSR is +the fault +status register value and shows why the MMU raised an exception.

The +number after CPSR is the value of the CPU's CPSR register when the exception +occurred. The 5 least-significant bits of the CPSR register indicate the ARM +processor modes (CPSR register).

Panics

If +the Fault Category is not Exception, then the fault is due to +a panic. In this case the only other valid field is the Fault reason; +the values of all other fields are meaningless.

The panic number is +the low 16-bits of the fault reason, shown in hexadecimal.

For example, +a KERN 27 panic would generate:

Fault Category: KERN Fault Reason: 0000001b +ExcId ffffee5e CodeAddr ffff99a9 DataAddr bfff3e54 Extra fffec4cd +

If the panic is KERN 4, then a thread or process marked as +protected has panicked. For other panics, kernel side code has panicked; this +code is either in the kernel itself or in a device driver.

See Kernel State Information +Commands to find out which process and thread were running at the time +of the panic.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-898704CF-26A1-50F5-BEFE-1E29D85064AA.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-898704CF-26A1-50F5-BEFE-1E29D85064AA.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,13 @@ + + + + + +ReferenceThis section describes the command and syntax for ROM building +tools and input files. \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-89BCF9A5-ABBD-5523-BA76-FDB00B806A30.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-89BCF9A5-ABBD-5523-BA76-FDB00B806A30.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,237 @@ + + + + + +Fair Scheduling and File CachingDescribes how to implement and configure the fair scheduling +and file caching features for file systems implementations. +

Enabling +fair scheduling

The MExtendedFileInterface API enables fair scheduling. The FAT, FAT32 and LFFS file systems +support MExtendedFileInterface, this API allows requests +to be split into one or more segments with the aOffset parameter. Support has been built in for large files by changing +the file’s position parameter (aPos) from a TInt to a TInt64.

To enable +fair scheduling, the file system mounted on a particular drive must +support CFileCB::MExtendedFileInterface. The object +returned by CFileSystem::NewFileL() must be derived +from CFileCB and CFileCB::MExtendedFileInterface. The file server determines whether this is the case by calling CFileCB::GetInterface.

The CFileCB::MExtendedFileInterface interface is as follows:

class MExtendedFileInterface +{ +public: + virtual void ReadL(TInt64 aPos, TInt& aLength, TDes8* aDes, const RMessagePtr2& aMessage, TInt aOffset) = 0; + virtual void WriteL(TInt64 aPos, TInt& aLength, const TDesC8* aDes, const RMessagePtr2& aMessage, TInt aOffset) = 0; + virtual void SetSizeL(TInt64 aSize) = 0; +};

The file system indicates its support for MExtendedFileInterface by intercepting the CFileCB::EExtendedFileInterface enumeration in the CFileCB::GetInterface() method +as in the following example:

TInt CFatFileCB::GetInterface(TInt aInterfaceId, TAny*& aInterface, TAny* aInput) + { + switch(aInterfaceId) + { + case EExtendedFileInterface: + ((CFileCB::MExtendedFileInterface*&) aInterface) = this; + return KErrNone; + + //etc. + + default: + return CFileCB::GetInterface(aInterfaceId, aInterface, aInput); + } + }

Enabling +read and write caching

To enable caching, the file system +must support reads and writes to local buffers, which are buffers +created and owned by the file server itself rather by a client of +the file server.

The local media subsystem already supports +local messages, but the file system and any file system extensions +need to be examined carefully to ensure that they do not call any RMessagePtr2 methods, otherwise a panic results.

The file server calls CMountCB::LocalBufferSupport() to find out whether the file system and all file system extensions +mounted on a particular drive fully support local buffers before it +enables caching. The file system handles the CMountCB::ELocalBufferSupport enumeration in its CMountCB::GetInterface() method +and passes the request on to the first proxy drive, as in the following +example:

TInt CFatMountCB::GetInterface(TInt aInterfaceId, TAny*& aInterface, TAny* /*aInput*/) + { + TInt r= KErrNone; + switch(aInterfaceId) + { + // file caching supported, so pass query on to first proxy drive + case CMountCB::ELocalBufferSupport: + r = LocalDrive()->LocalBufferSupport(); + break; + default: + r=KErrNotSupported; + } + return r; + }

If no file system extensions are loaded, then +the query is eventually handled by CLocalProxyDrive::GetInterface(), which returns KErrNone to indicate that TBusLocalDrive and the local media sub-system support local +buffers.

If there are any file system extensions, they must +handle the CProxyDrive::ELocalBufferSupport enumeration, +as in the following example:

TInt CBitExtProxyDrive::GetInterface(TInt aInterfaceId, TAny*& aInterface, TAny* aInput) + { + switch(aInterfaceId) + { + // file caching supported, so pass query on to next proxy drive + case ELocalBufferSupport: + return CBaseExtProxyDrive::LocalBufferSupport(); + + default: + return CBaseExtProxyDrive::GetInterface(aInterfaceId, aInterface, aInput); + } + }

Configuring +caching

The global and drive-specific cache property defaults +are defined in f32\sfile\sf_file_cache_defs.h. They may be overridden for a particular drive by appropriate entries +in the Base Starter component's ESTART.TXT configuration +file. The format of this file has been enhanced to support the .ini file style syntax:

C: 0 ELOCAL FAT 0 FS_FORMAT_COLD,FS_SYNC_DRIVE # IRAM +D: 1 ELOCAL FAT 0 FS_SCANDRIVE # MMC (textshell) +I: 2 ELOCAL FAT 0 FS_FORMAT_CORRUPT # NAND - USER DATA +K: 8 ELFFS LFFS 0 FS_FORMAT_CORRUPT # LFFS + +[DriveD] +FileCacheSize 256 +FairSchedulingLen 128 +FileCacheRead ON +FileCacheReadAhead ON +FileCacheWrite ON +ClosedFileKeepAliveTime 3000 +DirtyDataFlushTime 3000 +FileCacheReadAsync ON + +[DriveI] +FileCacheWrite ENABLED + +[DriveK] +FileCacheWrite ENABLED + +[FileCache] +GlobalCacheEnabled ON +GlobalCacheSize 32768 +GlobalCacheMaxLockedSize 1024 +LowMemoryThreshold 10

In this example, write caching +is enabled on drives I and K and has been turned on by default on +drive D.

Most of the properties in the example are set to +their default values: the definitions are redundant but are shown +for illustrative purposes.

For details, see Base Starter Technology.

Global +cache settings

The following table holds the global caching +properties:

+ + + + +

Property

Type

Comments

Default value

+ + +

GlobalCacheEnabled

boolean

on or off

+ + +

GlobalCacheSize

integer

Size of disconnected chunk shared by all files in kilobytes.

32768K (32MB)

+ + +

GlobalCacheMaxLockedSize

integer

Maximum amount of locked RAM for all files in kilobytes.

1024K (1 MB)

+ + +

LowMemoryThreshold

integer

Low memory threshold expressed as a percentage of total +RAM. If the amount of RAM drops below this value, attempts to allocate +memory for file caching fails.

10%

+ + + +

File +cache settings

The properties FileCacheRead, FileCacheReadAhead and FileCacheWrite may each be in one of 3 states:

OFF - file caching is permanently off and cannot be turned on.
ENABLED - file caching is off by default but may be turned on using an appropriate +file open mode, such as EFileReadBuffered
ON - file caching is on by default but may be turned off using an appropriate +file open mode, such as EFileReadDirectIO.

See Run time cache settings.

If FileCacheReadAsync is set, media driver reads on this drive are asynchronous. This +results in read ahead requests being issued before completing a client +read request. However, if FileCacheReadAsync is OFF, +then media driver reads on this drive are synchronous. So, issuing +a read ahead is likely to block any client thread that is normally +running at lower priority than the media driver's thread. In this +case read ahead requests only happen during periods of inactivity +to improve latency.

+ + + + +

Property

Type

Comments

Default value

+ + +

FileCacheSize

integer

Maximum amount of locked or unlocked RAM per file.

128K

+ + +

FairSchedulingLen

integer

Read & write requests greater than this length are split +up into 2 or more requests.

128K

+ + +

FileCacheRead

string

OFF, ENABLED or ON.

ENABLED

+ + +

FileCacheReadAhead

string

OFF, ENABLED or ON.

+ + +

FileCacheWrite

string

OFF, ENABLED or ON.

ENABLED

+ + +

FileCacheReadAsync

boolean

ON or OFF. If set, media driver reads on this drive are +asynchronous.

OFF

+ + +

ClosedFileKeepAliveTime

integer

Time after which a file is removed from the closed file +queue, in milliseconds.

3000ms (3 secs)

+ + +

DirtyDataFlushTime

integer

Time after which a file containing dirty data is flushed, +in milliseconds.

3000ms (3 secs)

+ + + +

+Fair +Scheduling and File Caching Background +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-8A1B6104-4B13-5200-AF3D-64B3929707BB-master.png Binary file Adaptation/GUID-8A1B6104-4B13-5200-AF3D-64B3929707BB-master.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-8A1B6104-4B13-5200-AF3D-64B3929707BB_d0e14531_href.png Binary file Adaptation/GUID-8A1B6104-4B13-5200-AF3D-64B3929707BB_d0e14531_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-8A5EC98B-E9AD-5496-9909-7C3B35610785.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-8A5EC98B-E9AD-5496-9909-7C3B35610785.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,64 @@ + + + + + +Demand +Paging Deadlock GuideDescribes deadlocks in the context of demand paging and how to +prevent them from occurring. +

Introduction

A +deadlock is when two or more processes have some resources, but not all of +the resources required to execute. The resources that are required are held +by the other processes, which in turn want the resources that are held by +the initial processes. In this state, no process can execute.

The +classic sign that a deadlock has occurred is that a collection of processes +just appear to never do anything i.e. 'just hang'.

In the context +of demand paging, the resource is a page of RAM that can be paged in or out. +If one process wants data in a page of RAM that is paged-in or out by another +process, then a potential deadlock condition can occur.

Deadlocks +are only likely to occur if you are altering or interacting with one of the +components used in paging in and out, such as media drivers or the paging +sub-system. The majority of user-side code does not need to worry about deadlocks +from paging.

This guide is most applicable to device side writers +and other engineers writing kernel-side code.

Deadlock features

For a deadlock to occur, +four necessary conditions must occur:

Mutual exclusion condition +

A resource cannot be used by more than one process at a time.

Hold +and wait condition

One process is holding one resource, but needs +another before it can finish.

No preemption condition

The +resources can only be relinquished by the process holding it.

Circular +wait condition

One process is holding a resource and wants another +resource that is held by another process, which in turn wants access to the +resource held by the initial process.

Deadlock Prevention

Since the cause of deadlocks +(as far as demand paging is concerned) is due to the paging in and out of +RAM, the following points have to be considered:

Make sure all kernel-side components are always unpaged.
Pinning; new APIs have been added that allows a process to over-ride + the demand paging rules as regards to how RAM pages are paged in and out +the phone's memory. The name comes from that fact that the RAM page is fixed +in the phone's RAM (as if a pin had been stuck into it) until a detached command +is executed (unpinned). This is implemented by using the new DLogicalChannel::SendMsg() method.
Mutex use in device drivers - if the nesting order is violated then +deadlock can occur. To overcome this, make sure that all device driver operations +that could cause a page fault don't use mutexes. In other words, any access +to paged memory while holding a mutex has the potential to cause a deadlock.
Code running in DFC Thread 1 must not access user memory. This DFC +thread is used by the implementation of the system timer functionality, hence +paging RAM in or out of the system by this thread could cause serious performance +problems or a deadlock.
For media drivers, make sure that when the media driver services page-in +requests, that the thread that the driver runs in does not also make requests +to page-in RAM pages. Because, if this was to occur, then the media driver +will not be able to service the page in request and a dead lock would occur.

+Thrashing +Guide +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-8A78D678-D1C8-4A4E-9BF1-81C7019815C3-master.png Binary file Adaptation/GUID-8A78D678-D1C8-4A4E-9BF1-81C7019815C3-master.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-8A78D678-D1C8-4A4E-9BF1-81C7019815C3_d0e94711_href.png Binary file Adaptation/GUID-8A78D678-D1C8-4A4E-9BF1-81C7019815C3_d0e94711_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-8B7E2A72-B793-5E70-87F0-92AA0A482F23.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-8B7E2A72-B793-5E70-87F0-92AA0A482F23.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,165 @@ + + + + + +Interrupt::Bind() +and Interrupt::Unbind() Describes two types of configuration used in the implementation +of bind and unbind functions. +

The functions Interrupt::Bind() and Interrupt::Unbind() provide +device drivers with a way of binding ISRs to interrupt sources, and unbinding +ISRs from interrupt sources. The implementation of these functions follows +a standard pattern that can be re-used in most cases.

The implementation can be different if there is a single Variant DLL, or +if there is also an ASSP extension.

Variant DLL only configuration

The following example +implementation of Interrupt::Bind() assumes that all ISRs +in the ISR table have been bound, by default, to the spurious interrupts handler function as done in initialising +the table. To bind an interrupt source, the spurious interrupts handler +is replaced with the provided ISR. The implementation prevents an ISR from +being bound to an interrupt source that is already bound, by assuming that +an unbound interrupt source is bound to the spurious interrupts handler.

The +implementation shows the basic idea but may need to be extended, especially +where chained +interrupts and/or multiple +interrupt sources and pseudo interrupt sources are involved.

Interrupt::Unbind() is the logical opposite +of Bind(), replacing the ISR with the spurious handler function. +The following code is the matching example implementation.

Note that functions in the Interrupt class +can be called from anywhere in kernel-side code, including ISRs, DFCs and +IDFCs, and kernel threads. You need to ensure that if you are manipulating +the ISR table, or any other structure that is shared, you need to disable interrupts +to prevent corruption of the data. Interrupts are disabled and re-enabled +using NKern::DisableAllInterrupts() and NKern::RestoreInterrupts().

ASSP Extension and Variant DLL configuration

When +a common ASSP extension is used, the Variant DLL may have to implement extra +interrupt binding and dispatch functions for the device-specific interrupts.

The +following code is an example of an implementation of Interrupt::Bind() in +the ASSP layer, where negative Interrupt IDs represent device specific interrupts.

The default device specific implementation of the VariantBind() function +might be as follows:

TInt TMyAsic::VariantBind( TInt aId, TIsr aIsr, TAny* aPtr ) + // Default implementation when device specific layer does not override + // and this is therefore an illegal aId. + { + return KErrArgument; + } +

The device specific implementation of VariantBind() would +follow the same general pattern as for the Interrupt::Bind() function +in the ASSP layer. The main difference is that the code refers to the device +specific ISR table, VariantHandlers[], defined within the +device specific layer, and the interrupt ID is converted to a positive number +so that it can be used as an index into this table:

SInterruptHandler VariantHandlers[KNumVariantInts]; EXPORT_C TInt TMyVariant::VariantBind(TInt aId, TIsr aIsr, TAny* aPtr) + { + TInt r = KErrNone; + aId = (-aId)-1; // convert to positive number >=0 + If (aId >= KInterruptSourceCount || aId < 0) + { + r = KErrArgument; // Illegal interrupt number + } + else + { + SInterruptHandler& h = VariantHandlers[aId]; + TInt irq = NKern::DisableAllInterrupts(); + if (h.iIsr != VariantSpuriousHandler) + { + r = KErrInUse; // Already bound to an ISR + } + else + { + h.iPtr = aPtr; + h.iIsr = anIsr; + } + NKern::RestoreInterrupts(irq); + } + return r; + }

Now you need a way of dispatching the interrupts and +since this is really a chained interrupt, the dispatch function can be packaged +as an ISR and bound to the core interrupt source it chains from. See IRQ and FIQ Dispatchers in +general and Dealing +with chained interrupts in particular.

+ +Interrupts in the split ASSP/Variant Configuration + +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-8B8CAEED-A89D-53B3-A311-51CF45B334B1.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-8B8CAEED-A89D-53B3-A311-51CF45B334B1.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,178 @@ + + + + + +IRQ +and FIQ DispatchersThe ASSP must supply two dispatcher functions, one for IRQ interrupts, +and one for FIQ interrupts. +

The following example code is a simple dispatcher for IRQ interrupts. +It assumes a simplistic interrupt controller that provides 32 interrupt sources, +and has a 32-bit pending-interrupt register where a 'one' bit indicates a +pending interrupt and all ones are cleared when the register is read.

+void IrqDispatch() + { + TUint32 pendingIrqs = TheAssp::IrqPendingRegister(); + // for the purposes of this example we assume that reading + // this register also clears the pending flags + + TInt index = 0; + while( pendingIrqs ) + { + // while there is at least one pending IRQ + if( pendingIrqs & 1 ) + { + // the next interrupt is pending - dispatch it + (IsrHandlers[index].iIsr)(IsrHandlers[index].iPtr); + } + ++index; + pendingIrqs >>= 1; + } + } + +

The code assumes that the interrupt source represented by the low order +bit in the pending-interrupt register is represented by interrupt ID number +0 etc.

When implementing the dispatcher it is usual to write it in C++ initially, +but once you have it working you would probably want to rewrite it in assembler +to gain maximum efficiency for what is a time-critical section of code.

Dealing with +chained interrupts

There are two considerations when dealing with chained +interrupts:

how to identify interrupts +on the lower priority chained controllers
how to handle the dispatch +of a chained interrupt.

The first point is a question of allocating locations in your ISR +table for the secondary controllers so that the interrupt ID identifies which hardware controller the interrupt is +on. For example, if each interrupt controller handles 32 interrupt sources, +you could make the first 32 IDs refer to the highest-level controller, the +next 32 refer to one of the second-level controllers etc.

There is +no need to change the Interrupt::Bind() and Interrupt::Unbind() functions, +although you may need to consider extending the Interrupt::Enable() and Interrupt::Disable() functions +to enable and disable the chain interrupt in a higher-level interrupt controller, +if necessary.

There are at least two ways of dispatching a chained +interrupt:

Dispatching a chained interrupt (1)

One +way of dispatching a chained interrupt is simply to make it a special case +in the main interrupt dispatcher. For example:

This approach works for a simple case, for example, where +there is only a main and secondary interrupt controller. It is does not scale +well because the special cases in the dispatcher become an overhead on the +dispatch of normal, unchained interrupts as the number and depth of the chaining +increases.

Dispatching a chained interrupt (2)

A better +way of handling chained interrupts is to bind an ISR to the interrupt source +in the main interrupt controller and use it to dispatch the chained interrupt. +This is far more scalable because you can bind any number of ISRs without +having to add special cases to any of the interrupt dispatchers.

The +dispatcher code could then be re-implemented as:

void IrqDispatch() + // MAIN IRQ DISPATCHER, FIRST-LEVEL INTERRUPT + { + TUint32 pendingIrqs = TheAssp::IrqPendingRegister(); + + TInt index = 0; + while( pendingIrqs ) + { + if( pendingIrqs & 1 ) + { + (IsrHandlers[index].iIsr)(IsrHandlers[index].iPtr); + } + ++index; + pendingIrqs >>= 1; + } + } + void SecondLevelIrqDispatch( TAny* /* aParam */ ) + { + TUint32 pendingIrqs = TheAssp::SecondLevelIrqPendingRegister(); + + TInt index = EStartOfSecondLevelIntId; + while( pendingIrqs ) + { + if( pendingIrqs & 1 ) + { + (IsrHandlers[index].iIsr)(IsrHandlers[index].iPtr); + } + ++index; + pendingIrqs >>= 1; + } + } + void InitialiseSecondLevelDispatch() + // Bind and enable the second-level dispatcher + { + Interrupt::Bind(EMainIntChainIrq,SecondLevelIrqDispatch,NULL); + Interrupt::Enable( EMainIntChainIrq ); + } + +Interrupt sources + +

The second level dispatcher, SecondLevelIrqDispatch(), +is itself an ISR, and takes a TAny * parameter, but is +not needed in this specific example. It reads the interrupt pending register +of the second-level interrupt controller. Note, however, that the TAny * +parameter may be useful when the second level dispatcher is in the variant +as opposed to the ASSP. In that case you have separate interrupt IDs for variant +level interrupts and separate ISR tables. The TAny * parameter +can point to the appropriate ISR table. Alternatively the TAny * +can point to a data block containing IO addresses - especially useful if you +have many I/O devices mapped as hardware chunks. See the code in ...\assabet\specific\variant.cpp.
The index count starts +at offset EStartOfSecondLevelIntId into the ISR table, where +the second-level interrupt ISRs are located. In this example, this symbol +would equate to 32.
EMainIntChainIrq is +the interrupt ID of the chained interrupt source to the main interrupt controller.

Dealing with multiple interrupt sources

The case +where multiple peripherals are connected to the same interrupt source can +be handled through the technique of pseudo interrupt sources. This involves +assigning pseudo-interrupt IDs in the ISR table to correspond to each of the +peripherals that is attached to the interrupt line, i.e. ISRs are bound to +these pseudo-interrupt sources.

Dealing with pseudo interrupt sources +is, in essence, a special case of Chained +interrupts.

The dispatcher can do one of two things:

examine the peripheral +hardware to determine which of the interrupts are pending, and then call the +appropriate ISR
call all the ISRs and +leave them to determine whether their peripheral is actually signalling an +interrupt.

As usual, it is entirely up to you to choose the ID numbers for these +pseudo-interrupts.

There should be no need to alter the implementations +of Interrupt::Bind() or Interrupt::Unbind() but +you will need some special handling in Interrupt::Enable() to +enable the true interrupt source, and Interrupt::Disable() to +disable this interrupt source.

Dispatching the interrupt can be done +in either of the two ways described in dealing with chained interrupts. Making use of a special case in the main interrupt +dispatcher is acceptable for simple cases, but for more complicated cases +with large numbers of pseudo-interrupts or a combination of chained and pseudo-interrupts, +it is better to use an ISR dispatcher bound to the true interrupt source.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-8BA1EEC2-78A3-54CC-95D9-81BF2659963D.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-8BA1EEC2-78A3-54CC-95D9-81BF2659963D.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,454 @@ + + + + + +Base +Starter TechnologyThis topic describes the purpose of the Base Starter, and which +parts of it can be customised by phone developers. +

The purpose of the Base Starter is to:

Define a handset's local +drives
Define what file systems +(.FSY) and file extensions (.FXT) +are to be mounted on those drives
Associate drive letters +with drives
Modify drive start-up +behaviour
Enable fair +scheduling and file caching on a drive by drive basis.

Handset manufacturers need to customise the Base Starter as part of the +process of porting Symbian platform to a new device. Mapping local drives is the most important part of this process, but customisation +using TFSStartup is also possible.

Note that there are some activities +that the Base Starter does not do

Mapping local +drives

There are two ways to do this:

Create local drive mapping files
Use automatic local drive mapping.

Create local drive mapping +files

A local drive mapping file is an ASCII text file that explicitly +defines the drive letter, file system, and file extension to be associated +with a drive. The file contains a set of records, one for each drive, that +specifies this information. Records are also referred to as drive mappings.

The +file is created as part of your hardware variant's source tree, but is copied +into a standard location in your ROM filing system when you build the ROM.

A +drive mapping file has a formal structure; the main rules are:

the file can contain +a maximum of 16 different drive mappings
each drive mapping is +represented by a separate record; each record occupies one line; each line +is separated by the new line character \n
information is represented +by items separated by at least one blank character
comments can occupy +a whole line or can be added onto the end of a record (i.e. at the end of +line). They are marked by a # character that must precede +the start of the comment text.

A record, or drive mapping, has the following items, each separated +by at least one blank character. Each item must appear in the order described:

<drive_letter> <drive_number> <file_system_filename> <file_system> <file_extension_filename> <flags> + + + +

<drive_letter>

A single character between A and Z followed +by a colon.

+ + +

<drive_number>

The local drive number associated with the drive letter .

+ + +

<file_system_filename>

The filename of the file system that is to be mounted on the drive. +This should be the filename without the .FSY extension. +If it is necessary to omit a file system file name for any reason, then this +item should contain the null character: 0.

+ + +

<file_system>

The name of the file system as implemented by <file_system_filename>.

If +the file system name is the same as the file name, as represented by the <file_system_filename> item, +then supply the null character 0. [Internally, the file system +name is sometimes referred to as the object name.]

Symbian platform +supplies the following file systems:

FAT
ROFS - +read/only file system
LFFS - +logging flash file system
COMP - +composite file system (but see the description of the FS_COMPOSITE flag +below)

Handset manufacturers may supply other file systems.

+ + +

<file_extension_filename>

The filename of the file extension that is to be mounted on the +drive. This should be the filename without the .FXT extension. +If it is necessary to omit a file extension file name for any reason, then +this item should contain the null character: 0.

+ + +

<flags>

A set of mount flags that modify the start-up behaviour of +the local drive. More than one flag can be specified, each separated by a +comma, with no intervening blank characters. If no flags apply, then the null +character: 0 must be coded.

+ + + +

FS_FORMAT_ALWAYS

Formats the drive as soon as it has been mounted.

+ + +

FS_FORMAT_COLD

Formats the drive as soon as it has been mounted if the device is +performing a cold boot. This is generally required for internal RAM drives.

+ + +

FS_FORMAT_CORRUPT

Formats the drive, if it is found to be corrupt when mounted.

+ + +

FS_DISMNT_CORRUPT

Dismounts the drive, if it is found to be corrupt when mounted. +The local drive mapping remains unaltered and the associated file system file +is not unloaded.

+ + +

FS_SWAP_CORRUPT-<drv>

Dismounts the drive, if it is found to be corrupt when mounted, +and swaps the mappings for this drive with the alternative drive <drv>, +and remounts both.

The alternative drive <drv> must +be specified, and must follow a '-' character, which follows +the FS_SWAP_CORRUPT symbol.

For example, to swap +with drive Y:, specify:

FS_SWAP_CORRUPT-Y

This +option is commonly used when handling corrupt flash user-data drives on C:. +The corrupt drive is mapped to another drive letter – allowing data to be +extracted from it. The C: drive is replaced by a RAM +disk – providing a temporary work disk for the OS, while the main one is restored. +Note that a mapping file must not specify more than one drive for swapping, +i.e. there can only be one occurrence of FS_SWAP_CORRUPT flag +per mapping file.

Both drives involved in the swap must be internal +drives.

+ + +

FS_SYNC_DRIVE

Mounts this drive as a synchronous drive. This means that requests +are handled in the main file server thread rather than in a dedicated drive +thread. This option is normally only specified for internal RAM drives.

+ + +

FS_SCANDRIVE

Runs Scandrive, once mounted, but only if the +rugged file system is enabled.

+ + +

FS_COMPOSITE

Marks the drive as contributing to the composite file system. The +composite file system allows multiple local drives to be overlaid with each +other, and with the core OS ROM image, and to make them appear as one drive.

Files +in one drive can add to, replace, or hide (i.e. logically remove) files in +another drive

There are number of rules:

the drive letter must +always be Z:
if the file system is +omitted, i.e. both <file_system_filename> and <file_system> are +set to '0', then the the ROFS file system is assumed, and this can be the only drive +marked with FS_COMPOSITE in a mapping file.
if the file system is +explicitly specified, i.e. <file_system_filename> and <file_system> are +set, then more than one drive can be marked with FS_COMPOSITE. +However, adding a drive that uses a file system other than ROFS is strongly +discouraged for performance reasons.
the order of the records +is important, as this defines the search order when Symbian platform is working +out which files will contribute to the final ROM. The core OS ROM file system +(containing the kernel, kernel extensions, media drivers, the file server, +file systems and the Base Starter executable) is searched first, followed +by the last drive in the mapping file marked with FS_COMPOSITE, +followed by the next last drive marked with FS_COMPOSITE etc.

Note: the use of COMP as a <file_system> seems +to contradict the use of this flag. COMP was used to specify +a composite file system that allowed a single drive to be combined +with the ROM file system. For compatibility purposes, and to ensure consistency +of syntax, you can still specify COMP with FS_COMPOSITE on +a drive mapping, but you cannot have any other drive mappings marked as FS_COMPOSITE. +If you specify COMP, then the underlying file system associated +with that drive is assumed to be ROFS.

See Mounting multiple ROM images +as a single ROM drive for more detail.

+ + +

FS_NO_MOUNT

Loads the file specified file system and the specified file extension, +and maps the drive as specified, but does not mount the drive. This is often +used in conjunction with FS_SWAP_CORRUPT. It allows the configuration +for the alternative drive involved in a swap to be specified – but for the +drive not to be mounted and accessible in normal operation. If the drive is +involved in a swap with another, then the FS_NO_MOUNT state +is ignored and the drive is mounted normally.

+ + +

FS_ALLOW_REM_ACC

This is reserved for future use.

+ + +

FS_NOT_RUGGED

Marks the mount as not rugged. Mounting the drive without the rugged +file system means that FS_SCANDRIVE is not supported. If FS_SCANDRIVE is +also defined, it is ignored.

+ + +

FS_SYSTEM_DRIVE

Assigns this drive as the system drive. Applications store user +data on the system drive, and call RFs::GetSystemDriveChar() to +discover the drive letter.

A mapping file can only specify one drive +as the system drive.

See the +system drive.

+ + + +

Use automatic local drive +mapping

If no drive mapping file exists or is unavailable, the +Base Starter decides which file system to mount on each local drive by interrogating +the capabilities of those drives. This is known as auto-detection.

Internally, +the Base Starter holds a table containing entries for every known supported +local drive configuration. This table is known as the auto-configuration table. +The information supplied by each entry in the table resembles that supplied +by a local +drive mapping file, and contains the following information:

The filename of the +file system for this configuration (the .FSY). The filename +corresponds to the <file_system_filename> item in a drive +mapping file entry.
The object name of the +file system for this configuration. The object name corresponds to the <file_system> item +in a drive mapping file entry.
The filename of the +file server extension for this configuration, if applicable. The filename +corresponds to the <file_system> item +in a drive mapping file entry.
The set of mount flags; +these correspond to the <flags> items in a drive mapping +file entry. There is one exception - FS_SWAP_CORRUPT is not +supported, because it is impossible to auto-detect which drive is to be swapped.
A file system identification +function that is used to decide whether the designated file system is really +suitable for this drive. Each function is an internal part of the generic +Base Starter code.

The Base Starter uses the following default mapping of drive letters +to drive numbers:

+ + + +

Local drive number

Drive letter

+ + +

+ + + +

Customisation +using TFSStartup

Most of the functionality provided by the Base +Starter is provided by the class TFSStartup. +This contains a number of virtual functions with default Symbian implementations. +A handset manufacturer can create a customised version of the Base Starter, +which overrides these functions.

Disabling drive auto-detection
Customising for multiple hardware states
Overriding the default drive mapping
Customising mount flags
Customising the drive initialisation sequence
Customising Loadlocale
Customising the restart mode
Customising other behaviour

Disabling drive auto-detection

The +most common customisation is to use the supplied version of the Base Starter +and to create one or more local drive mapping files . In this case, savings +in code space can be made by removing the code that deals with auto-detection. +This is achieved by adding the following line to the MMP file +describing the Base Starter, and then rebuilding it.

MACRO AUTODETECT_DISABLE

Customising for multiple +hardware states

If the state of your hardware varies, and it requires +different mapping files for different states, then it is still possible to +use the local drive mapping scheme. Examples of hardware state variations +might be differences in the state of a switch or jumper setting, or the presence +or absence of a hardware feature. In this situation, the ROM can be built +with more than one mapping file. A custom version of the Base Starter provides +its own version of the virtual function TFSStartUp::LocalDriveMappingFileName(); +this checks the appropriate settings, and returns the name of the appropriate +local drive mapping file. The returned name is the full path name.

Overriding the default drive +mapping

To override the default mapping of drive letters to drive +numbers on a drive by drive basis, a custom version of the Base Starter provides +its own version of the virtual function TFSStartUp::DefaultLocalDrive().

To +override the auto-configuration table used by the automatic local drive mapping +scheme, for example to add support for a new .FSY, a +custom version of the Base Starter provides its own version of the virtual +function TFSStartUp::GetNextStandardFSInfoEntry().

Customising mount flags

Whether +you use the automatic local drive mapping scheme or an explicit local drive +mapping file, you can provide support for additional mount flags. A custom +version of the Base Starter provides its own version of the virtual functions:

TFSStartUp::ParseCustomMountFlags()
TFSStartUp::HandleCustomMountFlags()

Customising the drive initialisation +sequence

To override the entire local drive initialisation sequence +provided by the generic version of the Base Starter, a custom version of the +Base Starter provides its own version of the virtual function TFSStartUp::LocalDriveInit().

Customising Loadlocale

User::UTCOffset() is called within the LoadLocale() function. Customise TFSStartup::LoadLocale() so +that the offset behaviour is correct for your time zone.

Setting the User::UTCOffset() is required within EStart +to provide backward compatibility and because it provides the system time +to components before the timezone/locale services are initialised.

See setting the universal time +offset.

Customising the restart +mode

TFSStartup::GetStartupMode() and TFSStartup::GetStartupModeFromFile() must be +implemented to get the restart mode at start-up.

Symbian platform +does not define any meaning to restart mode values. It is for the use of the +device manufacturer.

The restart mode is defined by the HAL attribute EPersistStartupM. This is a TAttribute enum +value defined in class HALData in ..\hal\inc\hal_data.h.

To +use this attribute, define it in your variant’s config.hcf file +and set an initial value in your variant’s values.hda file. +The template port defines the attribute as settable using the following definition +in the config.hcf file.

EPersistStartupModeKernel : set = ProcessPersistStartupMode

The value can be changed using HAL::Set(). ProcessPersistStartupMode is +the name of a function internal to Symbian platform. If you choose to make +the attribute settable, you must use this definition.

Calls to HAL::Get() are routed to the function Template::VariantHal() in +your variant's variant.cpp file, and handled by the EVariantHalGetPersistedStartupMode case.

Calls +to HAL::Set() are routed to the function Template::VariantHal() in +your variant's variant.cpp file, and handled by the EVariantHalPersistStartupMode case.

You +need to do the following:

If you choose to make +the custom startup mode settable (in Symbian platform terminology, the attribute +is said to be derived), you need to implement TFSStartup::GetStartupMode(). +Derived attributes are saved when the system is closed down. The function GetStartupMode() is +called before the file server starts.
If you choose to make +the custom startup mode non-settable (in Symbian platform terminology, the +attribute is said to be non-derived), you need to implement TFSStartup::GetStartupModeFromFile(). +Non-derived attributes are read from file, and this function is called after +the file server has started.
You need to provide +an implementation for your Template::VariantHal() function +in your variant.cpp file.

The example below is the OMAP H4 variant implementation of GetStartupModeFromFile() and GetStartupMode() found +in ...\dev1\omap_hrp\h4estart\estartmain.cpp.

TInt TH4FSStartup::GetStartupModeFromFile() + { + if (iStartupMode != EStartupModeUndefined) + { + TInt r = ReadAndReset(); + return r; + } + return KErrNone; + } + +TInt TH4FSStartup::GetStartupMode() + { + TInt r = ReadAndReset(); + return r; + } + +TInt TH4FSStartup::ReadAndReset() + { + TInt value; + TInt r = HAL::Get(HALData::EPersistStartupModeKernel, value); + if (r == KErrNone) + { + iStartupMode = value; + } + r = HAL::Set(HALData::EPersistStartupModeKernel, EStartupModeUndefined); + return r; + }

See User-Side +Hardware Abstraction.

Customising other behaviour

You +can change other default behaviour. For example, to add additional functionality +related to File Server initialisation, or the initialisation of other base +related components, then the following virtual functions can also be customised. +Follow the links to the individual functions for more detail:

TFSStartup::Init()
TFSStartup::Run()
TFSStartup::InitialiseHAL()
TFSStartup::StartSystem()
TFSStartup::Close()

Activities +that the Base Starter does not do

The Base Starter is responsible +for mapping local drives to drive letters and for loading the appropriate +file systems on local drives. It does not install media drivers, and +is not responsible for deciding which local drive a media driver will register +with. This is done by the individual media drivers and peripheral controllers +when they are initialised.

See Registering +the media driver for information about how to register a media driver.

See +also Local +Media Subsystem.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-8C22AF20-EE0E-5AD2-BEFD-FED5A7DBB09B.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-8C22AF20-EE0E-5AD2-BEFD-FED5A7DBB09B.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,25 @@ + + + + + +LCD +ExtensionThe LCD Extension is a kernel extension that manages the +screen hardware. This section describes how to create a port of it +for your phone hardware. +

The user-side interface to the LCD Extension is defined +by the EHalGroupDisplay group of HAL functions defined +by the User-Side Hardware Abstraction (HAL). The LCD Extension implements +a handler for this group of functions.

+ +User-Side Hardware Abstraction +Implementing +Dynamic DSA Allocation +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-8C9F26BC-2579-545C-9A86-9C45E06679F0-master.png Binary file Adaptation/GUID-8C9F26BC-2579-545C-9A86-9C45E06679F0-master.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-8C9F26BC-2579-545C-9A86-9C45E06679F0_d0e32265_href.png Binary file Adaptation/GUID-8C9F26BC-2579-545C-9A86-9C45E06679F0_d0e32265_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-8D237BD6-9759-4180-B190-F1624594017F.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-8D237BD6-9759-4180-B190-F1624594017F.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,76 @@ + + + + + +Time Client Interface Tutorial — Using the InterfaceProvides examples of how the Time client interface is used. +

The Time client interface methods can be executed independently. +The following examples show the Time client interface functions being +used along with an explanation.

Using +the <xref href="GUID-CC79A63E-15DF-3437-983B-9A90966B3004.dita#GUID-CC79A63E-15DF-3437-983B-9A90966B3004/GUID-AC7C2EFB-BE71-301A-9C03-A15BDC0EF310"><apiname>MRtcAdaptation::ValidateRtc()</apiname></xref> function

An example of the use of this function is:

MRtcAdaptation* rtcAdaptation = NewRtcAdaptationL(); +TPckgBuf<TBool> boolPckg; +TRequestStatus status; + +rtcAdaptation->ValidateRtc(boolPckg, status); +

The first three lines define the instance of the MRtcAdaptation class and the variables that are to be used.

The fifth line invokes the MRtcAdaptation::ValidateRtc() method. The first parameter will return the validity of the Real +Time Clock (RTC) as a boolean value. The second parameter returns +the completion status of the request. If the RTC clock is valid, then +this would be KErrNone.

Using +the <xref href="GUID-69C70CA3-1121-3C5B-AEA4-B2E0245539B9.dita#GUID-69C70CA3-1121-3C5B-AEA4-B2E0245539B9/GUID-2D7976BE-F6D5-3FC4-8253-C34A592A63D3"><apiname>ASIC::SetSystemTimeCalibration()</apiname></xref> function

An example of the use of this function is:

Asic Asic_class; +TInt r; +r = Asic_class::SetSystemTimeCalibration(30);

In the +above example, the RTC is being set with a time calibration value +of 30ppm (parts per million). This means that the RTC can lose up +to one second every 30 million seconds.

The value returned by +this function is either KErrNone or a system wide +error code if something went wrong.

Using +the <xref href="GUID-C82E90BC-451B-3BB4-83E0-243061BCFA14.dita#GUID-C82E90BC-451B-3BB4-83E0-243061BCFA14/GUID-611E6535-9CCA-39E3-8236-654FF280B7CD"><apiname>MRtcAdaption::SetWakeUpAlarm()</apiname></xref> function

An example of the use of this function is:

TPckgC <TTime> timePckg(testTime); + rtcAdaptation->SetWakeupAlarm(timePckg, status);

In +the above example, the first line declares the variable to be used +and initializes it. The second line is used to set the wake-up alarm +time.

Using +the <xref href="GUID-CC79A63E-15DF-3437-983B-9A90966B3004.dita#GUID-CC79A63E-15DF-3437-983B-9A90966B3004/GUID-C2A7DE1F-6354-31D6-A397-5CE690C4C67E"><apiname>MRtcAdaptation::UnsetWakeUpAlarm()</apiname></xref> function

An example of the use of this function is:

TRequestStatus status; +rtcAdaptation->UnsetWakeupAlarm(status); +

The first line declares the variable that is to be +used. The second line deletes the current device wake-up alarm time.

Using +the <xref href="GUID-CC79A63E-15DF-3437-983B-9A90966B3004.dita#GUID-CC79A63E-15DF-3437-983B-9A90966B3004/GUID-ADC7041A-23F0-319F-A163-29E8BB261D0B"><apiname>MRtcAdaptation::Cancel()</apiname></xref> function

An example of the use of this function is:

rtcAdaptation->Cancel(); +

In the above example, the last request made to the +instance of the MRtcAdaptation class, defined as rtcAdaptation in the above example, will be deleted.

Using +the <xref href="GUID-CC79A63E-15DF-3437-983B-9A90966B3004.dita#GUID-CC79A63E-15DF-3437-983B-9A90966B3004/GUID-C44E98E9-6568-3628-9A7E-85379C4298FD"><apiname>MRtcAdaptation::Release()</apiname></xref> function

An example of the use of this function is:

rtcAdaptation->Release(); +

In the above example, a call to the destructor in the +instance of the MRtcAdaptation class, defined as rtcAdaptation in the above example, is made.

Using +the <xref href="GUID-69C70CA3-1121-3C5B-AEA4-B2E0245539B9.dita#GUID-69C70CA3-1121-3C5B-AEA4-B2E0245539B9/GUID-EE99A729-F30E-3B3A-BCA2-0F10B383AB6C"><apiname>ASIC::SystemTimeInSecondsFrom2000()</apiname></xref> function

An example of the use of this function is:

Asic Asic_class; +TInt hwrtc = 0; +Asic_class::SystemTimeInSecondsFrom2000(hwrtc); +

The first and second lines declare and initialize the +variables and classes that are to be used. The third line calls the ASIC::SystemTimeInSecondsFrom2000() function. The number +of seconds since the start of the year 2000 is placed in the variable +that has been passed as a parameter.

The value returned by this +function is either KErrNone or a system wide error +code (if something went wrong).

Using +the <xref href="GUID-69C70CA3-1121-3C5B-AEA4-B2E0245539B9.dita#GUID-69C70CA3-1121-3C5B-AEA4-B2E0245539B9/GUID-C6983BB7-6496-3863-8109-6845F5DA62CF"><apiname>ASIC::SetSystemTimeInSecondsFrom2000()</apiname></xref> function

An example of the use of this function is:

Asic Asic_class; +TInt r=0; +r = Asic_class::SetSystemTimeInSecondsFrom2000(0);

The +first and second lines declare and initialize the variables and classes +that are to be used. The third line sets the RTC to be zero seconds +from the start of the year 2000.

The value returned by this +function is either KErrNone or a system wide error +code (if something went wrong).

+Time +Implementation Guide +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-8D7ED882-C61E-4B4F-8483-A323C60BFC57.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-8D7ED882-C61E-4B4F-8483-A323C60BFC57.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,112 @@ + + + + + +Register Access Interface OverviewProvides a summary of the Register Access platform service +interface. +

The Register Access platform service is provided by functions of +the AsspRegister class. The AsspRegister class is defined in the os/kernelhwsrv/kernel/eka/include/kernel/arm/assp.h file. The functions defined in the AsspRegister class must be implemented +in the baseport variant to allow device drivers and other kernel side +code to access registers.

+ Register read functions + + + +API +Description + + + + +AsspRegister::Read8(TLinAddr aAddr) +Read the contents of an 8 bit register + + +AsspRegister::Read16(TLinAddr aAddr) +Read the contents of a 16bit register + + +AsspRegister::Read32(TLinAddr aAddr) +Read the contents of a 32 bit register + + +AsspRegister::Read64(TLinAddr aAddr) +Read the contents of a 64 bit register + + + +

Register +write functions + + + +API +Description + + + + +AsspRegister::Write8(TLinAddr aAddr, TUint8 aValue) +Store a new value in an 8 bit register. + + +AsspRegister::Write16(TLinAddr aAddr, TUint16 aValue) +Store a new value in a 16 bit register. + + +AsspRegister::Write32(TLinAddr aAddr, TUint32 aValue) +Store a new value in a 32 bit register. + + +AsspRegister::Write64(TLinAddr aAddr, TUint64 aValue) +Store a new value in a 64 bit register. + + + +

The difference between write and modify +functions is that the modify function allows the client to change +partial contents of a register using masks.

+ + + +API +Description + + + + +AsspRegister::Modify8(TLinAddr aAddr, TUint8 aClearMask, +TUint8 aSetMask) +Modify the contents of an 8 bit register. + + +AsspRegister::Modify16(TLinAddr aAddr, TUint16 aClearMask, +TUint16 aSetMask) +Modify the contents of a 16 bit register. + + +AsspRegister::Modify32(TLinAddr aAddr, TUint32 aClearMask, +TUint32 aSetMask) +Modify the contents of a 32 bit register. + + +AsspRegister::Modify64(TLinAddr aAddr, TUint64 aClearMask, +TUint64 aSetMask) +Modify the contents of a 64 bit register + + + +

The header file for the Registry Access platform service +can be found here.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-8D9A9283-6E55-4AC8-89CE-DD2B55D05067.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-8D9A9283-6E55-4AC8-89CE-DD2B55D05067.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,20 @@ + + + + + +Time Technology GuideDescribes the technology involved in the Time platform +service. +

Real-time +clock

A real-time clock is a chip that keeps +track of elapsed time. It is more accurate and consumes less power +than computing time from elapsed execution cycles.

Alarms

The real-time clock can generate interrupts at specific times. +This provides a reliable alarm mechanism.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-8DC12024-7599-52E8-BCF1-D9D765EC7B9B.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-8DC12024-7599-52E8-BCF1-D9D765EC7B9B.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,12 @@ + + + + + +Dynamic BehaviourDescribes the behaviour of the Sound Driver for and record operations. \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-8EB25927-D49E-578F-BD93-294C4EECB7E7.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,809 @@ + + + + + +Basic +APIsAccessing APIs and basic functions in kernel-side programs. +

Device drivers, like user-side programs, need to use APIs for basic tasks +such as managing buffers and arrays. However, the EKA2 architecture does not +allow kernel-side programs such as drivers to link and use the User Library +(euser.dll) that provides these APIs to user-side programs. +This means kernel side code cannot use the majority of classes and +functions that are available to user side code.

However, some classes are available for use on both the user side and the +kernel side. The first section of this document, Available EUSER functionality, explains what these are. In other cases, +there are alternative Kernel-specific APIs or techniques that you can use. +The second section, Coding +techniques to replace EUSER functionality, describes these.

The detailed contents are given below:

Contents

Available EUSER functionality
- 8-bit descriptors
- Arrays
- Character representation
- Basic utility functions and classes
- The Package Buffers API
- The UID manipulation APIs
- Version handling API
- TRequestStatus
- TIpcArgs
- Basic graphic classes
Coding techniques to replace EUSER functionality
- Buffers: replacing HBufC8 with HBuf
- Buffers: replacing HBufC8 with C style pointers
- Handling 16-bit data items
- Replacing CBase with DBase
- Replacing User::QueryVersionSupported() with Kern::QueryVersionSupported()

Available EUSER +functionality

This is a list of USER side classes, types and APIs +that can still be used on the kernel side. However, a subset of the class +member functions may not be available.

8-bit descriptors
Arrays
Character representation (TChar)
Basic utility functions and classes
The Package Buffers API
The UID manipulation APIs
Version handling API
TRequestStatus
TIpcArgs
Basic graphic classes

8-bit descriptors

The +following classes, defined in e32des8.h, can be +used on the kernel side.

For some classes, the kernel side can use +the same member functions that are available to the user side. However, for +other classes, the kernel side is restricted to using a subset of functions; +where this is the case, the functions are listed

+ + + +

Classes available

Public member functions that are available to kernel side code

+ + +

TDesC8

TInt operator<(const TDesC8 &aDes) const;

TInt +operator<=(const TDesC8 &aDes) const;

TInt +operator>(const TDesC8 &aDes) const;

TInt operator>=(const +TDesC8 &aDes) const;

TInt operator==(const +TDesC8 &aDes) const;

TInt operator!=(const +TDesC8 &aDes) const;

const TUint8 &operator[](TInt +anIndex) const;

TInt Length() const;

TInt +Size() const;

const TUint8 *Ptr() const;

TInt +Compare(const TDesC8 &aDes) const;

TInt Match(const +TDesC8 &aDes) const;

TInt MatchF(const TDesC8 +&aDes) const;

TInt MatchC(const TDesC8 &aDes) +const;

TInt Locate(TChar aChar) const;

TInt +LocateReverse(TChar aChar) const;

TInt Find(const +TDesC8 &aDes) const;

TInt Find(const TUint8 +*pS,TInt aLenS) const;

TPtrC8 Left(TInt aLength) +const;

TPtrC8 Right(TInt aLength) const;

TPtrC8 +Mid(TInt aPos) const;

TPtrC8 Mid(TInt aPos,TInt +aLength) const;

TInt CompareF(const TDesC8 &aDes) +const;

+ + +

TDes8

TDes8& operator=(const TUint8 *aString);

TDes8& +operator=(const TDesC8 &aDes);

TDes8& operator=(const +TDes8 &aDes);

TInt MaxLength() const;

TInt +MaxSize() const;

const TUint8 &operator[](TInt +anIndex) const;

TUint8 &operator[](TInt anIndex);

TDes8 +&operator+=(const TDesC8 &aDes);

void Zero();

void +SetLength(TInt aLength);

void SetMax();

void +Copy(const TDesC8 &aDes);

void Copy(const TUint8 +*aBuf,TInt aLength);

void Copy(const TUint8 *aString);

void +Copy(const TDesC16 &aDes);

void Append(TChar +aChar);

void Append(const TDesC8 &aDes);

void +Append(const TDesC16 &aDes);

void Append(const +TUint8 *aBuf,TInt aLength);

void Fill(TChar aChar);

void +Fill(TChar aChar,TInt aLength);

void FillZ();

void +FillZ(TInt aLength);

void Num(TInt64 aVal);

void +Num(TUint64 aVal, TRadix aRadix);

void NumFixedWidth(TUint +aVal,TRadix aRadix,TInt aWidth);

void +AppendNum(TInt64 aVal);

void AppendNum(TUint64 +aVal, TRadix aRadix);

void AppendNumFixedWidth(TUint +aVal,TRadix aRadix,TInt aWidth);

+ + +

TPtrC8

Same as for user side code.

+ + +

TPtr8

Same as for user side code.

+ + +

TBufC8

Same as for user side code.

+ + +

TBuf8

Same as for user side code.

+ + +

TDes8Overflow

Same as for user side code.

+ + +

TLitC8

Same as for user side code.

+ + + +

Arrays

The +following classes, defined in e32cmn.h, can be +used on the kernel side.

+ + + +

Classes available

Public member functions that are available to kernel side code

+ + +

RArray <class T>

RArray();

RArray(TInt aGranularity);

RArray(TInt +aGranularity, TInt aKeyOffset);

RArray(TInt aMinGrowBy, +TInt aKeyOffset, TInt aFactor);

void +Close(); inline TInt Count() const;

const T& +operator[](TInt anIndex) const;

T& operator[](TInt +anIndex);

TInt Append(const T& anEntry);

TInt +Insert(const T& anEntry, TInt aPos);

void Remove(TInt +anIndex);

void Compress();

void +Reset();

TInt Find(const T& anEntry) const;

TInt +Find(const T& anEntry, TIdentityRelation<T> anIdentity) +const;

TInt FindInSignedKeyOrder(const T& anEntry) + const;

TInt FindInUnsignedKeyOrder(const +T& anEntry) const;

TInt +FindInOrder(const T& anEntry, TLinearOrder<T> +anOrder) const;

TInt FindInSignedKeyOrder(const +T& anEntry, TInt& anIndex) const;

TInt +FindInUnsignedKeyOrder(const T& anEntry, TInt& +anIndex) const;

TInt FindInOrder(const T& anEntry, +TInt& anIndex, TLinearOrder<T> anOrder) const;

TInt +SpecificFindInSignedKeyOrder(const T& anEntry, TInt +aMode) const;

TInt SpecificFindInUnsignedKeyOrder(const +T& anEntry, TInt aMode) const;

TInt +SpecificFindInOrder(const T& anEntry, TLinearOrder<T> +anOrder, TInt aMode) const;

TInt SpecificFindInSignedKeyOrder(const +T& anEntry, TInt& anIndex, TInt aMode) const;

TInt +SpecificFindInUnsignedKeyOrder(const T& anEntry, +TInt& anIndex, TInt aMode) const;

TInt SpecificFindInOrder(const +T& anEntry, TInt& anIndex, TLinearOrder<T> +anOrder, TInt aMode) const;

TInt InsertInSignedKeyOrder(const +T& anEntry);

TInt InsertInUnsignedKeyOrder(const +T& anEntry);

TInt InsertInOrder(const +T& anEntry, TLinearOrder<T> anOrder);

TInt +InsertInSignedKeyOrderAllowRepeats(const T& anEntry);

TInt +InsertInUnsignedKeyOrderAllowRepeats(const T& anEntry);

TInt +InsertInOrderAllowRepeats(const T& anEntry, TLinearOrder<T> +anOrder);

+ + +

RArray <TInt>

RArray();

RArray(TInt aGranularity);

RArray(TInt +aMinGrowBy, TInt aFactor);

void Close();

TInt +Count() const;

const TInt& operator[](TInt +anIndex) const;

TInt& operator[](TInt anIndex);

TInt +Append(TInt anEntry);

TInt Insert(TInt anEntry, +TInt aPos);

void Remove(TInt anIndex);

void +Compress();

void Reset();

TInt +Find(TInt anEntry) const;

TInt FindInOrder(TInt +anEntry) const;

TInt FindInOrder(TInt anEntry, +TInt& anIndex) const;

TInt +SpecificFindInOrder(TInt anEntry, TInt aMode) const;

TInt +SpecificFindInOrder(TInt anEntry, TInt& anIndex, +TInt aMode) const;

TInt InsertInOrder(TInt anEntry);

TInt +InsertInOrderAllowRepeats(TInt anEntry);

+ + +

RArray <TUint>

RArray();

RArray(TInt aGranularity);

RArray(TInt +aMinGrowBy, TInt aFactor);

void Close();

TInt +Count() const;

const TUint& operator[](TInt +anIndex) const;

TUint& operator[](TInt anIndex);

TInt +Append(TUint anEntry);

TInt Insert(TUint anEntry, +TInt aPos);

void Remove(TInt anIndex);

void +Compress();

void Reset();

TInt +Find(TUint anEntry) const;

TInt FindInOrder(TUint +anEntry) const;

TInt FindInOrder(TUint anEntry, +TInt& anIndex) const;

TInt +SpecificFindInOrder(TUint anEntry, TInt aMode) const;

TInt +SpecificFindInOrder(TUint anEntry, TInt& anIndex, +TInt aMode) const;

TInt InsertInOrder(TUint anEntry);

TInt +InsertInOrderAllowRepeats(TUint anEntry);

+ + +

RPointerArray <class T>

RPointerArray();

RPointerArray(TInt +aGranularity);

RPointerArray(TInt aMinGrowBy, TInt +aFactor);

void Close();

TInt +Count() const;

T* const& operator[](TInt anIndex) +const;

T*& operator[](TInt anIndex);

TInt +Append(const T* anEntry);

TInt Insert(const T* +anEntry, TInt aPos);

void Remove(TInt anIndex);

void +Compress();

void Reset();

void +ResetAndDestroy();

TInt Find(const T* anEntry) +const;

TInt Find(const T* anEntry, TIdentityRelation<T> + anIdentity) const;

TInt FindInAddressOrder(const +T* anEntry) const;

TInt FindInOrder(const T* anEntry, +TLinearOrder<T> anOrder) const;

TInt +FindInAddressOrder(const T* anEntry, TInt& anIndex) +const;

TInt FindInOrder(const T* anEntry, TInt& +anIndex, TLinearOrder<T> anOrder) const;

TInt +SpecificFindInAddressOrder(const T* anEntry, TInt aMode) +const;);

TInt SpecificFindInOrder(const T* anEntry, + TLinearOrder<T> anOrder, TInt aMode) const;

TInt +SpecificFindInAddressOrder(const T* anEntry, TInt& +anIndex, TInt aMode) const;

TInt SpecificFindInOrder(const +T* anEntry, TInt& anIndex, TLinearOrder<T> anOrder, +TInt aMode) const;

TInt InsertInAddressOrder(const +T* anEntry);

TInt InsertInOrder(const T* anEntry, + TLinearOrder<T> anOrder);

TInt +InsertInAddressOrderAllowRepeats(const T* anEntry);

TInt +InsertInOrderAllowRepeats(const T* anEntry, TLinearOrder<T> +anOrder);

+ + +

TIdentityRelation <class T>

Same as for user side code.

+ + +

TLinearOrder <class T>

Same as for user side code.

+ + + +

Character representation

The +following class, defined in e32cmn.h, can be used +on the kernel side.

For some classes, the kernel side can use the +same member functions that are available to the user side. However, for other +classes, the kernel side is restricted to using a subset of functions; where +this is the case, the functions are listed

+ + + +

Classes available

Public member functions that are available to kernel side code

+ + +

TChar

TChar();

TChar(TUint aChar);

TChar& +operator-=(TUint aChar);

TChar& operator+=(TUint +aChar);

TChar operator-(TUint aChar);

TChar +operator+(TUint aChar);

operator TUint() const;

+ + + +

Basic utility +functions and classes

The following global utility functions and +classes, defined in e32cmn.h, can be used on the +kernel side.

+ + + +

TRefByValue

+ + +

TInt Lim(TInt aVal,TUint aLimit);

+ + +

TInt LimX(TInt aVal,TUint aLimit);

+ + +

template <class T> T Min(T aLeft,T aRight);

+ + +

template <class T> T Min(T aLeft,TUint + aRight);

+ + +

template <class T> T Max(T aLeft,T aRight);

+ + +

template <class T> T Max(T aLeft,TUint + aRight);

+ + +

template <class T> T Abs(T aVal);

+ + +

template <class T> TBool Rng(T aMin,T aVal,T + aMax);

+ + +

template <class T,class S> T* PtrAdd(T* aPtr,S + aVal);

+ + +

template <class T,class S> T* PtrSub(T* aPtr,S + aVal);

+ + +

template <class T> T Align2(T aValue);

+ + +

template <class T> T Align4(T aValue);

+ + + +

The Package +Buffers API

The package buffers API, represented by classes defined +in e32cmn.h, can be used on the kernel side.

+ + + +

TPckgBuf

+ + +

TPckgC

+ + +

TPckg

+ + + +

The UID manipulation +APIs

The UID manipulation APIs, represented by classes defined +in e32cmn.h can be used on the kernel side. However, +only a subset of functions are available. See the detailed notes in +the following table.

+ + + +

TUid

Only the two inline functions can be used:

TUid::Uid
TUid::Null()

+ + +

TUidType

None of the member functions can be used; however, the iUid data +member is declared as public on the kernel side.

+ + +

TUidName

This will only ever be an 8-bit type descriptor.

+ + + +

Version handling +API

The version handling API, represented by the TVersion class +defined in e32cmn.h can be used on the kernel side.

TRequestStatus

The TRequestStatus class +representing the completion status of an asynchronous request, and defined +in e32cmn.h can be used on the kernel side.

TIpcArgs

The TIpcArgs class, which is part of the Version2 client/server APIs, +and defined in e32cmn.h, can be used on the kernel side. +However, the Set() and Type() member functions +that take 16-bit descriptors are not available.

Basic +graphic classes

The basic graphic classes TPoint and TSize are +defined on the kernel side. However, only the public data members are defined +- the member functions are not defined, and are not available for use.

Coding techniques +to replace EUSER functionality

Buffers: replacing HBufC8 with HBuf
Buffers: replacing HBufC8 with C style pointers
Handling 16-bit data items
Replacing CBase with DBase
Replacing User::QueryVersionSupported() with Kern::QueryVersionSupported()

Buffers: replacing +HBufC8 with HBuf

In EKA2, the heap descriptor buffer, HBufC8 is +not available. However, the kernel side defines and implements an equivalent +(kernel) heap descriptor buffer: HBuf8. HBuf8 is +behaves in a similar way to HBufC8, so nearly all of your +code can be reused, but note the following points:

If your code uses the +typedef HBufC, then you need to change it to HBuf.
On the kernel side, +there is no explicit support for 16-bit buffers, which means that there is +no class called HBuf16. In practice, this means that, HBuf is +always the same as HBuf8.
Unlike HBufC8, HBuf8 is +a modifiable type descriptor. It has TDes8 in its derivation +hierarchy, and this means that you can manipulate the descriptor's data (using +the TDes8 member functions).
The number of functions +available to create an HBuf8 object is more limited than +for HBufC8 - there are only three variants - although in +practice this is not a problem:
- HBuf8::New(TInt +aMaxLength) to allocate a heap descriptor buffer (on the kernel heap) +and set its length to zero; this behaves the same as the user side HBufC8::New(TInt +aMaxLength)
- HBuf8::New(const +TDesC8& aDes) to allocate a heap descriptor buffer (on the kernel +heap) and initialise it by copying an existing descriptor's data into it.
- HBuf8::ReAlloc(TInt +aNewMax) to re-allocate (i.e. to resize) a heap descriptor buffer +(on the kernel heap); this behaves the same as the user side HBufC8::New(TInt +aMaxLength)
There are no "leaving" +variants of these functions - if you have NewL(), NewLC(), and other "leaving" +variants, then you will need to change your code to explicitly check the return +code to make sure that the creation, or the reallocation of the heap descriptor +buffer has worked.
As the descriptor is +modifiable, there is no need for, and there is no equivalent of the function HBufC8::Des(); +you just use the base class TDes8 functions.
If your code uses the +assignment operators (i.e. the = operator), you don't need +to change your code; the compiler will use the operators implemented in the TDes8 base +class, which will do the right thing.
The descriptor function TDesC8::Alloc() is +no longer available on the kernel side, so you cannot create a heap descriptor +buffer from a general descriptor.

The following code fragments show code that is approximately equivalent +between EKA1 and EKA2. The fragments are a little artificial, and make assumptions +that would not necessarily be made in real code, but nevertheless still show +the essential differences.

+ + + +

EKA1

EKA2

+ + +

This is a function that allocates a heap descriptor buffer (HBufC8), +puts data into it, changes its size, replaces the data, deletes a part of +the data, and then deletes it.

_LIT8(KTxSmall,"abcdef"); +_LIT8(KTxBig,"ghijklmnopqrstuvwxyz"); + +void X::FunctionL() + { + // Create a buffer big enough to contain + // the text "abcdef". + // This uses the "leaving" variant, and leaves + // if there is insufficient memory. + HBufC8* pBuf = HBufC8::NewL(KTxSmall().Length()); + + // Copy the text "abcdedf" into it + *pBUf = KTxSmall; + + // Make the buffer bigger... + // ... and check that it worked OK + // Note that we are using the non-leaving version. + // We could use the leaving version, but we would + // need to handle the cleanup of pBuf + HBuf8* pNewBuf = pBuf->ReAlloc(KTxBig().Length());; + + if (pNewBuf) + { + pBuf = pNewBuf; + } + else + { + delete pBuf; + User::Leave(KErrNoMemory); + } + + // Replace content of the descriptor with + // the text "ghijkl......" + *pBuf = KTxBig; + + // Need to use the Des() function to create + // a modifiable descriptor before we can make + // changes to the text in the descriptor. + TPtr8 pDesPtr; + pDesPtr = pBuf->Des(); + + // Delete the 1st two characters. + PDesPtr.Delete(0,2) + + delete pBUf; + + return; + } +

A similar function, but it uses HBuf8 instead.

_LIT8(KTxSmall,"abcdef"); +_LIT8(KTxBig,"ghijklmnopqrstuvwxyz"); + +TInt X::Function() + { + // Create a buffer big enough to contain + // the text "abcdef", and copy the text + // from its source into the buffer. + // + // You need to check explicitly that this + // has worked. + HBuf8* pBuf = HBuf8::New(KTxSmall); + if (!pBuf) + { + return KErrNoMemory; + } + + // Make the buffer bigger... + // .. and check that it worked OK + HBuf8* pNewBuf = pBuf->ReAlloc(KTxBig().Length()); + + if (pNewBuf) + { + pBuf = pNewBuf; + } + else + { + delete pBuf; + return KErrNoMemory; + } + + // You can still use the =operator to replace + // the content of the heap descriptor ! + // Replace content with + // the text "ghijkl......" + *pBuf = KTxBig; + + + // Can now use use the TDes8 functions + // directly. + // This deletes the 1st two characters. + pBuf->Delete(0,2); + + // delete the heap descriptor + delete pBUf; + + return KErrNone; + } + + +

A small code fragment that uses TDesC8::Alloc() to +create an HBufC8 heap descriptor buffer from an existing +descriptor.

HBufC8* X::Function(const TDesC8& aDes) + { + // Returns NULL if creation + // of the heap descriptor buffer fails. + + return aDes.Alloc(); + }

or possibly:

HBufC8* X::FunctionL(const TDesC8& aDes) + { + // Leaves if creation of the heap + // descriptor buffer fails, otherwise it + // returns a valid pointer. + + return(aDes.AllocL()); + } +

An equivalent code fragment that creates an HBuf8 heap +descriptor buffer.

HBuf8* X::Function(const TDesC8& aDes) + { + // Returns NULL if creation + // of the heap descriptor buffer fails. + + return (HBuf8::New(aDes)); + } + + + +

Buffers: replacing +HBufC8 with C style pointers

Instead of replacing HBufC8 with HBuf, +it may be more suitable to replace your heap descriptor buffers with C style +pointers - effectively managing your buffers in open code or as part of the +implementation of your own purpose written classes.

You allocate memory +from the kernel heap using Kern::Alloc() or Kern::AllocZ() and +track the pointers to that memory. The following code fragments show how the +use of HBufC8 translates to the direct use of these functions.

Although +the EKA2 code here uses memcpy(), and memmove(), +you will also find the functions memclr(), memset(), wordmove() and memcompare() useful in your code.

+ + + +

EKA1

EKA2

+ + +

This is a function that allocates a heap descriptor buffer (HBufC8), +puts data into it, changes its size, replaces the data, deletes a part of +the data, and then deletes the whole buffer.

A similar function, but allocates memory on the kernel heap explicitly, +and manages its own pointers instead. Note the use of the nanokernel utility +function: memcpy(), and memmove()

_LIT8(KTxSmall,"abcdef"); +_LIT8(KTxBig,"ghijklmnopqrstuvwxyz"); + +TInt X::Function() + { + // Create a buffer big enough to contain + // the text "abcdef", and copy the text + // from its source into the buffer. + // + // Steps. + // 1. work out the size of buffer needed + // 2. Get the buffer. + // 3. Copy the source. + + TInt lengthInBuffer = 0; + + // 1. + TInt Smallsize; + SmallSize = KTxSmall().Length(); + lengthInBuffer = SmallSize; + + // 2. + TUint8* pBuf; + pBuf = Kern::Alloc(SmallSize); + if (!pBuf) + { + return KErrNoMemory; + } + + // 3. + memcpy(pBuf,KTxSmall().Ptr(),SmallSize)); + + + // Make the buffer bigger. + // If it works ok, then copy the data + // to the new buffer, delete the old buffer + TInt BiggerSize; + TUint8* pNewBuf; + + BiggerSize = KTxBig().Length(); + pNewBuf = Kern::Alloc(BiggerSize); + if (pNewBuf) + { + memcpy(pNewBuf, pBuf, SmallSize); + Kern::Free(pBuf); + pBuf = pNewBuf; + } + else + { + Kern::Free(pBuf); + return KErrNoMemory; + } + lengthInBuffer = BiggerSize; + + // Replace content with + // the text "ghijkl......" + memcpy(pNewBuf, KTxBig().Ptr(), BiggerSize); + + + // Delete 1st two characters + memmove(pNewBuf, pNewBuf+2, lengthInBuffer; + lengthInBuffer -= 2; + + Kern::Free(pBuf); + + return KErrNone; + } + + + +

Handling 16-bit +data items

If you need to handle 16-bit items on the kernel side, +then you can still use 8-bit heap descriptor buffers. You just need to be +aware that the data is 16 bit and cast accordingly. The following code fragments +are simplistic, but show you the basic idea.

+ + + +

EKA1

EKA2

+ + +

This is a function which is passed a 16-bit descriptor containing +16-bit wide characters.

void X::FunctionL(const TDes16& aDes) + { + HBuf16* pBuf = aDes.AllocL(); + + TInt noOfCharacters; + TUint16* pointerToData; + + noOfCharacters = pBuf->Length(); + pointerToData = pBuf->Ptr(); + + ... + } +

This is a similar function which is also passed 16-bit wide characters. +The function needs slight changes as it can only receive data through an 8-bit +descriptor.

TInt X::Function(const TDes8& aDes) + { + HBuf8* pBuf = HBuf8::New(aDes); + if (!pBuf) + { + return KErrNoMemory; + } + + TInt noOfCharacters; + TUint16* pointerToData; + + noOfCharacters = ((pBuf->Length()) >> 1); + pointerToData = (TUint16*)(pBuf->Ptr()); + + ... + + return KErrNone; + } + + + +

Replacing CBase +with DBase

The DBase class is the kernel-side +equivalent of the user-side CBase class. It provides zero-filling +of memory prior to object construction and a virtual destructor in a similar +way to CBase.

If you have a class derived from CBase, +then all you need to do is:

change your class definition +so that it is derived from DBase.
Remember to include +the klib.h header file.

you should not need to do anything else.

One additional feature +provided by DBase that is not available in CBase is +the function DBase::AsyncDelete(). This allows you to delete +an instance of a DBase derived class asynchronously, and +is useful if you need to delete a DBase derived object +in time-critical code.

Internally, asynchronous deletion works by +placing the object to be deleted onto a queue, and then triggering a DFC, +which runs in the context of the supervisor thread. This means that only a +small amount of code is executed by your (the calling) thread, and the actual +deletion is done by the supervisor thread.

Its use is straightforward.

class DMyObject : public DBase + { + ... + } DMyObject pPtr; + ... + pPtr = new DMyObject; + ... + pPtr->AsyncDelete(); + ...

Replacing +User::QueryVersionSupported() with Kern::QueryVersionSupported()

User::QueryVersionSupported() is +replaced by Kern::QueryVersionSupported() on the kernel +side.

The parameters passed to these functions are the same, both +in type and meaning. The behaviour of both functions is also the same. This +means that all you need to do is replace User:: with Kern:: in +your code.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-8F78705E-CD82-5039-A7CB-7C963F7FBA83-master.png Binary file Adaptation/GUID-8F78705E-CD82-5039-A7CB-7C963F7FBA83-master.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-8F78705E-CD82-5039-A7CB-7C963F7FBA83_d0e69457_href.png Binary file Adaptation/GUID-8F78705E-CD82-5039-A7CB-7C963F7FBA83_d0e69457_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-8FA1B2B0-5842-4D5D-BD61-C2D79B56ADC6.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-8FA1B2B0-5842-4D5D-BD61-C2D79B56ADC6.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,25 @@ + + + + + +Interrupt Service Routine (ISR)This document describes interrupt service routines as used by device +drivers. +

An ISR is a static function that will be executed when an interrupt occurs +on the interrupt source bound to the ISR.

+// Interrupt service routines +static void UartIsr(TAny* aParam); + +

An ISR performs the actions necessary to service the event of the peripheral +that generated the interrupt and to remove the condition that caused it to +interrupt. It queues a DFC to do the required processing. It disables the +interrupts and FIQs on ARM, if required, to handle the interrupt, and enables +them before leaving. It can also disable the source of the interrupt that +it is servicing.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-904C9C5A-5FDB-5978-88CF-E30D6C0DBB61-master.png Binary file Adaptation/GUID-904C9C5A-5FDB-5978-88CF-E30D6C0DBB61-master.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-904C9C5A-5FDB-5978-88CF-E30D6C0DBB61_d0e8869_href.png Binary file Adaptation/GUID-904C9C5A-5FDB-5978-88CF-E30D6C0DBB61_d0e8869_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-90B5FDD9-7D59-5035-BF53-2B177655DCD6.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-90B5FDD9-7D59-5035-BF53-2B177655DCD6.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,119 @@ + + + + + +Migration +Tutorial: Demand Paging and Internal MMC CardsExplains how to change the MMC media driver for when demand paging +is used. +

Demand paging is a change made from Symbian platform v9.3 to how the Kernel +uses RAM and storage media. This topic

For general information on migrating media drivers, see Migration +Tutorial: Demand Paging and Media Drivers.

PSL changes

ROM and code paging can be enabled +for a Multi Media Card (MMC) provided the card is non-removable. Removing +a card would result in a kernel fault whenever the next page-in request is +issued.

As the MMC media driver is entirely generic, a way of returning +the paging related information contained in variantmedia.def to the +generic part of the MMC stack is required. This is achieved by modifying the +Platform Specific Layer (PSL) of the MMC stack to implement the DMMCStack::MDemandPagingInfo interface +method:

class DMMCStack : public Dbase + { +public: + // etc… + }; + +/** +Demand paging support +@see KInterfaceDemandPagingInfo +*/ + +class TDemandPagingInfo + { +public: + const TInt* iPagingDriveList; + TInt iDriveCount; + TUint iPagingType; + TInt iReadShift; + TUint iNumPages; + TBool iWriteProtected; + TUint iSpare[3]; + }; + +class MDemandPagingInfo + { +public: + virtual TInt DemandPagingInfo(TDemandPagingInfo& aInfo) = 0; + // etc… + };

This example is taken from the H4 HRP VariantMedia.def changes:

// Variant parameters for the MMC Controller (EPBUSMMC.DLL) +#define MMC_DRIVECOUNT 1 +#define MMC_DRIVELIST 1 +#define MMC_NUMMEDIA 1 +#define MMC_DRIVENAME "MultiMediaCard0" + +#define MMC_PAGING_TYPE DPagingDevice::ERom | DPagingDevice::ECode +#define MMC_PAGEDRIVELIST 1 // code paging from User Data +#define MMC_PAGEDRIVECOUNT 1 +#define MMC_NUM_PAGES 8

This example is from H4 MMC +stack class definition:

class DDemandPagingInfo : public DMMCStack::MDemandPagingInfo + { +public: + virtual TInt DemandPagingInfo(DMMCStack::TDemandPagingInfo& aInfo); + }; + + +class DOmapMMCStack : public DCardStack + { +public: + virtual void GetInterface(TInterfaceId aInterfaceId, MInterface*& aInterfacePtr); + // etc… +private: + DDemandPagingInfo* iDemandPagingInfo; + // etc… + };

This example is from H4 MMC stack class implementation:

TInt DOmapMMCStack::Init() + { + if((iDemandPagingInfo = new DDemandPagingInfo()) == NULL) + return KErrNoMemory; + // etc… + } + +void DOmapMMCStack::GetInterface(TInterfaceId aInterfaceId, MInterface*& aInterfacePtr) + { + if (aInterfaceId == KInterfaceDemandPagingInfo) + aInterfacePtr = (DMMCStack::MInterface*) iDemandPagingInfo; + // etc… + } + +TInt DDemandPagingInfo::DemandPagingInfo(DMMCStack::TDemandPagingInfo& aDemandPagingInfo) + { + static const TInt pagingDriveNumbers[MMC_PAGEDRIVECOUNT] = {MMC_PAGEDRIVELIST}; + + aDemandPagingInfo.iPagingDriveList = pagingDriveNumbers; + aDemandPagingInfo.iDriveCount = MMC_PAGEDRIVECOUNT; + aDemandPagingInfo.iPagingType = MMC_PAGING_TYPE; + aDemandPagingInfo.iReadShift = 9; + aDemandPagingInfo.iNumPages = MMC_NUM_PAGES; + return KErrNone; + }

Preparing an internal MMC card for ROM paging - MMCLoader

To +support ROM paging from an internal card, the MMCLoader utility is used to +write the ROM image to the card. MMCLoader can be found in e32utils/mmcloader.

The +paged image is written as a normal file under the FAT file system. For paging +to work however, the images file’s clusters must all be contiguous so, before +doing anything else, MMCLoader formats the card. It then writes the paged +part of the ROM to a file and checks that the file’s clusters are contiguous, +which is normally the case as the card has just been formatted. A pointer +to the image file is stored in the boot sector. When the board is rebooted +the MMC/SD media driver reads the boot sector and uses this pointer to determine +where the image file starts so that it can begin to satisfy paging requests.

MMCLoader +takes the filename of the original ROM image file as an input. It then splits +the given file into unpaged and paged files. The following code fragment shows +the syntax:

Syntax: mmcloader <RomSrcFileName> <UnPagedRomDstFileName> <PagedRomDstFileName> +Eg: mmcloader z:\\core.img d:\\sys$rom.bin d:\\sys$rom.pag

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-9173EEBA-CC84-51D9-9C8D-A75F7F494D62-master.png Binary file Adaptation/GUID-9173EEBA-CC84-51D9-9C8D-A75F7F494D62-master.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-9173EEBA-CC84-51D9-9C8D-A75F7F494D62_d0e9004_href.png Binary file Adaptation/GUID-9173EEBA-CC84-51D9-9C8D-A75F7F494D62_d0e9004_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-91958EA5-9444-5895-B4B8-F2C670B81CD7-master.png Binary file Adaptation/GUID-91958EA5-9444-5895-B4B8-F2C670B81CD7-master.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-91958EA5-9444-5895-B4B8-F2C670B81CD7_d0e11017_href.png Binary file Adaptation/GUID-91958EA5-9444-5895-B4B8-F2C670B81CD7_d0e11017_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-919E48BE-6AA1-54CC-8B70-3A4B3A9C6CF1.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-919E48BE-6AA1-54CC-8B70-3A4B3A9C6CF1.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,65 @@ + + + + + +Writing +a Class Driver TutorialThis document set provides step-by-step instructions that will +enable a user to use the USB LDD interface to create a simple class driver. +

Before you start, +you must:

Understand USB,
Understand Shared +Chunks.

It is recommended +that shared chunks are used for speed of transfer when transmitting a large +amount of data. This approach is not recommended when transmitting smaller +amounts of data infrequently.

Complete the tasks listed below to create +a class driver that + interfaces with the USB LDD using shared chunks. +

+ + + Load and Open +a USB Channel, + + + Set the Configuration +Descriptors, + + + Set the Interface +Descriptors, + + + Allocate Resources +for Endpoints - this task is optional, + + + Re-Enumerate, + + + Using the BIL +Interface - this task is optional, but recommended, + + + Read Data from +USB using Shared Chunks, + + + Write Data to +USB using Shared Chunks, + + + Close and Unload +the Driver. + + + \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-921AF7A3-C711-5979-877B-4B6D977888E8-master.png Binary file Adaptation/GUID-921AF7A3-C711-5979-877B-4B6D977888E8-master.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-921AF7A3-C711-5979-877B-4B6D977888E8_d0e5006_href.png Binary file Adaptation/GUID-921AF7A3-C711-5979-877B-4B6D977888E8_d0e5006_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-922E4771-C1FD-5C88-9C11-57499684DB97.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-922E4771-C1FD-5C88-9C11-57499684DB97.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,80 @@ + + + + + +SPITOOL +

SPITOOL is a utility for creating static plug-in information (SPI) +files, which contain registration data for ROM-based plug-ins.

The tool is normally invoked by BUILDROM, +though it can be used independently (for example, for test purposes).

SPITOOL +command syntax spitool [options] files directories

The tool creates an SPI file by concatenating the specified input +files, using the options specified.

You can specify the input +files by specifying the full path to each file, or by specifying a +directory name, in which case all files from that directory are included.

options can be one or more of the following:

+ + + +

-t<SPIFileName>

<SPIFileName> is the name for the produced +SPI file (e.g. ecom.spi)

+ + +

-d<TargetDir>

<TargetDir> is the directory where +the SPI file should be created. The directory name should end with +a \.

+ + +

-i<Existing>

<Existing> is the path of an existing +SPI file to which to concatenate the specified input files.

If this option is used, then the specified file is used as a base +for the new output file. The output file will contain the contents +of the existing file with new input files appended. The location of +the output file is still specified using the -d and -t options.

+ + +

-uid[1 | 2 | 3]=<UIDValue>

Specifies that input files should be filtered by their UID +values.

This option can be used multiple times, so a list +of valid UID1 values can be specified, and similarly for UID2 and +UID3 values. The UIDs of each input file are compared with this list, +and if a UID value matches a relevant value in the UID lists, then +that file is included in the SPI file. If the file does not match +any values, it is excluded.

Use 1, 2, or 3 in the option keyword +to specify to which of the three UIDs the filter should apply. <UIDValue> should be a UID value in decimal or hexadecimal +(0x....).

+ + +

-existinguid[1 | 2 | 3]=<UIDValue>

Test that files concatenated in an existing SPI file use +the specified UID value. This allows the possibility of checking that +the correct type of files are being concatenated together.

Use 1, 2, or 3 in the option to specify to which of the three UIDs +the test should apply. <UIDValue> should be a +UID value in decimal or hexadecimal (0x....).

+ + +

-existinguidcrc=<CRCValue>

Test that files concatenated in an existing SPI file use +the specified CRC checksum value. A file's CRC is generated from all +three of its UIDs.

<CRCValue> should +be a value in decimal or hexadecimal (0x....).

+ + +

-hide <ResourceFileNames>

Marks a resource file as hidden in the SPI file.

<ResourceFileNames> is a list of resource file names separated +by a space or comma, which need to be marked as hidden in the SPI +file.

+ + + +

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-93DA75DE-096F-5E40-A47E-5A1A94C3145A.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-93DA75DE-096F-5E40-A47E-5A1A94C3145A.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,34 @@ + + + + + +Source Code OrganisationThis topic describes the Base Starter source code that +Symbian platform provides. + + + +

sf/os/kernelhwsrv/userlibandfileserver/fileserver/estart/estart.h

Header file containing the definition for the class TFSStartup, and other required structs, typedefs etc.

You do not make changes to the contents of this file.

+ + +

sf/os/kernelhwsrv/userlibandfileserver/fileserver/estart/estart.cpp

Contains generic code and default versions of the TFSStartup virtual functions. This file also contains the +code involved in auto-detection.

You do not make changes +to the contents of this file.

See Use automatic local drive mapping.

+ + +

sf/os/kernelhwsrv/userlibandfileserver/fileserver/estart/estartmain.cpp

Contains the entry point to the Base Starter. If you need +to customize the Base Starter, then you do it to a copy of +this file.

+ + + +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-9573F7B9-76E9-5DCB-A498-C0DE59606911.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-9573F7B9-76E9-5DCB-A498-C0DE59606911.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,16 @@ + + + + + +ConceptsDescribes the technology, architecture, and behaviour of the MMC +Controller.

+MMC Tutorials + +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-9595FD6F-1EDE-51A8-B00D-029CFDFE0F38.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-9595FD6F-1EDE-51A8-B00D-029CFDFE0F38.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,40 @@ + + + + + +Boot TableDescribes the boot table. +

The boot table consists of a linear array of 4-byte entries whose index +positions are defined by the TBootTableEntry enumeration +in os/kernelhwsrv/kernel/eka/include/arm/bootdefs.h.

The entries in the array are divided into two groups, one whose index positions +are defined by the enumerator names BTF_* and the other group +defined by the enumerator names BTP_*.

Entries in the first group specify addresses of Boot +Table Functions.

Entries in the second group specify Boot +Table MMU Permission and Cache Attribute Definitions to be used for +certain standard memory and I/O areas.

A boot table entry is the offset of the function from the beginning of +the bootstrap code but, since the bootstrap is linked for a base address of +zero and is position independent, bare function addresses can be used.

Use DCD to place a function in the boot table, for example:

+DCD function-name +

In the Template port, available in os/kernelhwsrv/bsptemplate/asspandvariant/template_variant/bootstrap/template.s, +the boot table is defined by the label BootTable, followed +by DCD entries for every boot table function, like in the +following example:

+BootTable + DCD DoWriteC ; output a debug character + DCD GetRamBanks ; get list of RAM banks + DCD SetupRamBank ; set up a RAM bank + DCD GetRomBanks ; get list of ROM banks + DCD SetupRomBank ; set up a ROM bank + ... + \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-9597DB22-D932-5A58-9C3C-4E5FCA244253.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-9597DB22-D932-5A58-9C3C-4E5FCA244253.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,14 @@ + + + + + +Re-Enumerate A short description of how to perform a Re-Enumeration.

Introduction

If any interface settings have been changed then a re-enumeration must be forced by calling RDevUsbcScClient::ReEnumerate(). A re-enumeration involves the device initiating a bus disconnection and re-connection.

Re-enumerate

ReEnumerate() is an asynchronous operation that completes when the controller is successfully configured by the host. Because it is not known if the operation has failed, set up a timer to complete after approximately 5 seconds. It can be assumed that if the operation has not completed in this time then it will not complete. When the request is completed status contains the result of the re-enumeration. See TRequestStatus.

TRequestStatus status; +gPort.ReEnumerate(status); +User::WaitForRequest(status);

If the re-enumeration has not completed within the expected time period then use RDevUsbcClient::ReEnumerateCancel() to cancel the request. Note: this function does not undo the re-enumeration.

If alternate interface settings have been set up enquire which interface has been selected following a re-enumeration by using RDevUsbcScClient::GetAlternateSetting().

After you have forced a re-enumeration you can use your USB class driver to Read Data from USB using Shared Chunks or Write Data to USB using Shared Chunks or if you wish to use the Buffer Interface Layer (recommended) then go to Using the BIL Interface.

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-95A33491-17AC-4F12-948E-A1352ADDA483.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-95A33491-17AC-4F12-948E-A1352ADDA483.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,85 @@ + + + + + +DMA Implementation GuideExplains how to implement the DMA Platform Specific Layer +(PSL) for your platform. +

The DMA Framework is made of a PIL and a PSL. You have to write +a new Platform specific implementation code whenever your hardware +changes, but the PIL and the platform service API do not change.

Prerequisites

You should be familiar with the DMA Technology Guide and with the specifications of your hardware DMA controller.

Architecture

In the diagram below, the classes in green provide the platform +service API and the classes in blue implement the Platform-specific +functions (PSL).

+PSL class diagram + +

Implementation +files

The following table lists the important files of the +DMA Framework and what you should do with each of them. + + + +File +Usage + + + + +/os/kernelhwsrv/kernel/eka/include/drivers/dma.h +
This file is the main header file for DMA.
Include +it in the PSL implementation.
+ + +/os/kernelhwsrv/kernel/eka/include/drivers/dma_v1.h +
This file contains the definitions of the PSL classes.
Refer to this file for the signature of the PSL functions.
+ + +/os/kernelhwsrv/kernel/eka/drivers/dma/dmapil.cpp +This file is for information only: it contains the source code +for the generic implementation. + + +/os/kernelhwsrv/kernel/eka/drivers/dma/dma_lib.mmp +
This file is the MMP for the PIL.
Use it to build +the .LIB file for the PIL.
+ + +/os/kernelhwsrv/bsptemplate/asspandvariant/template_assp/dmapsl.cpp +
This file contains the template code for the PSL implementation.
Copy it to your variant directory and modify it.
+ + +/os/kernelhwsrv/bsptemplate/asspandvariant/template_assp/dma.mmp +
This file is the template MMP for the PSL implementation.
Copy it to your variant directory and modify it.
Use the +new file to build the DMA Framework (PIL and PSL).
+ + + +

Implementation +process

To write the PSL for the DMA Framework, do the following:

Copy the template +listed in the above section to your own variant directory (at chip +level or at board level depending on where the DMA hardware is located).
Implement the DmaChannelMgr functions.
Derive the TDmac class and implement its controller-specific functions.
If necessary, +derive the TDmaChannel class or one of its sub-classes +to store channel-specific data.
Test the PSL +implementation.

+DMA +Client Interface Guide +DMA +Testing Guide +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-95BD3650-08CB-407D-969E-DFDB39B2FEFC.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-95BD3650-08CB-407D-969E-DFDB39B2FEFC.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,155 @@ + + + + + +What is a Platform Service?A platform service is an interface designed to make it +quick, easy and inexpensive to integrate hardware into a mobile device. +

Platform +Service

A platform service is a set of defined functionality, +usually providing an abstraction or encapsulation for functionality +provided by hardware.

For example, a platform service may provide +a standard interface for using a serial bus to send commands and data +between integrated circuits on the base board. Another example would +be providing a standard interface for Direct Memory Access (DMA) hardware +for moving blocks of data from one block of memory locations to another +or from a block of memory to a hardware device.

The platform +service separates the functionality required by kernel, device driver +and application processes from the specific hardware implementation. +This means, for example, that a device driver can be written for a +platform service that uses the published APIs, without needing to +know the specifics of the actual hardware device/chipset.

+Platform service + +

The platform service is a consistent hardware interface at +the bottom of the operating system platform software stack. In the +past much of the logic and configuration required to enable a new +piece of hardware was higher up in the operating system stack and +that made it difficult to support new or variant hardware. The platform +service architecture separates out the hardware specific interfaces +and encapsulates them behind a standard set of platform service (client +interface) APIs.

The platform service consists of :

Client Interface/Platform service APIs
Implementation of the APIs:
- Platform Independent Layer (PIL)/Framework/Generic implementation
- SHAI interface
- Platform Specific Layer (PSL)/SHAI Implementation/Hardware +implementation

The PIL contains all the common functionality code such as +maintaining a list of available channels for communication or holding +the pending list of memory transfers to be processed by DMA when the +hardware becomes available. Usually the PIL provides the implementation +of the Client Interface APIs. This is sometimes referred to as the +Framework.

The interface between the framework code and the +PSL code is known as the Symbian Hardware Adaptation Interface (SHAI). +The SHAI interface specifies how the PIL and PSL talk to each other +(APIs, shared memory areas etc.)

The PSL consists of the specific +code required to work with a particular piece of hardware. This means +that supporting a new or variant chipset only requires the PSL to +be amended or to have detection code to handle a particular piece +of hardware.

Some Platform Services, such as GPIO, provide +APIs that directly address the hardware, and so the PSL provides the +client interface API implementation directly. For example, there is +no GPIO PIL/framework.

Variations +on platform service

Not all platform services are as simple +as the diagram above suggests. Some platform services do not talk +to hardware directly or at all, but provide a higher-level abstraction, +often with further low-level platform services below them in the OS +stack. For example, the Power Manager Policy platform service, provides +APIs to control power management policy, but does not interface with +any hardware directly. In these cases there is either no PSL, or the +PSL provides configuration specific responses to a generic PIL. For +example, if a handset can be built in two variants, one with a hardware +graphics accelerator and one without but with a software emulated +graphics accelerator, then the PSL would be responsible for directing +graphics requests either to the hardware, or to the software and returning +the results back through the PIL to the client.

Some plaftorm +services, for example TV-Out, may use additional platform services +to output sound as well as providing hardware support for the TV-Out +chipset.

Some platform services may share a piece of hardware, +such as a radio chip. The chip may provide cellular telephony, WiFi, +FM radio transmission and other features all on one chip, but there +may be several separate platform services, each exposing an API for +one particular technology.

Both the PIL and PSL may make calls +to other OS components, including other platform services, for information +such as Hardware Configuration, power status, and the availability +of other services.

Why +have a platform service

Platform services +benefit both device creators and third party hardware/chipset developers +since they specify a standard software interface between the operating +system and standard functionality provided by hardware.

This +means that it is possible for a device creator to easily integrate +the best hardware for their device, and allows hardware creators to +work to a standard interface that can be used across multiple devices +and multiple customers.

As the platform service interface provides +a consistent interface to functionality, it allows the device creator +to concentrate on the core functionality and not worry about how the +hardware will provide it. And since the interface is standard for +each type of hardware component, each manufacturer can provide the +information or code for the PSL comparatively easily for each additional +variant they produce. So this means less code required from hardware +manufacturers per hardware component, and a larger market as each +new mobile device, from any device creator, can use that compliant +hardware.

The platform services abstraction for hardware adaptation +also means more common code that can be shared across the Symbian +Foundation member community. This includes sharing PSL code with other +hardware providers, and sharing code for device drivers and other +higher-level components that need to use the platform services APIs. +For example, if a device driver for a particular piece of hardware +also needs to use a serial inter-IC bus (IIC) to send commands to +that hardware, then it can use the IIC platform service APIs and re-use +code that other components have already tested for using the IIC client +interface APIs.

Platform services also allow the use of standardized +test tools and test suites. Each new piece of hardware in a particular +category (for example, camera, Bluetooth radio) has to comply with +the SHAI interface (PIL/PSL interface). This means that an existing +test suite that works with another camera module can be used to test +that this new piece of hardware works. This reduces the time taken +for testing and increases speed to market.

Who +uses the Platform Service?

Application developers, who need to use the functionality of +a hardware device, but do not need to know the specific details of +the hardware/hardware implementation. They use the client interface +and need to know what the APIs are, and what order they must be called +in and so on.
Framework developers, who need to know how to implement each +of the client interface APIs , and a description of the functionality +required within the framework.
Hardware Developers, who need to understand the hardware interface, +and have to write or update the hardware implementation (PSL) to support +their particular chipset/hardware.

Platform +service client interface APIs

In general these are function +calls, and associated enumerations. There are two main types of function +call:

Synchronous
Asynchronous

A synchronous function call from the client/device-driver +waits for the platform service to process it and make any return value. +The client thread waits for the synchronous call to complete.

An asynchronous function call asks the platform service to do something, +but then execution of the client continues immediately. For example, +this would be the case of any function that starts a long data transmission +or receive process, such as streaming video. One of the standard components +of an asynchronous function call is a way for the result to be communicated +back to the client. Often this is done by a “callback function” where +the client specifies a pointer to a function (and parameters) during +the original call, and the platform service puts the callback on the +Delayed Function Call (DFC) queue for the client when the platform +service has completed the request. This may indicate “transfer completed” +or “transfer failed, error code 123”, it may release a lock or other +functionality defined by the author of the client.

+ +Symbian Foundation SHAI page +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-95CE7187-66B2-581A-A5B8-6359AD431E87.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-95CE7187-66B2-581A-A5B8-6359AD431E87.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,16 @@ + + + + + +ReferenceSummary of file formats, tools command line syntax, and related +documentation for the User-Side Hardware Abstraction (HAL) component.

+API Reference: +User-Side Hardware Abstraction +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-970EC5A9-8ED3-53C5-93A3-2EC1A7B6F25F-master.png Binary file Adaptation/GUID-970EC5A9-8ED3-53C5-93A3-2EC1A7B6F25F-master.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-970EC5A9-8ED3-53C5-93A3-2EC1A7B6F25F_d0e13980_href.png Binary file Adaptation/GUID-970EC5A9-8ED3-53C5-93A3-2EC1A7B6F25F_d0e13980_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-97F97D7B-D5A3-5471-A359-77B805ED198C.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-97F97D7B-D5A3-5471-A359-77B805ED198C.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,44 @@ + + + + + +DesignDescribes different modes of operations of the DMA Framework . +

Some DMA controllers provide several modes of operation. For example, one +ASSP provides both single-buffer mode and scatter-gather mode transfers.

There are two options:

Select a single mode +of operation.
Select a multiple mode +of operation, and split the physical DMA controller into several logical controllers, +one for each mode to be supported. If this option is chosen, the PSL must +include one concrete controller class per logical controller; a controller +class is derived from TDmac.

If the DMA controller +supports more than one mode of operation, implement the simplest one first. +Implementing single-buffer mode first allows most of the the PSL (platform-specific +layer) to be debugged before you start to implement the more complex scatter-gather +functionality.

One reference implementation adopts a mixed strategy; the mode of operation +is selectable at build-time by defining the macro __DESFETCHMODE__ to +exercise and demonstrate two different modes of operation.

Scatter-gather support is essentially a superset of single-buffer support +because a scatter-gather list is an ordered set of variable sized buffers, +and means that code shown here demonstrates the implementation of a scatter-gather +DMA controller.

Almost all modern MCUs use scatter-gather capable DMA controllers. Note +that we refer to descriptor fetch mode synonymously with scatter-gather mode, +as scatter-gather is implemented by passing the DMA controller a linked list +of descriptors describing the buffers to be transferred. Non–descriptor mode +requires that the DMA controller registers are programmed by software to describe +the buffer transfer required. Since each transfer must be handled by an interrupt +service routine triggered when the DMA controller has completed the transfer, +non-descriptor mode is not capable of performing transfers past buffer boundaries.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-98210124-0B65-4679-BB3A-E94B9999365C.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-98210124-0B65-4679-BB3A-E94B9999365C.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,143 @@ + + + + + +IIC Client Interface GuideThis document explains how to use the IIC client interface +API. +

Introduction

This guide describes how to use the IIC client interface API.

Channels

In this document, a channel is a multi-wire bus with a two or +more devices connected to it. At least one of the devices can act +as the master.

Modes +of operation

There are three possible modes that a device +can be in as regards to the IIC client interface API (regardless of +the underlying two-wire bus that is being used ):

+ + + +

Mode

Description

+ + + + +

Master

The device is responsible for initializing and terminating +the data transfer.

+ + +

Slave

The device carries out the transfer initialized by a another +device acting as a master.

+ + +

MasterSlave

The device can perform both master and slave roles.

+ + + +

Transactions

A single exchange of data in one direction is known as a transfer.

A list of transfers is known as a transaction.

Transactions +can be performed in half-duplex, or , full-duplex (if the underlying +bus supports it).

Transaction +preamble

In certain instances, some pre-processing might +be required by the devices before a transaction can occur.

This +can be done by the transaction preamble functionality, which executes +immediately before the transaction is performed. This takes the form +of a function.

the following restrictions apply to this +function:

No spin locks are to be used.
There are no block or waiting on a fast mutex operations.
There are no calls to code that either uses spin locks, waits +or blocks a fast mutex.

This is for a device that is in master mode.

Extended +transactions

This is where a number of separate transactions +are linked together. It is used, for example, in situations where +it is not known in advance how big the transaction will be.

This is for a device that is in master mode.

Controller +and controller-less operation

Added to the above functionality, +the IIC platform service API has two modes of operation:

With-controller and
Controller-less

Controller operation is used in a situation where multiple +device drivers can communicate with multiple channels. In controller-less +operation, the link between a device driver and a channel is fixed.

In controller-less operation, the mode of the channel is set at +build time, buy using the following macros in the relevant mmp files:

+ + + +

Macro

Description

+ + + + +

MASTER_MODE

Specifies that the device is to act as a master.

+ + +

SLAVE_MODE

Specifies that the device is to act as a slave.

+ + + +

+IIC with-controller operation + + +IIC controller-less operation + +

Interface +classes

The class that is used for the client interface +depends on whether the IIC controller is to be used or not.

If the IIC Controller is to be used, then the client interface API +class is:

+ + + +

Name

Description

+ + + + +

IicBus

Client interface API for the IIC component.

+ + + +

If the IIC controller is not to be used, then the client +interface API classes are:

+ + + +

Name

Description

+ + + + +

DIicBusChannelMaster

Client interface API for the master channel operation.

+ + +

DIicBusChannelSlave

Client interface API for the slave channel operation.

+ + +

DIicBusChannelMasterSlave

Client interface API for the master slave channel operation.

+ + + +

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-984C2A0D-36BE-5A99-9D65-3F8791C669FF.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-984C2A0D-36BE-5A99-9D65-3F8791C669FF.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,65 @@ + + + + + +ASSP/Variant ArchitectureA base port must provide a software layer called the ASSP/Variant. +

The ASSP/Variant layer provides two main functions. First, it implements +a small number of hardware-specific functions that are used by the +Kernel. Second, it implements common peripheral control functions +that other extensions and device drivers can use.

The most important +of these functions is interrupt dispatching. During initialisation +the ASSP/Variant must specify a dispatch function to be called for +all hardware interrupts.

In general, the ASSP/Variant provides control functions for hardware +which is shared between multiple devices. For example it is often +not possible to do a read-modify-write on a GPIO port in order to +change the state of an individual output line. This may be either +because an output port register is write-only or because reading the +port register reads the actual logic levels on the pins, not the last +value written to the register, and the pin level typically lags the +written value due to capacitive loading. In this case, the ASSP/Variant +could provide a function to set and clear individual port bits, keeping +a RAM copy of the last value written to the port register.

The simplest implementation is put all the code in a single DLL, +called the Variant DLL (ecust.dll). For hardware +architectures based on an ASSP, you can allow multiple types of phones +that use the same ASSP to share the common code. To do this, the common +ASSP code is implemented in a kernel extension, and the Variant DLL +implements the code that is specific to the phone type.

+ + + +

In the Base Porting Guide, we refer to the ASSP layer and the Variant +Layer, where the ASSP layer contains the source code tailored to a +range of different microprocessors (e.g. ARM720/920/SA1/Xscale), and +the Variant layer contains the source code associated with off-chip +hardware (same CPU, different peripherals).

For example, the standard Symbian port for the template reference +board is split into a core layer (in directory ...\template_assp\...) and code specific to the template board (in directory ...\template_variant\...). The .mmp file for the ASSP layer is ...\template_assp\katemplate.mmp, and the .mmp file for the Variant layer is ...\template_variant\vtemplate.mmp.

The +Asic class

The heart of the ASSP/Variant is the Asic class, defined in ..\e32\include\kernel\arm\assp.h. This is a class that contains a number of pure virtual functions +that must be implemented.

Where there is an ASSP/Variant split, +the ASSP layer should derive a concrete implementation from the Asic class. The most convenient way of implementing the +Variant layer is to further derive from this ASSP class. Only the +Variant DLL is declared as ‘variant’ in the ROM – the ASSP is declared +as an extension. If there is no ASSP/Variant split, then the Variant +is simply a concrete implementation of the Asic class.

The ASSP layer can, itself, define additional functions +to be implemented in the Variant layer. For example, the ASSP layer +defines the pure virtual function VideoRamSize() which +the Variant layer provides to map the video frame buffer.

The template reference board port has the ASSP/Variant split. The +ASSP layer is implemented by the TemplateAssp class, +and the Variant layer is implemented by the Template class.

For reference: the template port ASSP layer implementation's .mmp file is at ...\template_assp\katemplate.mmp, and the Variant layer implementation's .mmp file is at ...\template_variant\vtemplate.mmp.

Note that one of the source files that forms the ASSP layer +must have the DECLARE_STANDARD_ASSP() declaration. +See ...\template_assp\assp.cpp.

+Asic +Class Tutorial +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-99637158-DE86-4BB4-98D4-3A3E64AB768F-master.png Binary file Adaptation/GUID-99637158-DE86-4BB4-98D4-3A3E64AB768F-master.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-99637158-DE86-4BB4-98D4-3A3E64AB768F_d0e87314_href.png Binary file Adaptation/GUID-99637158-DE86-4BB4-98D4-3A3E64AB768F_d0e87314_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-9986DCC6-EE73-59FB-BDAC-9B09DC64FBCE.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-9986DCC6-EE73-59FB-BDAC-9B09DC64FBCE.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,84 @@ + + + + + +Client of Master Channel TutorialDescribes a simple implementation of a client using the +master channel functionality. +

This document describes a simple implementation of an IIC client +using the master channel functionality.

Purpose

This tutorial explains how to use the IIC platform service API +as a master and to communicate with a peripheral using half-duplex.

Intended Audience

Device driver writers.

Required Background

Before you start, you must:

Have installed +the platform specific implementation of IIC channels that is required +to support the IIC platform service API.
Include the IIC.dll in the kernel.iby file.
Include the iic.h and iic_channel.h header files.

The code example fragments are for synchronous operation. +For asynchronous operation, the buffers must be allocated on the heap.

Implementing +the IIC platform service

The Following tasks will be covered +in this tutorial:

Performing read/write +operations.

Basic Procedure

The implementation +on which the following code examples are based is implemented IIC +via a SPI bus. On hardware with dedicated IIC ports, the IIC port +would be specified and the header data type would be TConfigIICV01.

The high level steps to performing read/write operations are +shown here:

First set the +bus type, the channel number and the slave address.

An example +of this is :
// Configure the port. + busId.SetBusType(DIicBusChannel::ESpi); // Specify which multi-wire bus is to be used. in this example, SPI. + busId.SetChanNum(0); // Set the channel number. + busId.SetSlaveAddr(13); // Set the slave address.
Configure the +channel.

An example of which, is :
// create header - this configures a SPI port. + const TConfigSpiV01 TestHeader = + { + ESpiWordWidth_8, // Set the word width. In this example, 8 bits. + 260000, // Set the clock speed of the port. In this example, 260KHz. + ESpiPolarityLowRisingEdge, // Set the clock mode value. In this example, Active high, odd edges. + 500, // Set the timeout period. In this example, 500msec. + EBigEndian, // Set which endian is to be used. In this example, BigEndian is used. + EMsbFirst, // Set which bit order is to be used. In this example, the Msb is first. + 0, // Set the number of transaction wait cycles. In this example, 0. + ESpiCSPinActiveLow // Set the Chip select active mode. In this example, chip select is active low. + };
Make linked +lists of the transfers that are to be carried out.

An example +of this is :
// Set the transaction header. + TPckgBuf<TConfigSpiV01> header(TestHeader); + + // Set up a transmit transaction. + // This txTransfer buffer acts as the start of the transaction linked list. + TIicBusTransfer txTransfer(TIicBusTransfer::EMasterWrite, 8, &txTransferBuf); + + // Set up a receive transaction. + TIicBusTransfer rxTransfer(TIicBusTransfer::EMasterRead, 8, &rxTransferBuf); + + // Add to the receive transaction to the transaction linked list. + txTransfer.LinkAfter(&rxTransfer); + + // Create a transaction using header and the transaction linked list. + TIicBusTransaction transaction(&header, &txTransfer);
Use the IicBus::QueueTransaction() method, specifying the configuration +of the port and the start location of the transaction linked lists. +This queues the transactions on to the selected IIC channel.

An example of this is :
// Queue the transaction. + // Once this command has been executed, the value of r should be KErrNone. + r = IicBus::QueueTransaction(busId.GetConfig(), &transaction);

+Client + of Slave Channel Tutorial +IIC +Concepts +I2C +Technology Guide +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-99C4FCCC-9E8B-51CC-85F8-F03BE18DF19E-master.png Binary file Adaptation/GUID-99C4FCCC-9E8B-51CC-85F8-F03BE18DF19E-master.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-99C4FCCC-9E8B-51CC-85F8-F03BE18DF19E_d0e82580_href.png Binary file Adaptation/GUID-99C4FCCC-9E8B-51CC-85F8-F03BE18DF19E_d0e82580_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-99F7E70F-2733-57B2-94F5-A0C0FF9219FE-master.png Binary file Adaptation/GUID-99F7E70F-2733-57B2-94F5-A0C0FF9219FE-master.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-99F7E70F-2733-57B2-94F5-A0C0FF9219FE_d0e10765_href.png Binary file Adaptation/GUID-99F7E70F-2733-57B2-94F5-A0C0FF9219FE_d0e10765_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-99FC067C-0AED-5373-AF63-8DB7FF5C1F7E.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-99FC067C-0AED-5373-AF63-8DB7FF5C1F7E.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,69 @@ + + + + + +SPI Technology GuideThis document describes the Serial Peripheral Interface +(SPI) technology. The SPI devices are used for fast data exchange +between two or more peripherals. + +

Introduction

The SPI is a synchronous serial interface. The SPI supports full +duplex communication channel for the devices that use SPI interface. +The devices and peripherals that use the SPI interface are described +as SPI devices in this document.

Architecture

In the SPI bus one of the node must be a master device and one +or more slave devices. There can be only one slave active at a time. +The master device initiates and terminates communication between the +SPI devices. The SPI is a full duplex serial data communication. In +full duplex communication the data can be transferred between the +master and the slave devices simultaneously.

The SPI devices +can be configured as master or slave. The SPI bus contain four wires. +The first one is the serial clock signal sent by the master device +to the slave device. The clock signal is used for synchronisation. +The Master Output / Slave Input (MOSI) is used to +send data from the master to the slave. The Slave Output / Master +Input (SOMI) is used by the master device to read +data from the slave device. The fourth line is the Slave Select (SS) that is used by the master to select a slave to initiate +the communication.

+ SPI Bus + +

Communication

The master device is the node on the SPI bus that initiates and +terminates the communication. The master must provide the configuration +to the slave devices. The configuration includes the details like +the channel number and the data length. The SPI devices uses 4 and +8 bit words to communicate. If a slave device or a channel is not +available the appropriate error is returned to the master.

Advantages

The following are the advantages of the SPI interface:

Full duplex +synchronous communication
Low power requirements +compared to the I2C devices
Less space compared +to the parallel bus
Slave devices +do not require unique address assigned

SPI +devices

Typically the SPI devices are used for data transfers +where a delay in the time taken to send the data is acceptable. The +clients of the SPI interface are device drivers running on the application +specific integrated circuits (ASIC). Some of the peripherals that +use SPI interface are:

Touch screens
Codecs
Real Time Clocks
Built-in cameras
Flash memory +like MMC and SD cards

+IIC +Concepts +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-9AE254D4-AA60-579E-8D9D-F2797106A413.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-9AE254D4-AA60-579E-8D9D-F2797106A413.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,228 @@ + + + + + +User-Side +Hardware Abstraction TechnologyDescription of HAL types and interfaces. +

The User-Side Hardware Abstraction (HAL) component provides a platform-independent +way to access and control many device specific features, and to hide hardware-specific +functionality. For example, HAL can be used to find out if a screen backlight +is present or not, or to set the display contrast. This topic

Attributes

Specific +items of hardware related information are referred to as attributes. +Symbian platform defines two types of attribute:

Non-derived attribute. +This is an attribute where the information it represent is simply a value +that is stored in, and retrieved from, the HAL.
Derived attribute. This +is an attribute that requires a software call to obtain and set its value. +The software component is, ultimately provided by a driver, kernel extension +or by the kernel itself. The drivers or kernel extensions normally need porting.

Attributes are identified by the enumeration values of the enumerator HALData::TAttribute defined +in ...\hal\inc\hal_data.h and is exported to ...\epoc32\include\.

To +maintain backwards compatibility, the numbers identifying HAL attributes are +allocated strictly increasing consecutive values, and that a given HAL attribute +always has the same enumeration number on all implementations of Symbian platform. +This means that new HAL attributes can only be added by Symbian. This also +means that the addition of custom HAL attributes is not possible.

User-side interface

Symbian +platform provides the following static functions to get and set information +about specific hardware features:

HAL::Get()
HAL::Set()
HAL::GetAll()

The HAL class is defined in the source tree header +file ...\hal\inc\hal.h, and is exported to ...\epoc32\include\. +The functions are exported from the HAL DLL, which is built as part of the +Variant.

Get() and Set() take an attribute to +identify specific hardware functionality.

GetAll(), +as its name implies gets all available hardware information, but is rarely +used. See Dealing +with the HAL::GetAll() function for more information.

Get() and Set() each +have a variation that allows a device number to be specified. The device number +allows more than one set of attributes to be used. Each set is associated +with a different device number. This is motivated by the need to support multiple +display screens where each screen is identified as a separate device of the +same 'type'. The idea of a device can be extended other hardware, and indeed +the underlying implementation assumes a device number. If a device number +is not specified and has no meaning, then a default device number of 0 is +assumed for compatibility with the underlying implementation.

For +example, on return from code such as:

... +TInt xpixels; +HAL::Get(EDisplayXPixels, xpixels); +...

xpixels contains the horizontal size +of the display screen in terms of the number of pixels. If you have more than +one screen, i.e. more than one device, then you would use the API variant +that takes a device number.

HAL handler +interface

A request for fetching and setting information about +hardware is dealt with by an entity called a HAL handler on the kernel side. +This section describes the types and concepts used to implement a HAL handler.

HAL groups and function-ids

It is useful to group +together requests for information about related hardware features so that +they can be dealt with by a single HAL handler. As an example, all the HAL +screen attributes are in the display group and are handled by the screen (i.e. +video or LCD) driver. This means that a HAL group has a one-to-one association +with a HAL handler.

A HAL group has an associated set of function-ids, +which identify requests for different pieces of information to the HAL handler.

Symbian +platform identifies HAL groups by a number defined by the THalFunctionGroup enum +in u32hal.h, which is exported to ...\epoc32\include. +For example, the EHalGroupDisplay enum value identifies +the group associated with the HAL screen attributes.

The function-ids +associated with each HAL group are also defined in u32hal.h. +Each set of function-ids is defined by an enum; for example the enum TDisplayHalFunction defines +the function-ids associated with the HAL group EHalGroupDisplay.

The +idea of the HAL group is what allows HAL handling functionality to be implemented +in the Variant, rather than in the kernel.

Up to 32 groups can be +defined. Often, a HAL group is concerned with mode settings for a particular +piece of hardware; for example there are standard HAL groups for keyboard, +digitiser and display. However, some groups are concerned with some overall +aspect of the platform which extends across all devices; for example, there +is a group to handle emulation parameters on emulator platforms.

An attribute maps +to a HAL group/function-id pair, although the mapping is not necessarily a +one-to-one relationship. For example, the calls:

TInt xPixels, yPixels; +... +HAL::Get(HALData::EDisplayXPixels,xPixels); +HAL::Get(HALData::EDisplayYPixels,yPixels); +...

both result in calls to the screen (i.e. video or LCD) +HAL handler, as represented by the HAL group number THalFunctionGroup::EHalGroupDisplay, +using the same function-id TDisplayHalFunction::EDisplayHalScreenInfo.

However, +there are HAL group/function-id pairs for which there are no corresponding +generic attributes. In these cases, the hardware attributes represented by +the HAL group/function-id pair are used internally, and can only be accessed +using the kernel side function Kern::HalFunction() **.

The +following picture shows the general idea:

+ +

**Technically, the user side function UserSvr::HalFunction() will +achieve the same thing, but this is internal to Symbian and is not +intended for general use.

HAL handler implementation

Most HAL handlers are +implemented as part of a driver, a kernel extension, the Variant or the kernel +itself. Some will need porting. See Groups +and the location of their HAL handlers.

An extension or a device +driver must register a handler for HAL group. It does so by calling Kern::AddHalEntry(), +specifying the group number. It is important to note that it is the extension +or driver's responsibility to do this; in other words, the kernel cannot know +what entity within a final ported Symbian platform is going to be the HAL +handler until it is explicitly told by registration. One point to note is +that the HAL handlers for the groups: EHalGroupKernel, EHalGroupVariant and EHalGroupPower are not explicitly registered - they are registered internally by the kernel +itself.

Internally, pointers to the HAL handler are stored in the +array K::HalFunction[], and this is indexed by the group +number.

On the template board, for example, the HAL handler for the +display group is part of the screen driver. The screen driver source can be +found in ...\template_variant\specific\lcd.cpp. The HAL +handler itself is the function:

LOCAL_C TInt halFunction(TAny* aPtr, TInt aFunction, TAny* a1, TAny* a2) + { + DLcdPowerHandler* pH=(DLcdPowerHandler*)aPtr; + return pH->HalFunction(aFunction,a1,a2); + }

The following code, implemented in the Create() function +of the main class, does the registration.

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

Security is the responsibility of the HAL handler. If +necessary, it needs to check the capability of the caller's process. Each +information item, as identified by the function-id, can have an associated +capability.

Each function-id defined in u32hal.h is +documented with the required capability. If no capability is listed, then +no specific capability is required.

See Implementing +HAL handlers for details.

Kernel-side +interface

Code such as device drivers that runs on the kernel side +need not use the generic interface provided by the HAL class functions. The Kern::HalFunction() API +is provided to access HAL information.

Unlike the HAL class functions, Kern::HalFunction() uses +the group number and function-ids to identify hardware related information. +This means that kernel side code does not use attributes to identify hardware +related information. The implication here is that you may have to make +changes to your kernel side code when porting to another platform. In practice, +no changes may be needed, but at the very least you need to check.

Config and Values files define attributes

Although +an attribute is +generic, some attributes may not have meaning on some platforms. In addition, +each platform needs to define whether an attribute is either:

non-derived, +i.e. has a value that is simply stored in the HAL,

or:

derived, i.e. +requires a call to a software entity to get and set the value.

This is the role of the Config file.

The Config file +contains a list of all the attributes that have meaning on a platform, and +uses the symbols defined in the enum HALData::TAttribute to +identify them. Using a simple syntax, an attribute can be defined as being +derived by associating the attribute symbol with the name of a function. This +function is known as the accessor function.

There is also a +file known as the Values file that defines the initial values for all +of the non-derived attributes, i.e. those attributes that are simply stored +in, and retrieved from, the HAL.

The Config and Values files are text +files that, for a specific implementation of the HAL, reside in the ...\variant\hal directory. +The MMP file also resides there, and the HAL is built as part of the Variant. +As part of the build process, the Config and Values files are passed to a +Perl script, halcfg.pl, which translates the contents +into C++ source files. The resulting binaries are linked in as part of the +resulting HAL DLL.

In effect, these C++ source files implement the +static data arrays defined by the HalInternal class. As its +name suggests, this class is internal to Symbian platform, and is only +discussed here to help with understanding.

class HalInternal + { + ... + static const TUint8 Properties[HAL::ENumHalAttributes]; + ... + static const TInt InitialValue[HAL::ENumHalAttributes]; + static const THalImplementation Implementation[HAL::ENumHalAttributes]; + ... + }

The data member Implementation[] is +an array of pointers to the accessor functions

See Creating +the Config & Values files for detailed syntax.

Derived attributes require accessor functions

Each +derived attribute has a corresponding accessor function. For example, ProcessDisplayContrast().

All +accessor functions are implemented in ...\hal\src\userhal.cpp, +and are provided by Symbian platform because of the 'connection' to attributes +which are themselves defined as part of the generic platform.

Generally +there is one accessor function per derived attribute, although there is nothing +to prevent an accessor function dealing with more than one attribute. The +attribute number is used to route calls made to HAL::Get() and HAL::Set() forward +to the correct accessor function. Internally, Symbian platform routes calls +to Get() and Set() for an attribute to the same accessor function, distinguishing +between the two by a boolean value.

A new implementation of an accessor +function should rarely, if ever, be needed as all likely accessor functions +are already defined and implemented by Symbian platform in ...\hal\src\userhal.cpp.

See Writing accessor functions +for derived attributes.

Accessor functions call UserSvr::HalFunction()

Typically, +an accessor function implementation calls UserSvr::HalFunction(), +specifying a group number, as defined in THalFunctionGroup, +and a function-id that is related to the attribute, but is not the +attribute number as defined in TAttribute. Function numbers +are published in u32hal.h, and exported into ...\epoc32\include; +for example, the enumerators of the enum TDigitiserHalFunction.

This +means that it is the accessor function, which is part of Symbian platform +generic code, that decides which HAL handler is to deal with a request (as +identified by the attribute).

The kernel uses the HAL group number +as an index to dispatch the call to the correct HAL handler.

Note +that there may be cases where access to a HAL attribute may be handled through +a device driver or server.

UserSvr::HalFunction() calls ExecHandler::HalFunction()

The +static function UserSvr::HalFunction(), which is internal to +Symbian platform, is the user side point of access. It takes a HAL group to identify a set of related hardware features. In addition, +it takes a function-id to identify specific hardware functionality within +the HAL group, for example, one of the TDisplayHalFunction enumerators.

A +call to this function results in a call to the kernel side function exechandler::HalFunction(), +passing the group number and the function-id. This, in turn, finds the appropriate HAL +handler function in the internal array K::HalFunction[], +using the group number as the index.

UserSvr::HalFunction() is +exported from euser.dll, and is therefore accessible +from the user side. However, it is not intended for general third party +use.

For information purposes, the UserSvr class +is defined in the source tree header file ...\e32\include\e32svr.h, +which is exported to ...\epoc32\include\.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-9B52E0C3-9EBB-44C6-A1BF-2F95711FFBA4.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-9B52E0C3-9EBB-44C6-A1BF-2F95711FFBA4.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,32 @@ + + + + + +Template +Source CodeThis document discusses the template code from which device drivers +are created. +

Template +source code

To help enable a base port be produced quickly, +Symbian platform provides template source code for drivers for most peripherals. +The template implements a framework and protocols for the type of peripheral; +the base port implementer then supplies additional implementation for the +particular hardware device. For example, for the UART driver, the PDD template +implements the standard hardware abstraction interfaces for serial communication, +such as the DComm class. It leaves some sections marked as +"TBD", which are specific to the device. Driver developers can start with +these templates and fill in the "TBD" functions to create a basic driver. +If required, additional functionality can then be added to this.

The +template drivers are located in the sf\os\kernelhwsrv\bsptemplate\asspandvariant\template_variant source +directory. The template directory provides a variant +base port that includes all the drivers required to do the minimal base port +for any variant.

Details of the templates for particular drivers are +discussed in the relevant sections of the Base Porting Guide. This +tutorial presents an additional example device driver.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-9B66387C-B6CF-41D9-BEFC-F79E30C70F52.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-9B66387C-B6CF-41D9-BEFC-F79E30C70F52.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,17 @@ + + + + + +Interrupt Build GuideDescribes how to build Interrupt platform service +

The Interrupt platform service is implemented as a part of the +ASSP variant layer and hence included in the baseport. For more information, +refer to ROM +Building guides.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-9BBDFF77-5E2C-4E13-BEB3-716CC80B3375.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-9BBDFF77-5E2C-4E13-BEB3-716CC80B3375.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,71 @@ + + + + + +SDIO Implementation GuideHow to port the SDIO Controller for your platform to provide +the SDIO adaptation. +

The SDIO implementation shares most of its functionality with the +Secure Digital (SD) Controller, which in turn extends the MultiMedia +Card (MMC) Controller. SDIO adds support for data transfer between +Input/Output hardware included on SDIO peripherals. The SDIO Controller +initializes SDIO peripherals and provides an API so that class drivers +can access the SDIO services.

Providing an SDIO adaptation for your platform means porting the +SDIO Controller. This is done by providing platform specific implementations +of the SDIO SHAI interface functions.

Prerequisites

SDIO depends on SD and MMC: the SDIO protocol is a super-set of +the SD protocol (and of the MMC protocol). Therefore, in addition +to the SDIO standard, you need to know about the following:

SD (Secure Digital)
MMC (MultiMedia Card)

Architecture

The following diagram illustrates the implementation of the SDIO +extension for the MMC Controller. The classes in green provide the +hardware interface and the classes in blue implement the platform-specific +functions.

+SDIO Controller classes + +

ImplementationThe Platform-Independent Layer (PIL) of the SDIO Controller is made +up from three sets of files described in the following table:

+ + + +Standard +Source code location + + + + +MMC +
os/kernelhwsrv/kernel/eka/drivers/pbus/mmc
See also Code Organization in the MMC section.
+ + +SD +os/kernelhwsrv/kernel/eka/drivers/pbus/mmc/sdcard/sdcard3c/
Also see Source Code in the SD section.
+ + +SDIO +os/kernelhwsrv/kernel/eka/drivers/pbus/mmc/sdcard/sdcard3c/sdio/ + + + +

The Platform-Specific Layer (PSL) should be located +in a variant directory and have a similar folder hierarchy to the +PIL. It should provide the following implementations:

Stack
Power Supply Unit (PSU)

These implementations are discussed in the tutorials:

SDIO +Stack Implementation Tutorial
SDIO +PSU Implementation Tutorial

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-9C05C157-D58E-4C43-87E4-82B4F310AEA9.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-9C05C157-D58E-4C43-87E4-82B4F310AEA9.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,50 @@ + + + + + +DmaChannelMgr ImplementationDescribes how to write the hardware-specific functions +of the DmaChannelMgr class. +

The DmaChannelMgr class is already defined in +the DMA header file but it belongs to the PSL implementation: opening +and closing channels require hardware-specific operations.

When implementing the PSL, you need to provide at least one function:TDmaChannel* DmaChannelMgr::Open(TUint32 aOpenId)

This function opens a DMA channel and returns the object controlling +this channel.

How the channel is allocated is hardware-dependent. The call to +the Open() function specifies which channel to open +through the aOpenId parameter. The format of the +parameter is not part of the DMA platform service and depends on an +agreement between the PSL implementation and the driver using DMA. +The example section below shows a static method, but the allocation +could also be completely or partially dynamic.

If you want to perform a hardware-specific operation when closing +the channel, you also need to update DmaChannelMgr::Close(). It is usually not necessary: in the template source code, it is +implemented as doing nothing.

+Open() example

This example illustrates +a simple allocation scheme where aOpenId represents +the index of the requested channel in the channel array (Controller.iChannels). +TDmaChannel* DmaChannelMgr::Open(TUint32 aOpenId) + { + __DMA_ASSERTA(aOpenId < static_cast<TUint32>(KChannelCount)); + TDmaChannel* pC = Controller.iChannels + aOpenId; + if (pC->IsOpened()) + pC = NULL; + else + { + pC->iController = &Controller; + pC->iPslId = aOpenId; + } + return pC; +}

+DMA +Client Interface Guide +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-9CC514E9-85C2-5F4B-9F3B-F9FA1F4CB20A-master.png Binary file Adaptation/GUID-9CC514E9-85C2-5F4B-9F3B-F9FA1F4CB20A-master.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-9CC514E9-85C2-5F4B-9F3B-F9FA1F4CB20A_d0e14358_href.png Binary file Adaptation/GUID-9CC514E9-85C2-5F4B-9F3B-F9FA1F4CB20A_d0e14358_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-9CF985F1-C100-5999-9410-58B7865A1E18.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-9CF985F1-C100-5999-9410-58B7865A1E18.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,12 @@ + + + + + +Obey Files

OBEY files are standard text files containing statements that are used to control the operation of the ROM building tools. ROMBUILDAn obey file has a .oby extension, and any files included by the OBEY file have a .iby extension.

ROMBUILD and ROFSBUILD understand a different subset of the complete set of OBEY file statements. Many statements are only understood by one tool, and a number of statements are common to both tools. In addition, some specific keywords are understood by BUILDROM only. BUILDROM typically converts them into statements that are understood by ROMBUILD, ROFSBUILD or both.

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-9D26E38F-5C7B-5330-A54B-8F97D0F204D0-GENID-1-2-1-8-1-1-7-1-1-5-1.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-9D26E38F-5C7B-5330-A54B-8F97D0F204D0-GENID-1-2-1-8-1-1-7-1-1-5-1.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,90 @@ + + + + + +Performance +LoggingSymbian platform provides macros that you can use in device driver +and kernel extension programs to write a trace log. +

You can use the trace log to test the performance of the programs.

Perfomance macros

There are three macros that you +can insert into your code. They only differ with respect to the optional data +that you can add to the trace record. All are defined in kernperfloger.h

PERF_LOG0 (aSubCategory)
PERF_LOG1 (aSubCategory,aUserData)
PERF_LOG2 (aSubCategory,aUserData,aUserData2)

Note: +the PERF_LOG macro is identical to PERF_LOG2.

You must specify an the 8-bit integer subcategory value in the aSubCategory argument. +You can also supply one or two (or zero) 32-bit values; you are free to decide +on the meaning of such values.

The macros wrap around the standard BTrace*** macros. +All trace records generated by these macros are given a category of BTrace::EKernPerfLog.

The +generation and capture of trace information is implemented as a kernel extension. +This means that it is loaded and activated at an early stage in the startup +process of the device.

Performance macro output format

The following table +shows which fields of a trace record are generated by each of the macros PERF_LOG0, PERF_LOG1, +and PERF_LOG2:

+ + + +

Field

PERF_LOG0

PERF_LOG1

PERF_LOG2

+ + +

Fast Counter Timestamp

Yes

+ + +

Context Id

Yes

+ + +

PC value

Yes

+ + +

the 32-bit integer value passed as aUserData

Yes

+ + +

the 32-bit integer value passed as aUserData2

Yes

+ + +

Tick Count as returned from a call to NKern::TickCount()

Yes

+ + + +

How to use the macros

To use the macros:

Include the header file kernperfloger.h in +your source code.
Link to btrace.lib in +your project
Call the PERF_LOG*** macros +at appropriate points in your code.

For examples, see the test code +for the macros in ...\e32test\group\d_perflogger_test_ldd.mmp and ...\e32test\group\t_perflogger.mmp
Rebuild your project

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-9D26E38F-5C7B-5330-A54B-8F97D0F204D0-GENID-1-2-1-9-1-8-1-19-1.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-9D26E38F-5C7B-5330-A54B-8F97D0F204D0-GENID-1-2-1-9-1-8-1-19-1.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,90 @@ + + + + + +Performance +LoggingSymbian platform provides macros that you can use in device driver +and kernel extension programs to write a trace log. +

You can use the trace log to test the performance of the programs.

Perfomance macros

There are three macros that you +can insert into your code. They only differ with respect to the optional data +that you can add to the trace record. All are defined in kernperfloger.h

PERF_LOG0 (aSubCategory)
PERF_LOG1 (aSubCategory,aUserData)
PERF_LOG2 (aSubCategory,aUserData,aUserData2)

Note: +the PERF_LOG macro is identical to PERF_LOG2.

You must specify an the 8-bit integer subcategory value in the aSubCategory argument. +You can also supply one or two (or zero) 32-bit values; you are free to decide +on the meaning of such values.

The macros wrap around the standard BTrace*** macros. +All trace records generated by these macros are given a category of BTrace::EKernPerfLog.

The +generation and capture of trace information is implemented as a kernel extension. +This means that it is loaded and activated at an early stage in the startup +process of the device.

Performance macro output format

The following table +shows which fields of a trace record are generated by each of the macros PERF_LOG0, PERF_LOG1, +and PERF_LOG2:

+ + + +

Field

PERF_LOG0

PERF_LOG1

PERF_LOG2

+ + +

Fast Counter Timestamp

Yes

+ + +

Context Id

Yes

+ + +

PC value

Yes

+ + +

the 32-bit integer value passed as aUserData

Yes

+ + +

the 32-bit integer value passed as aUserData2

Yes

+ + +

Tick Count as returned from a call to NKern::TickCount()

Yes

+ + + +

How to use the macros

To use the macros:

Include the header file kernperfloger.h in +your source code.
Link to btrace.lib in +your project
Call the PERF_LOG*** macros +at appropriate points in your code.

For examples, see the test code +for the macros in ...\e32test\group\d_perflogger_test_ldd.mmp and ...\e32test\group\t_perflogger.mmp
Rebuild your project

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-9D4B8CDF-60D7-5952-AAAF-94A3C1E8908F.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-9D4B8CDF-60D7-5952-AAAF-94A3C1E8908F.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,36 @@ + + + + + +ArchitectureExplains architecture of the User-Side Hardware Abstraction (HAL) +component. + + + +

Specific items of hardware +related information are called attributes.

The base port customises the hal.dll library to +set which attributes can be used on a device.

Some attributes are +simple values, but some attributes must be read and set with a function. These +functions are called accessor functions. The base port sets identifiers for +the accessor functions to use.
User-side programs use +the user-side +interface HAL class in hal.dll to +get and set information about attributes.
The accessor functions +are implemented on the kernel side by functions called HAL handlers.

The variant DLL and many device drivers in a +base port can implement HAL handlers.
Kernel-side programs +can use the Kernel-side +interface Kern::HalFunction() function to call HAL +handler functions.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-9D8C62FB-1E42-5B69-8ECC-2B68AD7C71A5-master.png Binary file Adaptation/GUID-9D8C62FB-1E42-5B69-8ECC-2B68AD7C71A5-master.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-9D8C62FB-1E42-5B69-8ECC-2B68AD7C71A5_d0e25863_href.png Binary file Adaptation/GUID-9D8C62FB-1E42-5B69-8ECC-2B68AD7C71A5_d0e25863_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-A04F46F8-1BA9-5A77-B455-59C67DD4AA36.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-A04F46F8-1BA9-5A77-B455-59C67DD4AA36.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,22 @@ + + + + + +Serial Port DriverThe Serial Port Driver is a device driver that handles serial port +hardware (create the physical channel). This section describes how to create +a port of it for your phone hardware. +

The Serial Port Driver +provides a logical device driver, ecomm.dll. You must +provide a physical device driver to implement the interface to the serial +port hardware on your phone.

+ +H4 serial connections +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-A25FFD79-0797-43EC-8975-8C23E7E539C4.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-A25FFD79-0797-43EC-8975-8C23E7E539C4.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,49 @@ + + + + + +Register Access Technology GuideProvides information about the Register Access technology. +

The Register Access platform service is implemented in the ASSP +layer. The Register Access functionality is provided to the clients +by implementing the AsspRegister class.

+ Purpose

The Register Access platform +service provides an interface to the kernel and device drivers to +read, write or modify the contents of only the ASSP registers.

Key +concepts

Register: A register is a memory location on the ASSP hardware to store +data that relates to the operation of that hardware. The Symbian platform +support registers that can store 8, 16, 32 and 64–bit data.
Bitmask: The Modify function of the AsspRegister class +allows the clients to set or clear certain bits stored in the register.
Application-Specific Standard Product (ASSP): ASSP is an integrated circuit consisting of CPU, Memory Management +Unit (MMU), cache and a number of on-chip peripherals, which is intended +to be used in a class of devices. Typical examples include UARTs, +timers, LCD controller that are designed and marketed by a silicon +vendor.

Typical +uses

The Register Access platform service allows the clients +to:

read data stored in 8, 16, 32 and 64–bit registers
store data in 8. 16, 32 and 64–bit registers
change certain bits of the data in 8, 16, 32 and 64–bit registers.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-A27BD4D8-8B0E-57C8-9C15-736109297DEA.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-A27BD4D8-8B0E-57C8-9C15-736109297DEA.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,369 @@ + + + + + +Keyword reference (D-F) +

This page lists the keywords starting from D to F.

data-aligndata-align = <hex-number>

rombuild +only

This keyword specifies the alignment for the executable's +data. It indicates the start address of a data segment that must be +aligned to a specified value.

Note: The +inclusion of data-align keyword in an OBY file does +not increase the size of ROM image.

datapagingoverride datapagingoverride [NOPAGING | ALWAYSPAGE | DEFAULTUNPAGED | DEFAULTPAGED]

rombuild and rofsbuild

If the datapagingoverride keyword is spe,cified in an OBY file, it overrides the configuration +for data paging for the executable files defined in OBY file. This +keyword takes a single argument, which can be one of the possible +values listed in codepagingoverride.

datapagingpolicy datapagingpolicy [NOPAGING | ALWAYSPAGE | DEFAULTUNPAGED | DEFAULTPAGED]

rombuild and rofsbuild

This overrides the default +settings for data paging and the settings from all the previous levels.

This keyword takes a single argument, +which can be one of the possible values listed in codepagingoverride.

data[[HWVD]] data[[HWVD]] = <source-file> <destination-file> [File-attribute-list] +

rombuild and rofsbuild

A file that +is copied from its source location into the ROM without any processing.

Note that the HWVD is optional but, if specified, must be enclosed +within square brackets.

dataaddress dataaddress = <hex-address>

rombuild only

Linear address of data/bss chunks +for all executables except the Kernel.

datadriveimagename datadriveimagename = <image name>

ROFSBUILD only

Specifies the name of the data +drive image.

DATA_IMAGE DATA_IMAGE <id> <name> [size=<partition size>] [FAT16 | FAT32] [compress | no-compress]

BUILDROM only

Defines a data drive image.

This is a data drive configuration feature. There is no limitation +for the number of data drive images that can be defined for an internal +media.

+ + + +

A value to identify the data drive image.

+ + +

name

A name suitable as a suffix for the data drive image, IBY +and logs.

+ + +

size = <partition size>

Defines the size of the data drive image that has to be +generated.

+ + +

compress

Compresses files in the image. If not specified, no compression +is the default behaviour.

+ + + +

To mark a file for inclusion in a data drive it is prefixed +with the keyword DATA_IMAGE. For example:

DATA_IMAGE[2] fatname size=16000000 fat16 -compress

The above information can also be included using '{' '}' braces, +for example:

DATA_IMAGE[2] + { + dataimagename=fatname + compress + dataimagefilesystem=fat16 + dataimagesize=16000000 + } +

dataimagefilesystem dataimagefilesystem = <FAT16 | FAT32>

BUILDROM and ROFSBUILD only

Specifies the file +system type of the datadrive image. If this is not specified then +by default BUILDROM sets the image file system as fat16.

dataimagename dataimagename = <image name>

ROFSBUILD only

Specifies the name of the datadrive +image. If this is not specified then by default BUILDROM sets +the image name as dataimagex, where x is the image index.

dataimagesize dataimagesize = <size in bytes>

ROFSBUILD only

Specifies the maximum size of +a data drive image. The default size is the size of the data drive +folder.

DEFAULT_LANGUAGE DEFAULT_LANGUAGE NN

BUILDROM only

Localisation support. Specifies +the default language as a Symbian 2-digit code. This keyword should +only be used once.

DEFINE DEFINE <name> <replacement>

BUILDROM only

Performs textual substitution. +All subsequent instances of <name> are replaced by <replacement>.

Notes:

There is no +UNDEFINE facility, and substitutions are applied in an unspecified +order
The C++ preprocessor +cannot be used conveniently because it inserts whitespace around substituted +text.

device[[HWVD]] device[[HWVD]] = <source-file> <destination-image-file> [File-attribute-list] [Override-Attribute-list]

rombuild only

Defines kernel-mode logical or +physical device drivers, which can have global data. The address of +this data is generated by rombuild.

Note +that the HWVD is optional but, if specified, must +be enclosed within square brackets.

dll[[HWVD]] dll[[HWVD]] = <source-file> <destination-image-file> [File-attribute-list] [Override-Attribute-list]

rombuild only

Specifies an executable file whose +entry point must be called.

debugport debugport = <32bit-number>

rombuild only

Specifies the destination port +for Kernel and Bootstrap traces.

rombuild stores the value in the ROM header. Each ASSP is free to interpret +the debug port as it pleases, for example, as a serial port number +or as an I/O base address. The default value is -1.

defaultstackreserve defaultstackreserve = <default stack reserve>

rombuild only

Specifies the maximum size of +the stack.

demandpagingconfig demandpagingconfig <MinLivePages> <MaxLivePages> <YoungOldPageRatio> <NANDPageReadDelay> <NANDPageReadCPUOverhead>

rombuild only

Specifies settings for demand +paging enabled ROM.

This keyword takes four arguments, which +are described below:

MinLivePages: This is the minimim number of RAM pages to reserve for the paging +system.The number must be at least equal to 2*(YoungOldPageRatio+1). +If a smaller number is specified, a number equal to this formula is +used instead.

For example, the YoungOldPageRatio is 3 and MinLivePages is set to 5. According to +the formula 2*(YoungOldPageRatio+1), the minimum number of live pages +must be 8, but the number specified is 5. So the minimum number is +set to 8.
MaxLivePages: The maximum number of RAM pages the paging system may use. The +number must be greater than or equal to MinLivePages. On a production system the number is always set to maximum (32767). +However, low values may be used to test the effects of low free RAM.
YoungOldPageRatio: The ratio of young to old pages maintained by the system. For this +purpose, the paging system maintains a list of live pages, which is +again split into two sub-lists: a list of young pages, and a list +of old pages in the system. The paging system uses YoungOldPageRatio to maintain the relative sizes of these two lists.

For example, +let us assume that the ratio is R, the number of young pages is N_y and the number of old pages is N_o. If N_y > RN_o, a page is taken from the end of the young pages +list and placed at the start of the old pages list. This process is +called aging.
NANDPageReadDelay: The delay in microseconds, between initiating a page read operation +and completing it. During this delay, other threads in the system +may use the CPU.
NANDPageReadCPUOverhead: The CPU instruction execution time in microseconds, to setup and +process a page read operation. During this delay, the CPU is busy +and is not accessible by other threads.

Note: All the above listed attributes are limited +to the value range 0-32767.

dlldatatop dlldatatop = <address of data region>

rombuild only

Specifies the top of the DLL data +region.

ECHO ECHO <anything at all>

BUILDROM only

Prints the rest of the line following +the ECHO keyword to standard output.

__ECOM_PLUGIN __ECOM_PLUGIN(<local build directory>, <rom binary directory>, <local epoc32\data\Z directory>, <rom resources directory>, <DLL filename>, <resource filename>)

BUILDROM only

Specifies an ECom plug-in, consisting +of an implementation DLL and an ECom registration resource file, to +include in ROM.

Symbian platform code does not use this keyword +directly. Instead, it uses the macro ECOM_PLUGIN, +defined in \epoc32\rom\include\header.iby, which +allows the plug-in to be specified more briefly, in the following +form:

ECOM_PLUGIN(<DLL name>,<resource file name>)

For example:

ECOM_PLUGIN(foo.dll,12345abc.rsc)

Note that the resource file name is specified using the <DLL-uid>.rsc format.

Use of this keyword allows BUILDROM to perform special handling of ECom plug-ins. In +particular, it allows BUILDROM optionally to create +a static plug-in information (SPI) file, which contains all the resource +registration files for ROM-based plug-ins. This allows ECom to be +more efficient, as it can use the SPI file to find all ROM-based plug-ins +and not have to scan the file system for them. BUILDROM implements +this using the spidata keyword.

Note that as part of the ROM creation +process, it is possible to add support for multiple languages. This +affects how ECom resource files are specified by BUILDROM:

If an SPI file +is being created the ECOM_PLUGIN lines are processed +at an intermediate BUILDROM stage to produce:
spidata=MULTI_LINGUIFY( EXT sourcename destname ) <spi-id> <target-spi-dir>
During the BUILDROM localisation stage these lines become:
spidata = <source-file> <original-destination-file> <spi-id> <target-spi-dir>
where <spi-id> has the extension .SPI for +the default language, and the extension .Snn for +all other language codes nn. This means that if +multiple languages are being included in the ROM image there is an +SPI file for each included language.
If an SPI file +is not being created ECOM_PLUGIN lines are processed +an intermediate BUILDROM stage to produce:
data=MULTI_LINGUIFY( EXT sourcename destname )
During the BUILDROM localisation stage these lines become:

data=sourcename.Enn destname.EXT for the default +language code

data=sourcename.Enn destname.Enn for all other language codes nn.

EPOCROOT EPOCROOT

BUILDROM only

A pre-defined substitution. This +is replaced with the value of the EPOCROOT environment variable.

Note that there is no UNDEFINE facility, and substitutions are +applied in an unspecified order.

epocwrapper epocwrapper

rombuild only

Indicates that a Symbian platform +ROM wrapper is required

ERROR ERROR <anything at all>

BUILDROM only

Prints the rest of the line following +the ERROR keyword to standard output, and reports the source file +name and the line number. In addition, it causes BUILDROM to terminate without attempting to create the ROM image(s).

exattrib exattrib=U

ROFSBUILD only

This keyword is used with the data keyword to specify an additional attribute for the file +being included in the ROM image. This attribute enables the file server +to append the ROFS mounting information in the format, file.ext[<mount_id>-00] when registering the file.

The following example shows how +this keyword is used to set the attribute for a text file, which is +copied to the ROM image:

data=EPOCROOT##epoc32\rom\rofstest\hello8.txt Exattrib\test1.txt exattrib=U +

Assuming that the test1.txt file +is in the ROFS image and is the first one to be mounted by the file +server, the file is included in the ROM image in the following format:

z:\Exattrib\test1.txt[01-00]

EXCLUDE_FEATURE EXCLUDE_FEATURE <feature name> [ SF <status flags> ] [ UD <user data> ]

Where <feature> is either the feature name +or a feature uid value.

Note: The space between the keyword FEATURE and <feature name> is +optional.

<status flags> is a 32 bit +hex number indicating the status flags of the feature. Each bit in +the status flag signifies the following:

+ + + + +Bit +Flag Name +Value + + + + +

Supported

If the bit is set the feature is included, else the feature +is excluded.

+ + +

Upgradeable

This bit is reserved for future use. It will be used to +upgrade a feature which is already associated to the device.

+ + +

Modifiable

If the bit is set the feature is modified at run-time. The +default flag values for such a feature are defined in a ROM image +obey file.

+ + +

Blacklisted

If the bit is set the feature is blacklisted, and cannot +be changed at run-time. It signifies that if the feature appears in +subsequent data files or plug-in info, it would be ignored.

It also prevents a feature from being upgraded and it can never be +changed/ overridden. If a feature is blacklisted, its upgradeable +flag is not set.

+ + +

Uninitialised

If the bit is set the flag supported state is not initialised +at build-time, and it is initialised at run-time by system software.

To set the supported flag of a specific feature, perform a runtime +call to RFeatureControl.

+ + +

Persisted

If the bit is set the flag value is preserved across reboot +or system turn off period.

+ + +

6-31

Reserved

These bits are reserved for future use.

+ + + +

<user data> is a 32 bit hex number +indicating the user data value associated with the feature.

BUILDROM only

The EXCLUDE_FEATURE keyword +is used to mark a feature as excluded.

extension[[HWVD]] extension[[HWVD]] = <source-file> <destination-image-file> [File-attribute-list] [Override-Attribute-list]

rombuild only

Defines a kernel-mode DLL that +can have global data, the address of which is generated by rombuild. Extension files are connected together in a linked +list, which allows the Kernel to load the extensions at boot time +before the ROM file system is available.

Note that the HWVD is optional but, if specified, must be enclosed within +square brackets.

extensionrofs extensionrofs

rofsbuild only

Marks the start of the definition +of an optional extension ROFS.

extensionrofsname extensionrofsname = <filename>

rofsbuild only

Defines the name of the ROFS +extension image.

Any new files added after this keyword will +appear in the extension. The files in the core can be renamed, hidden, +and aliased by using the other keywords.

extensionrom extensionrom = <rom-file-name>

rombuild only

This marks the start of an extension +ROM section. A filename of "*" can be specified, which means use the +file name specified on the romname keyword in a rom-information-statement

externaltool externaltool=<toolname>

BUILDROM only

Used for invoking external tools +through the IBY file keyword externaltool, specifying the list of +toolnames each seperated by a comma. externaltool=toolname1, +toolname2,... toolnameN

The same invocation can +be achieved alternatively by using BUILDROM command-line option -e<toolname>.

fattable fattable=<number of FAT tables>

rofsbuild only

Configures the number of FAT +tables for the file system in the data-drive image.

FEATURE FEATURE <feature name> [ SF <status flags> ] [ UD <user data> ]

Where <feature> is either the feature name +or the feature uid value.

Note: The space between +the keyword FEATURE and <feature name> is optional.

<status flags> is a 32 +bit hex number indicating the status flags of the feature. Each bit +in the status flag signifies the following:

+ + + + +Bit +Flag Name +Value + + + + +

Supported

If the bit is set the feature is included, else the feature +is excluded.

+ + +

Upgradeable

This bit is reserved for future use. It will be used to +upgrade a feature which is already associated to the device.

+ + +

Modifiable

If the bit is set the feature is modified at run-time. The +default flag values for such a feature are defined in a ROM image +obey file.

+ + +

Blacklisted

If the bit is set the feature is blacklisted, and cannot +be changed at run-time. It signifies that if the feature appears in +subsequent data files or plug-in info, it would be ignored.

It also prevents a feature from being upgraded and it can never be +changed/ overridden. If a feature is blacklisted, its upgradeable +flag is not set.

+ + +

Uninitialised

If the bit is set the flag supported state is not initialised +at build-time, and it is initialised at run-time by system software.

To set the supported flag of a specific feature, perform a runtime +call to RFeatureControl.

+ + +

Persisted

If the bit is set the flag value is preserved across reboot +or system turn off period.

+ + +

6-31

Reserved

These bits are reserved for future use.

+ + + +

<user data> is a 32 bit hex number +indicating the user data value associated with the feature.

BUILDROM only

The FEATURE keyword is used +to mark a feature as included.

file[[HWVD]] file[[HWVD]] = <source-file> <destination-image-file> [File-attribute-list] [Override-Attribute-list] [paged | unpaged]

rombuild and rofsbuild

A standard executable +file, for example, a .exe or a .dll, in PE format or E32 image format. Executable files are stripped +of their relocation information prior to being stored in the ROM. +The relocation information is not necessary in the ROM because all +files are executed in place with an address that is determined at +ROM build time. Use the modifiers paged and unpaged to specify whether to page the executables or not. +You can also use the MMP file keywords paged and unpaged to specify whether to +page an executable or not.

For example, the following entry +in the Obey file provides the source and destination locations of +the file MyLibrary.dll and marks the DLL as unpaged.

file=ABI_DIR\DEBUG_DIR\MyLibrary.dll \sys\bin\MyLibrary.dll unpaged

Notes:

the HWVD is optional but, if specified, must be enclosed within +square brackets.
the information +required to relocate the file is not preserved; this keyword provides +a fully resolved uncompressed file.

filecompressnone filecompressnone=\Epoc32\release\<platform><build><target directory><source file> <destination file>

rombuild only

Doesn't compress the resulting +ROM image.

For example:

filecompressnone=\epoc32\release\ARMV\UREL\TEST\RUNTEST.EXE sys\bin\RUNTEST.EXE

filecompressinflate filecompressinflate=\Epoc32\release\<platform><build><target directory><source file> <destination file>

rombuild only

Compresses the resulting ROM image +using the Deflate, Huffman+LZ77 algorithm.

For example:

filecompressinflate=\epoc32\release\ARMV\UREL\TEST\RUNTEST.EXE sys\bin\RUNTEST.EXE

filecompressbytepair filecompressbytepair=\Epoc32\release\<platform><build><target directory><source file> <destination file>

rombuild only

Compresses the resulting ROM image +using the bytepair algorithm.

For example:

filecompressbytepair=\epoc32\release\ARMV\UREL\TEST\RUNTEST.EXE sys\bin\RUNTEST.EXE

filecompress[[HWVD]] filecompress[[HWVD]] = <source-file> <destination-file> [File-attribute-list] [Override-Attribute-list]

rombuild only

An XIP (execute-in-place) executable +to be loaded into the ROM in compressed format. Note that the information +required to relocate the file is preserved.

fileuncompress[[HWVD]] fileuncompress[[HWVD]] = <source-file> <destination-file> [File-attribute-list] [Override-Attribute-list]

rombuild only

XIP (execute-in-place) executable +to be loaded into the ROM uncompressed format. Note that the information +required to relocate the file is preserved.

fixed fixed

rombuild only

This executable is loaded as a +fixed address process, and has its data fixed in kernel space (high +memory). The data of normal executables is paged in and out of low +memory as the executable runs. Fixing a chosen subset of the system +servers saves context switch time, and speeds execution considerably.

formatversion

formatversion= <format version>

Specifies the SMR image format version. This value is checked by +the SMR consumers (such as HCR) at runtime to ensure code compatibility +with image or data format.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-A328F9E3-7D91-594A-A589-E8CE5FA9227A-master.png Binary file Adaptation/GUID-A328F9E3-7D91-594A-A589-E8CE5FA9227A-master.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-A328F9E3-7D91-594A-A589-E8CE5FA9227A_d0e69077_href.png Binary file Adaptation/GUID-A328F9E3-7D91-594A-A589-E8CE5FA9227A_d0e69077_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-A3A3405C-C89C-5079-85CE-8CB069C8E0C0.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-A3A3405C-C89C-5079-85CE-8CB069C8E0C0.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,53 @@ + + + + + +IIC Client Interface QuickstartThis document gives a brief overview of the IIC client +interface API. +

Purpose

The IIC client interface API creates a common interface from +device drivers to serial inter-IC buses (IIC buses).

Intended +audience

This document is intended to be used by device +driver writers.

Architectural +relationship

The IIC client interface API is part of a +group of APIs which provide a common, hardware-independent, interface +from kernel to different hardware. Other APIs of this type include +GPIO.

Description

Physically, a bus represented +by IIC is accessed over a node. The IIC client interface API wraps +a node in a software construct called a channel. It provides functionality +for creating and accessing channels directly. There are two possible +modes of operation:

Controller
Where the device drivers that use the IIC +client interface API can access different IIC channels.
Controller-less
Where the channels that the device driver +can access are set at compile time.

Furthermore, there are three possible channel behaviors:

Master
The device driver initializes the data transfer.
Slave
The device driver carries out a data transfer that +is controlled by another node attached to the bus.
MasterSlave
The device driver can carry out both roles.

IIC +classes

If the access to the IIC bus is to be via a controller, +then the IIC platform service API class to use is:

IicBus

If the access to the IIC bus is to be without a controller +(controller-less operation), then the IIC platform service API classes +to use are:

DIicBusChannelMaster
DIicBusChannelSlave
DIicBusChannelMasterSlave

+Client +of Master Channel Tutorial +Client +of Slave Channel Tutorial +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-A4179FF3-4541-44B8-A8F3-52C1318159B3.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-A4179FF3-4541-44B8-A8F3-52C1318159B3.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,60 @@ + + + + + +Platform +SecurityThis document discusses how device drivers should implement platform +security. +

Device drivers must follow the Symbian platform security guidelines. As +a part of platform security, drivers must be given the necessary platform +security capabilities. A driver can also check the capabilities of a process +opening a channel on the device, in order to restrict access to the device.

Driver-side +definition

Because drivers are loaded by the Kernel, both LDDs +and PDDs must have the same level of trust and capability as the Kernel. This +means that platform security capabilities must be set to ALL in +the LDD and PDD .mmp files.

// LDD: mmp file +... +CAPABILITY ALL // PDD: mmp file +... +CAPABILITY ALL

The user program must have the necessary +capability set in its .mmp file to open and access the +driver API. The reference documentation for the API should say what capabilities +are required. Usually, they are the same as the minimum capability that is +required to load the drivers.

// Test application: mmp file +... +CAPABILITY CommDD ReadDeviceData PowerMgmt

User-side verification

A +device driver must check the capability of the process that is accessing it. +This is typically done during channel creation and, if required, for specific +requests to the LDD. The Kernel provides the Kern::CurrentThreadHasCapability() API +to check the capability of the calling process. It can check for more than +one capability.

The following shows how the example driver checks +during channel creation that the user has the ECapabilityCommD capability:

TInt DExDriverLogicalChannel::DoCreate(TInt /*aUnit*/, const TDesC8* +/*anInfo*/, const TVersion& aVer) + { + // Capability check - CommDD + if (!Kern::CurrentThreadHasCapability (ECapabilityCommDD, + __PLATSEC_DIAGNOSTIC_STRING("Checked by Tutorial Driver"))) + return KErrPermissionDenied; + ... + }

Data caging

Symbian +platform security requires that all DLLs and EXEs are placed in the folder /sys/bin. +Drivers and test application binaries must be placed in the /sys/bin folder +by their ROM .iby file.

// iby file +device[VARID]=KERNEL_DIR\DEBUG_DIR\exdriver_ldd.ldd \Sys\Bin\exdriver_ldd.ldd +device[VARID]=KERNEL_DIR\DEBUG_DIR\exdriver_pdd.pdd \Sys\Bin\exdriver_pdd.pdd +file=ABI_DIR\BUILD_DIR\exdriver_test.exe \Sys\Bin\exdriver_test.exe +

+Platform +security architecture +

\ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-A4C19890-2380-5498-A5F8-3B6D95CEFEF4.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-A4C19890-2380-5498-A5F8-3B6D95CEFEF4.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,428 @@ + + + + + +PSL +ImplementationDescribes how to create the PSL implementation. +

To create a port of the DMA Framework, you must create an implementation +of the PSL for the DMA controller hardware.

Define and +implement PSL-specific channel classes

The choice of class to be +used for implementing DMA channels is governed by the mode of operation to +be supported:

single-buffer channels +should use TDmaSbChannel
double-buffer channels +should use TDmaDbChannel
scatter-gather channels +should use TDmaSgChannel

These three classes are defined in dma.h.

In +addition, the PSL may need to store channel-specific data. One way of achieving +this is by deriving a PSL-specific class from one of the generic ones. For +example, the template scatter-gather implementation defines a TTemplateSgChannel class +derived from TDmaSgChannel for storing data when appending +new descriptors to a running channel:

class TTemplateSgChannel : public TDmaSgChannel + { +public: + TDmaDesc* iTmpDes; + TPhysAddr iTmpDesPhysAddr; + }; + +

Define and +implement the controller classes

A controller can either be a physical +controller, or a logical one depending on which DMA +mode you intend to support.

The PSL (platform-specific layer) +must define one concrete controller class per supported controller. A controller +class is derived from TDmac. The concrete class must implement +all the pure virtual functions defined in TDmac, and, optionally +the functions used to manipulate hardware descriptors.

Taking the +template port as an example, the class is defined as:

class TTemplateDmac : public TDmac + { +public: + TTemplateDmac(); + TInt Create(); +private: + // from TDmac (PIL pure virtual) + virtual void Transfer(const TDmaChannel& aChannel, const SDmaDesHdr& aHdr); + virtual void StopTransfer(const TDmaChannel& aChannel); + virtual TBool IsIdle(const TDmaChannel& aChannel); + virtual TInt MaxTransferSize(TDmaChannel& aChannel, TUint aFlags, TUint32 aPslInfo); + virtual TUint MemAlignMask(TDmaChannel& aChannel, TUint aFlags, TUint32 aPslInfo); + // from TDmac (PIL virtual) + virtual void InitHwDes(const SDmaDesHdr& aHdr, TUint32 aSrc, TUint32 aDest, TInt aCount, + TUint aFlags, TUint32 aPslInfo, TUint32 aCookie); + virtual void ChainHwDes(const SDmaDesHdr& aHdr, const SDmaDesHdr& aNextHdr); + virtual void AppendHwDes(const TDmaChannel& aChannel, const SDmaDesHdr& aLastHdr, + const SDmaDesHdr& aNewHdr); + virtual void UnlinkHwDes(const TDmaChannel& aChannel, SDmaDesHdr& aHdr); + // other + static void Isr(TAny* aThis); + inline TDmaDesc* HdrToHwDes(const SDmaDesHdr& aHdr); +private: + static const SCreateInfo KInfo; +public: + TTemplateSgChannel iChannels[KChannelCount]; + }; +

Notes:

The array of channels +must be defined in the PSL controller class because only the PSL knows what +kind of channels are used.
The PSL controller class +must be allocated in the BSS section of the DMA kernel extension. The second +phase constructor must be called from the extension entry point.
The C++ constructor +must pass a TDmac::SCreateInfo structure to the TDmac constructor. +This structure defines what the PIL (platform-independent layer) needs to +know about the underlying DMA controller. The template TTemplateDmac constructor +just passes a TDmac::ScreateInfo structure, which defines +the layout of the (base class managed) descriptor pool to the base class constructor +through a ctor list:
TTemplateDmac::TTemplateDmac() +// +// Constructor. +// + : TDmac(KInfo) + {} + +
where KInfo is a TDmac::ScreateInfo type.
The PSL controller class +needs a second phase constructor. This is the Create() function, +which must:
1. call the second phase +constructor of the base class: TDmac::Create().
2. perform any hardware-specific +initialisation.
3. bind and enable the +DMA interrupt(s).
In the template port, Create() calls the base class TDmac::Create() function +and then initialises the template specific channel object members (the temporary +descriptor fields used for appending requests to live channels), and performs +platform specific initialisation for the interrupt dispatch of DMA interrupt +events:
TInt TTemplateDmac::Create() +// +// Second phase construction. +// + { + TInt r = TDmac::Create(KInfo); // Base class Create() + if (r == KErrNone) + { + __DMA_ASSERTA(ReserveSetOfDes(KChannelCount) == KErrNone); + for (TInt i=0; i < KChannelCount; ++i) + { + TDmaDesc* pD = HdrToHwDes(*iFreeHdr); + iChannels[i].iTmpDes = pD; + iChannels[i].iTmpDesPhysAddr = DesLinToPhys(pD); + iFreeHdr = iFreeHdr->iNext; + } + r = Interrupt::Bind(EAsspIntIdDma, Isr, this); + if (r == KErrNone) + { + // TO DO: Map DMA clients (requests) to DMA channels here. + + r = Interrupt::Enable(EAsspIntIdDma); + } + } + return r; + } +

Implement the +channel allocator

Channel allocation is implemented in the PSL +(platform-specific layer) because this is a hardware-specific operation. There +are two basic options:

Preallocate, at design +time, one channel per DMA-aware peripheral. This is the simplest approach, +and it should be acceptable for most Symbian platform devices because the +set of supported peripherals is closed. In this case, cookies passed by client +device drivers map uniquely to DMA channels.
Full dynamic allocation. +This is a simple approach too, but DMA channels are, in general, not completely +identical. For example, some channels may have greater priorities than others.

Mixed schemes are also possible, for example, client device driver +cookies could be used to select a subset of channels, and dynamic allocation +used inside this subset.

Whatever option is chosen, the PSL must provide +an implementation for the function DmaChannelMgr::Open(). +The template implementation is:

TDmaChannel* DmaChannelMgr::Open(TUint32 aOpenId) +// +// +// + { + __KTRACE_OPT(KDMA, Kern::Printf(">DmaChannelMgr::Open aOpenId=%d", aOpenId)); + + __DMA_ASSERTA(aOpenId < static_cast<TUint32>(KChannelCount)); + + TDmaChannel* pC = Controller.iChannels + aOpenId; + if (pC->IsOpened()) + pC = NULL; + else + { + pC->iController = &Controller; + pC->iPslId = aOpenId; + } + + return pC; + } +

The template DMA channel manager returns a pointer to +a DMA channel if the channel has not been previously allocated. Note that +since channels possess preset priorities, the device drivers must be aware +of which channel(s) they require DMA service from and configure the DMA controller +to route sources to allocated channels accordingly.

The platform-specific +cookies passed by client device drivers to the PSL must be defined somewhere +so that client device drivers can access them.

[Optionally] +implement channel cleanup

In the template PSL (platform-specific +layer), the function DmaChannelMgr::Close() is a no-operation. +This function is called by the PIL (platform-independent layer) when client +device drivers call TDmaChannel::Close(). If the PSL needs +to perform any hardware-specific operation when the channel is closed, then +the implementation of DmaChannelMgr::Close() should be updated +to reflect that.

Implement the +mandatory controller virtual functions

The TDmac class +contains several pure virtual functions that must be implemented by the PSL +(platform-specific layer):

TDmac::Transfer()
TDmac::StopTransfer()
TDmac::IsIdle()

These functions start and stop transfers on a DMA channel and are +the main interface between the PIL (platform-independent layer) and the PSL. +The implementation of these functions depends on the hardware available for +performing DMA, and on the characteristics used to specify a DMA transfer:

the source and destination +addresses
the burst size
the maximum transfer +size
the transfer width, +i.e. number of bits per memory access
the memory alignment +and endianness.

The DMA Framework manages the transfer descriptors according to the +descriptor parameter passed into the TDmac constructor +by the derived class constructor; the descriptor parameter is a TDmac::SCreateInfo structure. +The per-request transfer parameters are passed into the descriptors for each +request issued by a driver.

The +transfer function: Transfer()

This function initiates a previously +constructed request on a specific channel. This is the template implementation:

void TTemplateDmac::Transfer(const TDmaChannel& aChannel, const SDmaDesHdr& aHdr) +// +// Initiates a (previously constructed) request on a specific channel. +// + { + const TUint8 i = static_cast<TUint8>(aChannel.PslId()); + TDmaDesc* pD = HdrToHwDes(aHdr); + + __KTRACE_OPT(KDMA, Kern::Printf(">TTemplateDmac::Transfer channel=%d des=0x%08X", i, pD)); + + // TO DO (for instance): Load the first descriptor address into the DMAC and start it + // by setting the RUN bit. + (void) *pD, (void) i; + + } +

The +stop transfer function: StopTransfer()

This function requires +that the RUN mode is cleared. This is the template implementation:

void TTemplateDmac::StopTransfer(const TDmaChannel& aChannel) +// +// Stops a running channel. +// + { + const TUint8 i = static_cast<TUint8>(aChannel.PslId()); + + __KTRACE_OPT(KDMA, Kern::Printf(">TTemplateDmac::StopTransfer channel=%d", i)); + + // TO DO (for instance): Clear the RUN bit of the channel. + (void) i; + + } +

The +function: IsIdle()

IsIdle() returns the state +of a given channel. This is the template implementation:

TBool TTemplateDmac::IsIdle(const TDmaChannel& aChannel) +// +// Returns the state of a given channel. +// + { + const TUint8 i = static_cast<TUint8>(aChannel.PslId()); + + __KTRACE_OPT(KDMA, Kern::Printf(">TTemplateDmac::IsIdle channel=%d", i)); + + // TO DO (for instance): Return the state of the RUN bit of the channel. + // The return value should reflect the actual state. + (void) i; + + return ETrue; + } +

Implement the +non-mandatory controller virtual functions

The following auxiliary +functions are used to implement the scatter-gather transfer mode behaviour +by creating and manipulating the linked list of transfer fragment headers +that describe a given scatter-gather transaction. They are called by the TDmac base +class functions when the instance of the TDmac derived class +reports itself as being capable of scatter-gather operations.

TDmac::InitHwDes()
TDmac::ChainHwDes()
TDmac::AppendHwDes()

First +scatter-gather support function: InitHwDes()

This is a function +for creating a scatter-gather list. From the information in the passed-in +request, the function sets up the descriptor with that fragment's:

source and destination +address
size
driver/DMA controller +specific transfer parameters: memory/peripheral, burst size, transfer width.

This is the template implementation:

void TTemplateDmac::InitHwDes(const SDmaDesHdr& aHdr, TUint32 aSrc, TUint32 aDest, TInt aCount, + TUint aFlags, TUint32 aPslInfo, TUint32 /*aCookie*/) +// +// Sets up (from a passed in request) the descriptor with that fragment's source and destination address, +// the fragment size, and the (driver/DMA controller) specific transfer parameters (mem/peripheral, +// burst size, transfer width). +// + { + TDmaDesc* pD = HdrToHwDes(aHdr); + + __KTRACE_OPT(KDMA, Kern::Printf("TTemplateDmac::InitHwDes 0x%08X", pD)); + + // Unaligned descriptor? Error in generic layer! + __DMA_ASSERTD(IsHwDesAligned(pD)); + + pD->iSrcAddr = (aFlags & KDmaPhysAddrSrc) ? aSrc : Epoc::LinearToPhysical(aSrc); + pD->iDestAddr = (aFlags & KDmaPhysAddrDest) ? aDest : Epoc::LinearToPhysical(aDest); + pD->iCmd = DcmdReg(aCount, aFlags, aPslInfo); + pD->iDescAddr = TDmaDesc::KStopBitMask; + } + +

Second +scatter-gather support function: ChainHwDes()

If the framework +needs to fragment the client’s request, for transfer size or memory discontiguousness +reasons, then the framework calls this function. It chains hardware descriptors +together by setting the next pointer of the original descriptor to the physical +address of the descriptor to be chained. It assumes that the DMAC channel +is quiescent when called.

This is the template implementation:

Third +scatter-gather support function: AppendHwDes()

This function is +called by the TDmac base class when a driver request is +called for a channel that is still active, i.e. where the intent is to provide +data streaming so that the target device is constantly provided with data; +for example, an audio device playing a track. In this case, the function provided +by the derived class must:

stop the DMAC to prevent +any corruption of the scatter-gather list while appending the new fragment +descriptor
append the new descriptor
re-enable the channel, +ideally before the target has detected the gap in service.

This is the template implementation:

void TTemplateDmac::AppendHwDes(const TDmaChannel& aChannel, const SDmaDesHdr& aLastHdr, + const SDmaDesHdr& aNewHdr) +// +// Appends a descriptor to the chain while the channel is running. +// + { + const TUint8 i = static_cast<TUint8>(aChannel.PslId()); + + TDmaDesc* pL = HdrToHwDes(aLastHdr); + TDmaDesc* pN = HdrToHwDes(aNewHdr); + + __KTRACE_OPT(KDMA, Kern::Printf(">TTemplateDmac::AppendHwDes channel=%d last des=0x%08X new des=0x%08X", + i, pL, pN)); + // Unaligned descriptor? Error in generic layer! + __DMA_ASSERTD(IsHwDesAligned(pL) && IsHwDesAligned(pN)); + + TPhysAddr newPhys = DesLinToPhys(pN); + + const TInt irq = NKern::DisableAllInterrupts(); + StopTransfer(aChannel); + + pL->iDescAddr = newPhys; + const TTemplateSgChannel& channel = static_cast<const TTemplateSgChannel&>(aChannel); + TDmaDesc* pD = channel.iTmpDes; + + // TO DO: Implement the appropriate algorithm for appending a descriptor here. + (void) *pD, (void) i; + + NKern::RestoreInterrupts(irq); + + __KTRACE_OPT(KDMA, Kern::Printf("<TTemplateDmac::AppendHwDes")); + } +

Implement an +interrupt service routine

The interrupt service routine needs to +do the following:

identify the channel +that raised the interrupt
decide whether the interrupt +was raised because of a successful data transfer or because of an error
call the base class +function TDmac::HandleIsr(), which queues a DFC, or increments +the number of pending interrupts if a DFC is already queued.

This is the template implementation:

void TTemplateDmac::Isr(TAny* aThis) +// +// This ISR reads the interrupt identification and calls back into the base class +// interrupt service handler with the channel identifier and an indication whether the +// transfer completed correctly or with an error. +// + { + TTemplateDmac& me = *static_cast<TTemplateDmac*>(aThis); + + // TO DO: Implement the behaviour described above, call HandleIsr(). + + HandleIsr(me.iChannels[5], 0); // Example + + } +

Implement the +test support table and function

The DMA Framework comes with a +test harness that can be used to validate the port if the underlying DMA controller +supports memory to memory transfers.

The test harness needs to know +about the capabilities of the port being tested. The PSL provides the global +function DmaTestInfo() that returns a TDmaTestInfo object +that contains this information. In the template PSL, this structure is initialised +to binary zeroes. Before using the test harness, it must be initialised with +valid values.

See TDmaTestInfo, DmaTestInfo() and Validation.

Optimise the +performance of critical functions

You can optionally optimise critical +functions by writing them in assembler. The two candidates for an assembler +rewrite are:

The interrupt service +routine
In scatter-gather mode, +the TDmac::AppendHwDes() function if it needs to suspend +a transfer when appending a new descriptor chain to an existing one.

Extend the +framework with platform-specific functionality

There are two ways +of extending the DMA Framework:

to provide platform-specific +functionality on a per-channel basis.
to provide platform-specific +functionality on a channel independent basis.

In the first case, the PSL provides an implementation of the virtual +function TDmac::Extension(). The default implementation +just returns KErrNotSupported.

TDmaChannel::Extension() calls TDmac::Extension().

In the second case, the PSL provides an implementation of the static +function DmaChannelMgr::StaticExtension(). The template +PSL implementation just returns KErrNotSupported.

TDmaChannel::StaticExtension() calls DmaChannelMgr::StaticExtension().

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-A4CCF2B6-26B7-5E8C-B738-9EE9E68A0B35.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-A4CCF2B6-26B7-5E8C-B738-9EE9E68A0B35.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,62 @@ + + + + + +ReferenceSummary of related documentation for the DMA Framework. +

API Reference

Kernel +Architecture 2

+ + + +

Item

Header

+ + +

DDmaRequest

dma.h

+ + +

DmaChannelMgr

dma.h

+ + +

SDmaDesHdr

dma.h

+ + +

SDmaPseudoDes

dma.h

+ + +

TDmac

dma.h

+ + +

TDmaChannel

dma.h

+ + +

TDmaSbChannel

dma.h

+ + +

TDmaSgChannel

dma.h

+ + +

TDmaTestInfo

dma.h

+ + + +

Engineering +Specifications

No specifications are published.

+ \ No newline at end of file diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-A51C3E48-3ED0-519B-A128-C5175D7E175B-master.png Binary file Adaptation/GUID-A51C3E48-3ED0-519B-A128-C5175D7E175B-master.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-A51C3E48-3ED0-519B-A128-C5175D7E175B_d0e19782_href.png Binary file Adaptation/GUID-A51C3E48-3ED0-519B-A128-C5175D7E175B_d0e19782_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-A568F9D3-58E3-58D6-8A6E-4EC6BEC41A4D-master.png Binary file Adaptation/GUID-A568F9D3-58E3-58D6-8A6E-4EC6BEC41A4D-master.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-A568F9D3-58E3-58D6-8A6E-4EC6BEC41A4D_d0e29723_href.png Binary file Adaptation/GUID-A568F9D3-58E3-58D6-8A6E-4EC6BEC41A4D_d0e29723_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-A6845EB0-4B4D-49C8-85A5-A933A2C351CF-master.png Binary file Adaptation/GUID-A6845EB0-4B4D-49C8-85A5-A933A2C351CF-master.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-A6845EB0-4B4D-49C8-85A5-A933A2C351CF_d0e89230_href.png Binary file Adaptation/GUID-A6845EB0-4B4D-49C8-85A5-A933A2C351CF_d0e89230_href.png has changed diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-A6D14A03-ADBF-570D-8AC7-E8BC2700F930.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-A6D14A03-ADBF-570D-8AC7-E8BC2700F930.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,183 @@ + + + + + +Factory +ImplementationMedia driver must implement a PDD factory class derived from DPhysicalDevice. +

The PDD factory creates the main media driver objects.

The Device Driver +Guide describes the general theory for implementing a derived class, +while this section gives the specifics for the media driver.

In implementing your DPhysicalDevice derived class, +you must, as a minimum, provide an implementation for the following four functions, +defined as pure virtual in DPhysicalDevice:

Install() - complete the initialisation of the PDD factory object
Create() - create the media driver object
Validate() - check that the PDD is suitable for use
GetCaps() - return the capabilities of the Media Driver

The following function is virtual in DPhysicalDevice but +has a default implementation that must be changed:

Info() - set the priority of the media driver

Install() - +complete the initialisation of the PDD factory object