devdriv.h

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

/* -*-C-*-
 *
 * $Revision: 1.7 $
 *   $Author: kwelton $
 *     $Date: 1996/07/30 12:52:29 $
 *
 * Copyright (c) 1996 Advanced RISC Machines Limited.
 * All Rights Reserved.
 *
 *   Project: ANGEL
 *
 *     Title: Device driver framework interface.
 */

#ifndef angel_devdriv_h
#define angel_devdriv_h

/*
 * This header exports the interface to the device driver framework
 * for use within specific device drivers.  These calls are not for use
 * by the body of Angel or of an application.
 */

#include "devconf.h"
#include "devclnt.h"
#include "serlock.h"            /* angel_RegBlock */
#include "params.h"

/* General purpose constants, macros, enums, typedefs */

/*
 * The following typedefs provide the prototypes for the various
 * entry points into a device driver.
 */

/*
 * device driver write entry point
 * ===============================
 *
 * + see angel_DeviceWrite() in devclnt.h for parameters.
 * + callbacks handled by the framework via angel_DD_SentPacket() below.
 */
typedef DevError (*angel_DeviceWriteFn)(DeviceID devID,
                                        p_Buffer buff, unsigned length,
                                        DevChanID chanID);

typedef DevError (*angel_RawWriteFn)(DeviceID devID,
                                     p_Buffer buff, unsigned length);

/*
 * device driver register read entry point
 * =======================================
 *
 * + see angel_DeviceRegisterRead() in devclnt.h for parameters.
 * + callbacks handled by the framework via angel_DD_GotPacket() below.
 */
typedef DevError (*angel_DeviceRegisterReadFn)(
                                        DeviceID devID, DevChanID chanID);

typedef DevError (*angel_RawReadFn)(DeviceID devID,
                                    p_Buffer buff, unsigned length);

/*
 * device driver control entry point
 * =================================
 *
 * + see angel_DeviceControl() in devclnt.h for parameters
 */
typedef DevError (*angel_DeviceControlFn)(DeviceID devID,
                                          DeviceControl op, void *arg);

/*
 * Interrupt entry point
 * =====================
 * 
 * Parameters:
 *             ident        the ident supplied by the HW-specific GETSOURCE
 *                          macro, which corresponds to the position in the
 *                          angel_IntHandler[] table in devices.c
 *
 *             data         the data entry in the angel_IntHandler[] table.
 *
 *             empty_stack  where to reset the stack to if the serialiser
 *                          is called.
 *                          This will be required should the handler wish
 *                          to use the serialiser to get the lock [by
 *                          calling Angel_SerialiseTask()]
 *
 * If the Interrupt handler can complete its servicing very quickly, then it
 * can simply return in the ordinary way.
 *
 * Any processing that will impact interrupt latency should be performed
 * as a serialised function, queued by a call to Angel_SerialiseTask(),
 * in which case the handler will appear not to return.
 */
typedef void (*angel_IntHandlerFn)(
    unsigned        ident,           /* hw-specific ident */
    unsigned        data,            /* data in Int table */
    unsigned        empty_stack      /* to be passed thru to SerialiseTask */
    );

/*
 * poll entry point
 * ================
 *
 * Parameters:
 *              data  the corresponding data entry in the angel_PollHandler[]
 *                    table in devices.c
 *
 * Note that there are two entries per polled device in the angel_PollHandler[]
 * table, one for 'read' and one for 'write'.
 *
 * Each entry in the angel_PollHandler[] table is called once
 * per Angel_Yield().  The poll handler should keep its own record of whether
 * it should perform any processing, and should return immediately if not.
 *
 * Note that poll handlers are called in SVC mode with the lock.
 */
typedef void (*angel_PollHandlerFn)(unsigned data);

/* Angel or raw device? */
typedef enum angel_DeviceType {
    DT_ANGEL,
    DT_RAW
} angel_DeviceType;

/* Read and write for Angel/shared devices */
typedef struct angel_AngelReadWrite {
    angel_DeviceWriteFn         async_write;
    angel_DeviceRegisterReadFn  register_read;
} angel_AngelReadWrite;

/* Read and write for raw devices */
typedef struct angel_RawReadWrite {
    angel_RawWriteFn            write;
    angel_RawReadFn             read;
} angel_RawReadWrite;

/* An entry in the main table of device drivers */
struct angel_DeviceEntry {
  angel_DeviceType           type;
  union {
    angel_AngelReadWrite angel;
    angel_RawReadWrite   raw;
  }                          rw;
  angel_DeviceControlFn      control;
  const void                *data;
  ParameterOptions           options;
  ParameterConfig            default_config;
};

/* Interrupt handler table entry */
struct angel_IntHandlerEntry {
  angel_IntHandlerFn    handler; /* the handler function */
  unsigned              data;    /* data passed to handler */
};

