Basic Management

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);