===== Common CAN API =====


Everybody interested in a common interface to CAN hardware, independent
of the operating system, is invited to provide his application requirements for a CAN API on this page.


  * message ID up to four byte
  * message queue for receive messages
  * message queue for transmit messages
  * time stamp
    * 1 µs resolution
    * POSIX compliant data structure
  * interface configuration with connection string
  * blocking read()
  * Set receive filters if supported by the hardware

==== Suggested message structure ====

  /**
   * The CAN message structure.
   * Used for all data transfers between the application and the driver
   * using read() or write().
   */
   typedef struct {
    /** flags, indicating or controlling special message properties */
    int             flags;       /**< Bit 0: Standard (11) or extended (29) length message */
                                 /**  Bit 1: Standard or RTR message */
    int             cob;         /**< Bit 0..3 CAN object number, used in Full CAN  */
                                 /**  Bit 4..7 CAN controller number, used if multiple buses present */
                                 /**    0 could mean 'default channel' in both cases */
    unsigned   long id;          /**< CAN message ID, 4 bytes  */
    struct timeval  timestamp;   /**< time stamp for received messages */
    short      int  length;      /**< number of bytes in the CAN message */
    unsigned   char data[CAN_MSG_LENGTH]; /**< data, 0...8, 64 bytes */
  } canmsg_t;


To see how can4linux defines it, and the flag values, have a look at [[drivers:main|[1].]]
Using struct timeval allows to store a time stamp with an absolute time with µs resolution.
Because this struct lacks a time zone information and daylight saving time information,
use GMT. 


  /** 
   * The CAN initialization structure.
   * Used to configure the interface in a way that does not depend on 
   * the specific hardware. Depending on the underlying hardware,
   * some fields may be not supported.
   */
  typedef struct {
    const char *   connection;     /**< Vendor specific parameters. */
    short int      btr0;           /**< Bit timing register 0 (82c200 style) */
    short int      btr1;           /**< Bit timing register 1 */
  /*int            bitrate;        alternative: < Bitrate: 125, 250... */
    int            read_timeout;   /**< Maximum read() blocking time in ms */
                                   /**    0 == non blocking **/
  } caninit_t;


read() should be able to block and wait for some time if there 
is no message in the receiving queue.
The timeout value can be specified when opening the interface.

To set driver parameters UNIX uses the ioctl(fd, request, parameter) call.

        int ioctl(int d, int request, ...); see ioctl(2).


That means you could have requests like

   CANGETTIMEOUT
   CANSETTIMEOUT
   CANGETBITRATE
   CANSETBITRATE
   CANGETRXQUELENGTH
   CANSETRXQUELENGTH
   CANGETSTATUS (used to detect busoff, error counters and the like)
   or for more sophisticated bit timings:
   CANSETPHASE1
   CANSETPHASE2
   CANSETBRPS - Bit Rate Pre Scaler