This file is part of CAN/CAN FD bus common support and implements CAN FIFOs and generic hubs/ends for chip and caracter driver interface sides. More...

#include <stdatomic.h>
#include <inttypes.h>
#include <sys/queue.h>
#include <rtems.h>
#include <rtems/timespec.h>
#include <rtems/status-checks.h>
#include <rtems/thread.h>
#include <dev/can/can-frame.h>
#include <dev/can/can-filter.h>

Data Structures
struct	rtems_can_queue_slot
	This structure represents one CAN message slot in the CAN FIFO queue. More...

struct	rtems_can_queue_fifo
	This structure represents CAN FIFO queue. It is implemented as a single linked list of slots prepared for processing. The empty slots are stored in single linked list. More...

struct	rtems_can_queue_edge
	This structure represents one direction connection from messages source ( input_ends) to message consumer ( output_ends) fifo ends hub. The edge contains rtems_can_queue_fifo for message fifo implementation-. More...

struct	rtems_can_queue_ends
	This structure represents place to connect edges to for CAN communication entity. The zero, one or more incoming and outgoing edges can be connected to this structure. More...

Macros
#define	RTEMS_CAN_SLOTF_CMD ( 0x00ff )
	Macro for command associated with allocated slot.

#define	RTEMS_CAN_FIFOF_DESTROY ( 1 << 15 )
	This is set when FIFO is scheduled for destruction.

#define	RTEMS_CAN_FIFOF_ERROR ( 1 << 14 )
	This is set when some error condition occurs.

#define	RTEMS_CAN_FIFOF_ERR2BLOCK ( 1 << 13 )
	This defines that error should lead to the FIFO block state.

#define	RTEMS_CAN_FIFOF_BLOCK ( 1 << 12 )
	This state blocks insertion of the next messages.

#define	RTEMS_CAN_FIFOF_OVERRUN ( 1 << 11 )
	This indicates attempt to acquire new slot, when FIFO is full.

#define	RTEMS_CAN_FIFOF_FULL ( 1 << 10 )
	This indicates FIFO full state.

#define	RTEMS_CAN_FIFOF_EMPTY ( 1 << 9 )
	This indicates no allocated slot in the FIFO.

#define	RTEMS_CAN_FIFOF_DEAD ( 1 << 8 )
	This is used when FIFO is beeing destroyed.

#define	RTEMS_CAN_FIFOF_INACTIVE ( 1 << 7 )
	This indicates FIFO is inactive.

#define	RTEMS_CAN_FIFOF_FREEONEMPTY ( 1 << 6 )
	This indicates FIFO was freed when being empty.

#define	RTEMS_CAN_FIFOF_READY ( 1 << 5 )
	This indicates FIFO is ready.

#define	RTEMS_CAN_FIFOF_NOTIFYPEND ( 1 << 4 )
	This indicates pending notification.

#define	RTEMS_CAN_QUEUE_NOTIFY_EMPTY ( 1 )
	out-> in all slots are processed by FIFO out side.

#define	RTEMS_CAN_QUEUE_NOTIFY_SPACE ( 2 )
	out -> in - full state negated => there is space for new message.

#define	RTEMS_CAN_QUEUE_NOTIFY_PROC ( 3 )
	out -> in - full state negated => there is space for new message.

#define	RTEMS_CAN_QUEUE_NOTIFY_NOUSR ( 4 )
	Notify, that the last user has released the edge usage called with some lock to prevent edge disappear.

#define	RTEMS_CAN_QUEUE_NOTIFY_DEAD ( 5 )
	Edge is in progress of deletion.

#define	RTEMS_CAN_QUEUE_NOTIFY_DEAD_WANTED ( 6 )
	Edge should be deleted.

#define	RTEMS_CAN_QUEUE_NOTIFY_ATTACH ( 7 )
	Edge is in progress of deletion.

Functions
int	rtems_can_queue_fifo_flush_slots (struct rtems_can_queue_fifo *fifo)
	This function frees all ready slots from the FIFO.

int	rtems_can_queue_fifo_init_slots (struct rtems_can_queue_fifo *fifo)
	This function initializes slot chain of one CAN FIFO.

	TAILQ_HEAD (rtems_can_queue_edges_list, rtems_can_queue_edge)

	TAILQ_HEAD (rtems_can_queue_ends_list, rtems_can_queue_ends)

