Xenomai API  2.6.5
Files | Data Structures | Macros | Typedefs | Enumerations
CAN Devices
Real-Time Driver Model » Device Profiles
Collaboration diagram for CAN Devices:

Files

file  rtcan.h
 Real-Time Driver Model for RT-Socket-CAN, CAN device profile header.
 

Data Structures

struct  can_bittime_std
 Standard bit-time parameters according to Bosch. More...
 
struct  can_bittime_btr
 Hardware-specific BTR bit-times. More...
 
struct  can_bittime
 Custom CAN bit-time definition. More...
 
struct  can_filter
 Filter for reception of CAN messages. More...
 
struct  sockaddr_can
 Socket address structure for the CAN address family. More...
 
struct  can_frame
 Raw CAN frame. More...
 

Macros

#define AF_CAN   29
 CAN address family.
 
#define PF_CAN   AF_CAN
 CAN protocol family.
 
#define SOL_CAN_RAW   103
 CAN socket levels. More...
 

Typedefs

typedef uint32_t can_id_t
 Type of CAN id (see CAN_xxx_MASK and CAN_xxx_FLAG)
 
typedef can_id_t can_err_mask_t
 Type of CAN error mask.
 
typedef uint32_t can_baudrate_t
 Baudrate definition in bits per second.
 
typedef enum CAN_BITTIME_TYPE can_bittime_type_t
 See CAN_BITTIME_TYPE.
 
typedef enum CAN_MODE can_mode_t
 See CAN_MODE.
 
typedef int can_ctrlmode_t
 See CAN_CTRLMODE.
 
typedef enum CAN_STATE can_state_t
 See CAN_STATE.
 
typedef struct can_filter can_filter_t
 Filter for reception of CAN messages. More...
 
typedef struct can_frame can_frame_t
 Raw CAN frame. More...
 

Enumerations

enum  CAN_BITTIME_TYPE { CAN_BITTIME_STD, CAN_BITTIME_BTR }
 Supported CAN bit-time types. More...
 

CAN ID masks

Bit masks for masking CAN IDs

#define CAN_EFF_MASK   0x1FFFFFFF
 Bit mask for extended CAN IDs.
 
#define CAN_SFF_MASK   0x000007FF
 Bit mask for standard CAN IDs.
 

CAN ID flags

Flags within a CAN ID indicating special CAN frame attributes

#define CAN_EFF_FLAG   0x80000000
 Extended frame.
 
#define CAN_RTR_FLAG   0x40000000
 Remote transmission frame.
 
#define CAN_ERR_FLAG   0x20000000
 Error frame (see Errors), not valid in struct can_filter.
 
#define CAN_INV_FILTER   CAN_ERR_FLAG
 Invert CAN filter definition, only valid in struct can_filter.
 

Particular CAN protocols

Possible protocols for the PF_CAN protocol family

Currently only the RAW protocol is supported.

#define CAN_RAW   1
 Raw protocol of PF_CAN, applicable to socket type SOCK_RAW.
 

CAN operation modes

Modes into which CAN controllers can be set

enum  CAN_MODE { CAN_MODE_STOP = 0, CAN_MODE_START, CAN_MODE_SLEEP }
 

CAN controller modes

Special CAN controllers modes, which can be or'ed together.

Note
These modes are hardware-dependent. Please consult the hardware manual of the CAN controller for more detailed information.
#define CAN_CTRLMODE_LISTENONLY   0x1
 
#define CAN_CTRLMODE_LOOPBACK   0x2
 
#define CAN_CTRLMODE_3_SAMPLES   0x4
 

CAN controller states

States a CAN controller can be in.

enum  CAN_STATE {
  CAN_STATE_ERROR_ACTIVE = 0 , CAN_STATE_ERROR_WARNING = 1 , CAN_STATE_ERROR_PASSIVE = 2 , CAN_STATE_BUS_OFF,
  CAN_STATE_SCANNING_BAUDRATE, CAN_STATE_STOPPED, CAN_STATE_SLEEPING
}
 

Timestamp switches

Arguments to pass to RTCAN_RTIOC_TAKE_TIMESTAMP

#define RTCAN_TAKE_NO_TIMESTAMPS   0
 Switch off taking timestamps.
 
#define RTCAN_TAKE_TIMESTAMPS   1
 Do take timestamps.
 

RAW socket options

Setting and getting CAN RAW socket options.

#define CAN_RAW_FILTER   0x1
 CAN filter definition. More...
 
#define CAN_RAW_ERR_FILTER   0x2
 CAN error mask. More...
 
#define CAN_RAW_LOOPBACK   0x3
 CAN TX loopback. More...
 
