can_api_by_wr.c

美国wind river 公司的CAN总线源代码

/* can_api.c - WindNet CAN API documentation. */

/* Copyright 1984-2001 Wind River Systems, Inc. */
#include "copyright_wrs.h"

/*
modification history
--------------------
01, 18Dec01, jac created
02, 7Jul02,  lsg modified
03, 20Aug02, lsg changed resulting from api review   
*/

/*
DESCRIPTION

This library provides functions to implement CAN communications using
the WindNet CAN API.

NOTE

For normal use, these functions are replaced by equivalent macro 
definitions in CAN/wnCAN.h. The user is free to redefine the macro names
in order to avoid namespace collisions in his application code, or to
implement a user-specific naming convention. The user may also dispense
with the macro definitions and use the function calls defined in this
file by manually setting the #define USE_CAN_FUNCTION_DEFS in the header
file CAN/wncan_api.h then recompiling the CAN library with the make utility.


INCLUDE FILES

CAN/wnCAN.h
CAN/canBoard.h

*/

/* includes */
#include <vxWorks.h>
#include <errnoLib.h>
#include <stdlib.h>
#include <string.h>
#include <CAN/wnCAN.h>
#include <CAN/canBoard.h>
#include <CAN/canController.h>

#ifdef USE_CAN_FUNCTION_DEFS

/* subfunctions */
/************************************************************************
* CAN_Open - return a handle to the requested WNCAN_DEVICE
* 
* This is the first function called. This function establishes links to the
* CAN controller specific API implementation. The CAN api cannot be
* accessed before the device pointer has been correctly initialized
* by this function.
*
* RETURNS: pointer to valid WNCAN_DEVICE, or 0 if an error occurred
*   
* ERRNO: S_can_unknown_board
*        S_can_illegal_board_no
*        S_can_illegal_ctrl_no
*        S_can_busy 
*
*/
struct WNCAN_Device *CAN_Open
(
    unsigned int brdType,   /* board type       */
    unsigned int brdNdx,    /* board index      */
    unsigned int ctrlNdx    /* controller index */
)
{
    return  WNCAN_Open(brdType, brdNdx, ctrlNdx);
}

/************************************************************************
* CAN_Close - close the handle to the requested WNCAN_DEVICE
*
* Deallocates device struct that is passed in. The links to the CAN 
* controller's api implementations do not exist after CAN_Close is called.
*
* RETURNS:N/A
*   
* ERRNO:  N/A
*        
*
*/

void CAN_Close
(
struct WNCAN_Device *pDev   /* CAN device pointer */
)
{
    WNCAN_Close(pDev);
}

/***************************************************************************   
* CAN_GetMode - get the current mode of the channel.
*
* This function returns the mode of the channel:
* WNCAN_CHN_TRANSMIT, WNCAN_CHN_RECEIVE, WNCAN_CHN_INACTIVE, WNCAN_CHN_INVALID
* For advanced controllers two additional modes exist:
* WNCAN_CHN_RTR_REQUESTER, or WNCAN_CHN_RTR_RESPONDER
* 
* The mode of the channel is relevant in software only, and is indirectly 
* related to the hardware capability (transmit,receive or both) of a channel 
* Mode        Function
* TRANSMIT    Transmits data frames. In case of simple controllers,this mode
*             can transmit a remote frame by calling CAN_SetRTR
* RECEIVE     Receives data frames. In case of simple controllers can
*             receive remote frames as well
* INVALID     Channel is available to the CAN driver, but is free and has not
*             been assigned a mode                                       
* INACTIVE    Channel is unavailable to the CAN driver
* RTR_REQUESTER Valid only for advanced controllers 
*             Channel is setup to send out a remote request and receives the 
*             response to the remote frame in the same hardware channel.
* RTR_RESPONDER Valid only for advanced controllers
*             Channel is setup to respond to an incoming remote request with 
*             the same identifier. On receiving such a frame, the response will
*             be sent out automatically   
*
* Note, if the channel has not been allocated by a previous call to
* CAN_SetMode(), CAN_GetTxChannel(), CAN_GetRxChannel(), 
* CAN_GetRTRResponderChannel() or CAN_GetRTRRequesterChannel().
* the return value will be WNCAN_CHN_INVALID even though the channel
* number is within the range of channels available on the
* controller.
*
* RETURNS: The channel mode
*
* ERRNO: N/A
*/
WNCAN_ChannelMode CAN_GetMode
(
struct WNCAN_Device *pDev, /* CAN Device pointer */
UCHAR chn                  /* device channel */
)
{
   return(WNCAN_GetMode(pDev, chn));
}

