/* vxLib.c - miscellaneous support routines *//* Copyright 1984-2001 Wind River Systems, Inc. *//*modification history--------------------01t,05jun02,wsl  remove reference to SPARC and i96001s,20nov01,hdn  updated x86 specific sections01r,16nov01,tlc  Update for MIPS architecture.01q,29oct01,zl   SH documentation updates.01p,03mar00,zl   merged SH support into T201o,12mar99,elg  VX_POWER_MODE_NAP is not supported by PPC860 (SPR 22432).01n,05oct98,jmp  doc: added {...} when necessary.01m,18aug98,fle  doc : added star character at the beginning of the                 vxPowerDown description01l,21apr98,jpd  added ARM SWPB note.01k,04jun97,dat  added vxMemArchProbe, SPR 865801j,12nov96,dgp  doc: add vxPowerModeGet/Set/Down routines01i,25nov95,jdi  removed 29k stuff.01h,23oct95,jdi  doc: added bit values to vxMemProbe() arg (SPR 4276).01g,22oct95,jdi  doc: added am29k test-and-set instruction (SPR 4356).01f,20mar95,jdi  added new vxSSEnable()/vxSSDisable() stuff from			mc68k/vxALib.s.01e,31jan95,rhp  doc tweaks.            jdi  changed 80960 to i960.01d,08nov93,pme Added vxUnalignedAccessEnable() and vxUnalignedAccessDisable().01c,15feb93,jdi made NOMANUAL: vxAtomicModify(), vxIACSend(), vxIMRClear(),		vxIMRSet(), vxSysctlSend().01b,20jan93,jdi documentation cleanup.01a,23sep92,jdi written, based on vxALib.s and vxLib.c for		mc68k, sparc, i960, mips.*//*DESCRIPTIONThis module contains miscellaneous VxWorks support routines.INCLUDE FILES: vxLib.h*//********************************************************************************* vxTas - C-callable atomic test-and-set primitive** 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'*	x86:    'lock bts'*	SH:	'tas.b'*	ARM:	'swpb'** This routine is equivalent to sysBusTas() in sysLib.** MIPS:* Because VxWorks does not support the MIPS MMU, only kseg0 and kseg1* addresses are accepted; other addresses return FALSE. ** NOTE X86:* BTS "Bit Test and Set" instruction is executed with LOCK instruction prefix* to lock the Bus during the execution.  The bit position 0 is toggled.** NOTE SH:* 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().** RETURNS:* TRUE if the value had not been set (but is now), or FALSE if the* value was set already.** SEE ALSO: sysBusTas()*/BOOL vxTas     (    void *	address		/* address to test and set */    )    {    ...    }/********************************************************************************* vxMemArchProbe - architecture specific part of vxMemProbe** 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.** RETURNS: OK or ERROR if an exception occurred during access.*/STATUS vxMemArchProbe     (    FAST char *  adrs,    /* address to be probed          */    int          mode,    /* VX_READ or VX_WRITE           */    int          length,  /* 1, 2, 4, or 8                 */    FAST char *  pVal     /* where to return value,        */			  /* or ptr to value to be written */    )    {    ...    }/********************************************************************************* vxMemProbe - probe an address for a bus error** 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).** EXAMPLE* .CS*     testMem (adrs)*         char *adrs;*         {*         char testW = 1;*         char testR;**         if (vxMemProbe (adrs, VX_WRITE, 1, &testW) == OK)*             printf ("value %d written to adrs %x\en", testW, adrs);**         if (vxMemProbe (adrs, VX_READ, 1, &testR) == OK)*             printf ("value %d read from adrs %x\en", testR, adrs);*         }* .CE** MODIFICATION* 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().** INTERNAL* This routine functions by setting the bus error trap vector to* vxMemProbeTrap and then trying to read/write the specified byte.  If the* address doesn't exist, vxMemProbeTrap will return ERROR.  Note that this* routine saves and restores the bus error vector that was there prior to* this call.  The entire procedure is done with interrupts locked out.** RETURNS:* OK, or ERROR if the probe caused a bus error or was misaligned.** SEE ALSO:* vxMemArchProbe()*/STATUS vxMemProbe     (    FAST char *  adrs,    /* address to be probed          */    int          mode,    /* VX_READ or VX_WRITE           */    int          length,  /* 1, 2, 4, or 8                 */    FAST char *  pVal     /* where to return value,        */			  /* or ptr to value to be written */    )    {    ...    }/********************************************************************************* vxMemProbeAsi - probe address in ASI space for bus error (SPARC)** 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.** EXAMPLE* .CS*     testMem (adrs)*        char *adrs;*        {*        char testW = 1;*        char testR;**        if (vxMemProbeAsi (adrs, VX_WRITE, 1, &testW) == OK)*            printf ("value %d written to adrs %x\en", testW, adrs);**        if (vxMemProbeAsi (adrs, VX_READ, 1, &testR) == OK)*            printf ("value %d read from adrs %x\en", testR, adrs);*        }* .CE** INTERNAL* This routine functions by setting the bus error trap vector to vxMemProbeTrap* and then trying to read/write the specified byte.* If the address doesn't exist, vxMemProbeTrap will return ERROR.* Note that this routine saves and restores the bus error vector that was* there prior to this call.  The entire procedure is done with interrupts* locked out.** RETURNS:* OK, or ERROR if the probe caused a bus error or* was misaligned.** NOMANUAL*/STATUS vxMemProbeAsi    (    FAST char *  adrs,	  /* address to be probed              */    int          mode,	  /* VX_READ or VX_WRITE               */    int          length,  /* 1, 2, 4, or 8                     */     FAST char *  pVal,	  /* where to return value,            */			  /* or ptr to value to be written     */    int	adrsAsi		  /* ASI field of address to be probed */    )    {    ...    }/********************************************************************************* vxAtomicModify - interface to the 'atmod' instruction (i960)** This routine atomically modifies a location in memory.** RETURNS: The original value in the memory location.** NOMANUAL*/UINT8 vxAtomicModify    (    UINT8    value,         /* value to place in memory */    UINT8 *  pMem,          /* location to modify       */    UINT8    mask           /* bit mask for value       */    )    {    ...    }/******************************************************************************** vxCacheInvalidate - invalidate the instruction cache (i960)** This routine invalidates the instruction cache.  The entire instruction* cache is flushed.** RETURNS: N/A** NOMANUAL*/  vxCacheInvalidate (void)    {    ...    }/******************************************************************************** vxSysctlSend - send a SYSCTL message to the processor (i960 CA)** This routine sends a SYSCTL message to the processor.** RETURNS: N/A** NOMANUAL*/vxSysctlSend    (    UINT32	f12,	/* arg0 contains field2 messageType field1 */    UINT32	f3,	/* arg1 contains field3                    */    UINT32	f4	/* arg2 contains field4                    */    )    {    ...    }/******************************************************************************** vxIACSend - send an IAC message to the processor (i960 KB/SB)** This routine sends an intra-agent communication (IAC) message to * the processor.** RETURNS: N/A** NOMANUAL*/vxIACSend    (    UINT32 *  iac	/* arg0 contains pointer to IAC structure */    )    {    ...    }/******************************************************************************** vxIMRClear - clear the interrupt mask register (i960)** This routine clears bits in the interrupt mask register.** RETURNS: N/A** NOMANUAL*/vxIMRClear    (    UINT32	mask	/* bits to clear in interrupt mask reg */    )    {    ...    }/******************************************************************************** vxIMRSet - set the interrupt mask register (i960)** This routine sets bits in the interrupt mask register.** RETURNS: N/A** NOMANUAL*/vxIMRSet    (    UINT32	mask	/* bits to set in interrupt mask reg */    )    {    ...    }/********************************************************************************* vxSSEnable - enable the superscalar dispatch (MC68060)** This function sets the ESS bit of the Processor Configuration Register (PCR)* to enable the superscalar dispatch.** RETURNS : N/A*/void vxSSEnable (void)    {    ...    }/********************************************************************************* vxSSDisable - disable the superscalar dispatch (MC68060)** This function resets the ESS bit of the Processor Configuration Register (PCR)* to disable the superscalar dispatch.** RETURNS : N/A*/void vxSSDisable (void)    {    ...    }/********************************************************************************* vxPowerModeSet - set the power management mode (PowerPC, SH, x86)** This routine selects the power management mode to be activated when* vxPowerDown() is called.  vxPowerModeSet() is normally called in the BSP* initialization routine sysHwInit().** USAGE PPC:* Power management modes include the following:* .iP "VX_POWER_MODE_DISABLE (0x1)"* Power management is disabled; this prevents the MSR(POW) bit from being