FDCAN peripheral API

libopencm3 STM32 FDCAN More...

Collaboration diagram for FDCAN peripheral API:

Functions
unsigned	fdcan_get_fifo_element_size (uint32_t canport, unsigned fifo_id)
	Returns actual size of FIFO entry in FIFO for given CAN port and FIFO. More...
unsigned	fdcan_get_txbuf_element_size (uint32_t canport)
	Returns actual size of transmit entry in transmit queue/FIFO for given CAN port. More...
void	fdcan_init_filter (uint32_t canport, uint8_t std_filt, uint8_t ext_filt)
	Configure amount of filters and initialize filtering block. More...
int	fdcan_start (uint32_t canport, uint32_t timeout)
	Enable FDCAN operation after FDCAN block has been set up. More...
void	fdcan_set_fifo_locked_mode (uint32_t canport, bool locked)
	Configure FDCAN FIFO lock mode. More...
int	fdcan_init (uint32_t canport, uint32_t timeout)
	Put FDCAN block into INIT mode for setup. More...
void	fdcan_set_can (uint32_t canport, bool auto_retry_disable, bool rx_fifo_locked, bool tx_queue_mode, bool silent, uint32_t n_sjw, uint32_t n_ts1, uint32_t n_ts2, uint32_t n_br_presc)
	Set essential FDCAN block parameters for plain CAN operation. More...
void	fdcan_set_fdcan (uint32_t canport, bool brs_enable, bool fd_op_enable, uint32_t f_sjw, uint32_t f_ts1, uint32_t f_ts2, uint32_t f_br_presc)
	Set FDCAN block parameters for FDCAN transmission. More...
void	fdcan_set_test (uint32_t canport, bool testing, bool loopback)
	Set FDCAN block testing features. More...
int	fdcan_get_init_state (uint32_t canport)
	Return current FDCAN block operation state. More...
void	fdcan_set_std_filter (uint32_t canport, uint32_t nr, uint8_t id_list_mode, uint32_t id1, uint32_t id2, uint8_t action)
	Configure filter rule for standard ID frames. More...
void	fdcan_set_ext_filter (uint32_t canport, uint32_t nr, uint8_t id_list_mode, uint32_t id1, uint32_t id2, uint8_t action)
	Configure filter rule for extended ID frames. More...
int	fdcan_transmit (uint32_t canport, uint32_t id, bool ext, bool rtr, bool fdcan_fmt, bool btr_switch, uint8_t length, const uint8_t *data)
	Transmit Message using FDCAN. More...
int	fdcan_receive (uint32_t canport, uint8_t fifo_id, bool release, uint32_t *id, bool *ext, bool *rtr, uint8_t *fmi, uint8_t *length, uint8_t *data, uint16_t *timestamp)
	Receive Message from FDCAN FIFO. More...
void	fdcan_release_fifo (uint32_t canport, uint8_t fifo_id)
	Release receive oldest FIFO entry. More...
void	fdcan_enable_irq (uint32_t canport, uint32_t irq)
	Enable IRQ from FDCAN block. More...
void	fdcan_disable_irq (uint32_t canport, uint32_t irq)
	Disable IRQ from FDCAN block. More...
bool	fdcan_available_tx (uint32_t canport)
	Check if there is free transmit buffer. More...
bool	fdcan_available_rx (uint32_t canport, uint8_t fifo)
	Tell if there is message waiting in receive FIFO. More...

Detailed Description

libopencm3 STM32 FDCAN

Version

1.0.0

Author

© 2021 Eduard Drusa <ventyl86 at netkosice dot sk>

Devices can have up to three FDCAN peripherals residing in one FDCAN block. The peripherals support both CAN 2.0 A and B standard and Bosch FDCAN standard. FDCAN frame format and bitrate switching is supported. The peripheral has several filters for incoming messages that can be distributed between two FIFOs and three transmit mailboxes. For transmitted messages it is possible to opt for event notification once message is transmitted.

LGPL License Terms libopencm3 License

Function Documentation

fdcan_available_rx()

bool fdcan_available_rx	(	uint32_t	canport,
		uint8_t	fifo
	)

Tell if there is message waiting in receive FIFO.