/***************************************************************************   
* CAN_SetMode - set the mode of the channel.
*
* This function sets the mode of the channel to one of five values:
* WNCAN_CHN_TRANSMIT, WNCAN_CHN_RECEIVE, WNCAN_CHN_INACTIVE, 
* and in addition for advanced controllers,
* WNCAN_CHN_RTR_REQUESTER, or WNCAN_CHN_RTR_RESPONDER.
* All available channels can be configured to be WNCAN_CHN_INACTIVE.
* The channels available for transmitting or receiving messages are
* determined by the device hardware, and therefore ,may or may not be
* configurable with this function call. If an attempt is made to set the mode 
* of a channel to WNCAN_CHN_RTR_RESPONDER or WNCAN_CHN_RTR_REQUESTER for a
* simple CAN controller such as SJA1000, WNCAN_CHN_INVALID is returned and an
* and errorno is set to reflect the error. 
* The preferred approach is to allow the device driver to manage the channels 
* internally using the CAN_GetTxChannel(), CAN_GetRxChannel(), 
* CAN_GetRTRRequesterChannel(), CAN_GetRTRResponderChannel() and
* CAN_FreeChannel() function calls.
*
* RETURNS: ERROR if the requested channel number is out of range,
           OK otherwise 
*
* ERRNO: S_can_illegal_channel_no
*/
STATUS CAN_SetMode
(
struct WNCAN_Device *pDev,    /* CAN device pointer */
UCHAR channelNum,             /* channel number */
WNCAN_ChannelMode mode        /* channel mode */
)
{
   return(WNCAN_SetMode(pDev,channelNum,mode));
}


/***************************************************************************   
* CAN_GetBusStatus - get the status of the CAN bus
*
* This function returns the status of the CAN bus. The bus is 
* either in a WNCAN_BUS_OFF, WNCAN_BUS_WARN, or WNCAN_BUS_OK state.
*
* WNCAN_BUS_OFF: CAN controller is in BUS OFF state
* A CAN node is bus off when the transmit error count is greater than
* or equal to 256
* WNCAN_BUS_WARN: CAN controller is in ERROR PASSIVE state
* A CAN node is in error warning state when the number of transmit errors
* equals or exceeds 128, or the number of receive errors equals or exceeds
* 128
* WNCAN_BUS_OK: CAN controller is in ERROR ACTIVE state
* A CAN node in error active state can normally take part in bus communication
* and sends an ACTIVE ERROR FLAG when an error has been detected. 
*
* RETURNS: the status of the CAN bus
*
* ERRNO:   N/A
*/
WNCAN_BusStatus CAN_GetBusStatus
(
 struct WNCAN_Device *pDev  /* CAN Device pointer */
)
{
   return (pDev->GetBusStatus(pDev));
}

/***************************************************************************
* CAN_GetBusError - get the bus errors
*
* This function returns an ORed bit mask of all the bus errors that have
* occured during the last bus activity.
* Bus errors returned by this function can have the following values:
* WNCAN_ERR_NONE: No errors detected
* WNCAN_ERR_BIT: Bit error. 
* WNCAN_ERR_ACK: Acknowledgement error. 
* WNCAN_ERR_CRC: CRC error
* WNCAN_ERR_FORM: Form error
* WNCAN_ERR_STUFF: Stuff error
* WNCAN_ERR_UNKNOWN: this condition should not occur
* The five errors are not mutually exclusive. 
* The occurence of an error will be indicated by an interrupt. Typically, 
* this function will be called from the error interrupt handling case in the
* user's ISR callback function, to find out the kind of error that occured
* on the bus.
*
* RETURNS: an 'OR'ed bit mask of all the bus errors
*
* ERRNO: S_can_Unknown_error
*/
WNCAN_BusError CAN_GetBusError
(
struct WNCAN_Device *pDev  /* CAN Device pointer */
)
{
   return(pDev->GetBusError(pDev));
}

/***************************************************************************   
* CAN_Init - initialize the CAN device
*
* This function initializes the CAN controller and makes default selections.
* 1. Puts the CAN controller into debug mode
* 2. Disables interrupts at the CAN controller level as well as channel 
* 3. Sets bit timing values according to values stored in the CAN controller
*    struct. Unless the user has changed these value, before init is called 
*    the default bit timing values are set to a baud rate of 250K
* 4. Clears error counters
* 5. Sets local and global receive masks to don't care (accept all)
* 6. Makes all channels inactive in hardware
* 7. Other controller specific initializations 
* 8. Before exiting the function, controller is brought of reset mode
*    (where relevant) but clocks are not enabled. The CAN controller has
*    now been initialized but will not participate in CAN bus communication
* In order to bring the CAN controller online, and enable active participation
* in CAN bus activity, CAN_Start must be called following CAN_Init.
*
* The user must call CAN_Init, subsequently followed by CAN_Start,
* after CAN_Open is called to obtain a valid device pointer. 
* In case of a bus off condition, user must call CAN_Init followed by CAN_Start
* to reinitialize and bring the CAN controller online again.
*
* RETURNS: OK
*
* ERRNO:   N/A
*/
STATUS CAN_Init
(
struct WNCAN_Device *pDev  /* CAN Device pointer */
)
{
   return(pDev->Init(pDev));
}

/***************************************************************************   
* CAN_Start - Bring CAN controller online
*
* This function is called to bring the CAN controller online. The CAN controller
* can now participate in transmissions and receptions on the CAN bus.
* This function must be called after CAN_Init has been called to initialize and
* bring the CAN controller up in a known state.
* This function negates the INIT/HALT (offline) bit.
*
* RETURNS: OK
*
*/
void CAN_Start
(
struct WNCAN_Device *pDev  /* CAN Device pointer */
)
{
   return(pDev->Start(pDev));
}

/***************************************************************************   
* CAN_Stop - Put CAN controller offline
*
* Disables communication between CAN controller and the CAN bus
*
* RETURNS: OK
*
*/
void CAN_Stop
(
struct WNCAN_Device *pDev  /* CAN Device pointer */
)
{
   return(pDev->Stop(pDev));
}

/***************************************************************************   
* CAN_SetBitTiming - set the bit timing parameters of the controller
*
* This function sets the baud rate of the controller. The selection
* of the input parameters should be based on an established set of 
* recommendations for the particular application.
* This function sets the bit timing values in the hardware as well as the
* controller structure, so that the bit timing values are not lost if Init
* is called again. The function will preserve the state of the CAN controller.
* i.e. if the CAN controller is online when the function is called, then the 
* CAN controller will be online when the function exits. 
*
* bit time = 1 + (tseg1 + 1) + (tseg2+1) time quanta 
* The interpretation of tseg1 are tseg2 are according to the controller's 
* definition and hence can be written to directly using this function.
*
* In all cases so far, tseg2 refers to the segment of bit time after the sample
* point. However, in some controllers tseg1 refers to the segment of bit time
* after the end of sync seg upto the sample point.                     
*  ---------------------------------------------------------
* |    |                    |                              |  
*  sync <--------tseg1 --->^|^<---------tseg2 ------------->
*                          sample point 
*