kernel/2.6/Documentation/networking/can/can-sockets.txt

   1 ============================================================================
   2
   3 can-sockets.txt : general socketCAN API documentation
   4
   5 See can-raw.txt and can-bcm.txt for in-depth documentation
   6 on RAW and BCM sockets.
   7
   8 Part of the documentation for the socketCAN subsystem
   9
  10 This file contains:
  11
  12   1 How to use Socket CAN
  13     1.1 Timestamps
  14
  15 ============================================================================
  16
  17 1. How to use Socket CAN
  18 ------------------------
  19
  20   Like TCP/IP, you first need to open a socket for communicating over a
  21   CAN network. Since Socket CAN implements a new protocol family, you
  22   need to pass PF_CAN as the first argument to the socket(2) system
  23   call. Currently, there are two CAN protocols to choose from, the raw
  24   socket protocol and the broadcast manager (BCM). So to open a socket,
  25   you would write
  26
  27     s = socket(PF_CAN, SOCK_RAW, CAN_RAW);
  28
  29   and
  30
  31     s = socket(PF_CAN, SOCK_DGRAM, CAN_BCM);
  32
  33   respectively.  After the successful creation of the socket, you would
  34   normally use the bind(2) system call to bind the socket to a CAN
  35   interface (which is different from TCP/IP due to different addressing
  36   - see overview.txt, chapter 3). After binding (CAN_RAW) or connecting
  37   (CAN_BCM) the socket, you can read(2) and write(2) from/to the socket
  38   or use send(2), sendto(2), sendmsg(2) and the recv* counterpart operations
  39   on the socket as usual. There are also CAN specific socket options
  40   described below.
  41
  42   The basic CAN frame structure and the sockaddr structure are defined
  43   in include/linux/can.h:
  44
  45     struct can_frame {
  46             canid_t can_id;  /* 32 bit CAN_ID + EFF/RTR/ERR flags */
  47             __u8    can_dlc; /* data length code: 0 .. 8 */
  48             __u8    data[8] __attribute__((aligned(8)));
  49     };
  50
  51   The alignment of the (linear) payload data[] to a 64bit boundary
  52   allows the user to define own structs and unions to easily access the
  53   CAN payload. There is no given byteorder on the CAN bus by
  54   default. A read(2) system call on a CAN_RAW socket transfers a
  55   struct can_frame to the user space.
  56
  57   The sockaddr_can structure has an interface index like the
  58   PF_PACKET socket, that also binds to a specific interface:
  59
  60     struct sockaddr_can {
  61             sa_family_t can_family;
  62             int         can_ifindex;
  63             union {
  64                     /* transport protocol class address info (e.g. ISOTP) */
  65                     struct { canid_t rx_id, tx_id; } tp;
  66
  67                     /* reserved for future CAN protocols address information */
  68             } can_addr;
  69     };
  70
  71   To determine the interface index an appropriate ioctl() has to
  72   be used (example for CAN_RAW sockets without error checking):
  73
  74     int s;
  75     struct sockaddr_can addr;
  76     struct ifreq ifr;
  77
  78     s = socket(PF_CAN, SOCK_RAW, CAN_RAW);
  79
  80     strcpy(ifr.ifr_name, "can0" );
  81     ioctl(s, SIOCGIFINDEX, &ifr);
  82
  83     addr.can_family = AF_CAN;
  84     addr.can_ifindex = ifr.ifr_ifindex;
  85
  86     bind(s, (struct sockaddr *)&addr, sizeof(addr));
  87
  88     (..)
  89
  90   To bind a socket to all(!) CAN interfaces the interface index must
  91   be 0 (zero). In this case the socket receives CAN frames from every
  92   enabled CAN interface. To determine the originating CAN interface
  93   the system call recvfrom(2) may be used instead of read(2). To send
  94   on a socket that is bound to 'any' interface sendto(2) is needed to
  95   specify the outgoing interface.
  96
  97   Reading CAN frames from a bound CAN_RAW socket (see above) consists
  98   of reading a struct can_frame:
  99
 100     struct can_frame frame;
 101
 102     nbytes = read(s, &frame, sizeof(struct can_frame));
 103
 104     if (nbytes < 0) {
 105             perror("can raw socket read");
 106             return 1;
 107     }
 108
 109     /* paranoid check ... */
 110     if (nbytes < sizeof(struct can_frame)) {
 111             fprintf(stderr, "read: incomplete CAN frame\n");
 112             return 1;
 113     }
 114
 115     /* do something with the received CAN frame */
 116
 117   Writing CAN frames can be done similarly, with the write(2) system call:
 118
 119     nbytes = write(s, &frame, sizeof(struct can_frame));
 120
 121   When the CAN interface is bound to 'any' existing CAN interface
 122   (addr.can_ifindex = 0) it is recommended to use recvfrom(2) if the
 123   information about the originating CAN interface is needed:
 124
 125     struct sockaddr_can addr;
 126     struct ifreq ifr;
 127     socklen_t len = sizeof(addr);
 128     struct can_frame frame;
 129
 130     nbytes = recvfrom(s, &frame, sizeof(struct can_frame),
 131                       0, (struct sockaddr*)&addr, &len);
 132
 133     /* get interface name of the received CAN frame */
 134     ifr.ifr_ifindex = addr.can_ifindex;
 135     ioctl(s, SIOCGIFNAME, &ifr);
 136     printf("Received a CAN frame from interface %s", ifr.ifr_name);
 137
 138   To write CAN frames on sockets bound to 'any' CAN interface the
 139   outgoing interface has to be defined certainly.
 140
 141     strcpy(ifr.ifr_name, "can0");
 142     ioctl(s, SIOCGIFINDEX, &ifr);
 143     addr.can_ifindex = ifr.ifr_ifindex;
 144     addr.can_family  = AF_CAN;
 145
 146     nbytes = sendto(s, &frame, sizeof(struct can_frame),
 147                     0, (struct sockaddr*)&addr, sizeof(addr));
 148
 149   1.1 Timestamps
 150
 151   For applications in the CAN environment it is often of interest an
 152   accurate timestamp of the instant a message from CAN bus has been received.
 153   Such a timestamp can be read with ioctl(2) after reading a message from
 154   the socket. Example:
 155
 156     struct timeval tv;
 157     ioctl(s, SIOCGSTAMP, &tv);
 158
 159   The timestamp on Linux has a resolution of one microsecond and it is set
 160   automatically at the reception of a CAN frame.
 161
 162   Alternatively the timestamp can be obtained as a control message (cmsg) using
 163   the recvmsg() system call. After enabling the timestamps in the cmsg's by
 164
 165     const int timestamp = 1;
 166     setsockopt(s, SOL_SOCKET, SO_TIMESTAMP, &timestamp, sizeof(timestamp));
 167
 168   the data structures filled by recvmsg() need to be parsed for
 169   cmsg->cmsg_type == SO_TIMESTAMP to get the timestamp. See cmsg() manpage.
 170