Firmware access

In order for a device driver to make certain settings (e.g. size of the frame buffer), it sometimes needs to communicate with the firmware, which runs on the VPU co-processor. This may be necessary from application code too, if specific settings should be made, which are not supported by Circle. The firmware can be accessed using the Mailbox property interface. This is supported in Circle by the class CBcmPropertyTags.

Note

This Mailbox property interface wiki article does not describe all supported functions. Information on more functions can only be retrieved from the Linux source code.

CBcmPropertyTags

#include <circle/bcmpropertytags.h>

class CBcmPropertyTags

boolean CBcmPropertyTags::GetTag(u32 nTagId, void *pTag, unsigned nTagSize, unsigned nRequestParmSize = 0): Makes a mailbox property call to the firmware with a single tag. nTagId is the tag identifier. The identifiers, used by Circle, are listed in the header file circle/bcmpropertytags.h. pTag points to the tag structure and nTagSize is the size of this structure. This header file defines the tag structure for a number of mailbox property functions too. The parameter nRequestParmSize specifies the number of bytes in the tag structure, which are passed as input parameters to the firmware, where the TPropertyTag header does not count. This parameter may be zero for property tags, which do not pass input parameters to the firmware. GetTag() returns TRUE, if the call succeeds.

boolean CBcmPropertyTags::GetTags(void *pTags, unsigned nTagsSize): Makes a mailbox property call to the firmware with multiple tags at once. pTags points to the tags structure, which is a concatenation of multiple property tag structures. nTagsSize is the total size of this structure. GetTags() returns TRUE, if the call succeeds.

Example

The following code retrieves the current clock rate of the ARM CPU from the firmware with the GetTag() method:

#include <circle/bcmpropertytags.h>

unsigned CMyClass::GetClockRate (void)
{
        CBcmPropertyTags Tags;                  // this class

        TPropertyTagClockRate TagClockRate;     // the tag structure

        TagClockRate.nClockId = CLOCK_ID_ARM;   // input parameter

        if (!Tags.GetTag (PROPTAG_GET_CLOCK_RATE,
                          &TagClockRate, sizeof TagClockRate,
                          sizeof TagClockRate.nClockId))
        {
                return 0;                       // return 0 on failure
        }

        return TagClockRate.nRate;              // return the clock rate
}

An example for using the GetTags() method is available in the frame buffer driver.