xopbarb.c

基于Xilinx-XUPV2P开发平台的嵌入式系统实验例程：实验4编写基本的应用程序

/* $Id: xopbarb.c,v 1.1 2002/06/26 17:36:23 linnj Exp $ */
/******************************************************************************
*
*       XILINX IS PROVIDING THIS DESIGN, CODE, OR INFORMATION "AS IS"
*       AS A COURTESY TO YOU, SOLELY FOR USE IN DEVELOPING PROGRAMS AND
*       SOLUTIONS FOR XILINX DEVICES.  BY PROVIDING THIS DESIGN, CODE,
*       OR INFORMATION AS ONE POSSIBLE IMPLEMENTATION OF THIS FEATURE,
*       APPLICATION OR STANDARD, XILINX IS MAKING NO REPRESENTATION
*       THAT THIS IMPLEMENTATION IS FREE FROM ANY CLAIMS OF INFRINGEMENT,
*       AND YOU ARE RESPONSIBLE FOR OBTAINING ANY RIGHTS YOU MAY REQUIRE
*       FOR YOUR IMPLEMENTATION.  XILINX EXPRESSLY DISCLAIMS ANY
*       WARRANTY WHATSOEVER WITH RESPECT TO THE ADEQUACY OF THE
*       IMPLEMENTATION, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OR
*       REPRESENTATIONS THAT THIS IMPLEMENTATION IS FREE FROM CLAIMS OF
*       INFRINGEMENT, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
*       FOR A PARTICULAR PURPOSE.
*
*       (c) Copyright 2002 Xilinx Inc.
*       All rights reserved.
*
******************************************************************************/
/*****************************************************************************/
/**
*
* @file xopbarb.c
*
* This component contains the implementation of the XOpbArb driver component.
*
* <pre>
* MODIFICATION HISTORY:
*
* Ver   Who  Date     Changes
* ----- ---- -------- -----------------------------------------------
* 1.02a rpm  08/13/01 First release
* </pre>
*
******************************************************************************/

/***************************** Include Files *********************************/

#include "xparameters.h"
#include "xopbarb.h"
#include "xio.h"

/************************** Constant Definitions *****************************/


/**************************** Type Definitions *******************************/


/***************** Macros (Inline Functions) Definitions *********************/


/************************** Function Prototypes ******************************/


/************************** Variable Definitions *****************************/

/*
 * Create the table of options which are processed to get/set the device
 * options. These options are table driven to allow easy maintenance and
 * expansion of the options.
 */
typedef struct
{
    Xuint32 Option;
    Xuint32 Mask;
} OptionsMap;

static OptionsMap OptionsTable[] =
{
    {XOA_DYNAMIC_PRIORITY_OPTION,   XOA_CR_DYNAMIC_ENABLE_MASK},
    {XOA_PARK_ENABLE_OPTION,        XOA_CR_PARK_ENABLE_MASK},
    {XOA_PARK_BY_ID_OPTION,         XOA_CR_PARK_ON_ID_MASK}
};

#define XOA_NUM_OPTIONS      (sizeof(OptionsTable) / sizeof(OptionsMap))

/*****************************************************************************/
/**
*
* Initializes a specific XOpbArb instance. The driver is initialized to allow
* access to the device registers. In addition, the configuration information
* is retrieved for the device. Currently, configuration information is stored
* in xopbarb_g.c.
*
* The state of the device after initialization is:
*   - Fixed or dynamic priority arbitration based on hardware parameter
*   - Bus parking is disabled
*
* @param    InstancePtr is a pointer to the XOpbArb instance to be worked on.
* @param    DeviceId is the unique id of the device controlled by this XOpbArb
*           component. Passing in a device id associates the generic XOpbArb
*           component to a specific device, as chosen by the caller or
*           application developer.
*
* @return
*
* The return value is XST_SUCCESS if successful or XST_DEVICE_NOT_FOUND if no
* configuration data was found for this device.
*
* @note
*
* None.
*
******************************************************************************/
XStatus XOpbArb_Initialize(XOpbArb *InstancePtr, Xuint16 DeviceId)
{
    XOpbArb_Config *ConfigPtr;   /* Pointer to Configuration ROM data */

    XASSERT_NONVOID(InstancePtr != XNULL);

    /*
     * Lookup the device configuration in the temporary CROM table. Use this
     * configuration info down below when initializing this component.
     */
    ConfigPtr = XOpbArb_LookupConfig(DeviceId);
    if (ConfigPtr == XNULL)
    {
        return XST_DEVICE_NOT_FOUND;
    }

    /*
     * Set some default values
     */
    InstancePtr->BaseAddress = ConfigPtr->BaseAddress;
    InstancePtr->NumMasters = ConfigPtr->NumMasters;

    /*
     * Indicate the component is now ready to use since it is initialized
     * without errors
     */
    InstancePtr->IsReady = XCOMPONENT_IS_READY;

    return XST_SUCCESS;
}

