www.beck-ipc.com

@CHIP-RTOS C Library V2.06 - CAN API


CAN_Set_Callback

Install a callback function to be called on specified event(s) within CAN interrupt service routine (ISR).

int CAN_Set_Callback ( unsigned int     port_idx,
                     CAN_ISR_CALLBACK vector,
                     unsigned int      events) ;

Parameters

port_idx

CAN port specifier:   CAN0_PORT = 0, or CAN1_PORT = 1

vector

User procedure address, or NULL to remove a callback previously installed.

events

Bit field specifying on which CAN events the callback should be made.

Return Value

Error code -
CAN_EC_SUCCESS = 0:   Success
CAN_EC_INVALID_PARAMS = -1:   port_idx invalid

Comments

This function either installs or removes a user callback procedure that is called from within the CAN driver's Interrupt Service Routine (ISR) upon specified events.   The vector argument can be set to NULL to remove existing vectors.   Note that the CAN_Close_Port will remove any callbacks established for the CAN port being closed.

The callback will be made from within the CAN driver's interrupt service routine, which has been registered with the RTX @Chip-RTOS.

The system maintains three independent callbacks for each CAN port:

  1. Receiver event callback:           CAN_CALLBACK_RX
  2. Transmit event callback:           CAN_CALLBACK_TX
  3. Bus off error event callback:     CAN_CALLBACK_ERR

The events argument determines which callbacks are set by this API.   The masks defined for this purpose in CAN_API.H are indicated above.   Combinations of these masks can be formed by OR'ing them together when it is desired that events share the same user callback.   For example, the CAN_CALLBACK_ALL mask will set all three callbacks to a single provided vector.

The set of three callbacks was implemented so that less logic is required inside the user callback to figure out why it had been called, when independent callback functions are used.   Note that all three transmit events are mapped to a single transmit callback.

The prototype for the user callback is as follows.

    void huge My_Callback(unsigned int event,
                        const CAN_MSG far *msg) ;

The event parameter in this callback will be a single bit that indicates the reason for the callback.   This bit is the same as used for the CAN_Event_Sleep() API's event masks, CAN0_EV_RX_RDY through CAN1_EV_BUS_OFF.   Note that which CAN channel the event occurred on is conveyed by this event bit.

The msg pointer argument passed to the bus error callback is always NULL.   No CAN message is associated with this callback.   For receive events, the msg pointer references the CAN message that was just received.   For transmit events, the msg pointer references the CAN message that just completed transmission.

The user callback function must preserve the DS, SS and SP registers.   All other registers the callback is free to modify.   The code within this callback must be keep to a minimum.   This callback is performed within the CAN interrupt service (except for possibly a first callback for transmit if transmitter was not currently operating at the CAN_Send() call).   Interrupts are masked on entry to the callback and must remain masked.   To encourage assembly language programming of this time critical callback, the parameters are also made available in registers:

  • CX - Contains the event parameter.

  • ES:DI - Contains the msg far pointer input parameter

These parameters are also pushed onto the stack to support a standard C language interface.

Inside this API the interrupts are masked for a short period and then re-enabled.   This function is reentrant.

Note:
    Use of callbacks may overload the system when CPU is operated in power save mode and CAN is operated at high baud rates.

See Also

RTOS API

This library function uses a dynamic link to reach the service offered by RTOS software interrupt.

Supported since or modified in @CHIP-RTOS version

    SC12SC13SC11SC1x3
    n/an/an/aV1.06

Supported by @CHIP-RTOS C Library since version

    CLIB
    V2.05

This API List
List of C Libraries
@CHIP-RTOS Main Index


End of document