int	rtems_can_queue_get_inslot (struct rtems_can_queue_ends qends, struct rtems_can_queue_edge qedgep, struct rtems_can_queue_slot *slotp, int cmd)
	This function finds one outgoing edge and allocates slot from it.

int	rtems_can_queue_get_inslot_for_prio (struct rtems_can_queue_ends qends, struct rtems_can_queue_edge qedgep, struct rtems_can_queue_slot slotp, const struct can_frame_header header, int cmd, int prio)
	This function finds best outgoing edge and slot for given priority.

int	rtems_can_queue_test_inslot (struct rtems_can_queue_ends *qends)
	This function tests whether there is a free space in any outgoing edge.

int	rtems_can_queue_put_inslot (struct rtems_can_queue_ends qends, struct rtems_can_queue_edge qedge, struct rtems_can_queue_slot *slot)
	This function schedules filled slot for processing.

int	rtems_can_queue_abort_inslot (struct rtems_can_queue_ends qends, struct rtems_can_queue_edge qedge, struct rtems_can_queue_slot *slot)
	This function aborts preparation of the message in the slot.

int	rtems_can_queue_filter_frame_to_edges (struct rtems_can_queue_ends qends, struct rtems_can_queue_edge src_edge, struct can_frame *frame, unsigned int flags2add)
	This function sends message into all edges which accept its ID.

int	rtems_can_queue_test_outslot (struct rtems_can_queue_ends qends, struct rtems_can_queue_edge qedgep, struct rtems_can_queue_slot *slotp)
	This function tests and retrieves ready slot for given ends.

int	rtems_can_queue_pending_outslot_prio (struct rtems_can_queue_ends *qends, int prio_min)
	This function tests ready outslot with minimum priority.

int	rtems_can_queue_free_outslot (struct rtems_can_queue_ends qends, struct rtems_can_queue_edge qedge, struct rtems_can_queue_slot *slot)
	This function frees processed output slot.

int	rtems_can_queue_push_back_outslot (struct rtems_can_queue_ends qends, struct rtems_can_queue_edge qedge, struct rtems_can_queue_slot *slot)
	This function reschedules output slot to process it again later.

int	rtems_can_queue_flush (struct rtems_can_queue_edge *qedge)
	This function flushes all ready slots in the edge.

int	rtems_can_queue_disconnect_edge (struct rtems_can_queue_edge *qedge)
	This function disconnects edge from communication entities.

int	rtems_can_queue_connect_edge (struct rtems_can_queue_edge qedge, struct rtems_can_queue_ends input_ends, struct rtems_can_queue_ends *output_ends)
	This function connects edge between two communication entities.

int	rtems_can_queue_ends_init (struct rtems_can_queue_ends *qends)
	This function implements subsystem independent routine to initialize ends state.

void	rtems_can_queue_block_inlist (struct rtems_can_queue_ends *qends)
	This function blocks slot allocation of all outgoing edges of specified ends.

void	rtems_can_queue_block_outlist (struct rtems_can_queue_ends *qends)
	This function blocks slot allocation of all incoming edges of specified ends.

int	rtems_can_queue_ends_kill_inlist (struct rtems_can_queue_ends *qends, int send_rest)
	This function sends request to die to all outgoing edges.

int	rtems_can_queue_ends_kill_outlist (struct rtems_can_queue_ends *qends)
	This function sends request to die to all incomming edges.

int	rtems_can_queue_ends_flush_inlist (struct rtems_can_queue_ends *qends)
	This function flushes all messages in incoming edges.

int	rtems_can_queue_ends_flush_outlist (struct rtems_can_queue_ends *qends)
	This function flushes all messages in outgoing edges.

void	rtems_can_queue_do_edge_decref (struct rtems_can_queue_edge *edge)
	This function decrements the edge user counter.

void	rtems_can_queue_edge_do_dead (struct rtems_can_queue_edge *qedge)
	This function disconnects the edge.

int	rtems_can_queue_fifo_init_kern (struct rtems_can_queue_fifo *fifo, int allocated_slot_count, int max_data_length)
	This function initializes one CAN FIFO.

int	rtems_can_queue_fifo_done_kern (struct rtems_can_queue_fifo *fifo)
	This function frees slots allocated for CAN FIFO.