/*****************************************************************************/
/**
*
* Runs a self-test on the driver/device. The self-test simply verifies that
* the arbiter's registers can be read and written. This is an intrusive test
* in that the arbiter will not be using the priority registers while the test
* is being performed.
*
* @param    InstancePtr is a pointer to the XOpbArb instance to be worked on.
*
* @return
*
* XST_SUCCESS if successful, or XST_REGISTER_ERROR if a register did
* not read or write correctly
*
* @note
*
* The priority level registers are restored after testing them in order to
* prevent problems with the registers being the same value after the test.
* <br><br>
* If the arbiter is in dynamic priority mode, this test changes the mode to
* fixed to ensure that the priority registers aren't changed by the arbiter
* during this test. The mode is restored to it's entry value on exit.
*
******************************************************************************/
XStatus XOpbArb_SelfTest(XOpbArb *InstancePtr)
{
    Xuint8 Level;
    Xuint8 Master;
    Xuint32 LvlReg;
    Xuint32 LvlOffset;
    Xboolean RestoreControlReg = XFALSE;
    Xuint32 MasterRestore;
    Xuint32 ControlReg;

    XASSERT_NONVOID(InstancePtr != XNULL);
    XASSERT_NONVOID(InstancePtr->IsReady == XCOMPONENT_IS_READY);

    /* If the priority registers of the arbiter are being used by the arbiter,
     * or priorities are dynamic, then set the control register such that it
     * does not use them before modifying them, otherwise the arbiter may hang
     * the bus if a master accesses the bus without a priority
     */
    ControlReg = XIo_In32(InstancePtr->BaseAddress + XOA_CR_OFFSET);
    if (ControlReg & (XOA_CR_PRIORITY_VALID_MASK | XOA_CR_DYNAMIC_ENABLE_MASK))
    {
        XIo_Out32(InstancePtr->BaseAddress + XOA_CR_OFFSET, ControlReg &
                  ~(XOA_CR_PRIORITY_VALID_MASK | XOA_CR_DYNAMIC_ENABLE_MASK));
        RestoreControlReg = XTRUE;
    }

    /*
     * Test read/write of all the priority level registers based on
     * the number of masters.
     */
    for (Level = 0; Level < InstancePtr->NumMasters; Level++)
    {
        /*
         * Calculate the offset of the priority level register
         */
        LvlOffset = XOA_LVLX_OFFSET + (Level * XOA_LVLX_SIZE);

        /*
         * Save a copy of the priority level register being tested such that
         * it can be restored after testing the register
         */
        MasterRestore = XIo_In32(InstancePtr->BaseAddress + LvlOffset);

        /*
         * Set the priority level register to each possible master value
         */
        for (Master = 0; Master < InstancePtr->NumMasters; Master++)
        {
            XIo_Out32(InstancePtr->BaseAddress + LvlOffset, Master);

            /*
             * Get the priority level register and verify it is set correctly
             */
            LvlReg = XIo_In32(InstancePtr->BaseAddress + LvlOffset);

            if (LvlReg != Master)
            {
                return XST_REGISTER_ERROR;
            }
        }

        /*
         * Restore the priority level register being tested to it's state
         * before the test
         */
        XIo_Out32(InstancePtr->BaseAddress + LvlOffset, MasterRestore);
    }

    /* If the control register was modified to prevent the arbiter from using
     * the priority registers or to put the arbiter into fixed priority during
     * this test, restore it to it's original value
     */
    if (RestoreControlReg)
    {
        XIo_Out32(InstancePtr->BaseAddress + XOA_CR_OFFSET, ControlReg);
    }

    return XST_SUCCESS;
}