#define CAN_RAW_RECV_OWN_MSGS   0x4
 CAN receive own messages. More...
 

IOCTLs

CAN device IOCTLs

#define SIOCGIFINDEX   defined_by_kernel_header_file
 Get CAN interface index by name. More...
 
#define SIOCSCANBAUDRATE   _IOW(RTIOC_TYPE_CAN, 0x01, struct ifreq)
 Set baud rate. More...
 
#define SIOCGCANBAUDRATE   _IOWR(RTIOC_TYPE_CAN, 0x02, struct ifreq)
 Get baud rate. More...
 
#define SIOCSCANCUSTOMBITTIME   _IOW(RTIOC_TYPE_CAN, 0x03, struct ifreq)
 Set custom bit time parameter. More...
 
#define SIOCGCANCUSTOMBITTIME   _IOWR(RTIOC_TYPE_CAN, 0x04, struct ifreq)
 Get custum bit-time parameters. More...
 
#define SIOCSCANMODE   _IOW(RTIOC_TYPE_CAN, 0x05, struct ifreq)
 Set operation mode of CAN controller. More...
 
#define SIOCGCANSTATE   _IOWR(RTIOC_TYPE_CAN, 0x06, struct ifreq)
 Get current state of CAN controller. More...
 
#define SIOCSCANCTRLMODE   _IOW(RTIOC_TYPE_CAN, 0x07, struct ifreq)
 Set special controller modes. More...
 
#define SIOCGCANCTRLMODE   _IOWR(RTIOC_TYPE_CAN, 0x08, struct ifreq)
 Get special controller modes. More...
 
#define RTCAN_RTIOC_TAKE_TIMESTAMP   _IOW(RTIOC_TYPE_CAN, 0x09, int)
 Enable or disable storing a high precision timestamp upon reception of a CAN frame. More...
 
#define RTCAN_RTIOC_RCV_TIMEOUT   _IOW(RTIOC_TYPE_CAN, 0x0A, nanosecs_rel_t)
 Specify a reception timeout for a socket. More...
 
#define RTCAN_RTIOC_SND_TIMEOUT   _IOW(RTIOC_TYPE_CAN, 0x0B, nanosecs_rel_t)
 Specify a transmission timeout for a socket. More...
 

Error mask

Error class (mask) in can_id field of struct can_frame to be used with CAN_RAW_ERR_FILTER.

Note: Error reporting is hardware dependent and most CAN controllers report less detailed error conditions than the SJA1000.

Note: In case of a bus-off error condition (CAN_ERR_BUSOFF), the CAN controller is not restarted automatically. It is the application's responsibility to react appropriately, e.g. calling CAN_MODE_START.

Note: Bus error interrupts (CAN_ERR_BUSERROR) are enabled when an application is calling a Recv function on a socket listening on bus errors (using CAN_RAW_ERR_FILTER). After one bus error has occured, the interrupt will be disabled to allow the application time for error processing and to efficiently avoid bus error interrupt flooding.

#define CAN_ERR_TX_TIMEOUT   0x00000001U
 TX timeout (netdevice driver)
 
#define CAN_ERR_LOSTARB   0x00000002U
 Lost arbitration (see data[0])
 
#define CAN_ERR_CRTL   0x00000004U
 Controller problems (see data[1])
 
#define CAN_ERR_PROT   0x00000008U
 Protocol violations (see data[2], data[3])
 
#define CAN_ERR_TRX   0x00000010U
 Transceiver status (see data[4])
 
#define CAN_ERR_ACK   0x00000020U
 Received no ACK on transmission.
 
#define CAN_ERR_BUSOFF   0x00000040U
 Bus off.
 
#define CAN_ERR_BUSERROR   0x00000080U
 Bus error (may flood!)
 
#define CAN_ERR_RESTARTED   0x00000100U
 Controller restarted.
 
#define CAN_ERR_MASK   0x1FFFFFFFU
 Omit EFF, RTR, ERR flags.
 

Arbitration lost error

Error in the data[0] field of struct can_frame.

#define CAN_ERR_LOSTARB_UNSPEC   0x00
 unspecified More...
 

Controller problems

Error in the data[1] field of struct can_frame.

#define CAN_ERR_CRTL_UNSPEC   0x00
 unspecified
 
#define CAN_ERR_CRTL_RX_OVERFLOW   0x01
 RX buffer overflow.
 
#define CAN_ERR_CRTL_TX_OVERFLOW   0x02
 TX buffer overflow.
 
#define CAN_ERR_CRTL_RX_WARNING   0x04
 reached warning level for RX errors
 
