VxWorks Reference Manual : Libraries
vxLib - miscellaneous support routines
vxTas( ) - C-callable atomic test-and-set primitive
vxMemArchProbe( ) - architecture specific part of vxMemProbe
vxMemProbe( ) - probe an address for a bus error
vxMemProbeAsi( ) - probe address in ASI space for bus error (SPARC)
vxSSEnable( ) - enable the superscalar dispatch (MC68060)
vxSSDisable( ) - disable the superscalar dispatch (MC68060)
vxPowerModeSet( ) - set the power management mode (PowerPC)
vxPowerModeGet( ) - get the power management mode (PowerPC)
vxPowerDown( ) - place the processor in reduced-power mode (PowerPC)
This module contains miscellaneous VxWorks support routines.
vxLib.h
vxTas( ) - C-callable atomic test-and-set primitive
BOOL vxTas ( void * address /* address to test and set */ )
This routine provides a C-callable interface to a test-and-set instruction. The test-and-set instruction is executed on the specified address. The architecture test-and-set instruction is:
68K: tas
SPARC: ldstub
i960: atmod
SH: tas.b
ARM swpbThis routine is equivalent to sysBusTas( ) in sysLib.
Only Kseg0 and Kseg1 addresses are accepted; other addresses always return FALSE.
The SH version of vxTas( ) simply executes the "tas.b" instruction, and the test-and-set (atomic read-modify-write) operation may require an external bus locking mechanism on some hardware. In this case, wrap the vxTas( ) with a bus locking and unlocking code in the sysBusTas( ).
TRUE if the value had not been set (but is now), or FALSE if the value was set already.
vxMemArchProbe( ) - architecture specific part of vxMemProbe
STATUS vxMemArchProbe ( char * adrs, /* address to be probed */ int mode, /* VX_READ or VX_WRITE */ int length, /* 1, 2, 4, or 8 */ char * pVal /* where to return value, or ptr to value to be written */ )
This is the routine implementing the architecture specific part of the vxMemProbe routine. It traps the relevant exceptions while accessing the specified address. If an exception occurs, then the result will be ERROR. If no exception occurs then the result will be OK.
OK or ERROR if an exception occurred during access.
vxMemProbe( ) - probe an address for a bus error
STATUS vxMemProbe ( char * adrs, /* address to be probed */ int mode, /* VX_READ or VX_WRITE */ int length, /* 1, 2, 4, or 8 */ char * pVal /* where to return value, or ptr to value to be written */ )
This routine probes a specified address to see if it is readable or writable, as specified by mode. The address is read or written as 1, 2, or 4 bytes, as specified by length (values other than 1, 2, or 4 yield unpredictable results). If the probe is a VX_READ (0), the value read is copied to the location pointed to by pVal. If the probe is a VX_WRITE (1), the value written is taken from the location pointed to by pVal. In either case, pVal should point to a value of 1, 2, or 4 bytes, as specified by length.
Note that only bus errors are trapped during the probe, and that the access must otherwise be valid (i.e., it must not generate an address error).
testMem (adrs) char *adrs; { char testW = 1; char testR; if (vxMemProbe (adrs, VX_WRITE, 1, &testW) == OK) printf ("value %d written to adrs %x\n", testW, adrs); if (vxMemProbe (adrs, VX_READ, 1, &testR) == OK) printf ("value %d read from adrs %x\n", testR, adrs); }
The SH version of vxMemProbe( ) calls next three BSP support routines: sysVxAdrsChk( ), sysBusErrVecSave( ), and sysBusErrVecRestore( ). First, sysVxAdrsChk( ) is called to check if a probing address is in a reserved address space. The vxMemProbe( ) does not actually probe the address if ERROR is returned from sysVxAdrsChk( ). Second, sysBusErrVecSave( ) is called to save the original bus error handler and to attach a special handler, vxMemProbeTrap( ). Then the actual probing is executed. After probing, sysBusErrVecRestore( ) is called to restore the original handler.
The BSP can modify the behaviour of vxMemProbe( ) by supplying an alternate routine and placing the address in the global variable _func_vxMemProbeHook. The BSP routine will be called instead of the architecture specific routine vxMemArchProbe( ).
OK, or ERROR if the probe caused a bus error or was misaligned.
vxLib, vxMemArchProbe( )
vxMemProbeAsi( ) - probe address in ASI space for bus error (SPARC)
STATUS vxMemProbeAsi ( char * adrs, /* address to be probed */ int mode, /* VX_READ or VX_WRITE */ int length, /* 1, 2, 4, or 8 */ char * pVal, /* where to return value, or ptr to value to be written */ int adrsAsi /* ASI field of address to be probed */ )
This routine probes the specified address to see if it is readable or writable, as specified by mode. The address will be read/written as 1, 2, 4, or 8 bytes as specified by length (values other than 1, 2, 4, or 8 return ERROR). If the probe is a VX_READ (0), then the value read will be returned in the location pointed to by pVal. If the probe is a VX_WRITE (1), then the value written will be taken from the location pointed to by pVal. In either case, pVal should point to a value of the appropriate length, 1, 2, 4, or 8 bytes, as specified by length.
The fifth parameter adrsAsi is the ASI parameter used to modify the adrs parameter.
testMem (adrs) char *adrs; { char testW = 1; char testR; if (vxMemProbeAsi (adrs, VX_WRITE, 1, &testW) == OK) printf ("value %d written to adrs %x\n", testW, adrs); if (vxMemProbeAsi (adrs, VX_READ, 1, &testR) == OK) printf ("value %d read from adrs %x\n", testR, adrs); }
OK, or ERROR if the probe caused a bus error or was misaligned.
vxSSEnable( ) - enable the superscalar dispatch (MC68060)
void vxSSEnable (void)
This function sets the ESS bit of the Processor Configuration Register (PCR) to enable the superscalar dispatch.
N/A
vxSSDisable( ) - disable the superscalar dispatch (MC68060)
void vxSSDisable (void)
This function resets the ESS bit of the Processor Configuration Register (PCR) to disable the superscalar dispatch.
N/A
vxPowerModeSet( ) - set the power management mode (PowerPC)
STATUS vxPowerModeSet ( UINT32 mode /* power management mode to select */ )
This routine selects the power management mode to be activated when vxPowerDown( ) is called. vxPowerModeSet( ) is normally called in the BSP initialization routine sysHwInit( ).
Power management modes include the following:
- VX_POWER_MODE_DISABLE (0x1)
- Power management is disabled; this prevents the MSR(POW) bit from being set (all PPC).
- VX_POWER_MODE_FULL (0x2)
- All CPU units are active while the kernel is idle (PPC603, PPCEC603 and PPC860 only).
- VX_POWER_MODE_DOZE (0x4)
- Only the decrementer, data cache, and bus snooping are active while the kernel is idle (PPC603, PPCEC603 and PPC860).
- VX_POWER_MODE_NAP (0x8)
- Only the decrementer is active while the kernel is idle (PPC603, PPCEC603 and PPC604 ).
- VX_POWER_MODE_SLEEP (0x10)
- All CPU units are inactive while the kernel is idle (PPC603, PPCEC603 and PPC860 - not recommended for the PPC603 and PPCEC603 architecture).
- VX_POWER_MODE_DEEP_SLEEP (0x20)
- All CPU units are inactive while the kernel is idle (PPC860 only - not recommended).
- VX_POWER_MODE_DPM (0x40)
- Dynamic Power Management Mode (PPC603 and PPCEC603 only).
- VX_POWER_MODE_DOWN (0x80)
- Only a hard reset causes an exit from power-down low power mode (PPC860 only - not recommended).
OK, or ERROR if mode is incorrect or not supported by the processor.
vxLib, vxPowerModeGet( ), vxPowerDown( )
vxPowerModeGet( ) - get the power management mode (PowerPC)
UINT32 vxPowerModeGet (void)
This routine returns the power management mode set by vxPowerModeSet( ).
The power management mode, or ERROR if no mode has been selected or if power management is not supported.
vxLib, vxPowerModeSet( ), vxPowerDown( )
vxPowerDown( ) - place the processor in reduced-power mode (PowerPC)
UINT32 vxPowerDown (void)
This routine activates the reduced-power mode if power management is enabled. It is called by the scheduler when the kernel enters the idle loop. The power management mode is selected by vxPowerModeSet( ).
OK, or ERROR if power management is not supported or if external interrupts are disabled.
vxLib, vxPowerModeSet( ), vxPowerModeGet( )
STATUS vxPowerDown (void)