doc/socket-api.tex

   1 % $Id$
   2
   3 \newpage
   4 \section{Allgemeine Hinweise zur Socket-API beim \LL}
   5 \label{socket-api}
   6
   7 Für die Kommunikation auf dem CAN-Bus wird eine neue Protokoll-Familie
   8 \verb+PF_CAN+ im Socket-Layer implementiert. Aus Anwender-
   9 bzw. Programmierersicht wird mit den \LL-Sockets analog zu
  10 Internet-Protokoll-Sockets (Protokoll-Familie \verb+PF_INET+) mit den
  11 üblichen Systemaufrufen \man{socket}{2}, \man{bind}{2}, \man{listen}{2},
  12 \man{accept}{2}, \man{connect}{2}, \man{read}{2},
  13 \man{write}{2} und \man{close}{2} genutzt. Siehe dazu auch die
  14 Einleitung in Kapitel \ref{intro}.\\
  15
  16 Im Gegensatz zur Adressstruktur der Internet-Adressen
  17 (\verb+sockaddr_in+) benötigt die Adressierung der PF\_CAN-Sockets
  18 andere Inhalte. Die Adressstruktur \verb+sockaddr_can+ ist in der
  19 Include-Datei \verb+af_can.h+ definiert:
  20
  21 \begin{code}
  22 struct sockaddr_can {
  23     sa_family_t   can_family;
  24     int           can_ifindex;
  25     union {
  26         struct { canid_t rx_id, tx_id; } tp16;
  27         struct { canid_t rx_id, tx_id; } tp20;
  28         struct { canid_t rx_id, tx_id; } mcnet;
  29     } can_addr;
  30 };
  31 \end{code}
  32
  33 Neben dem Interface-Index des CAN-Interfaces sind hierbei besonders
  34 für die jeweiligen Transport-Protokolle die CAN-IDs \verb+tx_id+ und
  35 \verb+rx_id+ relevant. Transport-Protokolle bilden auf dem CAN-Bus
  36 auf zwei CAN-IDs eine virtuelle Punkt-zu-Punkt-Verbindung ab.\\
  37
  38 Eine weitere wichtige Struktur stellt das CAN-Frame dar, dass in
  39 der Include-Datei \verb+can.h+ definiert ist:
  40
  41 \begin{code}
  42 typedef __u32 canid_t;
  43
  44 struct can_frame {
  45     canid_t can_id;      /* 32 bit CAN_ID + EFF/RTR flags */
  46     __u8    can_dlc;     /* data length code: 0 .. 8 */
  47     __u8    data[8] __attribute__ ((aligned(8)));
  48 };
  49
  50 /* special address description flags for the CAN_ID */
  51 #define CAN_EFF_FLAG 0x80000000U /* EFF/SFF is set in the MSB */
  52 #define CAN_RTR_FLAG 0x40000000U /* remote transmission request */
  53
  54 /* valid bits in CAN ID for frame formats */
  55 #define CAN_SFF_MASK 0x000007FFU /* standard frame format (SFF) */
  56 #define CAN_EFF_MASK 0x1FFFFFFFU /* extended frame format (EFF) */
  57 \end{code}
  58
  59 Die definierte Struktur \verb+can_frame+ enthält die Elemente eines
  60 CAN-Frame, wie es auf dem CAN-Bus definiert ist. Die Anordnung der
  61 Nutzdaten (Byte-Order, Word-Order, Little/Big Endian) ist auf dem
  62 CAN-Bus generell nicht definiert, weshalb die Datenelemente
  63 \verb+data[]+ als Array von 8 Byte ausgeführt sind. Da die
  64 Datenelemente allerdings auf einer 8 Byte Speichergrenze ausgerichtet,
  65 ist hier auch ein Zugriff bis zu einer Breite von 64 Bit möglich:
  66
  67 \begin{code}
  68 #define U64_DATA(p) (*(unsigned long long*)(p)->data)
  69
  70 U64_DATA(&myframe) = 0xFFFFFFFFFFFFFFFFULL;
  71 U64_DATA(&myframe) = 0;
  72 \end{code}
  73
  74 Durch die Trennung der Informationen in die Include-Dateien
  75 \verb+af_can.h+ und \verb+can.h+ ist zum Erstellen eines
  76 CAN-Netzwerk-Treibers nur die Include-Datei \verb+can.h+ nötig.\\
  77
  78 \subsection{Zeitstempel}
  79
  80 Für die Anwendungen im CAN-Umfeld ist häufig ein genauer Zeitstempel
  81 von Interesse, der den Empfangszeitpunkt einer Nachricht vom CAN-Bus
  82 wiedergibt. Ein solcher zugehöriger Zeitstempel kann über ein
  83 \man{ioctl}{2} nach dem Lesen einer Nachricht vom Socket ausgelesen
  84 werden. Dieses gilt auch für die Sockets von Transportprotokollen,
  85 wobei hier der Zeitstempel der letzten zugehörigen TPDU ausgegeben
  86 wird. Der Aufruf - z.B. \verb+ioctl(s, SIOCGSTAMP, &tv)+ - wird in den
  87 jeweiligen Testprogrammen zur Veranschaulichung verwendet.\\
  88
  89 Die Zeitstempel haben unter Linux eine Auflösung von einer Mikrosekunde
  90 und werden beim Empfang eines CAN-Frame im CAN-Networkdevice
  91 automatisch gesetzt.
  92