#define CAN_ERR_CRTL_TX_WARNING   0x08
 reached warning level for TX errors
 
#define CAN_ERR_CRTL_RX_PASSIVE   0x10
 reached passive level for RX errors
 
#define CAN_ERR_CRTL_TX_PASSIVE   0x20
 reached passive level for TX errors
 

Protocol error type

Error in the data[2] field of struct can_frame.

#define CAN_ERR_PROT_UNSPEC   0x00
 unspecified
 
#define CAN_ERR_PROT_BIT   0x01
 single bit error
 
#define CAN_ERR_PROT_FORM   0x02
 frame format error
 
#define CAN_ERR_PROT_STUFF   0x04
 bit stuffing error
 
#define CAN_ERR_PROT_BIT0   0x08
 unable to send dominant bit
 
#define CAN_ERR_PROT_BIT1   0x10
 unable to send recessive bit
 
#define CAN_ERR_PROT_OVERLOAD   0x20
 bus overload
 
#define CAN_ERR_PROT_ACTIVE   0x40
 active error announcement
 
#define CAN_ERR_PROT_TX   0x80
 error occured on transmission
 

Protocol error location

Error in the data[4] field of struct can_frame.

#define CAN_ERR_PROT_LOC_UNSPEC   0x00
 unspecified
 
#define CAN_ERR_PROT_LOC_SOF   0x03
 start of frame
 
#define CAN_ERR_PROT_LOC_ID28_21   0x02
 ID bits 28 - 21 (SFF: 10 - 3)
 
#define CAN_ERR_PROT_LOC_ID20_18   0x06
 ID bits 20 - 18 (SFF: 2 - 0 )
 
#define CAN_ERR_PROT_LOC_SRTR   0x04
 substitute RTR (SFF: RTR)
 
#define CAN_ERR_PROT_LOC_IDE   0x05
 identifier extension
 
#define CAN_ERR_PROT_LOC_ID17_13   0x07
 ID bits 17-13.
 
#define CAN_ERR_PROT_LOC_ID12_05   0x0F
 ID bits 12-5.
 
#define CAN_ERR_PROT_LOC_ID04_00   0x0E
 ID bits 4-0.
 
#define CAN_ERR_PROT_LOC_RTR   0x0C
 RTR.
 
#define CAN_ERR_PROT_LOC_RES1   0x0D
 reserved bit 1
 
#define CAN_ERR_PROT_LOC_RES0   0x09
 reserved bit 0
 
#define CAN_ERR_PROT_LOC_DLC   0x0B
 data length code
 
#define CAN_ERR_PROT_LOC_DATA   0x0A
 data section
 
#define CAN_ERR_PROT_LOC_CRC_SEQ   0x08
 CRC sequence.
 
#define CAN_ERR_PROT_LOC_CRC_DEL   0x18
 CRC delimiter.
 
#define CAN_ERR_PROT_LOC_ACK   0x19
 ACK slot.
 
#define CAN_ERR_PROT_LOC_ACK_DEL   0x1B
 ACK delimiter.
 
#define CAN_ERR_PROT_LOC_EOF   0x1A
 end of frame
 
#define CAN_ERR_PROT_LOC_INTERM   0x12
 intermission
 
#define CAN_ERR_TRX_UNSPEC   0x00
 0000 0000
 
#define CAN_ERR_TRX_CANH_NO_WIRE   0x04
 0000 0100
 
#define CAN_ERR_TRX_CANH_SHORT_TO_BAT   0x05
 0000 0101
 
#define CAN_ERR_TRX_CANH_SHORT_TO_VCC   0x06
 0000 0110
 
#define CAN_ERR_TRX_CANH_SHORT_TO_GND   0x07
 0000 0111
 
#define CAN_ERR_TRX_CANL_NO_WIRE   0x40
 0100 0000
 
#define CAN_ERR_TRX_CANL_SHORT_TO_BAT   0x50
 0101 0000
 
#define CAN_ERR_TRX_CANL_SHORT_TO_VCC   0x60
 0110 0000
 
#define CAN_ERR_TRX_CANL_SHORT_TO_GND   0x70
 0111 0000
 
#define CAN_ERR_TRX_CANL_SHORT_TO_CANH   0x80
 1000 0000
 

Detailed Description

This is the common interface a RTDM-compliant CAN device has to provide. Feel free to report bugs and comments on this profile to the "Socketcan" mailing list (Socke.nosp@m.tcan.nosp@m.-core.nosp@m.@lis.nosp@m.ts.be.nosp@m.rlio.nosp@m.s.de) or directly to the authors (wg@gr.nosp@m.ande.nosp@m.gger..nosp@m.com or Sebas.nosp@m.tian.nosp@m..Smol.nosp@m.orz@.nosp@m.stud..nosp@m.uni-.nosp@m.hanno.nosp@m.ver..nosp@m.de).