/*****************************************************************************/
/**
*
* Sets the options for the OPB arbiter. The options control how the device
* grants the bus to requesting masters.
*
* @param    InstancePtr is a pointer to the XOpbArb instance to be worked on.
* @param    Options contains the specified options to be set. This is a bit
*           mask where a 1 means to turn the option on, and a 0 means to turn
*           the option off. See xopbarb.h for a description of the options.
*
* @return
*
*   - XST_SUCCESS if options are successfully set.
*   - XST_NO_FEATURE if an attempt was made to enable dynamic priority
*     arbitration when the device is configured only for fixed priority
*     arbitration, or an attempt was made to enable parking when bus parking
*     is not supported by the device.
*   - XST_OPBARB_PARK_NOT_ENABLED if bus parking by park ID was enabled
*     but bus parking itself was not enabled.
*
* @note
*
* None.
*
******************************************************************************/
XStatus XOpbArb_SetOptions(XOpbArb *InstancePtr, Xuint32 Options)
{
    Xuint32 ControlReg;
    int Index;

    XASSERT_NONVOID(InstancePtr != XNULL);
    XASSERT_NONVOID(InstancePtr->IsReady == XCOMPONENT_IS_READY);

    ControlReg = XIo_In32(InstancePtr->BaseAddress + XOA_CR_OFFSET);

    /*
     * If the user is trying to enable dynamic priorities, but the hardware
     * is parameterized for fixed priorities only, then return an error. We
     * determine how the hardware is parameterized based on the read/write
     * nature of the dynamic priority enable bit in the control register.
     */
    if (Options & XOA_DYNAMIC_PRIORITY_OPTION)
    {
        if ((ControlReg & XOA_CR_DYNAMIC_RW_MASK) == 0)
        {
            /*
             * Dynamic Priority Enable bit is read-only, so dynamic priority
             * arbitration is not included in the device
             */
            return XST_NO_FEATURE;
        }
    }

    /*
     * If the user is trying to enable bus parking, but the hardware does not
     * support it based on its parameters, then return an error. We determine
     * how the hardware is parameterized based on the read/write nature of the
     * park enable bit in the control register.
     */
    if (Options & (XOA_PARK_ENABLE_OPTION | XOA_PARK_BY_ID_OPTION))
    {
        if ((ControlReg & XOA_CR_PARK_RW_MASK) == 0)
        {
            /*
             * Park Enable bit is read-only, so bus parking is not included in
             * the device
             */
            return XST_NO_FEATURE;
        }
    }

    /*
     * Verify that if the user is requesting bus parking by ID, they have also
     * enabled bus parking.
     */
    if ((Options & XOA_PARK_BY_ID_OPTION) &&
        ((Options & XOA_PARK_ENABLE_OPTION) == 0))
    {
        return XST_OPBARB_PARK_NOT_ENABLED;
    }

    /*
     * Loop through the options table, turning the option on or off
     * depending on whether the bit is set in the incoming options flag.
     */
    for (Index = 0; Index < XOA_NUM_OPTIONS; Index++)
    {
        if (Options & OptionsTable[Index].Option)
        {
            ControlReg |= OptionsTable[Index].Mask;     /* turn it on */
        }
        else
        {
            ControlReg &= ~OptionsTable[Index].Mask;    /* turn it off */
        }
    }

    /*
     * Now write the control register.
     */
    XIo_Out32(InstancePtr->BaseAddress + XOA_CR_OFFSET, ControlReg);

    return XST_SUCCESS;
}

/*****************************************************************************/
/**
*
* Gets the options for the arbiter. The options control how the device grants
* the bus to requesting masters.
*
* @param    InstancePtr is a pointer to the XOpbArb instance to be worked on.
*
* @return
*
* The options of the device. This is a bit mask where a 1 means the option is
* on, and a 0 means the option is off. See xopbarb.h for a description of the
* options.
*
* @note
*
* None.
*
******************************************************************************/
Xuint32 XOpbArb_GetOptions(XOpbArb *InstancePtr)
{
    Xuint32 OptionsFlag = 0;
    Xuint32 ControlReg;
    int Index;

    XASSERT_NONVOID(InstancePtr != XNULL);
    XASSERT_NONVOID(InstancePtr->IsReady == XCOMPONENT_IS_READY);

    /*
     * Get the control register to determine which options are currently set.
     */
    ControlReg = XIo_In32(InstancePtr->BaseAddress + XOA_CR_OFFSET);

    /*
     * Loop through the options table to determine which options are set
     */
    for (Index = 0; Index < XOA_NUM_OPTIONS; Index++)
    {
        if (ControlReg & OptionsTable[Index].Mask)
        {
            OptionsFlag |= OptionsTable[Index].Option;
        }
    }

    return OptionsFlag;