Parameters

[in]	canport	FDCAN port. See FDCAN block base addresses.
[in]	fifo	Rx FIFO number, 0 or 1

Returns

true if there is at least one message waiting in given receive FIFO, false otherwise.

Definition at line 687 of file fdcan_common.c.

References FDCAN_RXFIFO_FL_MASK, FDCAN_RXFIFO_FL_SHIFT, and FDCAN_RXFIS.

fdcan_available_tx()

bool fdcan_available_tx

(

uint32_t

canport

)

Check if there is free transmit buffer.

Parameters

[in]

canport

FDCAN port. See FDCAN block base addresses.

Returns

true if there is at least one free transmit buffer for new message to be sent, false otherwise.

Definition at line 675 of file fdcan_common.c.

References FDCAN_E_BUSY, and fdcan_get_free_txbuf().

Here is the call graph for this function:

fdcan_disable_irq()

void fdcan_disable_irq	(	uint32_t	canport,
		uint32_t	irq
	)

Disable IRQ from FDCAN block.

This routine configures FDCAN to disable certain IRQ. Each FDCAN block supports two IRQs.

Parameters

[in]	canport	FDCAN block base address. See FDCAN block base addresses.
[in]	irq	number of IRQ to be enabled (currently 0 or 1)

Definition at line 664 of file fdcan_common.c.

References FDCAN_ILE, FDCAN_ILE_INT0, and FDCAN_ILE_INT1.

fdcan_enable_irq()

void fdcan_enable_irq	(	uint32_t	canport,
		uint32_t	irq
	)

Enable IRQ from FDCAN block.

This routine configures FDCAN to enable certain IRQ. Each FDCAN block supports two IRQs.

Parameters

[in]	canport	FDCAN block base address. See FDCAN block base addresses.
[in]	irq	number of IRQ to be enabled (currently 0 or 1)

Definition at line 651 of file fdcan_common.c.

References FDCAN_ILE, FDCAN_ILE_INT0, and FDCAN_ILE_INT1.

fdcan_get_fifo_element_size()

unsigned fdcan_get_fifo_element_size	(	uint32_t	canport,
		unsigned	fifo_id
	)

Returns actual size of FIFO entry in FIFO for given CAN port and FIFO.

Obtains value of FIFO entry length. For G4 it returns constant value as G4 has FIFO element length hardcoded.

Parameters

[in]	canport	FDCAN block base address. See FDCAN block base addresses. Unused.
[in]	fifo_id	ID of FIFO whole length is queried. Unused.

Returns

Length of FIFO entry length covering frame header and frame payload.

Definition at line 57 of file fdcan.c.

Referenced by fdcan_get_rxfifo_addr().

Here is the caller graph for this function:

fdcan_get_init_state()

int fdcan_get_init_state

(

uint32_t

canport

)

Return current FDCAN block operation state.

This function effectively returns value of FDCAN_CCCR's INIT bit.

Parameters

[in]

canport

FDCAN block base address. See FDCAN block base addresses.

Returns

1 if FDCAN block is in INIT mode, 0 if it is already started.

Definition at line 396 of file fdcan_common.c.

References FDCAN_CCCR, and FDCAN_CCCR_INIT.

fdcan_get_txbuf_element_size()

unsigned fdcan_get_txbuf_element_size

(

uint32_t

canport

)

Returns actual size of transmit entry in transmit queue/FIFO for given CAN port.

Obtains value of entry length in transmit queue/FIFO. For G4 it returns constant value as G4 has transmit buffer entries of fixed length.

Parameters

[in]

canport

FDCAN block base address. See FDCAN block base addresses. Unused.

Returns

Length of FIFO entry length covering frame header and frame payload.

Definition at line 75 of file fdcan.c.

Referenced by fdcan_get_txbuf_addr().

Here is the caller graph for this function:

fdcan_init()

int fdcan_init	(	uint32_t	canport,
		uint32_t	timeout
	)

Put FDCAN block into INIT mode for setup.