Profile Revision: 2

Device Characteristics

Device Flags: RTDM_PROTOCOL_DEVICE

Protocol Family: PF_CAN

Socket Type: SOCK_RAW

Device Class: RTDM_CLASS_CAN

Supported Operations

Socket
Environments: non-RT (RT optional, deprecated)

Specific return values:
  • -EPROTONOSUPPORT (Protocol is not supported by the driver. See CAN protocols for possible protocols.)


Close
Blocking calls to any of the Send or Receive functions will be unblocked when the socket is closed and return with an error.

Environments: non-RT (RT optional, deprecated)

Specific return values: none


IOCTL
Mandatory Environments: see below
Specific return values: see below


Bind
Binds a socket to one or all CAN devices (see struct sockaddr_can). If a filter list has been defined with setsockopt (see Sockopts), it will be used upon reception of CAN frames to decide whether the bound socket will receive a frame. If no filter has been defined, the socket will receive all CAN frames on the specified interface(s).

Binding to special interface index 0 will make the socket receive CAN frames from all CAN interfaces.

Binding to an interface index is also relevant for the Send functions because they will transmit a message over the interface the socket is bound to when no socket address is given to them.


Environments: non-RT (RT optional)

Specific return values:
  • -EFAULT (It was not possible to access user space memory area at the specified address.)
  • -ENOMEM (Not enough memory to fulfill the operation)
  • -EINVAL (Invalid address family, or invalid length of address structure)
  • -ENODEV (Invalid CAN interface index)
  • -ENOSPC (No enough space for filter list)
  • -EBADF (Socket is about to be closed)
  • -EAGAIN (Too many receivers. Old binding (if any) is still active. Close some sockets and try again.)


Setsockopt, Getsockopt
These functions allow to set and get various socket options. Currently, only CAN raw sockets are supported.

Supported Levels and Options:

Environments: non-RT (RT optional)
Specific return values: see links to options above.


Recv, Recvfrom, Recvmsg
These functions receive CAN messages from a socket. Only one message per call can be received, so only one buffer with the correct length must be passed. For SOCK_RAW, this is the size of struct can_frame.

Unlike a call to one of the Send functions, a Recv function will not return with an error if an interface is down (due to bus-off or setting of stop mode) or in sleep mode. Moreover, in such a case there may still be some CAN messages in the socket buffer which could be read out successfully.

It is possible to receive a high precision timestamp with every CAN message. The condition is a former instruction to the socket via RTCAN_RTIOC_TAKE_TIMESTAMP. The timestamp will be copied to the msg_control buffer of struct user_msghdr if it points to a valid memory location with size of nanosecs_abs_t. If this is a NULL pointer the timestamp will be discarded silently.

Note: A msg_controllen of 0 upon completion of the function call indicates that no timestamp is available for that message.

Supported Flags [in]:
  • MSG_DONTWAIT (By setting this flag the operation will only succeed if it would not block, i.e. if there is a message in the socket buffer. This flag takes precedence over a timeout specified by RTCAN_RTIOC_RCV_TIMEOUT.)
  • MSG_PEEK (Receive a message but leave it in the socket buffer. The next receive operation will get that message again.)

Supported Flags [out]: none

Environments: RT (non-RT optional)

Specific return values:
  • Non-negative value (Indicating the successful reception of a CAN message. For SOCK_RAW, this is the size of struct can_frame regardless of the actual size of the payload.)
  • -EFAULT (It was not possible to access user space memory area at one of the specified addresses.)
  • -EINVAL (Unsupported flag detected, or invalid length of socket address buffer, or invalid length of message control buffer)
  • -EMSGSIZE (Zero or more than one iovec buffer passed, or buffer too small)
  • -EAGAIN (No data available in non-blocking mode)
  • -EBADF (Socket was closed.)
  • -EINTR (Operation was interrupted explicitly or by signal.)
  • -ETIMEDOUT (Timeout)


Send, Sendto, Sendmsg
These functions send out CAN messages. Only one message per call can be transmitted, so only one buffer with the correct length must be passed. For SOCK_RAW, this is the size of struct can_frame.

The following only applies to SOCK_RAW: If a socket address of struct sockaddr_can is given, only can_ifindex is used. It is also possible to omit the socket address. Then the interface the socket is bound to will be used for sending messages.

