serlock.h

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

/* -*-C-*-
 *
 * $Revision: 1.10.6.1 $
 *   $Author: rivimey $
 *     $Date: 1997/12/19 15:54:49 $
 *
 * Copyright (c) 1996 Advanced RISC Machines Limited.
 * All Rights Reserved.
 *
 *   Project: ANGEL
 *
 *     Title: Definitions for the serial kernel of Angel.
 *
 */

#ifndef angel_serlock_h
#define angel_serlock_h

#ifdef TARGET
# include "angel.h"
#else
# include "host.h"
#endif

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

/*
 * This definition is central to the way in which the serial core of Angel
 * keeps track of interrupted and schedulable states.
 *
 * The following structure is capable of holding the complete set of
 * registers, sufficient to resume an instruction stream in exactly the same
 * state as it was in when it was interrupted (or interrupted itself). The .r
 * field holds the nominal registers r0 to r15 (= pc), while the .cpsr and
 * .spsr fields hold the Current Program Status register and the Saved
 * Program Status Register respectively.
 *
 * The identity of banked registers is implied by the mode held in the .cpsr
 * field.
 *
 * Note: the order of the fields is optimized so that the entire contents can
 * be placed on a full descending stack.
 */

typedef struct angel_RegBlock
{
    unsigned cpsr;
    unsigned spsr;
    unsigned r[16];
} angel_RegBlock;

typedef enum angel_TaskPriority {
    TP_IdleLoop = 0,
    TP_AngelInit = 1,
    TP_Application = 2,
    TP_ApplCallBack = 3,
    TP_AngelCallBack = 4,
    TP_AngelWantLock = 5
} angel_TaskPriority;

#define TP_MaxEnum  (TP_AngelWantLock)


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

/*
 * The following items are the (globally accessible) register blocks
 * used by interrupt handlers, the undefined instruction handler and
 * the SWI handler.  They are used to hold an interrupted_regblock
 * (element 0) and a desired_regblock (element 1) to be used by
 * SerialiseTask.
 */

extern angel_RegBlock Angel_MutexSharedTempRegBlocks[2];

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

/*
 *        Function:  Angel_SerialiseTask
 *         Purpose:  To queue a function to be executed in a serial queue of
 *                   actions with "the lock". In this desired state, mutual
 *                   exclusion is automatically achieved, by serialization.
 *
 *       Arguments:  called_by_yield       1 if called by Angel_Yield
 *                                         0 otherwise.
 *                   fn:                   is the function which desires the
 *                                         lock
 *                   state:                is a parameter for fn
 *                   empty_stack:          the value of the stack pointer
 *                                         of the current mode such that its
 *                                         stack is empty - it will be reset
 *                                         to this value, and hence fn must
 *                                         not need to access any items which
 *                                         might have been left there
 *
 * Implicit Argument Angel_MutexSharedTempRegBlocks[0] must hold the
 *                   interrupted regblock on entry to Angel_SerialiseTask.
 *
 *  Pre-conditions:  This function may be called from IRQ, FIQ, UND or SVC
 *                   mode.
 *
 *          Effect:  If the lock is presently unowned, fn will be executed
 *                   immediately in SVC with the I-bit and F-bit clear. If it
 *                   is already owned, however, the complete context needed
 *                   to execute it later is saved.
 *
 *                   This is not a "normal" function, in the sense that it
 *                   does not necessarily preserve sequence.
 *
 *                   When fn is ready to be executed, the registers will be
 *                   as follows:
 *
 *                      r0 (a1) = <state>
 *                      sp     -> (empty) SVC stack area
 *                      sl      = SVC stack limit
 *                      fp      = 0    (no previous frames)
 *                      lr     -> entry point to NextTask
 *                      pc     -> <fn>
 *                      CPSR   => SVC mode, I-clear, F-clear
 *
 *                   Thus, when fn exits, it will invoke NextTask.
 */

typedef void (*angel_SerialisedFn)(void *);