struct rtems_can_queue_edge *	rtems_can_queue_new_edge_kern (int allocated_slot_countm, int max_data_length)
	This function allocates new edge structure.

int	rtems_can_queue_ends_sync_all_kern (struct rtems_can_queue_ends qends, struct timespec ts)
	This function waits for all ends to TX their messages.

int	rtems_can_queue_sync_wait_kern (struct rtems_can_queue_ends qends, struct rtems_can_queue_edge qedge, bool nowait, rtems_interval timeout)
	This function waits for all slots processing.

int	rtems_can_queue_ends_dispose_kern (struct rtems_can_queue_ends *qends, bool nonblock)
	This function provides finalizing of the ends structure for clients.

int	rtems_can_queue_kern_initialize (void)
	This function provides initialization of kernel queue side.

Detailed Description

This file is part of CAN/CAN FD bus common support and implements CAN FIFOs and generic hubs/ends for chip and caracter driver interface sides.

Implementation is based on original LinCAN - Linux CAN bus driver Part of OrtCAN project https://ortcan.sourceforge.net/

Function Documentation

◆ rtems_can_queue_abort_inslot()

int rtems_can_queue_abort_inslot	(	struct rtems_can_queue_ends *	qends,
		struct rtems_can_queue_edge *	qedge,
		struct rtems_can_queue_slot *	slot
	)

This function aborts preparation of the message in the slot.

Frees slot previously acquired by rtems_can_queue_get_inslot or rtems_can_queue_get_inslot_for_prio function call. Used when message copying into slot fails.

Parameters

qends	Ends structure belonging to calling communication object.
qedge	Edge the slot belongs to.
slot	Pointer to the preprared slot.

Returns: Positive value informs, that queue full state has been negated.

◆ rtems_can_queue_block_inlist()

void rtems_can_queue_block_inlist ( struct rtems_can_queue_ends * qends )

This function blocks slot allocation of all outgoing edges of specified ends.

Parameters

qends Pointer to ends structure.

Returns: None.

◆ rtems_can_queue_block_outlist()

void rtems_can_queue_block_outlist ( struct rtems_can_queue_ends * qends )

This function blocks slot allocation of all incoming edges of specified ends.

Parameters

qends Pointer to ends structure.

Returns: None.

◆ rtems_can_queue_connect_edge()

int rtems_can_queue_connect_edge	(	struct rtems_can_queue_edge *	qedge,
		struct rtems_can_queue_ends *	input_ends,
		struct rtems_can_queue_ends *	output_ends
	)

This function connects edge between two communication entities.

Parameters

qedge	Pointer to edge.
input_ends	Pointer to ends the input of the edge should be connected to.
output_ends	Pointer to ends the output of the edge should be connected to.

Returns: Negative value informs about failed operation.

◆ rtems_can_queue_disconnect_edge()

int rtems_can_queue_disconnect_edge ( struct rtems_can_queue_edge * qedge )

This function disconnects edge from communication entities.

Parameters

qedge Pointer to edge.

Returns: Negative value means, that edge is used by somebody other and cannot be disconnected. Operation has to be delayed.

◆ rtems_can_queue_do_edge_decref()

void rtems_can_queue_do_edge_decref ( struct rtems_can_queue_edge * edge )

This function decrements the edge user counter.

Parameters

qedge Pointer to the edge to be disconnected.

Returns: None

◆ rtems_can_queue_edge_do_dead()

void rtems_can_queue_edge_do_dead ( struct rtems_can_queue_edge * qedge )

This function disconnects the edge.

Parameters

qedge Pointer to the edge to be disconnected.

Returns: None

◆ rtems_can_queue_ends_dispose_kern()

int rtems_can_queue_ends_dispose_kern	(	struct rtems_can_queue_ends *	qends,
		bool	nonblock
	)

This function provides finalizing of the ends structure for clients.

Parameters

qends	Pointer to ends structure.
nonblock	Flag indicating that user does not want to wait for processing of all remaining messages.

Returns: Function should be designed such way to not fail.

◆ rtems_can_queue_ends_flush_inlist()

int rtems_can_queue_ends_flush_inlist ( struct rtems_can_queue_ends * qends )

This function flushes all messages in incoming edges.

Parameters

