@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:
- Receiver event callback: CAN_CALLBACK_RX
- Transmit event callback: CAN_CALLBACK_TX
- 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-
SC12 | SC13 | SC11 | SC1x3 |
-
n/a | n/a | n/a | V1.06 |
Supported by @CHIP-RTOS C Library since version
This API List
List of C Libraries
@CHIP-RTOS Main Index
End of document
|