boardchangecli.c

dsp DM642 pci 详细的开发例程

// BoardChangeCLI.c
//////////////////////////////////////////////////////////////////////////////
////
////  Copyright (c) 2003, Valley Technologies, Inc.
////  All rights reserved.
////
//////////////////////////////////////////////////////////////////////////////
////
////  $Header $
////
////  $ReleaseClass: src $
////
////  Original Author                 : ebersole
////  Most Recent Contributing $Author: ebersole $
////
//////////////////////////////////////////////////////////////////////////////
////
////  This file contains the CLI routines necessary to open, close, change,
////    and find DM642 cards.  The routines in this file interact with the
////    user to obtain certain information.  The routines pass this info
////    on into the DM642 Library, which does the lower-level dirty work.
////
//////////////////////////////////////////////////////////////////////////////


//############################################################################


// Includes
#include <stdio.h>
#include <dm642_lib.h>
#include "Dm642Cli.h"


//############################################################################
//                        Static (PRIVATE) Functions
//############################################################################


//////////////////////////////////////////////////////////////////////////////
////
////  Name: getVendorAndDeviceIDsFromUser
////
////  Purpose: This routine gets the Vendor ID and Device ID (of a PCI
////           device) from the user.
////
////  Input Parameters: none
////
////  Output Parameters:
////      pdwVendorID -- The PCI Vendor ID that the user entered
////      pdwDeviceID -- The PCI Device ID that the user entered
////
////  Return Value(s):
////      -1 => ERROR => invalid Vendor ID from user
////                     If this value is returned, none of the output
////                     parameters will be set/changed.
////       0 => SUCCESS
////
//////////////////////////////////////////////////////////////////////////////

static int getVendorAndDeviceIDsFromUser( DWORD *pdwVendorID,
                                          DWORD *pdwDeviceID )
{
    char  line[80];
    DWORD dwVendorID, dwDeviceID;


    printf ("Enter VendorID: ");

    fgets (line, sizeof(line), stdin);
    sscanf(line, "%x",         &dwVendorID);

    if (dwVendorID == 0)
    {
        return (-1);
    }

    printf ("Enter DeviceID: ");

    fgets (line, sizeof(line), stdin);
    sscanf(line, "%x",         &dwDeviceID);

    *pdwVendorID = dwVendorID;
    *pdwDeviceID = dwDeviceID;

    return (0);

}       // END getVendorAndDeviceIDsFromUser()

//////////////////////////////////////////////////////////////////////////////


//////////////////////////////////////////////////////////////////////////////
////
////  Name: getCardNumberFromUser
////
////  Purpose: This routine gets, from user, the number of the DM642 card
////           to use/activate.  An invalid choice by the user causes the
////           routine to return a default selection of '0'.
////
////  Input Parameters:
////      nNumCards -- Total number of DM642 cards found by the most recent
////                   scan of the PCI bus.
////
////  Output Parameters: none
////
////  Return Value(s):
////       0                 Either card #0 was selected, or a bad selection
////                         resulted in an auto-select of card #0
////       1..(nNumCards-1)  The number of the card selectd by the user.
////
//////////////////////////////////////////////////////////////////////////////

static DWORD getCardNumberFromUser(DWORD nNumCards)
{
    char  line[80];
    DWORD nMyCard;


    //--------------------------------------
    // Prompt the user to select a card #
    //--------------------------------------
    printf ("Found %u matching PCI cards\n", (UINT)nNumCards);
    printf ("Select card (0-%u): ",          (UINT)nNumCards - 1);

    //----------------------------------
    // Flush/Clean the input 'buffers'
    //----------------------------------
    nMyCard = 0;
    fflush(stdin);

    //-------------------------
    // Get the card # ...
    //-------------------------
    fgets (line, sizeof(line), stdin);
    sscanf(line, "%d",         &nMyCard);

    //---------------------------------------------
    // Verify that the user's choice is valid
    //   If so, return that choice to the caller
    //---------------------------------------------
    if ((nMyCard >= 0) && (nMyCard < nNumCards))
    {
        return(nMyCard);
    }

    printf ("Choice is out of range\n");

    //------------------------------------------------
    // If the user selects an invalid card, use
    //   card #0 as his/her selection.
    //------------------------------------------------
    return (0);

}       // End getCardNumberFromUser()

//////////////////////////////////////////////////////////////////////////////


//////////////////////////////////////////////////////////////////////////////
////
////  Name: DM642LocateBoard
////
////  Purpose: This routine determines which DM642 card to use/activate.
////           It will get input from the user, as necesary.
////
////  Input Parameters:
////      pdwVendorID -- The PCI Vendor ID to locate
////                     [if 0, user is prompted for a VID+DID]
////      pdwDeviceID -- The PCI Device ID to locate
////                     [undefined if pdwVendorID == NULL/0]
////
////  Output Parameters:
////      pdwVendorID -- PCI Vendor ID, as entered by the user
////      pdwDeviceID -- PCI Device ID, as entered by the user
////
////  Return Value(s):
////       < 0: ERROR
////      >= 0: The number of the card to use/activate
////
//////////////////////////////////////////////////////////////////////////////

static DWORD DM642LocateBoard(DWORD *pdwVendorID, DWORD *pdwDeviceID)
{
    DWORD  nNumCards,
           nCardSelected;


    //------------------------------------------------------------------------
    // If an invalid Vendor ID was entered, then get BOTH the Vendor ID and
    //   the Device ID from the user.
    //------------------------------------------------------------------------
    if (pdwVendorID == NULL || *pdwVendorID == 0)
    {
        if (getVendorAndDeviceIDsFromUser(pdwVendorID, pdwDeviceID) < 0)
        {
            // ERROR -- invalid VID or DID ...
            return (-1);
        }
    }

    //---------------------------------------------------------------
    // Count the number of cards in the chassis that have the given 
    //   VID & DID combo ...
    //---------------------------------------------------------------
    nNumCards = DM642CountCards (*pdwVendorID, *pdwDeviceID);

    //-----------------------------------------
    // Not finding any cards is an error ...
    //-----------------------------------------
    if (nNumCards == 0)
    {
        printf ("%s", DM642_ErrorString);
        return (-1);
    }

    //---------------------------------------------------
    // Finding one card makes choosing superfluous ...
    //---------------------------------------------------
    if (nNumCards == 1)
    {
        return (0);
    }

    //---------------------------------------------------
    // Finding more than one card requires the user to
    //   choose which one to use/activate
    //---------------------------------------------------
    nCardSelected = getCardNumberFromUser(nNumCards);

    return (nCardSelected);

}       // END DM642LocateBoard()


//############################################################################
//                        Non-Static (PUBLIC) Functions
//############################################################################


//////////////////////////////////////////////////////////////////////////////
////
////  Name: DM642OpenBoard
////
////  Purpose: Opens/Activates the given DM642 board.  If this fails,
////           the routine prints an error message.
////
////  Input Parameters:
////      pdwVendorID -- The PCI Vendor ID of the DM642 board to open/enable
////      pdwDeviceID -- The PCI Device ID of the DM642 board to open/enable
////      dwBoardNum  -- The number of the DM642 board to open/enable
////
////  Output Parameters: none
////
////  Return Value(s):
////      NULL    : ERROR opening the card
////      non-NULL: Handle to the DM642 board just opened
////
//////////////////////////////////////////////////////////////////////////////

DM642_HANDLE DM642OpenBoard(DWORD dwVendorID, DWORD dwDeviceID, DWORD dwBoardNum)
{
    DM642_HANDLE hDM642 = NULL;


    //----------------------------------------------------------------------
    // Attempt to open the indicated DM642.
    // If this fails, print an error message (constructed inside the DM642
    //   library) and bail.
    //----------------------------------------------------------------------
    if (!DM642Open (&hDM642, dwVendorID, dwDeviceID, dwBoardNum))
    {
        printf ("%s", DM642_ErrorString);
        return (NULL);
    }

    printf ("DM642 PCI card opened!\n");

    //--------------------------------------------------------
    // If we do open the DM642 successfully, set our global
    //   board-number constant to the open card's number
    //--------------------------------------------------------
    g_dwBoardNum = dwBoardNum;

    return (hDM642);

}       // END DM642OpenBoard()

//////////////////////////////////////////////////////////////////////////////


//////////////////////////////////////////////////////////////////////////////
////
////  Name: DM642CloseBoard
////
////  Purpose: This routine closes/deactivates an open DM642 card.
////           The occurs iff the given card is already open.
////
////  Input Parameters:
////      phDM642 - POINTER to handle of currently-open DM642 board
////
////  Output Parameters:
////      phDM642 - POINTER to handle of a DM642 board
////                Will be set to NULL.
////
////  Return Value(s)  : none
////
//////////////////////////////////////////////////////////////////////////////

void DM642CloseBoard(DM642_HANDLE *phDM642)
{
    if (*phDM642 != NULL)
    {
        DM642Close(*phDM642);
    }

    *phDM642     = NULL;
    g_dwBoardNum = -1;

}       // End DM642CloseBoard()

//////////////////////////////////////////////////////////////////////////////


//////////////////////////////////////////////////////////////////////////////
////
////  Name: ChangeBoard
////
////  Purpose: This routine changes the currently active/open DM642 to a
////           different one.  Any necessary info is obtained from the user.
////           If no boards are open, this routine will just open the newly
////           selected DM642 (ie, it can be used at boot/init)
////
////  Input Parameters:
////      phDM642     - POINTER to handle of currently-open DM642 board
////      pdwVendorID - The PCI Vendor ID of the board to change to
////      pdwDeviceID - The PCI Device ID of the board to change to
////
////  Output Parameters:
////      phDM642 - POINTER to handle of a DM642 board
////                NULL     if opening a new board fails
////                non-NULL (valid board handle) otherwise
////
////  Return Value(s):
////      -1 : ERROR     (either invalid input OR board-open failed)
////       0 : SUCCESS
////
//////////////////////////////////////////////////////////////////////////////

int ChangeBoard(DM642_HANDLE *phDM642, DWORD dwVendorID, DWORD dwDeviceID)
{
    DWORD dwBoardNum;


    ///--------------------------------------
    // Determine which DM642 to switch to.
    ///--------------------------------------
    dwBoardNum = DM642LocateBoard(&dwVendorID, &dwDeviceID);

    //------------------------------------------------------------------------
    // If an error (including invalid user input) occurred while determining
    //  the new board number to use, bail w/o changing a thing.
    //------------------------------------------------------------------------
    if (dwBoardNum < 0)
    {
        return (-1);
    }

    //----------------------------------------------------------
    // ASSERT: dwBoardNum (newly selected board number) >= 0
    //         IE, the new board number is valid.
    //----------------------------------------------------------

    //------------------------------------------------------------
    // Skip the Close()-then-Open() sequence if we actually are
    //   not changing boards.  We already have the desired board
    //   opened, in that case.
    //------------------------------------------------------------
    if (g_dwBoardNum == dwBoardNum)
    {
        return (0);
    }

    //--------------------------------------------
    // Close the old board and Open the new one
    //--------------------------------------------
    DM642CloseBoard(phDM642);
    *phDM642 = DM642OpenBoard(dwVendorID, dwDeviceID, dwBoardNum);
    if (NULL == *phDM642)
    {
        return (-1);
    }

    return (0);

}       // END ChangeBoard()


//############################################################################
//                             End of Functions
//############################################################################