qends pointer to ends structure

Return Value: Negative value informs about unsuccessful result

◆ rtems_can_queue_ends_flush_outlist()

int rtems_can_queue_ends_flush_outlist ( struct rtems_can_queue_ends * qends )

This function flushes all messages in outgoing edges.

Parameters

qends Pointer to ends structure.

Returns: Negative value informs about unsuccessful result.

◆ rtems_can_queue_ends_init()

int rtems_can_queue_ends_init ( struct rtems_can_queue_ends * qends )

This function implements subsystem independent routine to initialize ends state.

Parameters

qends Pointer to the end.

Returns: This fucntion cannot fail.

◆ rtems_can_queue_ends_kill_inlist()

int rtems_can_queue_ends_kill_inlist	(	struct rtems_can_queue_ends *	qends,
		int	send_rest
	)

This function sends request to die to all outgoing edges.

Parameters

qends	Pointer to ends structure.
send_rest	Select, whether already allocated slots should be processed by FIFO output side.

Returns: Non-zero value means, that not all edges could be immediately disconnected and that ends structure memory release has to be delayed.

◆ rtems_can_queue_ends_kill_outlist()

int rtems_can_queue_ends_kill_outlist ( struct rtems_can_queue_ends * qends )

This function sends request to die to all incomming edges.

Parameters

qends Pointer to ends structure.

Returns: Non-zero value means, that not all edges could be immediately disconnected and that ends structure memory release has to be delayed.

◆ rtems_can_queue_ends_sync_all_kern()

int rtems_can_queue_ends_sync_all_kern	(	struct rtems_can_queue_ends *	qends,
		struct timespec *	ts
	)

This function waits for all ends to TX their messages.

Parameters

qends	Pointer to ends structure.
ts	Absolute time againts CLOCK_MONOTONIC that informs rtems_can_queue_sync_wait_kern how long to wait.

Returns: 0 on success, -ETIME in case of timeout.

◆ rtems_can_queue_fifo_done_kern()

int rtems_can_queue_fifo_done_kern ( struct rtems_can_queue_fifo * fifo )

This function frees slots allocated for CAN FIFO.

Parameters

fifo	Pointer to the FIFO structure.

Returns: This function should not fail.

◆ rtems_can_queue_fifo_flush_slots()

int rtems_can_queue_fifo_flush_slots ( struct rtems_can_queue_fifo * fifo )

This function frees all ready slots from the FIFO.

The caller should be prepared to handle situations, when some slots are held by input or output side slots processing. These slots cannot be flushed or their processing interrupted.

Parameters

fifo	Pointer to the FIFO structure.

Returns: The nonzero value indicates that queue has not been empty before the function call.

◆ rtems_can_queue_fifo_init_kern()

int rtems_can_queue_fifo_init_kern	(	struct rtems_can_queue_fifo *	fifo,
		int	allocated_slot_count,
		int	max_data_length
	)

This function initializes one CAN FIFO.

Parameters

fifo	Pointer to the FIFO structure.
allocated_slot_count	Number of requested slots.
max_data_length	Maximum size of data in one slot/frame.

Returns: The negative value indicates, that there is no memory to allocate space for the requested number of the slots.

◆ rtems_can_queue_fifo_init_slots()

int rtems_can_queue_fifo_init_slots ( struct rtems_can_queue_fifo * fifo )

This function initializes slot chain of one CAN FIFO.

The caller should be prepared to handle situations, when some slots are held by input or output side slots processing. These slots cannot be flushed or their processing interrupted.

Parameters

fifo	Pointer to the FIFO structure.

Returns: The negative value indicates that there is no memory to allocate space for the requested number of the slots.

◆ rtems_can_queue_filter_frame_to_edges()

int rtems_can_queue_filter_frame_to_edges	(	struct rtems_can_queue_ends *	qends,
		struct rtems_can_queue_edge *	src_edge,
		struct can_frame *	frame,
		unsigned int	flags2add
	)

This function sends message into all edges which accept its ID.

Sends message to all outgoing edges connected to the given ends, which accepts message communication ID.

Parameters

qends	Ends structure belonging to calling communication object
src_edge	Optional source edge for echo detection
frame	Pointer to CAN frame.
flags2add	Optional additional CAN Frame flags.

Returns: Returns number of edges message has been send to.

