/** * @file * @note Copyright (C) 2006 Wolfgang Grandegger * * @note Copyright (C) 2005, 2006 Sebastian Smolorz * * * This program is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, but * WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * * General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program; if not, write to the Free Software Foundation, * Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ #ifndef _RTDM_CAN_H #define _RTDM_CAN_H #include #include #include /** * @ingroup rtdm_profiles * @defgroup rtdm_can CAN Devices * * 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 (Socketcan-core@lists.berlios.de) or directly to the authors * (wg@grandegger.com or Sebastian.Smolorz@stud.uni-hannover.de). * * @b Profile @b Revision: 2 * @n * @n * @par Device Characteristics * @n * @ref rtdm_driver_flags "Device Flags": @c RTDM_PROTOCOL_DEVICE @n * @n * @ref rtdm_driver.protocol_family "Protocol Family": @c PF_CAN @n * @n * @ref rtdm_driver.socket_type "Socket Type": @c SOCK_RAW @n * @n * @ref rtdm_driver_profile "Device Class": @c RTDM_CLASS_CAN @n * @n * * @par Supported Operations * @n * @b Socket @n * @coretags{secondary-only} * @n * Specific return values: * - -EPROTONOSUPPORT (Protocol is not supported by the driver. * See @ref CAN_PROTO "CAN protocols" * for possible protocols.) * . * @n * @n * @b Close @n * Blocking calls to any of the @ref Send or @ref Recv "Receive" functions * will be unblocked when the socket is closed and return with an error. @n * @n * @coretags{secondary-only} * @n * Specific return values: none @n * @n * @n * @b IOCTL @n * @coretags{task-unrestricted}. see @ref CANIOCTLs "below" * Specific return values: see @ref CANIOCTLs "below" @n * @n * @n * @anchor Bind * @b Bind @n * Binds a socket to one or all CAN devices (see struct sockaddr_can). If * a filter list has been defined with setsockopt (see @ref 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 @b all CAN frames on the specified interface(s). @n * @n * Binding to special interface index @c 0 will make the socket receive * CAN frames from all CAN interfaces. @n * @n * Binding to an interface index is also relevant for the @ref Send functions * because they will transmit a message over the interface the socket is * bound to when no socket address is given to them. @n * @n * @n * @coretags{secondary-only} * @n * 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.) * . * @n * @n * @anchor Sockopts * Setsockopt, Getsockopt@n * These functions allow to set and get various socket options. Currently, * only CAN raw sockets are supported. @n * @n * Supported Levels and Options: * @n * - Level @b SOL_CAN_RAW : CAN RAW protocol (see @ref CAN_RAW) * - Option @ref CAN_RAW_FILTER : CAN filter list * - Option @ref CAN_RAW_ERR_FILTER : CAN error mask * - Option @ref CAN_RAW_LOOPBACK : CAN TX loopback to local sockets * . * . * @n * @coretags{task-unrestricted} * Specific return values: see links to options above. @n * @n * @n * @anchor Recv * Recv, Recvfrom, Recvmsg @n * 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 @c SOCK_RAW, this is the size of struct can_frame. @n * @n * Unlike a call to one of the @ref 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. @n * @n * It is possible to receive a high precision timestamp with every CAN * message. The condition is a former instruction to the socket via * @ref RTCAN_RTIOC_TAKE_TIMESTAMP. The timestamp will be copied to the * @c msg_control buffer of struct msghdr if it points to a valid * memory location with size of @ref nanosecs_abs_t. If this * is a NULL pointer the timestamp will be discarded silently. @n * @n * @b Note: A @c msg_controllen of @c 0 upon completion of the function call * indicates that no timestamp is available for that message. * @n * @n * 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 @ref 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.) * . * @n * Supported Flags [out]: none @n * @n * @coretags{mode-unrestricted} * @n * Specific return values: * - Non-negative value (Indicating the successful reception of a CAN message. * For @c 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) * . * @n * @n * @anchor Send * Send, Sendto, Sendmsg @n * 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 @c SOCK_RAW, this is the size of struct can_frame. @n * @n * The following only applies to @c SOCK_RAW: If a socket address of * struct sockaddr_can is given, only @c 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. @n * @n * 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. @n * @n * @n * 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 @ref RTCAN_RTIOC_SND_TIMEOUT.) * . * @coretags{mode-unrestricted} * @n * 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 @e or: Invalid length of socket * address @e or: Invalid address family @e or: Data length code * of CAN frame not between 0 and 15 @e 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 - @c 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) * . * @b Note: A successful completion of the function call does not implicate a * successful transmission of the message. * * @{ * * @anchor CANutils @name CAN example and utility programs * @{ * @example rtcanconfig.c * @example rtcansend.c * @example rtcanrecv.c * @example can-rtt.c * @} * * @} */ #endif /* !_RTDM_CAN_H */