Initialize the selected CAN peripheral block. This function will switch CAN block into initialization mode. CAN block is then left in initialization mode in order to perform setup, which can't be adjusted once FDCAN block is started. It is mandatory to call at least fdcan_set_can function to configure basic timing values for CAN 2.0 operation. Functions which only have effect, if FDCAN block is in INIT mode are:

• fdcan_set_can
• fdcan_set_fdcan
• fdcan_init_filter
• fdcan_set_test

You can check if FDCAN block is in INIT mode or it is started using fdcan_get_init_state.

Parameters

[in]	canport	CAN register base address. See FDCAN block base addresses.
[in]	timeout	Amount of empty busy loops, which routine should wait for FDCAN confirming that it entered INIT mode. If set to 0, function will return immediately.

Returns

Operation error status. See FDCAN error return values.

Definition at line 260 of file fdcan_common.c.

References FDCAN_CCCR, FDCAN_CCCR_CCE, fdcan_cccr_init_cfg(), FDCAN_E_OK, and FDCAN_E_TIMEOUT.

Here is the call graph for this function:

fdcan_init_filter()

void fdcan_init_filter	(	uint32_t	canport,
		uint8_t	std_filt,
		uint8_t	ext_filt
	)

Configure amount of filters and initialize filtering block.

This function allows to configure global amount of filters present. FDCAN block will only ever check as many filters as this function configures. Function will also clear all filter blocks to zero values. This function can be only called after fdcan_init has already been called and fdcan_start has not been called yet as registers holding filter count are write-protected unless FDCAN block is in INIT mode. It is possible to reconfigure filters (fdcan_set_std_filter and fdcan_set_ext_filter) after FDCAN block has already been started.

Parameters

[in]	canport	FDCAN block base address. See FDCAN block base addresses.
[in]	std_filt	requested amount of standard ID filter rules (0-28)
[in]	ext_filt	requested amount of extended ID filter rules (0-8)

Definition at line 99 of file fdcan.c.

References fdcan_extended_filter::conf_id1, FDCAN_EFT_MAX_NR, fdcan_get_flesa_addr(), fdcan_get_flssa_addr(), FDCAN_RXGFC, FDCAN_RXGFC_LSE_MASK, FDCAN_RXGFC_LSE_SHIFT, FDCAN_RXGFC_LSS_MASK, FDCAN_RXGFC_LSS_SHIFT, FDCAN_SFT_MAX_NR, fdcan_standard_filter::type_id1_conf_id2, and fdcan_extended_filter::type_id2.

Here is the call graph for this function:

fdcan_receive()

int fdcan_receive	(	uint32_t	canport,
		uint8_t	fifo_id,
		bool	release,
		uint32_t *	id,
		bool *	ext,
		bool *	rtr,
		uint8_t *	fmi,
		uint8_t *	length,
		uint8_t *	data,
		uint16_t *	timestamp
	)

Receive Message from FDCAN FIFO.

Reads one message from receive FIFO. Returns message ID, type of ID, message length and message payload. It is mandatory to provide valid pointers to suitably sized buffers for these outputs. Additionally, it is optinally possible to provide non-zero pointer to obtain filter identification, request of transmission flag and message timestamp. If pointers provided for optional outputs are NULL, then no information is returned for given pointer.

Parameters

[in]	canport	FDCAN block base address. See FDCAN block base addresses
[in]	fifo_id	FIFO id.
[in]	release	Release the FIFO automatically after copying data out
[out]	id	Returned message ID. Mandatory.
[out]	ext	Returned type of the message ID (true if extended). Mandatory.
[out]	rtr	Returnes flag if request of transmission was requested. Optional.
[out]	fmi	Returned ID of the filter which matched this frame. Optional.
[out]	length	Length of message payload in bytes. Mandatory.
[out]	data	Buffer for storage of message payload data. Mandatory.
[out]	timestamp	Returned timestamp of received frame. Optional.

Returns

Operation error status. See FDCAN error return values.

Definition at line 562 of file fdcan_common.c.