If an interface goes down (due to bus-off or setting of stop mode) all senders that were blocked on this interface will be woken up.


Supported Flags:
  • MSG_DONTWAIT (By setting this flag the transmit operation will only succeed if it would not block. This flag takes precedence over a timeout specified by RTCAN_RTIOC_SND_TIMEOUT.)
Environments: RT (non-RT optional)

Specific return values:
  • Non-negative value equal to given buffer size (Indicating the successful completion of the function call. See also note.)
  • -EOPNOTSUPP (MSG_OOB flag is not supported.)
  • -EINVAL (Unsupported flag detected or: Invalid length of socket address or: Invalid address family or: Data length code of CAN frame not between 0 and 15 or: CAN standard frame has got an ID not between 0 and 2031)
  • -EMSGSIZE (Zero or more than one buffer passed or invalid size of buffer)
  • -EFAULT (It was not possible to access user space memory area at one of the specified addresses.)
  • -ENXIO (Invalid CAN interface index - 0 is not allowed here - or socket not bound or rather bound to all interfaces.)
  • -ENETDOWN (Controller is bus-off or in stopped state.)
  • -ECOMM (Controller is sleeping)
  • -EAGAIN (Cannot transmit without blocking but a non-blocking call was requested.)
  • -EINTR (Operation was interrupted explicitly or by signal)
  • -EBADF (Socket was closed.)
  • -ETIMEDOUT (Timeout)
Note: A successful completion of the function call does not implicate a successful transmission of the message.

Macro Definition Documentation

#define CAN_CTRLMODE_3_SAMPLES   0x4

Triple sampling mode

In this mode the CAN controller uses Triple sampling.

#define CAN_CTRLMODE_LISTENONLY   0x1

Listen-Only mode

In this mode the CAN controller would give no acknowledge to the CAN-bus, even if a message is received successfully and messages would not be transmitted. This mode might be useful for bus-monitoring, hot-plugging or throughput analysis.

Examples:
rtcanconfig.c.
#define CAN_CTRLMODE_LOOPBACK   0x2

Loopback mode

In this mode the CAN controller does an internal loop-back, a message is transmitted and simultaneously received. That mode can be used for self test operation.

Examples:
rtcanconfig.c.
#define CAN_ERR_LOSTARB_UNSPEC   0x00

unspecified

else bit number in bitstream

#define CAN_RAW_ERR_FILTER   0x2

CAN error mask.

A CAN error mask (see Errors) can be set with setsockopt. This mask is then used to decide if error frames are delivered to this socket in case of error condidtions. The error frames are marked with the CAN_ERR_FLAG of CAN_xxx_FLAG and must be handled by the application properly. A detailed description of the errors can be found in the can_id and the data fields of struct can_frame (see Errors for futher details).


Parameters
[in]levelSOL_CAN_RAW
[in]optnameCAN_RAW_ERR_FILTER
[in]optvalPointer to error mask of type can_err_mask_t.
[in]optlenSize of error mask: sizeof(can_err_mask_t).

Environments: non-RT (RT optional)

Specific return values:

  • -EFAULT (It was not possible to access user space memory area at the specified address.)
  • -EINVAL (Invalid length "optlen")
Examples:
rtcanrecv.c.
#define CAN_RAW_FILTER   0x1

CAN filter definition.

A CAN raw filter list with elements of struct can_filter can be installed with setsockopt. This list is used upon reception of CAN frames to decide whether the bound socket will receive a frame. An empty filter list can also be defined using optlen = 0, which is recommanded for write-only sockets.
If the socket was already bound with Bind, the old filter list gets replaced with the new one. Be aware that already received, but not read out CAN frames may stay in the socket buffer.

Parameters
[in]levelSOL_CAN_RAW
[in]optnameCAN_RAW_FILTER
[in]optvalPointer to array of struct can_filter.
[in]optlenSize of filter list: count * sizeof( struct can_filter).
Environments: non-RT (RT optional)

Specific return values:
  • -EFAULT (It was not possible to access user space memory area at the specified address.)
  • -ENOMEM (Not enough memory to fulfill the operation)
  • -EINVAL (Invalid length "optlen")
  • -ENOSPC (No space to store filter list, check RT-Socket-CAN kernel parameters)
Examples:
rtcan_rtt.c, rtcanrecv.c, and rtcansend.c.
#define CAN_RAW_LOOPBACK   0x3

CAN TX loopback.

The TX loopback to other local sockets can be selected with this setsockopt.

Note
The TX loopback feature must be enabled in the kernel and then the loopback to other local TX sockets is enabled by default.