/* Poll handler table entry */
struct angel_PollHandlerEntry {
  angel_PollHandlerFn   read_handler;   /* the poll handler for reads */
  unsigned              read_data;      /* data passed to read handler */
  angel_PollHandlerFn   write_handler;  /* the poll handler for writes */
  unsigned              write_data;     /* data passed to write handler */
};

/* flags for public device status -- see angel_DeviceStatus below */
#define DEV_COMMON_FLAGS_MASK  (0xFF)
#define DEV_PRIVATE_FLAGS_MASK ((2^sizeof(unsigned)-1)^DEV_COMMON_MASK)

/*
 * DEV_READ_BUSY is set once a reader has been registered
 * for the corresponding device channel
 */
#define DEV_READ_BUSY(devchan) (1<<(devchan))
#define DEV_READ_APPL_BUSY  (1<<0)
#define DEV_READ_DBUG_BUSY  (1<<1)
#define DEV_READ_BUSY_MASK  (DEV_READ_APPL_BUSY | DEV_READ_DBUG_BUSY)

/*
 * DEV_WRITE_BUSY is set whenever a write is in progress
 */
#define DEV_WRITE_BUSY      (1<<7)
/* other bits reserved */


/* Publically-accessible globals */

/*
 * the public state of the devices
 * -- bits 0 thru 7 used by DEV_WRITE_BUSY and DEV_READ_BUSY, etc.
 * -- remaining bits free for use by device driver
 */
extern volatile unsigned int angel_DeviceStatus[DI_NUM_DEVICES];

/*
 * the main device driver table
 *
 * DI_NUM_DEVICES is in devconf.h
 */
extern const struct angel_DeviceEntry * const angel_Device[DI_NUM_DEVICES];

/*
 * a standard do-nothing device which is used as a place filler for
 * devices which are not configured into Angel
 */
extern const struct angel_DeviceEntry angel_NullDevice;

/*
 * an error-reporting interrupt handler, used as a place filler for
 * interrupt-driven devices which are not configured into Angel
 */
extern void angel_NodevIntHandler(unsigned int ident, unsigned int data,
                                  unsigned int empty_stack);

/* the Interrupt handler table */
#if DE_NUM_INT_HANDLERS>0
extern const struct angel_IntHandlerEntry
                    angel_IntHandler[];
#endif

/* the poll handler table */
#if DE_NUM_POLL_HANDLERS>0
extern const struct angel_PollHandlerEntry 
                    angel_PollHandler[];
#endif


/* Public functions */

/*
 * The _DD_ functions are convenience functions to be called from
 * the device drivers, which handle the details of callbacks, etc.
 */

/*
 * Function: angel_DD_GetBuffer
 *  Purpose: Grab a buffer for receiving a packet into, called once
 *           the device driver knows which Device Channel the read
 *           is for, and how much space is required.
 *
 *   Params:
 *              Input: devid     device ID of the driver
 *                     devchan   which device channel the request is for
 *                     req_size  required buffer size
 */
p_Buffer angel_DD_GetBuffer( DeviceID   devid,
                             DevChanID  devchan,
                             unsigned   req_size );

/*
 * Function: angel_DD_GotPacket
 *  Purpose: Allows the device driver to queue a callback on completion of
 *           reading a packet, or when a read error occurs once the DevChanID
 *           of the packet in error has been established.
 *
 *   Params:
 *              Input:  devid      device ID of the driver
 *                      buff       buffer with packet in
 *                      length     length of packet
 *                      status     read completion status
 *                      devchanID  which device channel the packet is for
 */
void angel_DD_GotPacket(DeviceID        devID,
                        p_Buffer        buff,
                        unsigned        length,
                        DevStatus       status,
                        DevChanID       devchanID);

/*
 * Function: angel_DD_SentPacket
 *  Purpose: Allows the device driver to queue a callback on completion of
 *           sending a packet.
 *
 *  Pre-conditions: Must be called in SVC mode
 *
 *   Params:
 *              Input:  devid      device ID of the driver
 *                      buff       buffer with packet in
 *                      length     length of packet
 *                      status     write completion status
 *                      devchanID  which device channel the write was for
 */
void angel_DD_SentPacket(DeviceID        devID,    /* which device */
                         p_Buffer        buff,     /* pointer to data */
                         unsigned        length,   /* how much done */
                         DevStatus       status,   /* success code */
                         DevChanID       devchanID); /* appl or chan */


/*
 * Function: angel_DeviceYield
 *  Purpose: allow any polled devices to do a poll
 *
 *   Params:    None
 *
 * Will be called from Angel_Yield to call all the neccessary poll
 * functions.
 */
void angel_DeviceYield(void);


#endif /* ndef angel_devdriv_h */

/* EOF devdriv.h */