void Angel_SerialiseTask(bool called_by_yield,
                         angel_SerialisedFn fn,
                         void *state,
                         unsigned empty_stack);

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

/*
 *        Function:  Angel_QueueCallback
 *         Purpose:  This routine enables device drivers, the breakpoint
 *                   (undefined instruction) handler, the SWI handler or the
 *                   "yield" code to queue requests.
 *
 *                   It is, in fact, just a veneer on QueueTask - for the
 *                   sake of ease of use.
 *
 *       Arguments:  fn:       the function to be placed in the appropriate
 *                             queue
 *                   priority: this identifies the queue into which the
 *                             request is to b placed
 *                   a1:       first argument to <fn> (goes in r0)
 *                   a2:       second argument to <fn> (goes in r1)
 *                   a3:       third argument to <fn> (goes in r2)
 *                   a4:       fourth argument to <fn> (goes in r3)
 *
 *  Pre-conditions:  This code must be called in SVC mode, with the lock.
 *
 *          Effect:  QueueTask is called, with registers set up as above,
 *                   and in addition:
 *
 *                     fp   = 0  (no previous frames)
 *                     lr  -> entry point of NextTask
 *                     pc  -> <fn>
 *                     cpsr = USR, I-clear, F-clear
 *                     sl, sp are set to be the Application stack
 *
 *            Note:  This routine is not atomic, but it does call QueueTask,
 *                   which is.
 */

typedef void (*angel_CallbackFn)(void *a1,
                                 void *a2,
                                 void *a3,
                                 void *a4);

void Angel_QueueCallback(angel_CallbackFn fn,
                         angel_TaskPriority priority,
                         void *a1,
                         void *a2,
                         void *a3,
                         void *a4);

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

/*
 *        Function:  Angel_BlockApplication
 *         Purpose:  To block the application (both its "normal level" and
 *                   any callbacks).
 *
 *        Argument:  The argument value controls whether the application is
 *                   to be blocked or unblocked:
 *
 *                       0 => unblock application tasks
 *                       1 => block application tasks
 *
 *  Pre-conditions:  None - this function does not need to be atomic.
 *
 *          Effect:  The application is blocked or unblocked, according to
 *                   the value of "value".
 */

void Angel_BlockApplication(int value);

/*
 *        Function:  Angel_IsApplicationBlocked
 *         Purpose:  To return whether or not the Application and 
 *                   Application Callbacks have been blocked by Angel
 *
 *       Arguments:  None
 *
 *  Pre-conditions:  None - this function does not need to be atomic.
 *
 *          Effect:  0 is returned if the Application is not blocked
 *                   1 is returned if the Application is blocked
 */

int Angel_IsApplicationBlocked(void);

/*
 *        Function:  Angel_IsApplicationRunning
 *         Purpose:  To return whether or not the Application or an
 *                   Application Callback is running.  This can be used
 *                   to determine whether or not it is safe to switch
 *                   tasks in an OS scheduler.
 *
 *       Arguments:  None
 *
 *  Pre-conditions:  None - this function does not need to be atomic.
 *
 *          Effect:  1 is returned if the Application/Appl Callback is running
 *                   0 is returned if not
 */

int Angel_IsApplicationRunning(void);

/*
 *        Function:  Angel_AccessApplicationRegblock
 *         Purpose:  To obtain a pointer to the register block structure which
 *                   contains the registers of the application.
 *
 *  Pre-conditions:  This function does not need to be atomic. It is assumed
 *                   that the application is blocked.
 *
 *          Effect:  A pointer to the relevant data structure is returned.
 *                   This structure will remain valid until the application
 *                   is unblocked.
 */

angel_RegBlock *Angel_AccessApplicationRegBlock(void);

/*
 *        Function:  Angel_FlushApplicationCallbacks
 *         Purpose:  To remove any outstanding callbacks from the application
 *                   task - that is, any with priority ApplCallBack.
 *