io_api.h

MIPS下的boottloader yamon 的源代码

#ifndef IO_API_H
#define IO_API_H

/************************************************************************
 *
 *      io_api.h
 *
 *      The 'io' module implements a generic api for all device drivers.
 *      Through this interface all interaction between the user and the
 *      device driver is executed by use of a standard set of io-functions
 *      to:
 *
 *        1) init  device,
 *        2) open  device,
 *        3) close device,
 *        4) read  device,
 *        5) write device,
 *        6) ctrl  device.
 *
 *
 *
 * ######################################################################
 *
 * Copyright (c) 1999-2000 MIPS Technologies, Inc. All rights reserved. 
 * 
 * Unpublished rights reserved under the Copyright Laws of the United States of 
 * America. 
 * 
 * This document contains information that is proprietary to MIPS Technologies, 
 * Inc. ("MIPS Technologies"). Any copying, modifying or use of this information 
 * (in whole or in part) which is not expressly permitted in writing by MIPS 
 * Technologies or a contractually-authorized third party is strictly 
 * prohibited. At a minimum, this information is protected under unfair 
 * competition laws and the expression of the information contained herein is 
 * protected under federal copyright laws. Violations thereof may result in 
 * criminal penalties and fines. 
 * MIPS Technologies or any contractually-authorized third party reserves the 
 * right to change the information contained in this document to improve 
 * function, design or otherwise. MIPS Technologies does not assume any 
 * liability arising out of the application or use of this information. Any 
 * license under patent rights or any other intellectual property rights owned 
 * by MIPS Technologies or third parties shall be conveyed by MIPS Technologies 
 * or any contractually-authorized third party in a separate license agreement 
 * between the parties. 
 * The information contained in this document constitutes one or more of the 
 * following: commercial computer software, commercial computer software 
 * documentation or other commercial items. If the user of this information, or 
 * any related documentation of any kind, including related technical data or 
 * manuals, is an agency, department, or other entity of the United States 
 * government ("Government"), the use, duplication, reproduction, release, 
 * modification, disclosure, or transfer of this information, or any related 
 * documentation of any kind, is restricted in accordance with Federal 
 * Acquisition Regulation 12.212 for civilian agencies and Defense Federal 
 * Acquisition Regulation Supplement 227.7202 for military agencies. The use of 
 * this information by the Government is further restricted in accordance with 
 * the terms of the license agreement(s) and/or applicable contract terms and 
 * conditions covering this information from MIPS Technologies or any 
 * contractually-authorized third party. 
 *
 ************************************************************************/




/************************************************************************
 *    Include files
 ************************************************************************/

#include "sysdefs.h"
#include "syserror.h"


/************************************************************************
 *  System Definitions
*************************************************************************/


/* 
   Device driver service function prototype
                                                                        */
typedef INT32 (*t_io_service)( 
          UINT32 major,          /* IN: major device number             */
          UINT32 minor,          /* IN: minor device number             */
          void   *p_param ) ;    /* INOUT: device parameter block       */


/************************************************************************
 *   IO enumeration definitions
*************************************************************************/

/*
   ERROR completion codes for the IO system
                                                                        */
typedef enum IO_error_ids
{
    ERROR_IO_ILLEGAL_MAJOR = ERROR_IO,  /* Illegal major device number  */
    ERROR_IO_NO_DRIVER,                 /* Driver not installed         */
    ERROR_IO_NO_SERVICE,                /* Driver service not implem.   */
    ERROR_IO_NO_SPACE,                  /* Major device slot not free   */
    ERROR_IO_ILLEGAL_DEVICE,            /* No services implemented      */


/******* ADD NEW IO ERROR TAGS JUST BEFORE THIS LINE ONLY *******/

    ERROR_IO_TAG_SIZE
} t_IO_error_ids;



/************************************************************************
 *    Public variables
 ************************************************************************/

/************************************************************************
 *   Public functions
 ************************************************************************/