Parameters
[in]levelSOL_CAN_RAW
[in]optnameCAN_RAW_LOOPBACK
[in]optvalPointer to integer value.
[in]optlenSize of int: sizeof(int).

Environments: non-RT (RT optional)

Specific return values:

  • -EFAULT (It was not possible to access user space memory area at the specified address.)
  • -EINVAL (Invalid length "optlen")
  • -EOPNOTSUPP (not supported, check RT-Socket-CAN kernel parameters).
Examples:
rtcansend.c.
#define CAN_RAW_RECV_OWN_MSGS   0x4

CAN receive own messages.

Not supported by RT-Socket-CAN, but defined for compatibility with Socket-CAN.

#define RTCAN_RTIOC_RCV_TIMEOUT   _IOW(RTIOC_TYPE_CAN, 0x0A, nanosecs_rel_t)

Specify a reception timeout for a socket.

Defines a timeout for all receive operations via a socket which will take effect when one of the receive functions is called without the MSG_DONTWAIT flag set.

The default value for a newly created socket is an infinite timeout.

Note
The setting of the timeout value is not done atomically to avoid locks. Please set the value before receiving messages from the socket.
Parameters
[in]argPointer to nanosecs_rel_t variable. The value is interpreted as relative timeout in nanoseconds in case of a positive value. See Timeouts for special timeouts.
Returns
0 on success, otherwise:
  • -EFAULT: It was not possible to access user space memory area at the specified address.

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Kernel-based task
  • User-space task (RT, non-RT)

Rescheduling: never.

Examples:
rtcanrecv.c.
#define RTCAN_RTIOC_SND_TIMEOUT   _IOW(RTIOC_TYPE_CAN, 0x0B, nanosecs_rel_t)

Specify a transmission timeout for a socket.

Defines a timeout for all send operations via a socket which will take effect when one of the send functions is called without the MSG_DONTWAIT flag set.

The default value for a newly created socket is an infinite timeout.

Note
The setting of the timeout value is not done atomically to avoid locks. Please set the value before sending messages to the socket.
Parameters
[in]argPointer to nanosecs_rel_t variable. The value is interpreted as relative timeout in nanoseconds in case of a positive value. See Timeouts for special timeouts.
Returns
0 on success, otherwise:
  • -EFAULT: It was not possible to access user space memory area at the specified address.

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Kernel-based task
  • User-space task (RT, non-RT)

Rescheduling: never.

Examples:
rtcansend.c.
#define RTCAN_RTIOC_TAKE_TIMESTAMP   _IOW(RTIOC_TYPE_CAN, 0x09, int)

Enable or disable storing a high precision timestamp upon reception of a CAN frame.

A newly created socket takes no timestamps by default.

Parameters
[in]argint variable, see Timestamp switches
Returns
0 on success.

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Kernel-based task
  • User-space task (RT, non-RT)
Note
Activating taking timestamps only has an effect on newly received CAN messages from the bus. Frames that already are in the socket buffer do not have timestamps if it was deactivated before. See Receive for more details.

Rescheduling: never.

Examples:
rtcanrecv.c.
#define SIOCGCANBAUDRATE   _IOWR(RTIOC_TYPE_CAN, 0x02, struct ifreq)

Get baud rate.

Parameters
[in,out]argPointer to interface request structure buffer (struct ifreq from linux/if.h). ifr_name must hold a valid CAN interface name, ifr_ifru will be filled with an instance of can_baudrate_t.
Returns
0 on success, otherwise:
  • -EFAULT: It was not possible to access user space memory area at the specified address.
  • -ENODEV: No device with specified name exists.
  • -EINVAL: No baud rate was set yet.

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Kernel-based task
  • User-space task (RT, non-RT)

Rescheduling: never.

#define SIOCGCANCTRLMODE   _IOWR(RTIOC_TYPE_CAN, 0x08, struct ifreq)

Get special controller modes.

Parameters
[in]argPointer to interface request structure buffer (struct ifreq from linux/if.h). ifr_name must hold a valid CAN interface name, ifr_ifru must be filled with an instance of can_ctrlmode_t.
Returns
0 on success, otherwise:
  • -EFAULT: It was not possible to access user space memory area at the specified address.
  • -ENODEV: No device with specified name exists.
  • -EINVAL: No baud rate was set yet.

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Kernel-based task
  • User-space task (RT, non-RT)

Rescheduling: possible.

#define SIOCGCANCUSTOMBITTIME   _IOWR(RTIOC_TYPE_CAN, 0x04, struct ifreq)

Get custum bit-time parameters.

