rtcan.h

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

     *  errors in @ref CAN_STATE_ACTIVE. */
    CAN_MODE_START,

   /*! Set controller into Sleep mode. @n
    *  This is only possible if the controller is not stopped or bus-off. @n
    *  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. @n
    *  To actively leave sleep mode again trigger @c CAN_MODE_START. */
    CAN_MODE_SLEEP
};
/** @} */

/** See @ref CAN_MODE */
typedef enum CAN_MODE can_mode_t;

/*!
 * @anchor CAN_CTRLMODE @name CAN controller modes
 * Special CAN controllers modes, which can be or'ed together.
 * @{ */
/** Listen-Only mode */
#define CAN_CTRLMODE_LISTENONLY 0x1
/** Loopback mode */
#define CAN_CTRLMODE_LOOPBACK   0x2
/** @} */

/** See @ref CAN_CTRLMODE */
typedef int can_ctrlmode_t;

/*!
 * @anchor CAN_STATE @name CAN controller states
 * States a CAN controller can be in.
 * @{ */
enum CAN_STATE {
    /** CAN controller is error active */
    CAN_STATE_ACTIVE = 0,

    /** CAN controller is error active, warning level is reached */
    CAN_STATE_BUS_WARNING,

    /** CAN controller is error passive */
    CAN_STATE_BUS_PASSIVE,

    /** CAN controller went into Bus Off */
    CAN_STATE_BUS_OFF,

    /** CAN controller is scanning to get the baudrate */
    CAN_STATE_SCANNING_BAUDRATE,

    /** CAN controller is in stopped mode */
    CAN_STATE_STOPPED,

    /** CAN controller is in Sleep mode */
    CAN_STATE_SLEEPING,
};
/** @} */

/** See @ref CAN_STATE */
typedef enum CAN_STATE can_state_t;

#define CAN_STATE_OPERATING(state) ((state) < CAN_STATE_BUS_OFF)

/**
 * Filter for reception of CAN messages.
 *
 * This filter works as follows:
 * A received CAN ID is AND'ed bitwise with @c can_mask and then compared to
 * @c can_id. If this comparison is true the message will be received by the
 * socket.
 *
 * Multiple filters can be arranged in a filter list and set with 
 * @ref Sockopts. If one of these filters matches a CAN ID upon reception 
 * of a CAN frame, this frame is accepted.
 *
 * @note Only @ref CAN_EFF_FLAG of @ref CAN_xxx_FLAG "CAN ID flags" is
 * valid for @c can_id and none for @c can_mask. This means that the RTR bit
 * is not taken into account while filtering messages.
 *
 * Extended IDs are received only if @ref CAN_EFF_FLAG is set in
 * @c can_id. If it is cleared only standard IDs are accepted.
 */
typedef struct can_filter {

    /** CAN ID which must match with incoming IDs after passing the mask */
    uint32_t    can_id;

    /** Mask which is applied to incoming IDs. See @ref CAN_xxx_MASK
     *  "CAN ID masks" if exactly one CAN ID should come through. */
    uint32_t    can_mask;
} can_filter_t;


/**
 * Socket address structure for the CAN address family
 */
struct sockaddr_can {
    /** CAN address family, must be @c AF_CAN */    
    sa_family_t  can_family;
    /** Interface index of CAN controller. See @ref SIOCGIFINDEX. */
    int          can_ifindex;
};


/**
 * Raw CAN frame
 *
 * Central structure for receiving and sending CAN frames.
 */
typedef struct can_frame {

    /** CAN ID of the frame
     *
     *  See @ref CAN_xxx_FLAG "CAN ID flags" for special bits.
     */
    can_id_t     can_id;

    /** Size of the payload in bytes */
    uint8_t      can_dlc;

    /** Payload data bytes */
    uint8_t      data[8] __attribute__ ((aligned(8)));
} can_frame_t;



/*!
 * @anchor RTCAN_TIMESTAMPS   @name Timestamp switches
 * Arguments to pass to @ref RTCAN_RTIOC_TAKE_TIMESTAMP
 * @{ */
#define RTCAN_TAKE_NO_TIMESTAMPS    0   /**< Switch off taking timestamps */
#define RTCAN_TAKE_TIMESTAMPS       1   /**< Do take timestamps */
/** @} */


#define RTIOC_TYPE_CAN              RTDM_CLASS_CAN


/*!
 * @anchor Rawsockopts @name RAW socket options
 * Setting and getting CAN RAW socket options.
 * @{ */

/**
 * CAN filter definition
 *
 * A CAN raw filter list with elements of struct can_filter can be installed 
 * with @c 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.
 * @n
 * If the socket was already bound with @ref 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.
 * @n
 * @n
 * @param [in] level @b SOL_CAN_RAW 
 *
 * @param [in] optname @b CAN_RAW_FILTER
 *
 * @param [in] optval Pointer to array of struct can_filter.
 *
 * @param [in] optlen Size of filter list: count * sizeof( struct can_filter).
 * @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 length "optlen")
 * - -ENOSPC (No space to store filter list, check RT-Socket-CAN kernel
 *            parameters)
 * .
 */
