io.c

MIPS YAMON, a famous monitor inc. source, make file and PDF manuals.

 *  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       */
{
    /* check for invalid major device number */
    IO_CHECK_MAJOR( major, last_device ) ;

    /* call service */
    return( IO[major].init( major, minor, p_param ) ) ;
}


/************************************************************************
 *
 *                          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 :
 *  ---------------
 *
 *  '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 'open'
 *
 *
 *  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_open(
          UINT32 major,          /* IN: major device number             */
          UINT32 minor,          /* IN: minor device number             */
          void   *p_param )      /* INOUT: device parameter block       */
{
    /* check for invalid major device number */
    IO_CHECK_MAJOR( major, last_device ) ;

    /* call service */
    return( IO[major].open( major, minor, p_param ) ) ;
}



/************************************************************************
 *
 *                          IO_close
 *  Description :
 *  -------------
 *
 *  This function looks up the 'close' function of the driver by use of
 *  the 'major' device number and calls the 'close' 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 'close'
 *
 *
 *  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_close(
          UINT32 major,          /* IN: major device number             */
          UINT32 minor,          /* IN: minor device number             */
          void   *p_param )      /* INOUT: device parameter block       */
{
    /* check for invalid major device number */
    IO_CHECK_MAJOR( major, last_device ) ;

    /* call service */
    return( IO[major].close( major, minor, p_param ) ) ;
}



/************************************************************************
 *
 *                          IO_read
 *  Description :
 *  -------------
 *
 *  This function looks up the 'read' function of the driver by use of
 *  the 'major' device number and calls the 'read' 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 'read'
 *
 *
 *  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_read(
          UINT32 major,          /* IN: major device number             */
          UINT32 minor,          /* IN: minor device number             */
          void   *p_param )      /* INOUT: device parameter block       */
{
    /* check for invalid major device number */
    IO_CHECK_MAJOR( major, last_device ) ;

    /* call service */
    return( IO[major].read( major, minor, p_param ) ) ;
}



/************************************************************************
 *
 *                          IO_write
 *  Description :
 *  -------------
 *
 *  This function looks up the 'write' function of the driver by use of
 *  the 'major' device number and calls the 'write' 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 'write'
 *
 *
 *  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_write(
          UINT32 major,          /* IN: major device number             */
          UINT32 minor,          /* IN: minor device number             */
          void   *p_param )      /* INOUT: device parameter block       */
{
    /* check for invalid major device number */
    IO_CHECK_MAJOR( major, last_device ) ;

    /* call service */
    return( IO[major].write( major, minor, p_param ) ) ;
}


/************************************************************************
 *
 *                          IO_ctrl
 *  Description :
 *  -------------
 *
 *  This function looks up the 'ctrl' function of the driver by use of
 *  the 'major' device number and calls the 'ctrl' 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 'ctrl'
 *
 *
 *  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_ctrl(
          UINT32 major,          /* IN: major device number             */
          UINT32 minor,          /* IN: minor device number             */
          void   *p_param )      /* INOUT: device parameter block       */
{
    /* check for invalid major device number */
    IO_CHECK_MAJOR( major, last_device ) ;

    /* call service */
    return( IO[major].ctrl( major, minor, p_param ) ) ;
}


/************************************************************************
 *
 *                          IO_lookup
 *  Description :
 *  -------------
 *
 *  Lookup device driver data context pointer
 *  
 *
 *  Parameters :
 *  ------------
 *
 *  'major',     IN,    major device number
 *  'p_data',    OUT,   data context pointer
 *
 *
 *  Return values :
 *  ---------------
 *
 *  'OK'(=0)
 *  'ERROR_IO_ILLEGAL_MAJOR': Illegal major device number
 *  'ERROR_IO_NO_DRIVER':     Driver not installed
 *
 ************************************************************************/
INT32 IO_lookup(  
          UINT32 major,          /* IN: major device number             */
          void   **p_data )      /* OUT: device context data            */
{
    /* in case any error detected, return 'NULL' */
    *p_data = NULL ;

    /* check for invalid major device number */
    IO_CHECK_MAJOR( major, last_device ) ;

    /* check, if driver has been installed */
    if ( IO[major].state == IO_DEVICE_PRESENT )
    {
        *p_data = IO[major].data ;
        return( OK ) ;
    }
    else
    {
        return( ERROR_IO_NO_DRIVER ) ;
    }
}


/************************************************************************
 *
 *                          IO_save
 *  Description :
 *  -------------
 *
 *  Save device driver data context pointer
 *  
 *
 *  Parameters :
 *  ------------
 *
 *  'major',     IN,    major device number
 *  'p_data',    IN,    data context pointer
 *
 *
 *  Return values :
 *  ---------------
 *
 *  'OK'(=0)
 *  'ERROR_IO_ILLEGAL_MAJOR': Illegal major device number
 *  'ERROR_IO_NO_DRIVER':     Driver not installed
 *
 ************************************************************************/
INT32 IO_save(  
          UINT32 major,          /* IN: major device number             */
          void   *p_data )       /* IN: device context data             */
{
    /* check for invalid major device number */
    IO_CHECK_MAJOR( major, last_device ) ;

    /* check, if driver has been installed */
    if ( IO[major].state == IO_DEVICE_PRESENT )
    {
        IO[major].data = p_data ;
        return( OK ) ;
    }
    else
    {
        return( ERROR_IO_NO_DRIVER ) ;
    }
}



/************************************************************************
 *      Implementation : Static functions
 ************************************************************************/


/************************************************************************
 *
 *                          IO_dummy_no_driver
 *  Description :
 *  -------------
 *
 *  This is a dummy device driver service, which is inserted in each
 *  service entry of each allocated device in the IO device table.
 *  This will ensure a device service to be handled with a correct
 *  service completion ('ERROR_IO_NO_DRIVER') as default service.
 *  
 *
 *  Parameters :
 *  ------------
 *
 *  'major',     IN,    major device number
 *  'minor',     IN,    minor device number for multi device drivers
 *  'p_param',   INOUT, device specific parameter block
 *
 *
 *  Return values :
 *  ---------------
 *
 *  'ERROR_IO_NO_DRIVER':     Driver not installed
 *
 ************************************************************************/
static
INT32 IO_dummy_no_driver(
          UINT32 major,          /* IN: major device number             */
          UINT32 minor,          /* IN: minor device number             */
          void   *p_param )      /* INOUT: device parameter block       */
{
    return( ERROR_IO_NO_DRIVER ) ;
}



/************************************************************************
 *
 *                          IO_dummy_no_service
 *  Description :
 *  -------------
 *
 *  This is a dummy device driver service, which is the default service,
 *  for unsupported services of installed device drivers.
 *  This will ensure a device service to be handled with a correct
 *  service completion ('ERROR_IO_NO_SERVICE') as default service.
 *  
 *
 *  Parameters :
 *  ------------
 *
 *  'major',     IN,    major device number
 *  'minor',     IN,    minor device number for multi device drivers
 *  'p_param',   INOUT, device specific parameter block
 *
 *
 *  Return values :
 *  ---------------
 *
 *  'ERROR_IO_NO_SERVICE':     Unsupported service
 *
 ************************************************************************/
static
INT32 IO_dummy_no_service(
          UINT32 major,          /* IN: major device number             */
          UINT32 minor,          /* IN: minor device number             */
          void   *p_param )      /* INOUT: device parameter block       */
{
    return( ERROR_IO_NO_SERVICE ) ;
}