◆ rtems_can_queue_flush()

int rtems_can_queue_flush ( struct rtems_can_queue_edge * qedge )

This function flushes all ready slots in the edge.

Tries to flush all allocated slots from the edge, but there could exist some slots associated to edge which are processed by input or output side and cannot be flushed at this moment

Parameters

qedge Pointer to the edge.

Returns: The nonzero value indicates, that queue has not been empty before the function call

◆ rtems_can_queue_free_outslot()

int rtems_can_queue_free_outslot	(	struct rtems_can_queue_ends *	qends,
		struct rtems_can_queue_edge *	qedge,
		struct rtems_can_queue_slot *	slot
	)

This function frees processed output slot.

Function releases processed slot previously acquired by rtems_can_queue_test_outslot function call.

Parameters

qends	Ends structure belonging to calling communication object.
qedge	Edge the slot belongs to.
slot	Pointer to the processed slot.

Returns: Informs if input side has been notified to know about change of edge state

◆ rtems_can_queue_get_inslot()

int rtems_can_queue_get_inslot	(	struct rtems_can_queue_ends *	qends,
		struct rtems_can_queue_edge **	qedgep,
		struct rtems_can_queue_slot **	slotp,
		int	cmd
	)

This function finds one outgoing edge and allocates slot from it.

Function looks for the first non-blocked outgoing edge in @qends structure and tries to allocate slot from it.

Parameters

qends	Ends structure belonging to calling communication object.
qedgep	Place to store pointer to found edge.
slotp	Place to store pointer to allocated slot.
cmd	Command type for slot.

Returns: If there is no usable edge or there is no free slot in edge negative value is returned.

◆ rtems_can_queue_get_inslot_for_prio()

int rtems_can_queue_get_inslot_for_prio	(	struct rtems_can_queue_ends *	qends,
		struct rtems_can_queue_edge **	qedgep,
		struct rtems_can_queue_slot **	slotp,
		const struct can_frame_header *	header,
		int	cmd,
		int	prio
	)

This function finds best outgoing edge and slot for given priority.

Function looks for the non-blocked outgoing edge accepting messages with given ID. If edge is found, slot is allocated from that edge. The edges with non-zero mask are preferred over edges open to all messages. If more edges with mask accepts given message ID, the edge with highest priority below or equal to required priority is selected.

Parameters

qends	Ends structure belonging to calling communication object.
qedgep	Place to store pointer to found edge.
slotp	Place to store pointer to allocated slot.
cmd	Command type for slot.
can_frame_header	Pointer to CAN frame header.
prio	Optional priority of message,

Returns: If there is no usable edge or there is no free slot in edge negative value is returned.

◆ rtems_can_queue_kern_initialize()

int rtems_can_queue_kern_initialize ( void )

This function provides initialization of kernel queue side.

Returns: Zero on success.

◆ rtems_can_queue_new_edge_kern()

struct rtems_can_queue_edge * rtems_can_queue_new_edge_kern	(	int	allocated_slot_countm,
		int	max_data_length
	)

This function allocates new edge structure.

Parameters

allocated_slot_count	Required number of slots in the newly allocated edge structure.
max_data_length	Maximul data length of one CAN frame.

Returns: Pointer to rtems_can_queue_edge structure on success, NULL on error.

◆ rtems_can_queue_pending_outslot_prio()

int rtems_can_queue_pending_outslot_prio	(	struct rtems_can_queue_ends *	qends,
		int	prio_min
	)

This function tests ready outslot with minimum priority.

Function searches for ready slot in active incoming edge. The difference from rtems_can_queue_test_outslot function is that this function does not retreive the slot from FIFO, it just checks its existence. This can be used to determined whether there is a slot with higher priority class in the infrastruce.

Parameters

qends	Ends structure belonging to calling communication object.
prio_min	Minimum slot priority to be considered

Returns: Negative value informs, that there is no ready output slot for given ends and minimum priority. Positive value informs about the available slot priority.

◆ rtems_can_queue_push_back_outslot()

int rtems_can_queue_push_back_outslot	(	struct rtems_can_queue_ends *	qends,
		struct rtems_can_queue_edge *	qedge,
		struct rtems_can_queue_slot *	slot
	)

This function reschedules output slot to process it again later.

