serlock.h

ARM入门的好帮手.包含了从简单到相对较复杂的程序.

 *  Pre-conditions:  This must be executed in SVC, either with the lock, or
 *                   with interrupts disabled.
 *
 *          Effect:  All outstanding callbacks are removed from the queue
 *                   waiting to be effected by the application.
 *
 *                   This routine is needed in two circumstances: on loading
 *                   a new application, or on reloading the current one.
 *
 *                   It should in fact be called only from the function
 *                   InitialiseApplication.
 */

void Angel_FlushApplicationCallbacks(void);

/****************************************************************************/

/*
 *        Function:  Angel_Yield
 *         Purpose:  This is a voluntary yield function, which allows the
 *                   polling loop to execute; this permits an application to
 *                   give control to the polling loop and perform any necessary
 *                   polling actions.
 *
 *  Pre-conditions:  This routine may be called either from USR or from SVC.
 *                   In the latter case, the lock should be held.
 *
 *          Effect:  If not in SVC, a transparent stack switch is made (the
 *                   USR stack pointer and stack limit register are copied to
 *                   the SVC ones) so that the code is APCS conformant. The
 *                   idle loop is then called so that any polled devices may
 *                   be checked.
 *
 *                   On exit, a transparent switch is made back to USR if the
 *                   original call came from USR - in which case the SVC stack
 *                   is also reset so that it is empty.
 */

void Angel_Yield(void);


/*
 *        Function:  Angel_YieldCore
 *         Purpose:  Given a uniform enviroment with the lock, give
 *                   polled devices a chance to do their work.
 *
 *       Arguments:  None.
 *
 *   Pre-conditions: This function will be called from SVC mode with the
 *                   SVC stack set up for use.  On entry IRQ's and
 *                   FIQ's will be enabled, and the lock will be held
 *                   by this function.  It will only ever be called from
 *                   the assembler veneer code in Angel_Yield
 *
 *                   In practice this means it should only be called via
 *                   the serialiser, and the only user code which might
 *                   ever want to do this is code to call Angel Yield at
 *                   regular intervals off an interrupt.
 *
 *          Effect:  All polled devices will be given a chance to do
 *                   their work.
 *
 *                   This is an APCS conformant function, but the veneer
 *                   which calls it is not.
 *
 *  Post-conditions: This function should be exited just by using return.
 *                   This will actually return to angel_NextTask.
 */

extern void Angel_YieldCore(void);


/****************************************************************************/

/*
 *        Function:  Angel_EnterSVC
 *         Purpose:  Switch to SVC mode from USR mode, setting the I-bit
 *                   and the F-bit.
 *
 *  Pre-conditions:  The caller must presently be executing in USR.
 *
 *          Effect:  Execution continues in SVC transparently. The I-bit and
 *                   the F-bit are both set. A switch of stacks occurs (the
 *                   USR stack pointer and stack limit are copied to the
 *                   SVC registers), so that the transition is transparent to
 *                   APCS.
 */

void Angel_EnterSVC(void);

/*
 *        Function:  Angel_ExitToUSR
 *         Purpose:  Switch back to USR mode after executing for a while
 *                   in SVC.
 *
 *  Pre-conditions:  The caller must presently be executing in SVC.
 *
 *          Effect:  Execution continues in USR mode transparently. The I-bit
 *                   and F-bit are both cleared. The SVC stack pointer and
 *                   stack limit are copied to the USR registers, so that the
 *                   transition is transparent to APCS, and the SVC stack
 *                   is reset to an empty state.
 */

void Angel_ExitToUSR(void);


/*
 *        Function:  Angel_DisableInterruptsFromSVC
 *         Purpose:  Disable interrupts while executing in SVC mode
 *
 *  Pre-conditions:  The caller must presently be executing in SVC mode
 *                   and must have obtained the serialiser lock.
 *
 *          Inputs:  None
 *
 *         Returns:  Processor State on entry to the routine
 *
 *          Effect:  Interrupts are disabled.
 */
unsigned int Angel_DisableInterruptsFromSVC(void);

