rtcan.h

Peak-CAN控制器(PCI接口)的驱动程序

/**
 * @file
 * Real-Time Driver Model for RT-Socket-CAN, CAN device profile header
 *
 * @note Copyright (C) 2006 Wolfgang Grandegger <[e-mail]>
 *
 * @note Copyright (C) 2005, 2006 Sebastian Smolorz
 *                         <[e-mail]>
 *
 * This RTDM CAN device profile header is based on:
 *
 * include/linux/can.h, include/linux/socket.h, net/can/pf_can.h in
 * linux-can.patch, a CAN socket framework for Linux
 *
 * Copyright (C) 2004, 2005,
 * Robert Schwebel, Benedikt Spranger, Marc Kleine-Budde, Pengutronix
 *
 * 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.
 *
 * @ingroup rtcan
 */

/*!
 * @ingroup profiles
 * @defgroup rtcan 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 ([e-mail]) or directly to the authors
 * ([e-mail] or [e-mail]).
 * @n
 * @par Device Characteristics
 * @n
 * @ref rtdm_device.device_flags "Device Flags": @c RTDM_PROTOCOL_DEVICE @n
 * @n
 * @ref rtdm_device.protocol_family "Protocol Family": @c PF_CAN @n
 * @n
 * @ref rtdm_device.socket_type "Socket Type": @c SOCK_RAW @n
 * @n
 * @ref rtdm_device.device_class "Device Class": @c RTDM_CLASS_CAN @n
 * @n
 *
 * @par Supported Operations
 * @n
 * @b Socket @n
 * Environments: non-RT (RT optional)@n
 * @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
 * Environments: non-RT (RT optional)@n
 * @n
 * Specific return values: none @n
 * @n
 * @n
 * @b IOCTL @n
 * Mandatory Environments: see @ref IOCTLs "below" @n
 * Specific return values: see @ref IOCTLs "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
 * Environments: non-RT (RT optional)@n
 * @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
 * <b>Setsockopt, Getsockopt</b>@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_PROTO_RAW)
 *   - Option @ref CAN_RAW_FILTER : CAN filter list
 *   - Option @ref CAN_RAW_ERR_FILTER : CAN error mask
 *   - Option @ref CAN_RAW_TX_LOOPBACK : CAN TX loopback to local sockets
 *   .
 * .
 * @n
 * Environments: non-RT (RT optional)@n
 * Specific return values: see links to options above. @n
 * @n
 * @n
 * @anchor Recv
 * <b>Recv, Recvfrom, Recvmsg</b> @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 <TT>struct msghdr</TT> 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
 * Environments: RT (non-RT optional)@n
 * @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
 * <b>Send, Sendto, Sendmsg</b> @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.)
 * .
 * Environments: RT (non-RT optional)@n
 * @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.
 *
 * @{
 */

#ifndef _RTCAN_H
#define _RTCAN_H


#ifdef __KERNEL__

#include <linux/net.h>
#include <linux/socket.h>
#include <linux/if.h>

#else  /* !__KERNEL__ */

#include <net/if.h>

#endif /* !__KERNEL__ */


#include <rtdm/rtdm.h>

#ifndef AF_CAN

/** CAN address family */
#define AF_CAN	29

/** CAN protocol family */
#define PF_CAN	AF_CAN

#endif

/** Particular CAN protocols
 *
 *  Currently only the RAW protocol is supported.
 */
#define CAN_RAW  0

/** CAN socket levels
 *
 *  Used for @ref Sockopts for the particular protocols.
 */
#define SOL_CAN_RAW 103

/** Type of CAN id (see @ref CAN_xxx_MASK and @ref CAN_xxx_FLAG) */
typedef uint32_t can_id_t;
typedef uint32_t canid_t;

/** Type of CAN error mask */
typedef can_id_t can_err_mask_t;

/*!
 * @anchor CAN_xxx_MASK @name CAN ID masks
 * Bit masks for masking CAN IDs
 * @{ */

/** Bit mask for extended CAN IDs */
#define CAN_EFF_MASK  0x1FFFFFFF

/** Bit mask for standard CAN IDs */
#define CAN_SFF_MASK  0x000007FF

/** @} */


/*!
 * @anchor CAN_xxx_FLAG @name 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 flag */
#define CAN_ERR_FLAG  0x20000000 /**< error frame (see @ref Errors) */
/** @} */


/*!
 * @anchor CAN_PROTO @name CAN protocols
 * Possible protocols for PF_CAN protocol family
 * @{ */
enum CAN_PROTO {
    /** Raw protocol of @c PF_CAN, applicable to socket 
	type @c SOCK_RAW */
    CAN_PROTO_RAW,
    CAN_PROTO_MAX
};
/** @} */

#define CAN_BAUDRATE_UNKNOWN       ((uint32_t)-1)
#define CAN_BAUDRATE_UNCONFIGURED  0

/** 
 * Baudrate definition in bits per second 
 */
typedef uint32_t can_baudrate_t;


/** 
 * Supported CAN bit-time types
 */
enum CAN_BITTIME_TYPE {
    /** Standard bit-time definition according to Bosch */
    CAN_BITTIME_STD,  
    /** Hardware-specific BTR bit-time definition */
    CAN_BITTIME_BTR
};


/**
 * See @ref CAN_BITTIME_TYPE
 */
typedef enum CAN_BITTIME_TYPE can_bittime_type_t;

/**
 * Standard bit-time parameters according to Bosch
 */
struct can_bittime_std {
    uint32_t brp;        /**< Baud rate prescaler */
    uint8_t  prop_seg;   /**< from 1 to 8 */
    uint8_t  phase_seg1; /**< from 1 to 8 */
    uint8_t  phase_seg2; /**< from 1 to 8 */
    uint8_t  sjw:7;      /**< from 1 to 4 */
    uint8_t  sam:1;      /**< 1 - enable triple sampling */
};

/**
 * Hardware-specific BTR bit-times 
 */
struct can_bittime_btr {

    uint8_t  btr0;       /**< Bus timing register 0 */
    uint8_t  btr1;       /**< Bus timing register 1 */
};


/**
 * Custom CAN bit-time definition
 */
struct can_bittime {
    /** Type of bit-time definition */
    can_bittime_type_t type;
    union {
	/** Standard bit-time */
        struct can_bittime_std std;
	/** Hardware-spcific BTR bit-time */
        struct can_bittime_btr btr;
    };
};

/*!
 * @anchor CAN_MODE @name CAN operation modes
 * Modes into which CAN controllers can be set
 * @{ */
enum CAN_MODE {

    /** Set controller in Stop mode (no reception / transmission possible) */
    CAN_MODE_STOP = 0,

    /*! Set controller into normal operation. @n
     *  Coming from stopped mode or bus off, the controller begins with no