References fdcan_rx_fifo_element::data, fdcan_dlc_to_length(), FDCAN_E_NOTAVAIL, FDCAN_E_OK, FDCAN_FIFO_DLC_MASK, FDCAN_FIFO_DLC_SHIFT, FDCAN_FIFO_EID_MASK, FDCAN_FIFO_EID_SHIFT, FDCAN_FIFO_MM_MASK, FDCAN_FIFO_MM_SHIFT, FDCAN_FIFO_RTR, FDCAN_FIFO_RXTS_MASK, FDCAN_FIFO_RXTS_SHIFT, FDCAN_FIFO_SID_MASK, FDCAN_FIFO_SID_SHIFT, FDCAN_FIFO_XTD, fdcan_get_fill_rxfifo(), fdcan_get_rxfifo_addr(), FDCAN_RXFIA, FDCAN_RXFIFO_AI_SHIFT, fdcan_rx_fifo_element::filt_fmt_dlc_ts, and fdcan_rx_fifo_element::identifier_flags.

Here is the call graph for this function:

fdcan_release_fifo()

void fdcan_release_fifo	(	uint32_t	canport,
		uint8_t	fifo_id
	)

Release receive oldest FIFO entry.

This function will mask oldest entry in FIFO as released making space for another received frame. This function can be used if fdcan_receive was called using release = false. If used in other case, then messages can get lost.

Parameters

[in]	canport	FDCAN block base address. See FDCAN block base addresses.
[in]	fifo_id	ID of FIFO where release should be performed (0 or 1)

Definition at line 628 of file fdcan_common.c.

References FDCAN_RXFIA, FDCAN_RXFIFO_AI_SHIFT, FDCAN_RXFIFO_FL_SHIFT, FDCAN_RXFIFO_GI_SHIFT, and FDCAN_RXFIS.

fdcan_set_can()

void fdcan_set_can	(	uint32_t	canport,
		bool	auto_retry_disable,
		bool	rx_fifo_locked,
		bool	tx_queue_mode,
		bool	silent,
		uint32_t	n_sjw,
		uint32_t	n_ts1,
		uint32_t	n_ts2,
		uint32_t	n_br_presc
	)

Set essential FDCAN block parameters for plain CAN operation.

Allows configuration of prescalers and essential transmit and FIFO behavior used during transmission in plain CAN 2.0 mode. In this mode FDCAN frame format is not available nor is possible to use fast bitrates. This function does neither enable FD-CAN mode after reset nor disable it after re-entering INIT mode of previously configured block. Timing values set here are valid for both arbitration phase of all frames and for data phase of both CAN and FDCAN frames, which don't use bitrate switching. This function can only be called after FDCAN block has been switched into INIT mode. It is possible to receive FDCAN frames even if FDCAN block is configured only using this function as long as bitrate switching is not used.

Parameters

[in]	canport	FDCAN block base address. See FDCAN block base addresses.
[in]	auto_retry_disable	Disable automatic frame retransmission on error
[in]	rx_fifo_locked	Enable FIFO locked mode. Upon FIFO overflow all received messages are discarded.
[in]	tx_queue_mode	Enable transmission queue mode. Otherwise transmission works in FIFO mode.
[in]	silent	Enable silent mode. Transmitter stays recessive all the time.
[in]	n_sjw	Resynchronization time quanta jump width
[in]	n_ts1	Time segment 1 time quanta
[in]	n_ts2	Time segment 2 time quanta
[in]	n_br_presc	Arbitration phase / CAN mode bitrate prescaler

Definition at line 296 of file fdcan_common.c.

References FDCAN_CCCR, FDCAN_CCCR_DAR, FDCAN_CCCR_MON, FDCAN_NBTP, FDCAN_NBTP_NBRP_SHIFT, FDCAN_NBTP_NSJW_SHIFT, FDCAN_NBTP_NTSEG1_SHIFT, FDCAN_NBTP_NTSEG2_SHIFT, fdcan_set_fifo_locked_mode(), FDCAN_TXBC, and FDCAN_TXBC_TFQM.

Here is the call graph for this function:

fdcan_set_ext_filter()

void fdcan_set_ext_filter	(	uint32_t	canport,
		uint32_t	nr,
		uint8_t	id_list_mode,
		uint32_t	id1,
		uint32_t	id2,
		uint8_t	action
	)

Configure filter rule for extended ID frames.