#define CAN_RAW_FILTER      0x1

/**
 * CAN error mask
 *
 * A CAN error mask (see @ref Errors) can be set with @c setsockopt. This 
 * mask is then used to decided if error frames are send to this socket 
 * in case of error condidtions. The error frames are marked with the 
 * @ref CAN_ERR_FLAG of @ref CAN_xxx_FLAG and must be handled by the 
 * application properly. A detailed description of the error can be
 * found in the @c can_id and the @c data fields of struct can_frame 
 * (see @ref Errors for futher details). 
 *
 * @n
 * @param [in] level @b SOL_CAN_RAW 
 *
 * @param [in] optname @b CAN_RAW_ERR_FILTER
 *
 * @param [in] optval Pointer to error mask of type can_err_mask_t.
 *
 * @param [in] optlen Size of error mask: sizeof(can_err_mask_t).
 *
 * 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.)
 * - -EINVAL (Invalid length "optlen")
 * .
 */
#define CAN_RAW_ERR_FILTER  0x2

/**
 * CAN TX loopback
 *
 * The TX loopback to other local sockets can be selected with this
 * @c 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.
 *
 * @n
 * @param [in] level @b SOL_CAN_RAW
 *
 * @param [in] optname @b CAN_RAW_TX_LOOPBACK
 *
 * @param [in] optval Pointer to integer value.
 *
 * @param [in] optlen Size of int: sizeof(int).
 *
 * 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.)
 * - -EINVAL (Invalid length "optlen")
 * - -EOPNOTSUPP (not supported, check RT-Socket-CAN kernel parameters).
 */
#define CAN_RAW_TX_LOOPBACK  0x3

/** @} */

/*!
 * @anchor IOCTLs @name IOCTLs
 * CAN device IOCTLs
 * @{ */

/**
 * Get CAN interface index by name
 *
 * @param [in,out] arg Pointer to interface request structure buffer
 *                     (<TT>struct ifreq</TT> from linux/if.h). If
 *                     <TT>ifr_name</TT> holds a valid CAN interface name
 *                     <TT>ifr_ifindex</TT> will be filled with the
 *                     corresponding interface index.
 *
 * @return 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.
 *
 */
#ifndef SIOCGIFINDEX
#define SIOCGIFINDEX \
            _IOWR(RTIOC_TYPE_CAN, 0x00, struct ifreq)
#endif

/**
 * 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
 * @ref SIOCSCANCUSTOMBITTIME to set custom bit-timing. 
 *
 * @param [in] arg Pointer to interface request structure buffer
 *                 (<TT>struct ifreq</TT> from linux/if.h).
 *                 <TT>ifr_name</TT> must hold a valid CAN interface name,
 *                 <TT>ifr_ifru</TT> must be filled with an instance of
 *                 @ref can_baudrate_t.
 *
 * @return 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 @ref 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.
 */
#define SIOCSCANBAUDRATE \
            _IOW(RTIOC_TYPE_CAN, 0x01, struct ifreq)

/**
 * Get baud rate
 *
 * @param [in,out] arg Pointer to interface request structure buffer
 *                    (<TT>struct ifreq</TT> from linux/if.h).
 *                    <TT>ifr_name</TT> must hold a valid CAN interface name,
 *                    <TT>ifr_ifru</TT> will be filled with an instance of
 *                    @ref can_baudrate_t.
 *
 * @return 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 SIOCGCANBAUDRATE \
            _IOWR(RTIOC_TYPE_CAN, 0x02, struct ifreq)

/**
 * Set custom bit time parameter
 *
 * Custem-bit time could be defined in various formats (see 
 * struct can_bittime).
 *
 * @param [in] arg Pointer to interface request structure buffer
 *                 (<TT>struct ifreq</TT> from linux/if.h).
 *                 <TT>ifr_name</TT> must hold a valid CAN interface name,
 *                 <TT>ifr_ifru</TT> must be filled with an instance of
 *                 struct can_bittime.
 *
 * @return 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 @ref 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.
 */
#define SIOCSCANCUSTOMBITTIME \
            _IOW(RTIOC_TYPE_CAN, 0x03, struct ifreq)

/**
 * Get custum bit-time parameters
 *
 * @param [in,out] arg Pointer to interface request structure buffer
 *                    (<TT>struct ifreq</TT> from linux/if.h).
 *                    <TT>ifr_name</TT> must hold a valid CAN interface name,
 *                    <TT>ifr_ifru</TT> will be filled with an instance of
 *                    struct can_bittime.
 *
 * @return 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: