Physical Channel Implementation

Constructor

The media driver object is created by your PDD factory object's implementation of the Create() function. The following is the relevant line of code:

...
//Create my DMediaDriver derived object
DMyMediaDriver* pD=new DMyMediaDriver (aMediaId);
...

Your constructor, prototyped as:

DMyMediaDriver (TInt aMediaId);

gives you the chance to do any initialisation that is safe, i.e. that cannot fail. Typically, this is the kind of initialisation that does not need to acquire resources. This is the first phase of the typical Symbian platform two-phase construction process.

DMyMediaDriver::DMyMediaDriver (TInt aMediaId)
    :DMediaDriver(aMediaId)
    {
    //…do safe initialisation here
    }
        

As this code fragment shows, you need to call the base class constructor first, forwarding the TInt aMediaId value. You do not need to do anything else with this value. Note that this value is the unique media ID used when the media driver was registered.

DoCreate() - second phase constructor

The media driver object is created by your PDD factory object's implementation of the Create() function. The following is the relevant line of code, which is called after successful creation of the media driver object:

...
// Call my media driver’s second-stage constructor
Tint r = KErrNoMemory;
    if(pD)
        {
        r = pD->DoCreate(aMediaId);
        }
...
        

This is a second-phase constructor that allows you to do more complex initialisation, and initialisation that might fail. Typically, this is initialisation that acquires resources (including memory). The outline implementation of DoCreate() is:

TInt DMyMediaDriver::DoCreate(TInt aMediaId)
    {
    TInt r = KErrNone;
    //…do complex initialisation here
    return r;
    }
        

Depending on the complexity of your initialisation, you can either do all your initialisation here, and complete immediately, or you can do the initialisation as an asynchronous operation, in which case initialisation will complete at some later time.

If you do this synchronously, then the return code should reflect the success or failure of the operation. In practice, this will almost always be KErrNone.

If you do this asynchronously, then, on completion of the initialisation processing, a call should be made to: DMediaDriver::OpenMediaDriverComplete() passing either KErrNone or one of the other system-wide codes as appropriate.

PartitionInfo() - return the partition information

Once the media driver has been successfully created and initialised, and has informed the media driver subsystem of this fact by a call to DMediaDriver::OpenMediaDriverComplete(), then the subsystem makes a call to the media driver's PartitionInfo() function to get partition information for the media device.

The prototype function is:

TInt PartitionInfo(TPartitionInfo& anInfo);

A TPartitionInfo object is passed to the function, which the media driver must fill in.

Decoding of partition information may require media access, and as such may be a long running activity. Support is provided that allows this to be done asynchronously. You use the return code from PartitionInfo() to tell the media driver subsystem which operational mode you are using:

• return KErrNone, if the decoding operation is to be done asynchronously. Note that on completion, the asynchronous operation must call DMediaDriver::PartitionInfoComplete(), returning KErrNone, or one of the other system-wide error codes, if appropriate.

• return a value other than KErrNone , if the decoding operation has been done synchronously. If the synchronous operation is successful, return KErrCompletion, otherwise return one of the other system-wide error codes, but not KErrNone.

Decoding simple partitions

The following example shows the implementation of a simple PartitionInfo() function. Such an implementation would be provided for non-removable media, such as internal Flash memory, where the layout is simple and known to the system.

This implementation reports a single partition with the size of the entire media. The partition expects to be mounted with the FAT filesystem.

Note that this operation is done synchronously, and the function returns KErrCompletion to indicate this.

TInt DMyMediaDriver::PartitionInfo(TPartitionInfo& aInfo)
    {
    aInfo.iPartitionCount                = 1;
    aInfo.iEntry[0].iPartitionBaseAddr    = 0;
    aInfo.iEntry[0].iPartitionLen        = TotalSizeInBytes();
    aInfo.iEntry[0].iPartitionType        = KPartitionTypeFAT12;
    
    aInfo.iMediaSizeInBytes                = TotalSizeInBytes();

    return KErrCompletion;
    }
          

Decoding FAT Partitions

More complex implementations of PartitionInfo() may be required when handling removable media or more complex internal media where the layout of the media is unknown to the system.

This example shows a typical implementation for a FAT based removable media device. Here, PartitionInfo() starts the operation, which is done asynchronously by the DoPartitionInfo() function.

Note that PartitionInfo() returns KErrNone, which tells the media driver subsystem that the operation will be done asynchronously.

Note also that on completion, DoPartitionInfo() calls PartitionInfoComplete() to tell the media driver subsystem that the operation is complete.

TInt DMyMediaDriverFlash::PartitionInfo(TPartitionInfo& aInfo)
    {
    iPartitionInfo = &anInfo                        // Store aInfo until needed

    TInt errCode = LaunchPartitionInfoRequest();    // Start the asynchronous request

    return(errCode);    // This needs to be KErrNone to indicate that the operation
                        // will be completed asynchronously (unless an error occurs launching
                        // the asynchronous request!)
    }
          

This is the function that runs asynchronously

TInt DMyMediaDriver::DoPartitionInfo()
    {
    TInt partitionCount = iPartitionInfo->iPartitionCount = 0;

    // Read of the first sector successful so check for a Master Boot Record
    if (*(TUint16*)(&iIntBuf[KMBRSignatureOffset])!=0xAA55)
        {
        return(KErrCorrupt);
        }

    // Move the partition entries to a 4 byte boundary
    memcpy(&iIntBuf[0],&iIntBuf[KMBRFirstPartitionEntry],(sizeof(TMBRPartitionEntry)<<2)); 

    // Search for a x86 default boot partition - let this be the first
    TMBRPartitionEntry *pe=(TMBRPartitionEntry*)(&iIntBuf[0]);

    TInt i;
    TInt defaultPartitionNumber=-1;
    for (i=0;i<KMaxPartitionEntries;i++,pe++)
        {
        if (pe->IsDefaultBootPartition())
            {
            SetPartitionEntry(&iPartitionInfo->iEntry[0],pe->iFirstSector,pe->iNumSectors);
            iHiddenSectors=pe->iFirstSector;
            defaultPartitionNumber=i;
            partitionCount++;
            break;
            }
        }

    // Now add any other partitions
    pe=(TMBRPartitionEntry*)(&iIntBuf[0]);     // Reset it
    for (i=0;i<KMaxPartitionEntries;i++,pe++)
        {
        if (defaultPartitionNumber==i)
            {
            continue;    // Already sorted
            }
        if (pe->IsValidDosPartition())
            {
            SetPartitionEntry(&iPartitionInfo->iEntry[partitionCount],pe->iFirstSector,pe->iNumSectors);
            if (partitionCount==0)
            iHiddenSectors=pe->iFirstSector;
            partitionCount++;
            }
        }

    if (defaultPartitionNumber==(-1) && partitionCount==0)
        {
        // Assume it has no MBR, and the Boot Sector is in the 1st sector
        SetPartitionEntry(&iPartitionInfo->iEntry[0], 0, iMediaSize);
        iHiddenSectors=0;
        partitionCount=1;
        }
        
    iPartitionInfo->iPartitionCount=partitionCount;
    iPartitionInfo->iMediaSizeInBytes=TotalSizeInBytes();

    PartitionInfoComplete(err);
    
    return(KErrNone);
    }
          

Request() - handling requests

You handle requests by implementing your media driver's Request() function. This is prototyped as:

TInt Request(TLocDrvRequest& aRequest)=0;

This function is usually called in the context of the client thread that originally initiated the I/O request to the file server, although you should never assume so. Note that you may also see the originating thread referred to as the remote thread.

The request type, as identified by the request ID, and the information associated with the request is accessed through the TLocDrvRequest object, which is passed to the Request() function. The information supplied includes offsets, data lengths, the requesting thread etc, but clearly depends on the request ID. You get the request ID by calling TLocDrvRequest::Id(), and this will be one of the DLocalDrive::TRequestId enum values.

Each request ID, as defined by DLocalDrive::TRequestId has a specific meaning. The information that is available also depends on the request ID.

Depending on the request ID, the operation can be done synchronously or asynchronously. However, it is the responsibility of the implementor of the media driver to handle the incoming requests and to handle them as appropriate to the specific media, i.e. synchronously or asynchronously.

In general, the function should return once the request is initiated. If the entire operation cannot be completed immediately, then further request processing must occur within ISRs and DFCs, i.e. using some hardware specific mechanism to indicate completion, or by the use of considerate poll timers to considerately poll the device for it’s current status, with the final request completion being done from within a DFC. The code that implements the asynchronous requests can run within its own thread, or use one of the default threads provided by the kernel (DFC queue thread 0).

The underlying media driver framework allows multiple requests to be processed simultaneously. However, other than being able to issue multiple requests, there is no inherent support in the media driver framework to support the handling of multiple requests, so such functionality must be handled by the media driver itself. The underlying media driver framework does, however, provide basic support for deferring requests for later processing should the media driver not be capable of supporting multiple requests.

...
if (id == DLocalDrive::ECaps)
    {
    TLocalDriveCapsV2& c = *(TLocalDriveCapsV2*)aRequest.RemoteDes();
    ...
    }
....
              

...
TPtrC8 des((const TUint8*)(iBase),len);
TInt r=iReadReq->WriteRemote(&des,0);
...
              

A simple implementation

TInt DMyMediaDriver::Request(TLocDrvRequest& aRequest)
    {
    TInt err = KErrNotSupported;
    TInt id  = aRequest.Id();

    if (id == DLocalDrive::ECaps)
        {
        TLocalDriveCapsV2& c = *(TLocalDriveCapsV2*)aRequest.RemoteDes();
        err = Caps(c);
        c.iSize = m.Drive()->iPartitionLen;
        c.iPartitionType = m.Drive()->iPartitionType;
        return(err);
        }

    if(iCurrentReq != NULL)
        {
        return(KMediaDriverDeferRequest);
        }

    iCurrentReq = &aRequest;

    switch(id)
        {
        case DLocalDrive::ERead:
            r = StartRead();
            break;
        case DLocalDrive::EWrite:
            r = StartWrite();
            break;
        case DLocalDrive::EFormat:
            r = StartErase();
            break;
        }

    if (err < 0)
        {
        iCurrentReq = NULL;
        DMediaDriver::Complete(aRequest, err);
        }
    
    return(err);
    }
            

This demonstrates the following behaviour:

• The ECaps request is inherently synchronous, and must complete immediately.

• This example only handles a single request at a time. If the media driver is busy handling a request, it can return the value KMediaDriverDeferRequest which defers the message until the current request is complete.

• Each message is passed on to the specific function that is responsible for handling the message. This provides readability and ease of maintenance.

• If an error occurs, the request is completed immediately with the specified error code.

The following code is the implementation of the StartWrite() function that initiates the asynchronous write operation. It gets the length and position information, and then calls DoWriteStep():

TInt DMyMediaDriver::StartWrite()
    {
    // Start an asynchronous write operation

    iCurrentPos = iCurrentReq->Pos();
    iCurrentLength = iCurrentReq->Length();

    TInt err = DoWriteStep();
        
    return(err);
    }
                

DoWriteStep() performs a single write operation. In this example, a single write operation cannot exceed the capabilities of the hardware, so the request is split up into chunks of KMyMediaDriverWriteLength bytes.

TInt DMyMediaDriver::DoWriteStep()
    {
    // Perform a single write step

    TUint8* destAddress = iBaseAddress + iCurrentPos;
    TInt writeLength = MIN(iCurrentLength, KMyMediaDriverWriteLength);
        
    TPtr8 des(iData, writeLength);
    TInt err = iCurrentReq->ReadRemote(&des, iCurrentPos - iCurrentReq->Pos());
    if (err != KErrNone)
        {
        return(err);
        }

        iCurrentPos += writeLength;
        iCurrentLength -= writeLength;

        TheHardware::StartWrite(iCurrentPos, writeLength, iData);
    }
                

The write operation to the hardware is performed by TheHardware::StartWrite(). For most hardware, completion is signalled by an interrupt, and the ISR handling the interrupt will queue a DFC. This in turn can call a function like WriteComplete() shown below:

TInt DMyMediaDriver::WriteComplete(TInt aResult)
    {
    // Called upon completion of the write operation
    // (ie – in DFC after completion interrupt or polled status completion)

    TBool completeRequest = (iCurrentLength == 0) || (aResult ! = KErrNone);
        
    if(!completeRequest)
        {
        // There is more data remaining, so write some more data…
        if((aResult = DoWriteStep()) != KErrNone)
            {
            completeRequest = ETrue;
            }
        }
        
    if(completeRequest)
        {
        // We are all done, or an error occurred…
        DMediaDriver::Complete(iCurrentReq, aResult);
        iCurrentReq = NULL;
        }
    }
                

WriteComplete() is an example of a callback or completion function, and shows how a single request may be broken up into a number of smaller chunks. The write request is only completed when the entire write operation is complete or an error occurs.

This simple example has demonstrated how a simple EWrite request may be handled. The ERead and EFormat requests are handled in exactly the same way, taking into account the message parameters shown in the previous table.

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

See also Register media driver support for physical addresses