Parameters
[in,out]argPointer to interface request structure buffer (struct ifreq from linux/if.h). ifr_name must hold a valid CAN interface name, ifr_ifru will be filled with an instance of struct can_bittime.
Returns
0 on success, otherwise:
  • -EFAULT: It was not possible to access user space memory area at the specified address.
  • -ENODEV: No device with specified name exists.
  • -EINVAL: No baud rate was set yet.

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Kernel-based task
  • User-space task (RT, non-RT)

Rescheduling: never.

#define SIOCGCANSTATE   _IOWR(RTIOC_TYPE_CAN, 0x06, struct ifreq)

Get current state of CAN controller.

States are divided into main states and additional error indicators. A CAN controller is always in exactly one main state. CAN bus errors are registered by the CAN hardware and collected by the driver. There is one error indicator (bit) per error type. If this IOCTL is triggered the error types which occured since the last call of this IOCTL are reported and thereafter the error indicators are cleared. See also CAN controller states.

Parameters
[in,out]argPointer to interface request structure buffer (struct ifreq from linux/if.h). ifr_name must hold a valid CAN interface name, ifr_ifru will be filled with an instance of can_mode_t.
Returns
0 on success, otherwise:
  • -EFAULT: It was not possible to access user space memory area at the specified address.
  • -ENODEV: No device with specified name exists.

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Kernel-based task
  • User-space task (RT, non-RT)

Rescheduling: possible.

#define SIOCGIFINDEX   defined_by_kernel_header_file

Get CAN interface index by name.

Parameters
[in,out]argPointer to interface request structure buffer (struct ifreq from linux/if.h). If ifr_name holds a valid CAN interface name ifr_ifindex will be filled with the corresponding interface index.
Returns
0 on success, otherwise:
  • -EFAULT: It was not possible to access user space memory area at the specified address.
  • -ENODEV: No device with specified name exists.

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Kernel-based task
  • User-space task (RT, non-RT)

Rescheduling: never.

Examples:
rtcan_rtt.c, rtcanconfig.c, rtcanrecv.c, and rtcansend.c.
#define SIOCSCANBAUDRATE   _IOW(RTIOC_TYPE_CAN, 0x01, struct ifreq)

Set baud rate.

The baudrate must be specified in bits per second. The driver will try to calculate resonable CAN bit-timing parameters. You can use SIOCSCANCUSTOMBITTIME to set custom bit-timing.

Parameters
[in]argPointer to interface request structure buffer (struct ifreq from linux/if.h). ifr_name must hold a valid CAN interface name, ifr_ifru must be filled with an instance of can_baudrate_t.
Returns
0 on success, otherwise:
  • -EFAULT: It was not possible to access user space memory area at the specified address.
  • -ENODEV: No device with specified name exists.
  • -EINVAL: No valid baud rate, see can_baudrate_t.
  • -EDOM : Baud rate not possible.
  • -EAGAIN: Request could not be successully fulfilled. Try again.

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Kernel-based task
  • User-space task (RT, non-RT)
Note
Setting the baud rate is a configuration task. It should be done deliberately or otherwise CAN messages will likely be lost.

Rescheduling: possible.

Examples:
rtcanconfig.c.
#define SIOCSCANCTRLMODE   _IOW(RTIOC_TYPE_CAN, 0x07, struct ifreq)

Set special controller modes.

Various special controller modes could be or'ed together (see CAN_CTRLMODE for further information).

Parameters
[in]argPointer to interface request structure buffer (struct ifreq from linux/if.h). ifr_name must hold a valid CAN interface name, ifr_ifru must be filled with an instance of can_ctrlmode_t.
Returns
0 on success, otherwise:
  • -EFAULT: It was not possible to access user space memory area at the specified address.
  • -ENODEV: No device with specified name exists.
  • -EINVAL: No valid baud rate, see can_baudrate_t.
  • -EAGAIN: Request could not be successully fulfilled. Try again.

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Kernel-based task
  • User-space task (RT, non-RT)
Note
Setting special controller modes is a configuration task. It should be done deliberately or otherwise CAN messages will likely be lost.

Rescheduling: possible.

Examples:
rtcanconfig.c.
#define SIOCSCANCUSTOMBITTIME   _IOW(RTIOC_TYPE_CAN, 0x03, struct ifreq)

Set custom bit time parameter.

Custem-bit time could be defined in various formats (see struct can_bittime).