/*
 *        Function:  Angel_EnableInterruptsFromSVC
 *         Purpose:  Enable interrupts while executing in SVC mode
 *
 *  Pre-conditions:  The caller must presently be executing in SVC mode
 *                   and must have obtained the serialiser lock.
 *
 *          Inputs:  Nothing
 *
 *         Returns:  Processor State on entry to the routine
 *
 *          Effect:  Interrupts are enabled.
 */
unsigned int Angel_EnableInterruptsFromSVC(void);

/*
 *        Function:  Angel_RestoreInterruptsFromSVC
 *         Purpose:  Enable interrupts while executing in SVC mode
 *
 *  Pre-conditions:  The caller must presently be executing in SVC mode.
 *
 *          Inputs:  state      State returned from previous call to
 *                              Angel_DisableInterruptsFromSVC() or
 *                              Angel_EnableInterruptsFromSVC().
 *
 *          Effect:  The interrupt state is restored.
 */
void Angel_RestoreInterruptsFromSVC(unsigned int state);

/****************************************************************************/

/*        Function:  angel_InitialiseOneOff
 *         Purpose:  To initialize the free angel_RegBlocks and all the
 *                   associated structures, returning with the application
 *                   task flagged as as blocked, and returning a pointer to
 *                   a valid angel_RegBlock (whose contents are meaningless
 *                   at this point).
 *
 *  Pre-conditions:  This routine is called once only, by the main Angel
 *                   initialization code. It is assumed that the I-bit and the
 *                   F-bit are set, and that the routine is called in SVC.
 *
 *          Inputs:  None.
 *
 *         Outputs:  None. (The angel_RegBlock allocated may be accessed via
 *                   the standard route.)
 */

void angel_InitialiseOneOff(void);

/*
 *
 */
void Angel_InitialiseTaskFinished(void);


/*        Function:  angel_ReadBankedRegs
 *         Purpose:  To save the state of banked registers when the debugger
 *                   asks for them in debogos.c
 *
 *  Pre-conditions:  It is called in USR mode
 *
 *          Inputs:  A Regblock in which to save the state of banked regs
 *                   The mode of the regs to read.
 *
 *         Outputs:  None
 */

void angel_ReadBankedRegs(angel_RegBlock *rb, unsigned mode);


/****************************************************************************/

/*
 *  The following enumerated constants control the handling of the F-bit,
 *  depending on the use made of FIQs in the particular configuration.
 *
 *  The definitions are as follows:
 *
 *    FIQ_CannotBeOptimised:
 *
 *        If this option is selected, the F-bit and the I-bit will be
 *        disabled together - it is assumed that an FIQ may do anything
 *        which an IRQ may do (such as enter the serialiser and perform
 *        any actions available to it in that state).
 *
 *    FIQ_NeverUsesSerialiser:
 *
 *        If this option is selected, it is assumed that FIQs never attempt
 *        to gain the lock, and so are completely independent of the lock
 *        mechanism.
 *
 *    FIQ_NeverUsesSerialiser_DoesNotReschedule:
 *
 *        If this option is selected, there is added an additional constraint:
 *        FIQs must _never_ be used for rescheduling in any third party OS.
 *
 *    FIQ_NeverUsesSerialiser_DoesNotReschedule_HasNoBreakpoints:
 *
 *        If this option is selected, no breakpoint must ever occur in code
 *        executed in FIQ mode.
 *
 *  The #define below is the default (i.e. safest) option.
 */

typedef enum angel_FIQSafety {
  FIQ_CannotBeOptimised = 0,
  FIQ_NeverUsesSerialiser = 1,
  FIQ_NeverUsesSerialiser_DoesNotReschedule = 2,
  FIQ_NeverUsesSerialiser_DoesNotReschedule_HasNoBreakpoints = 3
} angel_FIQSafety;

/* Note that FIQ_SAFETYLEVEL is defined in devconf,h */

/*
 * Macros Enter / Leave a critical section, that is, an area of code in
 * which the task must not be interrupted, e.g. by a device driver.
 *
 * Under Angel, this is implemented by calls to enter supervisor mode,
 * which are queued if more than one such task makes the request.
 */
#define Angel_EnterCriticalSection()  Angel_EnterSVC()
#define Angel_LeaveCriticalSection()  Angel_ExitToUSR()

#endif /* ndef angel_serlock_h */

/* EOF serlock.h */