Sets up filter rule for frames having extended ID. Each FDCAN block can have its own set of filtering rules. It is only possible to configure as many filters as was configured previously using fdcan_init_filter.

Parameters

[in]	canport	FDCAN block base address. See FDCAN block base addresses.
[in]	nr	number of filter to be configured
[in]	id_list_mode	mode in which id1 and id2 are used to match the rule. See Extended ID filter match type.
[in]	id1	extended ID for matching. Used as exact value, lower bound or bit pattern depending on matching mode selected
[in]	id2	extended ID or bitmask. Used as exact value, upper bound or bit mask depending on matching mode selected
[in]	action	Action performed if filtering rule matches frame ID. See Extended ID filter action.

Definition at line 458 of file fdcan_common.c.

References fdcan_extended_filter::conf_id1, FDCAN_EFEC_SHIFT, FDCAN_EFID1_MASK, FDCAN_EFID1_SHIFT, FDCAN_EFID2_MASK, FDCAN_EFID2_SHIFT, FDCAN_EFT_SHIFT, fdcan_get_flesa_addr(), and fdcan_extended_filter::type_id2.

Here is the call graph for this function:

fdcan_set_fdcan()

void fdcan_set_fdcan	(	uint32_t	canport,
		bool	brs_enable,
		bool	fd_op_enable,
		uint32_t	f_sjw,
		uint32_t	f_ts1,
		uint32_t	f_ts2,
		uint32_t	f_br_presc
	)

Set FDCAN block parameters for FDCAN transmission.

Enables and configures parameters related to FDCAN transmission. This function allows configuration of bitrate switching, FDCAN frame format and fast mode timing. This function can only be called if FDCAN block is in INIT mode. It is safe to call this function on previously configured block in order to enable/disable/change FDCAN mode parameters. Non-FDCAN parameters won't be affected.

Parameters

[in]	canport	FDCAN block base address. See FDCAN block base addresses.
[in]	brs_enable	Enable FDCAN bitrate switching for fast mode operation
[in]	fd_op_enable	Enable transmission of FDCAN-formatted frames
[in]	f_sjw	Resynchronization time quanta jump width in fast mode
[in]	f_ts1	Time segment 1 time quanta in fast mode
[in]	f_ts2	Time segment 2 time quanta in fast mode
[in]	f_br_presc	Fast mode operation bitrate prescaler

Definition at line 343 of file fdcan_common.c.

References FDCAN_CCCR, FDCAN_CCCR_BRSE, FDCAN_CCCR_FDOE, FDCAN_DBTP, FDCAN_DBTP_DBRP_SHIFT, FDCAN_DBTP_DSJW_SHIFT, FDCAN_DBTP_DTSEG1_SHIFT, and FDCAN_DBTP_DTSEG2_SHIFT.

fdcan_set_fifo_locked_mode()

void fdcan_set_fifo_locked_mode	(	uint32_t	canport,
		bool	locked
	)

Configure FDCAN FIFO lock mode.

This function allows to choose between locked and overewrite mode of FIFOs. In locked mode, whenever FIFO is full and new frame arrives, which would normally been stored into given FIFO, then frame is dropped. If overwrite mode is active, then most recent message in FIFO is rewritten by frame just received.

Parameters

[in]	canport	FDCAN block base address. See FDCAN block base addresses.
[in]	locked	true activates locked mode, false activates overwrite mode

Definition at line 177 of file fdcan.c.

References FDCAN_RXGFC, FDCAN_RXGFC_F0OM, and FDCAN_RXGFC_F1OM.

Referenced by fdcan_set_can().

Here is the caller graph for this function:

fdcan_set_std_filter()

void fdcan_set_std_filter	(	uint32_t	canport,
		uint32_t	nr,
		uint8_t	id_list_mode,
		uint32_t	id1,
		uint32_t	id2,
		uint8_t	action
	)

Configure filter rule for standard ID frames.

Sets up filter rule for frames having standard ID. Each FDCAN block can have its own set of filtering rules. It is only possible to configure as many filters as was configured previously using fdcan_init_filter.

Parameters