Parameters
[in]argPointer to interface request structure buffer (struct ifreq from linux/if.h). ifr_name must hold a valid CAN interface name, ifr_ifru must be filled with an instance of struct can_bittime.
Returns
0 on success, otherwise:
  • -EFAULT: It was not possible to access user space memory area at the specified address.
  • -ENODEV: No device with specified name exists.
  • -EINVAL: No valid baud rate, see can_baudrate_t.
  • -EAGAIN: Request could not be successully fulfilled. Try again.

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Kernel-based task
  • User-space task (RT, non-RT)
Note
Setting the bit-time is a configuration task. It should be done deliberately or otherwise CAN messages will likely be lost.

Rescheduling: possible.

Examples:
rtcanconfig.c.
#define SIOCSCANMODE   _IOW(RTIOC_TYPE_CAN, 0x05, struct ifreq)

Set operation mode of CAN controller.

See CAN controller modes for available modes.

Parameters
[in]argPointer to interface request structure buffer (struct ifreq from linux/if.h). ifr_name must hold a valid CAN interface name, ifr_ifru must be filled with an instance of can_mode_t.
Returns
0 on success, otherwise:
  • -EFAULT: It was not possible to access user space memory area at the specified address.
  • -ENODEV: No device with specified name exists.
  • -EAGAIN: (CAN_MODE_START, CAN_MODE_STOP) Could not successfully set mode, hardware is busy. Try again.
  • -EINVAL: (CAN_MODE_START) Cannot start controller, set baud rate first.
  • -ENETDOWN: (CAN_MODE_SLEEP) Cannot go into sleep mode because controller is stopped or bus off.
  • -EOPNOTSUPP: unknown mode

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Kernel-based task
  • User-space task (RT, non-RT)
Note
Setting a CAN controller into normal operation after a bus-off can take some time (128 occurrences of 11 consecutive recessive bits). In such a case, although this IOCTL will return immediately with success and SIOCGCANSTATE will report CAN_STATE_ACTIVE, bus-off recovery may still be in progress.
If a controller is bus-off, setting it into stop mode will return no error but the controller remains bus-off.

Rescheduling: possible.

Examples:
rtcanconfig.c.
#define SOL_CAN_RAW   103

CAN socket levels.

Used for Sockopts for the particular protocols.

Examples:
rtcan_rtt.c, rtcanrecv.c, and rtcansend.c.

Typedef Documentation

typedef struct can_filter can_filter_t

Filter for reception of CAN messages.

This filter works as follows: A received CAN ID is AND'ed bitwise with can_mask and then compared to can_id. This also includes the CAN_EFF_FLAG and CAN_RTR_FLAG of CAN_xxx_FLAG. If this comparison is true, the message will be received by the socket. The logic can be inverted with the can_id flag CAN_INV_FILTER :

1 if (can_id & CAN_INV_FILTER) {
2  if ((received_can_id & can_mask) != (can_id & ~CAN_INV_FILTER))
3  accept-message;
4 } else {
5  if ((received_can_id & can_mask) == can_id)
6  accept-message;
7 }

Multiple filters can be arranged in a filter list and set with Sockopts. If one of these filters matches a CAN ID upon reception of a CAN frame, this frame is accepted.

typedef struct can_frame can_frame_t

Raw CAN frame.

Central structure for receiving and sending CAN frames.

Examples:
rtcanrecv.c.

Enumeration Type Documentation

enum CAN_BITTIME_TYPE

Supported CAN bit-time types.

Enumerator
CAN_BITTIME_STD 

Standard bit-time definition according to Bosch.

CAN_BITTIME_BTR 

Hardware-specific BTR bit-time definition.

enum CAN_MODE
Enumerator
CAN_MODE_STOP 

Set controller in Stop mode (no reception / transmission possible)

CAN_MODE_START 

Set controller into normal operation.
Coming from stopped mode or bus off, the controller begins with no errors in CAN_STATE_ACTIVE.

CAN_MODE_SLEEP 

Set controller into Sleep mode.
This is only possible if the controller is not stopped or bus-off.
Notice that sleep mode will only be entered when there is no bus activity. If the controller detects bus activity while "sleeping" it will go into operating mode again.
To actively leave sleep mode again trigger CAN_MODE_START.

enum CAN_STATE
Enumerator
CAN_STATE_ERROR_ACTIVE 

CAN controller is error active.

CAN_STATE_ERROR_WARNING 

CAN controller is error active, warning level is reached.

CAN_STATE_ERROR_PASSIVE 

CAN controller is error passive.

CAN_STATE_BUS_OFF 

CAN controller went into Bus Off.

CAN_STATE_SCANNING_BAUDRATE 

CAN controller is scanning to get the baudrate.

CAN_STATE_STOPPED 

CAN controller is in stopped mode.

CAN_STATE_SLEEPING 

CAN controller is in Sleep mode.