HALDeviceSysPeri_CPUClk (changes)

Showing changes from revision #4 to #5: Added | Removed | Changed

Hardware Abstraction Layer

» HAL Device API

» List of HAL devices

» CPU clock generator

(HALDeviceSysPeri_CPUClk)

Device API

API versions 0 and 0.1 are currently defined.

API version 0

API version 0 only allows the CPU clock rate to be set to one of a limited number of values, and the main entry points (numspeeds, info, get and set) to be re-entrant.

struct cpuclkdevice
{
  struct device dev;
  uint32_t (*numspeeds)(struct cpuclkdevice *cpuclk);
  uint32_t (*info)(struct cpuclkdevice *cpuclk,
                   uint32_t idx);
  uint32_t (*get)(struct cpuclkdevice *cpuclk);
  int (*set)(struct cpuclkdevice *cpuclk,
             uint32_t idx);
  int (*override)(struct cpuclkdevice *cpuclk,
                  const void *table,
                  uint32_t numentries,
                  int format);
};

API version 0.1

API version 0.1 adds a getoverride entry point as the opposite of override defined in API version 0.

struct cpuclkdevice_0_1
{
  /* Version 0 interface */
  struct cpuclkdevice dev;

  /* 0.1 extension */
  int (*getoverride)(struct cpuclkdevice *cpuclk,
                     void *table,
                     uint32_t numentries,
                     int format);
};

struct cpuclkdevice_0_2
{
  /* Version 0.1 interface */
  struct cpuclkdevice_0_1 dev;

  /* 0.2 extension */
  unsigned int (*getdietemperature)(struct cpuclkdevice *cpuclk);
};

Reading the available CPU speeds

The numspeeds and info entry points are used to read the number of available CPU speeds, and the corresponding clock rate (in MHz) for each speed index. These calls are equivalent to Portable_Speed2 reason codes 4 and 5. Clock rates returned by info must be increasing order.

Getting the current CPU speed

The get entry point should return the current CPU speed, as an index. If the call was made while in the middle of changing speed, the call must act to complete the change request before returning with the new clock speed. This call is equivalent to Portable_Speed2 reason code 7.

Setting the current CPU speed

The set entry point is used to set the CPU speed to the given index. If the call was made while in the middle of changing speed, the previous change request must be cancelled and the CPU should instead switch to the new speed. A return value of 0 indicates success, and -1 indicates failure. If a change request is cancelled due to set being re-entered, 0 is returned.

Overriding the list of available speeds

The override entry point can be used to override the list of CPU speeds that the device supports. This can be used for purposes such as overclocking. On entry, table must point to a device-specific table of data describing the available speeds, and numentries must be the number of entries in the table. format must be a device-specific identifier specifying the table format.

If the call is successful, the contents of table will be copied into the device and the value of format will be returned.

If the call fails due to the table format being incorrect, the expected table format value will be returned.

If the call fails for any other reason (e.g. because the system is in the middle of changing speed), -1 will be returned.

For details about the supported table formats, see the source code/documentation accompanying the relevant device implementation.

Reading the table of override data

Copies numentries entries from the override table into the table pointer in the given format. Return values as for override entry point.

Support in RISC OS

The PortableHAL version of the Portable module will search for a HALDeviceSysPeri_CPUClk device upon initialisation. If it finds such a device, and the device initialises successfully, it will use that device to provide implementations of the Portable_Speed and Portable_Speed2 SWIs.

Known implementations

Information sources: Kernel.Hdr.HALDevice, HWSupport.PortableHAL.Hdr.CPUClkDevice in CVS