/************************************************************************
 *
 *                          IO_setup
 *  Description :
 *  -------------
 *
 *  Initializes the 'IO' module.
 *  
 *  
 *  
 *
 *  Parameters :
 *  ------------
 *
 *  'devices',   IN,    allocate space for max. 'devices' to be
 *                      handled by the IO system
 *
 *
 *  Return values :
 *  ---------------
 *
 *  'OK'(=0)
 *  'ERROR_IO_NO_SPACE':       Not enough memory
 *
 ************************************************************************/
INT32 IO_setup(  
          UINT32 devices  ) ; /* IN: max. 'devices' to be supported     */



/************************************************************************
 *
 *                          IO_install
 *  Description :
 *  -------------
 *
 *  Installs the device drivers services in the IO system at the
 *  specified device slot, which is adressed with the 'major'
 *  device number. The service function pointers may be 'NULL',
 *  but at least one service must be supplied.
 *  
 *  
 *  
 *
 *  Parameters :
 *  ------------
 *
 *  'major',     IN,    major device number
 *  'init',      IN,    device drivers 'init'  service function pointer
 *  'open',      IN,    device drivers 'open'  service function pointer
 *  'close',     IN,    device drivers 'close' service function pointer
 *  'read',      IN,    device drivers 'read'  service function pointer
 *  'write',     IN,    device drivers 'write' service function pointer
 *  'ctrl',      IN,    device drivers 'ctrl'  service function pointer
 *
 *
 *  Return values :
 *  ---------------
 *
 *  'OK'(=0)
 *  'ERROR_IO_ILLEGAL_DEVICE': No device services are provided
 *  'ERROR_IO_ILLEGAL_MAJOR':  Illegal major device number
 *  'ERROR_IO_NO_SPACE':       Device slot already allocated
 *
 ************************************************************************/
INT32 IO_install(
          UINT32       major,    /* IN: major device number             */
          t_io_service init,     /* 'init'  service function pointer    */
          t_io_service open,     /* 'open'  service function pointer    */
          t_io_service close,    /* 'close' service function pointer    */
          t_io_service read,     /* 'read'  service function pointer    */
          t_io_service write,    /* 'write' service function pointer    */
          t_io_service ctrl ) ;  /* 'ctrl'  service function pointer    */



/************************************************************************
 *
 *                          IO_init
 *  Description :
 *  -------------
 *
 *  This function looks up the 'init' function of the driver by use of
 *  the 'major' device number and calls the 'init' function with the
 *  supplied parameters, 'minor' and 'p_param'.
 *  
 *
 *  Parameters :
 *  ------------
 *
 *  'major',     IN,    major device number
 *  'minor',     IN,    minor device number for multi device drivers
 *  'p_param',   INOUT, device specific parameter block
 *
 *
 *  Return values :
 *  ---------------
 *
 *  'OK'(=0)
 *  'ERROR_IO_ILLEGAL_MAJOR': Illegal major device number
 *  'ERROR_IO_NO_DRIVER':     Driver not installed
 *  'ERROR_IO_NO_FUNCTION':   Driver don't implement 'init'
 *
 *
 *  Note :
 *  ------
 *  The return values above are the IO-system specific values only.
 *  Errors, which are specific for the device driver, may be returned too.
 *
 ************************************************************************/
INT32 IO_init(
          UINT32 major,          /* IN: major device number             */
          UINT32 minor,          /* IN: minor device number             */
          void   *p_param ) ;    /* INOUT: device parameter block       */




/************************************************************************
 *
 *                          IO_open
 *  Description :
 *  -------------
 *
 *  This function looks up the 'open' function of the driver by use of
 *  the 'major' device number and calls the 'open' function with the
 *  supplied parameters, 'minor' and 'p_param'.
 *  
 *
 *  Parameters :
 *  ------------
 *
 *  'major',     IN,    major device number
 *  'minor',     IN,    minor device number for multi device drivers
 *  'p_param',   INOUT, device specific parameter block
 *
 *
 *  Return values :
 *  ---------------