Function reschedules slot previously acquired by rtems_can_queue_test_outslot function call for second time processing.

Parameters

qends	Ends structure belonging to calling communication object.
qedge	Edge the slot belongs to.
slot	Pointer to the processed slot.

Returns: Function cannot fail.

◆ rtems_can_queue_put_inslot()

int rtems_can_queue_put_inslot	(	struct rtems_can_queue_ends *	qends,
		struct rtems_can_queue_edge *	qedge,
		struct rtems_can_queue_slot *	slot
	)

This function schedules filled slot for processing.

Puts slot previously acquired by rtems_can_queue_get_inslot or rtems_can_queue_get_inslot_for_prio function call into FIFO queue and activates edge processing if needed.

Parameters

qends	Ends structure belonging to calling communication object.
qedge	Edge the slot belongs to.
slot	Pointer to the preprared slot.

Returns: Positive value informs, that activation of output end has been necessary

◆ rtems_can_queue_sync_wait_kern()

int rtems_can_queue_sync_wait_kern	(	struct rtems_can_queue_ends *	qends,
		struct rtems_can_queue_edge *	qedge,
		bool	nowait,
		rtems_interval	timeout
	)

This function waits for all slots processing.

Parameters

qends	Ends structure belonging to calling communication object.
qedge	Pointer to edge.
nowait	True if semaphore should not wait
timeout	Number of clock ticks to wait for semaphore. Passing zero indicates an infinite timeout.

Returns: Positive value indicates, that edge empty state has been reached. Negative or zero value informs the semaphore timeouted.

◆ rtems_can_queue_test_inslot()

int rtems_can_queue_test_inslot ( struct rtems_can_queue_ends * qends )

This function tests whether there is a free space in any outgoing edge.

Function looks for the first non-blocked outgoing edge in @qends structure with free space for slot.

Parameters

qends Ends structure belonging to calling communication object.

Returns: 0 if there is usable edge with free space available, -1 otherwise.

◆ rtems_can_queue_test_outslot()

int rtems_can_queue_test_outslot	(	struct rtems_can_queue_ends *	qends,
		struct rtems_can_queue_edge **	qedgep,
		struct rtems_can_queue_slot **	slotp
	)

This function tests and retrieves ready slot for given ends.

Function takes highest priority active incoming edge and retrieves oldest ready slot from it.

Parameters

qends	Ends structure belonging to calling communication object.
qedgep	Place to store pointer to found edge.
slotp	Place to store pointer to received slot.

Returns: Negative value informs, that there is no ready output slot for given ends. Positive value is equal to the command slot has been allocated by the input side.

Data Structures

Macros

Functions

Detailed Description

Function Documentation

◆ rtems_can_queue_abort_inslot()

◆ rtems_can_queue_block_inlist()

◆ rtems_can_queue_block_outlist()

◆ rtems_can_queue_connect_edge()

◆ rtems_can_queue_disconnect_edge()

◆ rtems_can_queue_do_edge_decref()

◆ rtems_can_queue_edge_do_dead()

◆ rtems_can_queue_ends_dispose_kern()

◆ rtems_can_queue_ends_flush_inlist()

◆ rtems_can_queue_ends_flush_outlist()

◆ rtems_can_queue_ends_init()

◆ rtems_can_queue_ends_kill_inlist()

◆ rtems_can_queue_ends_kill_outlist()

◆ rtems_can_queue_ends_sync_all_kern()

◆ rtems_can_queue_fifo_done_kern()

◆ rtems_can_queue_fifo_flush_slots()

◆ rtems_can_queue_fifo_init_kern()

◆ rtems_can_queue_fifo_init_slots()

◆ rtems_can_queue_filter_frame_to_edges()

◆ rtems_can_queue_flush()

◆ rtems_can_queue_free_outslot()

◆ rtems_can_queue_get_inslot()

◆ rtems_can_queue_get_inslot_for_prio()

◆ rtems_can_queue_kern_initialize()

◆ rtems_can_queue_new_edge_kern()

◆ rtems_can_queue_pending_outslot_prio()

◆ rtems_can_queue_push_back_outslot()

◆ rtems_can_queue_put_inslot()

◆ rtems_can_queue_sync_wait_kern()

◆ rtems_can_queue_test_inslot()

◆ rtems_can_queue_test_outslot()