[in]	canport	FDCAN block base address. See FDCAN block base addresses.
[in]	nr	number of filter to be configured
[in]	id_list_mode	Mode in which id1 and id2 are used to match the rule. See Standard ID filter match type.
[in]	id1	standard ID for matching. Used as exact value, lower bound or bit pattern depending on matching mode selected
[in]	id2	standard ID or bitmask. Used as exact value, upper bound or bit mask depending on matching mode selected
[in]	action	Action performed if filtering rule matches frame ID. See Standard ID filter action.

Definition at line 418 of file fdcan_common.c.

References fdcan_get_flssa_addr(), FDCAN_SFEC_SHIFT, FDCAN_SFID1_MASK, FDCAN_SFID1_SHIFT, FDCAN_SFID2_MASK, FDCAN_SFID2_SHIFT, FDCAN_SFT_SHIFT, and fdcan_standard_filter::type_id1_conf_id2.

Here is the call graph for this function:

fdcan_set_test()

void fdcan_set_test	(	uint32_t	canport,
		bool	testing,
		bool	loopback
	)

Set FDCAN block testing features.

Configures self-test functions of FDCAN block. It is safe to call this function on fully configured interface. This function can only be called after FDCAN block is put into INIT mode.

Parameters

[in]	canport	FDCAN block base address. See FDCAN block base addresses.
[in]	testing	Enables testing mode of FDCAN block
[in]	loopback	Enables transmission loopback

Definition at line 374 of file fdcan_common.c.

References FDCAN_CCCR, FDCAN_CCCR_TEST, FDCAN_TEST, and FDCAN_TEST_LBCK.

fdcan_start()

int fdcan_start	(	uint32_t	canport,
		uint32_t	timeout
	)

Enable FDCAN operation after FDCAN block has been set up.

This function will disable FDCAN configuration effectively allowing FDCAN to sync up with the bus. After calling this function it is not possible to reconfigure amount of filter rules, yet it is possible to configure rules themselves. FDCAN block operation state can be checked using fdcan_get_init_state.

Parameters

[in]	canport	FDCAN block base address. See FDCAN block base addresses.
[in]	timeout	Amount of empty busy loops, which routine should wait for FDCAN confirming that it left INIT mode. If set to 0, function will return immediately.

Returns

Operation error status. See FDCAN error return values.

Note

If this function returns with timeout, it usually means that FDCAN_clk is not set up properly.

Definition at line 154 of file fdcan.c.

References fdcan_cccr_init_cfg(), FDCAN_E_OK, and FDCAN_E_TIMEOUT.

Here is the call graph for this function:

fdcan_transmit()

int fdcan_transmit	(	uint32_t	canport,
		uint32_t	id,
		bool	ext,
		bool	rtr,
		bool	fdcan_fmt,
		bool	btr_switch,
		uint8_t	length,
		const uint8_t *	data
	)

Transmit Message using FDCAN.

Parameters

[in]	canport	CAN block register base. See FDCAN block base addresses.
[in]	id	Message ID
[in]	ext	Extended message ID
[in]	rtr	Request transmit
[in]	fdcan_fmt	Use FDCAN format
[in]	btr_switch	Switch bitrate for data portion of frame
[in]	length	Message payload length. Must be valid CAN or FDCAN frame length
[in]	data	Message payload data

Returns

int 0, 1 or 2 on success and depending on which outgoing mailbox got selected. Otherwise returns error code. For error codes, see FDCAN error return values.

Definition at line 486 of file fdcan_common.c.

References fdcan_tx_buffer_element::data, fdcan_tx_buffer_element::evt_fmt_dlc_res, FDCAN_E_BUSY, FDCAN_E_INVALID, FDCAN_FIFO_BRS, FDCAN_FIFO_DLC_SHIFT, FDCAN_FIFO_EID_MASK, FDCAN_FIFO_EID_SHIFT, FDCAN_FIFO_FDF, FDCAN_FIFO_RTR, FDCAN_FIFO_SID_MASK, FDCAN_FIFO_SID_SHIFT, FDCAN_FIFO_XTD, fdcan_get_free_txbuf(), fdcan_get_txbuf_addr(), fdcan_length_to_dlc(), FDCAN_TXBAR, and fdcan_tx_buffer_element::identifier_flags.

Here is the call graph for this function: