/* can_api.c - WIND NET CAN API Library */

/* 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 defines the WIND NET CAN API, an interface for
implementations of CAN communications.

MACRO USE

For normal use, these routines are replaced by equivalent macro
definitions in CAN/wnCAN.h. To avoid namespace collisions in your
application code, or to implement a custom naming convention, you can
redefine the macro names. To dispense with the macro definitions and
use the function calls defined in this file, manually set the #define
USE_CAN_FUNCTION_DEFS in the header file CAN/wncan_api.h, then
recompile 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

/* subroutines */
/************************************************************************
* CAN_Open - get a handle to the requested WNCAN_DEVICE
*
* This is the first routine called. This routine 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 routine.
*
* 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
*
* This routine deallocates the 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 routine returns the mode of the channel:
* WNCAN_CHN_TRANSMIT, WNCAN_CHN_RECEIVE, WNCAN_CHN_INACTIVE, or
* 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.
*
* \ts
* 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 set up 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 set up to respond to an incoming remote request with the same identifier. On receiving such a frame, the response will be sent out automatically.
* \te
*
* 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 routine sets the mode of the channel to one of five values:
* WNCAN_CHN_TRANSMIT, WNCAN_CHN_RECEIVE, WNCAN_CHN_INACTIVE,
* WNCAN_CHN_RTR_REQUESTER, or WNCAN_CHN_RTR_RESPONDER.
* WNCAN_CHN_RTR_REQUESTER and WNCAN_CHN_RTR_RESPONDER are used for
* advanced controllers. 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 errno 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: 'OK', or 'ERROR' if the requested channel number is out of range.
*
* 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 routine returns the status of the CAN bus. The bus is
* either in a WNCAN_BUS_OFF, WNCAN_BUS_WARN, or WNCAN_BUS_OK state.
*
* \is
* \i 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.
*
* \i 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.
*
* \i 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.
* \ie
*
* 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 routine returns an \'OR\'ed bit mask of all the bus errors that have
* occurred during the last bus activity.
*
* Bus errors returned by this routine can have the following values:
*
* \ml
* \m -
* WNCAN_ERR_NONE: No errors detected.
* \m -
* WNCAN_ERR_BIT: Bit error.
* \m -
* WNCAN_ERR_ACK: Acknowledgement error.
* \m -
* WNCAN_ERR_CRC: CRC error.
* \m -
* WNCAN_ERR_FORM: Form error.
* \m -
* WNCAN_ERR_STUFF: Stuff error.
* \m -
* WNCAN_ERR_UNKNOWN: Unable to determine cause of error.
* \me
*
*
* The five errors are not mutually exclusive. The occurrence of an error
* will be indicated by an interrupt. Typically, this routine will be called
* from the error interrupt handling case in the user's ISR callback function,
* to find out the kind of error that occurred 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 controller
*
* This routine initializes the CAN controller and makes default selections.
*
* \ml
* \m 1.
* Puts the CAN controller into debug mode.
* \m 2.
* Disables interrupts at the CAN controller level as well as channel.
* \m 3.
* Sets bit timing values according to values stored in the CAN controller
* struct. Unless the user has changed these values before CAN_Init() is called,
* the default bit timing values are set to a baud rate of 250K.
* \m 4.
* Clears error counters.
* \m 5.
* Sets local and global receive masks to don't care (accept all).
* \m 6.
* Makes all channels inactive in hardware.
* \m 7.
* Other controller specific initializations.
* \m 8.
* On exiting the CAN_Init() routine, the CAN controller has been initialized,
* but is offline and unable to participate in CAN bus communication.
* \me
*
*
* CAN_Open() is called to obtain a valid device pointer. Subsequently,
* CAN_Init() and CAN_Open() are called to initialize the controller, bring
* it online, and enable active participation in CAN bus activity.
*
* RETURNS: 'OK'.
*
* ERRNO:   N/A
*/
STATUS CAN_Init
    (
    struct WNCAN_Device *pDev  /* CAN Device pointer */
    )
    {
       return(pDev->Init(pDev));
    }

/***************************************************************************
* CAN_Start - bring the CAN controller online
*
* This routine is called to bring the CAN controller online. The CAN
* controller can now participate in transmissions and receptions on the CAN
* bus. This routine must be called after CAN_Init() has been called to
* initialize and bring the CAN controller up in a known state. This routine
* 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 the CAN controller offline
*
* This routine disables communication between the CAN controller and the
* CAN bus.
*
* RETURNS: 'OK'.
*
* ERRNO: N/A
*
*/
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 routine sets the baud rate and sample point of the controller. The
* values of the input parameters should be based on an established set of
* recommendations.
*
* This routine sets the bit timing values in the hardware as well as the
* controller structure, so that the bit timing values are not lost if
* CAN_Init() is called again.
*
* The routine will preserve the state of the CAN controller.
* For example, if the CAN controller is online when the routine