lincan-0.3.3/doc/lincandoc/lincan/can_lincan.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <section>
   3   <title>Linux CAN Driver (LINCAN)</title>
   4
   5   <para>The LINCAN is an implementation of the Linux device driver supporting
   6   more CAN controller chips and many CAN interface boards. Its
   7   implementation has long history already. The OCERA version of the driver
   8   adds new features, continuous enhancements and reimplementation of
   9   structure of the driver. The usage of the driver is tightly coupled to
  10   the virtual CAN API interface component which hides driver low level
  11   interface to the application programmers.</para>
  12
  13   <section>
  14     <title>Summary</title>
  15
  16     <variablelist>
  17       <varlistentry>
  18         <term>Name of the component</term>
  19
  20         <listitem>
  21           <para>Linux CAN Driver (LINCAN)</para>
  22         </listitem>
  23       </varlistentry>
  24
  25       <varlistentry>
  26         <term>Author</term>
  27
  28         <listitem>
  29           <para>Arnaud Westenberg</para>
  30
  31           <para>Tomasz Motylewski</para>
  32
  33           <para>Pavel Pisa</para>
  34         </listitem>
  35       </varlistentry>
  36
  37       <varlistentry>
  38         <term>Reviewer</term>
  39
  40         <listitem>
  41           <para>The previous driver versions were tested by more users. The
  42           actual version was tested at CTU by more OCERA developers and by
  43           BFAD GmbH, which use pre-OCERA and current version of the driver
  44           in their products.</para>
  45         </listitem>
  46       </varlistentry>
  47
  48       <varlistentry>
  49         <term>Layer</term>
  50
  51         <listitem>
  52           <para>High-level available</para>
  53         </listitem>
  54       </varlistentry>
  55
  56       <varlistentry>
  57         <term>Version</term>
  58
  59         <listitem>
  60           <para>0.7-pi3.4 alpha</para>
  61         </listitem>
  62       </varlistentry>
  63
  64       <varlistentry>
  65         <term>Status</term>
  66
  67         <listitem>
  68           <para>Alpha</para>
  69         </listitem>
  70       </varlistentry>
  71
  72       <varlistentry>
  73         <term>Dependencies</term>
  74
  75         <listitem>
  76           <para>The driver requires CAN interface hardware.</para>
  77
  78           <para>Linux kernels from 2.2.x and 2.4.x series are fully
  79           supported.</para>
  80
  81           <para>Support for latest 2.5.x and future 2.6.x. is in
  82           preparation</para>
  83
  84           <para>The use of VCA API library is suggested for seamless
  85           application transitions between driver kinds and versions.</para>
  86         </listitem>
  87       </varlistentry>
  88
  89       <varlistentry>
  90         <term>Release date</term>
  91
  92         <listitem>
  93           <para>N/A</para>
  94         </listitem>
  95       </varlistentry>
  96     </variablelist>
  97   </section>
  98
  99   <section>
 100     <title>Description</title>
 101
 102     <para id="LINCAN" xreflabel="LINCAN">The LINCAN driver is the loadable
 103     module for the Linux kernel which implements CAN driver. The driver
 104     communicates and controls one or more CAN controllers chips. The each
 105     chip/CAN interface is represented to the applications as one or more CAN
 106     message objects through the character device interface. The application
 107     can open the character device and use <function>read</function>/<function>write</function>
 108     system calls for CAN messages transmission or reception through
 109     the connected message object. The parameters of the message object can be
 110     modified by the <function>IOCTL</function> system call. The closing of
 111     the character device releases resources allocated by the application.</para>
 112
 113     <para>The present version of the driver supports three most common CAN
 114     controllers:<itemizedlist><listitem><para>Intel i82527 chips</para></listitem><listitem><para>Philips
 115     82c200 chips</para></listitem><listitem><para>Philips SJA1000 chips in
 116     standard and PeliCAN mode</para></listitem></itemizedlist>The
 117     intelligent CAN/CANopen cards should be supported by future versions.
 118     One of such cards is P-CAN series of cards produced by Unicontrols.
 119     The driver contains support for more than ten CAN cards basic types
 120     with different combinations of the above mentioned chips. Not all card
 121     types are held by OCERA members, but CTU has and tested more SJA1000
 122     type cards and will test some i82527 cards in near future.</para>
 123   </section>
 124
 125   <section id="lincan-api" xreflabel="lincan-api-fops">
 126     <title>API / Compatibility</title>
 127
 128     <section>
 129       <title>Driver API Overview</title>
 130
 131       <para>Each driver is a subsystem which has no direct application level
 132       API. The operating system is responsible for user space calls
 133       transformation into driver functions calls or dispatch routines
 134       invocations. The CAN driver is implemented as a character device with
 135       the standard device node names <filename>/dev/can0</filename>,
 136       <filename>/dev/can1</filename>, etc. The application program
 137       communicates with the driver through the standard system low level
 138       input/output primitives (<function>open</function>,
 139       <function>close</function>, <function>read</function>,
 140       <function>write</function>, <function>select</function> and
 141       <function>ioctl</function>). The CAN driver convention of usage of
 142       these functions is described in the next subsection.</para>
 143
 144       <para>The <function>read</function> and <function>write</function>
 145       functions need to transfer one or more CAN messages. The structure
 146       <structname>canmsg_t</structname> is defined for this purpose and is
 147       defined in include file <filename>can/can.h</filename>. The
 148       <structname>canmsg_t</structname> structure has next fields:</para>
 149
 150       <programlisting>
 151       struct canmsg_t {
 152           int flags;
 153           int cob;
 154           unsigned long   id;
 155           canmsg_tstamp_t timestamp;
 156           unsigned short  length;
 157           unsigned char   data[CAN_MSG_LENGTH];
 158       };</programlisting>
 159
 160       <variablelist>
 161         <varlistentry>
 162           <term>flags</term>
 163
 164           <listitem>
 165             <para>The flags field holds information about message type.
 166             The bit <constant>MSG_RTR</constant> marks remote transmission
 167             request messages. Writing of such message into the CAN message object
 168             handle results in transmission of the RTR message. The RTR message
 169             can be received by the read call if no buffer with corresponding
 170             ID is pre-filled in the driver. The bit <constant>MSG_EXT</constant>
 171             indicates that the message with extended (29&#x00A0;bit) ID will
 172             be send or was received. The bit <constant>MSG_OVR</constant>
 173             is intended for fast indication of the reception message queue
 174             overfill.</para>
 175           </listitem>
 176         </varlistentry>
 177
 178         <varlistentry>
 179           <term>cob</term>
 180
 181           <listitem>
 182             <para>The field reserved for a holding message communication
 183             object number. It could be used for serialization of
 184             received messages from more message object into one message
 185             queue in the future.</para>
 186           </listitem>
 187         </varlistentry>
 188
 189         <varlistentry>
 190           <term>id</term>
 191
 192           <listitem>
 193             <para>CAN message ID.</para>
 194           </listitem>
 195         </varlistentry>
 196
 197         <varlistentry>
 198           <term>timestamp</term>
 199
 200           <listitem>
 201             <para>The field intended for storing of the message reception
 202             time.</para>
 203           </listitem>
 204         </varlistentry>
 205
 206         <varlistentry>
 207           <term>length</term>
 208
 209           <listitem>
 210             <para>The number of the data bytes send or received in the CAN message.
 211             The number of data load bytes is from 0 to 8.</para>
 212           </listitem>
 213         </varlistentry>
 214
 215         <varlistentry>
 216           <term>data</term>
 217
 218           <listitem>
 219             <para>The byte array holding message data.</para>
 220           </listitem>
 221         </varlistentry>
 222       </variablelist>
 223
 224       <para>As was mentioned above, direct communication with the driver
 225       through system calls is not encouraged because this interface is
 226       partially system dependent and cannot be ported to all environments.
 227       The suggested alternative is to use OCERA provided VCA library which
 228       defines the portable and clean interface to the CAN driver implementation.</para>
 229
 230       <para>The other issue is addition of the support for new CAN
 231       interface boards and CAN controller chips. The subsection <link
 232       linkend="lincan-api-board">Driver Board Support Interface</link>
 233       describes template functions, which needs to be implemented for
 234       newly supported board. The template of board support can be found in
 235       the file <filename>src/template.c</filename>.</para>
 236
 237       <para>The other task for more brave souls is addition of the support for
 238       the unsupported chip type. The source supporting the SJA1000 chip in the
 239       PeliCAN mode can serve as an example. The full source of this chip
 240       support is stored in the file <filename>src/sja1000p.c</filename>. The
 241       subsection <link linkend="lincan-api-board">Driver Chip Support
 242       Interface</link> describes basic functions necessary for the new chip
 243       support.</para>
 244     </section>
 245
 246     <section id="lincan-api-fops" xreflabel="lincan-api-fops">
 247       <title>CAN Driver File Operations</title>
 248
 249       <refentry>
 250         <refmeta>
 251           <refentrytitle><phrase id="LINCAN-open">open</phrase></refentrytitle>
 252         </refmeta>
 253
 254         <refnamediv>
 255           <refname>open</refname>
 256
 257           <refpurpose>message communication object open system call</refpurpose>
 258         </refnamediv>
 259
 260         <refsynopsisdiv>
 261           <title>Synopsis</title>
 262
 263           <funcsynopsis>
 264             <funcprototype>
 265               <funcdef>int <function>open </function></funcdef>
 266
 267               <paramdef>const char * <parameter>pathname</parameter></paramdef>
 268
 269               <paramdef>int <parameter>flags</parameter></paramdef>
 270             </funcprototype>
 271           </funcsynopsis>
 272         </refsynopsisdiv>
 273
 274         <refsect1>
 275           <title>Arguments</title>
 276
 277           <variablelist>
 278             <varlistentry>
 279               <term><parameter>pathname</parameter></term>
 280
 281               <listitem>
 282                 <para>The path to driver device node is specified there.
 283                 The conventional device names for Linux CAN driver are
 284                 <filename>/dev/can0</filename>, <filename>/dev/can1</filename>,
 285                 etc.</para>
 286               </listitem>
 287             </varlistentry>
 288
 289             <varlistentry>
 290               <term><parameter>flags</parameter></term>
 291
 292               <listitem>
 293                 <para>flags modifying style of open call. The standard
 294                 <constant>O_RDWR</constant> mode should be used for CAN
 295                 device. The mode <constant>O_NOBLOCK</constant> can be
 296                 used with driver as well. This mode results in immediate
 297                 return of <function>read</function> and
 298                 <function>write</function>.</para>
 299               </listitem>
 300             </varlistentry>
 301           </variablelist>
 302         </refsect1>
 303
 304         <refsect1>
 305           <title>Description</title>
 306
 307           <para>Returns negative number in the case of error. Returns the
 308           file descriptor for named CAN message object in other cases.</para>
 309         </refsect1>
 310       </refentry>
 311
 312       <refentry>
 313         <refmeta>
 314           <refentrytitle><phrase id="LINCAN-close">close</phrase></refentrytitle>
 315         </refmeta>
 316
 317         <refnamediv>
 318           <refname>close</refname>
 319
 320           <refpurpose>message communication object close system call</refpurpose>
 321         </refnamediv>
 322
 323         <refsynopsisdiv>
 324           <title>Synopsis</title>
 325
 326           <funcsynopsis>
 327             <funcprototype>
 328               <funcdef>int <function>close </function></funcdef>
 329
 330               <paramdef>int <parameter>fd</parameter></paramdef>
 331             </funcprototype>
 332           </funcsynopsis>
 333         </refsynopsisdiv>
 334
 335         <refsect1>
 336           <title>Arguments</title>
 337
 338           <variablelist>
 339             <varlistentry>
 340               <term><parameter>fd</parameter></term>
 341
 342               <listitem>
 343                 <para>file descriptor to opened can message communication
 344                 object</para>
 345               </listitem>
 346             </varlistentry>
 347           </variablelist>
 348         </refsect1>
 349
 350         <refsect1>
 351           <title>Description</title>
 352
 353           <para>Returns negative number in the case of error.</para>
 354         </refsect1>
 355       </refentry>
 356
 357       <refentry>
 358         <refmeta>
 359           <refentrytitle><phrase id="LINCAN-read">read</phrase></refentrytitle>
 360         </refmeta>
 361
 362         <refnamediv>
 363           <refname>read</refname>
 364
 365           <refpurpose>reads received CAN messages from message object</refpurpose>
 366         </refnamediv>
 367
 368         <refsynopsisdiv>
 369           <title>Synopsis</title>
 370
 371           <funcsynopsis>
 372             <funcprototype>
 373               <funcdef>ssize_t <function>read</function></funcdef>
 374
 375               <paramdef>int <parameter>fd</parameter></paramdef>
 376
 377               <paramdef>void * <parameter>buf</parameter></paramdef>
 378
 379               <paramdef>size_t <parameter>count</parameter></paramdef>
 380             </funcprototype>
 381           </funcsynopsis>
 382         </refsynopsisdiv>
 383
 384         <refsect1>
 385           <title>Arguments</title>
 386
 387           <variablelist>
 388             <varlistentry>
 389               <term><parameter>fd</parameter></term>
 390
 391               <listitem>
 392                 <para>file descriptor to opened can message communication
 393                 object</para>
 394               </listitem>
 395             </varlistentry>
 396
 397             <varlistentry>
 398               <term><parameter>buf</parameter></term>
 399
 400               <listitem>
 401                 <para>pointer to array of <structname>canmsg_t</structname>
 402                 structures.</para>
 403               </listitem>
 404             </varlistentry>
 405
 406             <varlistentry>
 407               <term><parameter>count</parameter></term>
 408
 409               <listitem>
 410                 <para>size of message array buffer in number of bytes</para>
 411               </listitem>
 412             </varlistentry>
 413           </variablelist>
 414         </refsect1>
 415
 416         <refsect1>
 417           <title>Description</title>
 418
 419           <para>Returns negative value in the case of error else returns
 420           number of read bytes which is multiple of
 421           <structname>canmsg_t</structname> structure size.</para>
 422         </refsect1>
 423       </refentry>
 424
 425       <refentry>
 426         <refmeta>
 427           <refentrytitle><phrase id="LINCAN-write">write</phrase></refentrytitle>
 428         </refmeta>
 429
 430         <refnamediv>
 431           <refname>write</refname>
 432
 433           <refpurpose>writes CAN messages to message object for
 434           transmission</refpurpose>
 435         </refnamediv>
 436
 437         <refsynopsisdiv>
 438           <title>Synopsis</title>
 439
 440           <funcsynopsis>
 441             <funcprototype>
 442               <funcdef>ssize_t <function>write</function></funcdef>
 443
 444               <paramdef>int <parameter>fd</parameter></paramdef>
 445
 446               <paramdef>const void * <parameter>buf</parameter></paramdef>
 447
 448               <paramdef>size_t <parameter>count</parameter></paramdef>
 449             </funcprototype>
 450           </funcsynopsis>
 451         </refsynopsisdiv>
 452
 453         <refsect1>
 454           <title>Arguments</title>
 455
 456           <variablelist>
 457             <varlistentry>
 458               <term><parameter>fd</parameter></term>
 459
 460               <listitem>
 461                 <para>file descriptor to opened can message communication
 462                 object</para>
 463               </listitem>
 464             </varlistentry>
 465
 466             <varlistentry>
 467               <term><parameter>buf</parameter></term>
 468
 469               <listitem>
 470                 <para>pointer to array of <structname>canmsg_t</structname>
 471                 structures.</para>
 472               </listitem>
 473             </varlistentry>
 474
 475             <varlistentry>
 476               <term><parameter>count</parameter></term>
 477
 478               <listitem>
 479                 <para>size of message array buffer in number of bytes. The
 480                 parameter informs driver about number of messages prepared
 481                 for transmission and should be multiple of
 482                 <structname>canmsg_t</structname> structure size.</para>
 483               </listitem>
 484             </varlistentry>
 485           </variablelist>
 486         </refsect1>
 487
 488         <refsect1>
 489           <title>Description</title>
 490
 491           <para>Returns negative value in the case of error else returns
 492           number of bytes successfully stored into message object
 493           transmission queue. The positive returned number is multiple of
 494           <structname>canmsg_t</structname> structure size.</para>
 495         </refsect1>
 496       </refentry>
 497     </section>
 498
 499     <section id="lincan-api-board" xreflabel="lincan-api-board">
 500       <title>Driver Board Support Interface</title>
 501
 502       <refentry>
 503         <refmeta>
 504           <refentrytitle><phrase id="API-template-request-io">template_request_io</phrase></refentrytitle>
 505         </refmeta>
 506
 507         <refnamediv>
 508           <refname>template_request_io</refname>
 509
 510           <refpurpose>reserve io memory</refpurpose>
 511         </refnamediv>
 512
 513         <refsynopsisdiv>
 514           <title>Synopsis</title>
 515
 516           <funcsynopsis>
 517             <funcprototype>
 518               <funcdef>int <function>template_request_io </function></funcdef>
 519
 520               <paramdef>unsigned long <parameter>io_addr</parameter></paramdef>
 521             </funcprototype>
 522           </funcsynopsis>
 523         </refsynopsisdiv>
 524
 525         <refsect1>
 526           <title>Arguments</title>
 527
 528           <variablelist>
 529             <varlistentry>
 530               <term><parameter>io_addr</parameter></term>
 531
 532               <listitem>
 533                 <para>The reserved memory starts at
 534                 <parameter>io_addr</parameter>, which is the module
 535                 parameter <parameter>io</parameter>.</para>
 536               </listitem>
 537             </varlistentry>
 538           </variablelist>
 539         </refsect1>
 540
 541         <refsect1>
 542           <title>Description</title>
 543
 544           <para>The function <function>template_request_io</function> is
 545           used to reserve the io-memory. If your hardware uses a dedicated
 546           memory range as hardware control registers you will have to add
 547           the code to reserve this memory as well. <constant>IO_RANGE</constant>
 548           is the io-memory range that gets reserved, please adjust
 549           according your hardware. Example: #define IO_RANGE 0x100 for
 550           i82527 chips or #define IO_RANGE 0x20 for sja1000 chips in basic
 551           CAN mode.</para>
 552         </refsect1>
 553
 554         <refsect1>
 555           <title>Return Value</title>
 556
 557           <para>The function returns zero on success or
 558           <constant>-ENODEV</constant> on failure</para>
 559         </refsect1>
 560
 561         <refsect1>
 562           <title>File</title>
 563
 564           <para>src/template.c</para>
 565         </refsect1>
 566       </refentry>
 567
 568       <refentry>
 569         <refmeta>
 570           <refentrytitle><phrase id="API-template-release-io">template_release_io</phrase></refentrytitle>
 571         </refmeta>
 572
 573         <refnamediv>
 574           <refname>template_release_io</refname>
 575
 576           <refpurpose>free reserved io-memory</refpurpose>
 577         </refnamediv>
 578
 579         <refsynopsisdiv>
 580           <title>Synopsis</title>
 581
 582           <funcsynopsis>
 583             <funcprototype>
 584               <funcdef>int <function>template_release_io </function></funcdef>
 585
 586               <paramdef>unsigned long <parameter>io_addr</parameter></paramdef>
 587             </funcprototype>
 588           </funcsynopsis>
 589         </refsynopsisdiv>
 590
 591         <refsect1>
 592           <title>Arguments</title>
 593
 594           <variablelist>
 595             <varlistentry>
 596               <term><parameter>io_addr</parameter></term>
 597
 598               <listitem>
 599                 <para>Start of the memory range to be released.</para>
 600               </listitem>
 601             </varlistentry>
 602           </variablelist>
 603         </refsect1>
 604
 605         <refsect1>
 606           <title>Description</title>
 607
 608           <para>The function <function>template_release_io</function> is
 609           used to free reserved io-memory. In case you have reserved more
 610           io memory, don&#39;t forget to free it here. IO_RANGE is the
 611           io-memory range that gets released, please adjust according your
 612           hardware. Example: #define IO_RANGE 0x100 for i82527 chips or
 613           #define IO_RANGE 0x20 for sja1000 chips in basic CAN mode.</para>
 614         </refsect1>
 615
 616         <refsect1>
 617           <title>Return Value</title>
 618
 619           <para>The function always returns zero</para>
 620         </refsect1>
 621
 622         <refsect1>
 623           <title>File</title>
 624
 625           <para>src/template.c</para>
 626         </refsect1>
 627       </refentry>
 628
 629       <refentry>
 630         <refmeta>
 631           <refentrytitle><phrase id="API-template-reset">template_reset</phrase></refentrytitle>
 632         </refmeta>
 633
 634         <refnamediv>
 635           <refname>template_reset</refname>
 636
 637           <refpurpose>hardware reset routine</refpurpose>
 638         </refnamediv>
 639
 640         <refsynopsisdiv>
 641           <title>Synopsis</title>
 642
 643           <funcsynopsis>
 644             <funcprototype>
 645               <funcdef>int <function>template_reset </function></funcdef>
 646
 647               <paramdef>int <parameter>card</parameter></paramdef>
 648             </funcprototype>
 649           </funcsynopsis>
 650         </refsynopsisdiv>
 651
 652         <refsect1>
 653           <title>Arguments</title>
 654
 655           <variablelist>
 656             <varlistentry>
 657               <term><parameter>card</parameter></term>
 658
 659               <listitem>
 660                 <para>Number of the hardware card.</para>
 661               </listitem>
 662             </varlistentry>
 663           </variablelist>
 664         </refsect1>
 665
 666         <refsect1>
 667           <title>Description</title>
 668
 669           <para>The function <function>template_reset</function> is used
 670           to give a hardware reset. This is rather hardware specific so I
 671           haven&#39;t included example code. Don&#39;t forget to check the
 672           reset status of the chip before returning.</para>
 673         </refsect1>
 674
 675         <refsect1>
 676           <title>Return Value</title>
 677
 678           <para>The function returns zero on success or
 679           <constant>-ENODEV</constant> on failure</para>
 680         </refsect1>
 681
 682         <refsect1>
 683           <title>File</title>
 684
 685           <para>src/template.c</para>
 686         </refsect1>
 687       </refentry>
 688
 689       <refentry>
 690         <refmeta>
 691           <refentrytitle><phrase id="API-template-init-hw-data">template_init_hw_data</phrase></refentrytitle>
 692         </refmeta>
 693
 694         <refnamediv>
 695           <refname>template_init_hw_data</refname>
 696
 697           <refpurpose>Initialize hardware cards</refpurpose>
 698         </refnamediv>
 699
 700         <refsynopsisdiv>
 701           <title>Synopsis</title>
 702
 703           <funcsynopsis>
 704             <funcprototype>
 705               <funcdef>int <function>template_init_hw_data </function></funcdef>
 706
 707               <paramdef>int <parameter>card</parameter></paramdef>
 708             </funcprototype>
 709           </funcsynopsis>
 710         </refsynopsisdiv>
 711
 712         <refsect1>
 713           <title>Arguments</title>
 714
 715           <variablelist>
 716             <varlistentry>
 717               <term><parameter>card</parameter></term>
 718
 719               <listitem>
 720                 <para>Number of the hardware card.</para>
 721               </listitem>
 722             </varlistentry>
 723           </variablelist>
 724         </refsect1>
 725
 726         <refsect1>
 727           <title>Description</title>
 728
 729           <para>The function <function>template_init_hw_data</function> is
 730           used to initialize the hardware structure containing information
 731           about the installed CAN-board. <constant>RESET_ADDR</constant>
 732           represents the io-address of the hardware reset register.
 733           <constant>NR_82527</constant> represents the number of Intel
 734           82527 chips on the board. <constant>NR_SJA1000</constant>
 735           represents the number of Philips sja1000 chips on the board. The
 736           flags entry can currently only be <constant>PROGRAMMABLE_IRQ</constant>
 737           to indicate that the hardware uses programmable interrupts.</para>
 738         </refsect1>
 739
 740         <refsect1>
 741           <title>Return Value</title>
 742
 743           <para>The function always returns zero</para>
 744         </refsect1>
 745
 746         <refsect1>
 747           <title>File</title>
 748
 749           <para>src/template.c</para>
 750         </refsect1>
 751       </refentry>
 752
 753       <refentry>
 754         <refmeta>
 755           <refentrytitle><phrase id="API-template-init-chip-data">template_init_chip_data</phrase></refentrytitle>
 756         </refmeta>
 757
 758         <refnamediv>
 759           <refname>template_init_chip_data</refname>
 760
 761           <refpurpose>Initialize chips</refpurpose>
 762         </refnamediv>
 763
 764         <refsynopsisdiv>
 765           <title>Synopsis</title>
 766
 767           <funcsynopsis>
 768             <funcprototype>
 769               <funcdef>int <function>template_init_chip_data </function></funcdef>
 770
 771               <paramdef>int <parameter>card</parameter></paramdef>
 772
 773               <paramdef>int <parameter>chipnr</parameter></paramdef>
 774             </funcprototype>
 775           </funcsynopsis>
 776         </refsynopsisdiv>
 777
 778         <refsect1>
 779           <title>Arguments</title>
 780
 781           <variablelist>
 782             <varlistentry>
 783               <term><parameter>card</parameter></term>
 784
 785               <listitem>
 786                 <para>Number of the hardware card</para>
 787               </listitem>
 788             </varlistentry>
 789
 790             <varlistentry>
 791               <term><parameter>chipnr</parameter></term>
 792
 793               <listitem>
 794                 <para>Number of the CAN chip on the hardware card</para>
 795               </listitem>
 796             </varlistentry>
 797           </variablelist>
 798         </refsect1>
 799
 800         <refsect1>
 801           <title>Description</title>
 802
 803           <para>The function <function>template_init_chip_data</function>
 804           is used to initialize the hardware structure containing
 805           information about the CAN chips. <constant>CHIP_TYPE</constant>
 806           represents the type of CAN chip. <constant>CHIP_TYPE</constant>
 807           can be <quote>i82527</quote> or <quote>sja1000</quote>. The
 808           <parameter>chip_base_addr</parameter> entry represents the start
 809           of the &#39;official&#39; memory map of the installed chip.
 810           It&#39;s likely that this is the same as the
 811           <parameter>io_addr</parameter> argument supplied at module
 812           loading time. The <parameter>clock</parameter> entry holds the
 813           chip clock value in Hz. The entry <parameter>sja_cdr_reg</parameter>
 814           holds hardware specific options for the Clock Divider register.
 815           Options defined in the <constant>sja1000</constant>.h file:
 816           <constant>CDR_CLKOUT_MASK</constant>, <constant>CDR_CLK_OFF</constant>,
 817           <constant>CDR_RXINPEN</constant>, <constant>CDR_CBP</constant>,
 818           <constant>CDR_PELICAN</constant> The entry
 819           <parameter>sja_ocr_reg</parameter> holds hardware specific
 820           options for the Output Control register. Options defined in the
 821           <constant>sja1000</constant>.h file: <constant>OCR_MODE_BIPHASE</constant>,
 822           <constant>OCR_MODE_TEST</constant>, <constant>OCR_MODE_NORMAL</constant>,
 823           <constant>OCR_MODE_CLOCK</constant>, <constant>OCR_TX0_LH</constant>,
 824           <constant>OCR_TX1_ZZ</constant>. The entry
 825           <parameter>int_clk_reg</parameter> holds hardware specific
 826           options for the Clock Out register. Options defined in the
 827           <constant>i82527</constant>.h file: <constant>iCLK_CD0</constant>,
 828           <constant>iCLK_CD1</constant>, <constant>iCLK_CD2</constant>,
 829           <constant>iCLK_CD3</constant>, <constant>iCLK_SL0</constant>,
 830           <constant>iCLK_SL1</constant>. The entry <parameter>int_bus_reg</parameter>
 831           holds hardware specific options for the Bus Configuration
 832           register. Options defined in the <constant>i82527</constant>.h
 833           file: <constant>iBUS_DR0</constant>, <constant>iBUS_DR1</constant>,
 834           <constant>iBUS_DT1</constant>, <constant>iBUS_POL</constant>,
 835           <constant>iBUS_CBY</constant>. The entry <parameter>int_cpu_reg</parameter>
 836           holds hardware specific options for the cpu interface register.
 837           Options defined in the <constant>i82527</constant>.h file:
 838           <constant>iCPU_CEN</constant>, <constant>iCPU_MUX</constant>,
 839           <constant>iCPU_SLP</constant>, <constant>iCPU_PWD</constant>,
 840           <constant>iCPU_DMC</constant>, <constant>iCPU_DSC</constant>,
 841           <constant>iCPU_RST</constant>.</para>
 842         </refsect1>
 843
 844         <refsect1>
 845           <title>Return Value</title>
 846
 847           <para>The function always returns zero</para>
 848         </refsect1>
 849
 850         <refsect1>
 851           <title>File</title>
 852
 853           <para>src/template.c</para>
 854         </refsect1>
 855       </refentry>
 856
 857       <refentry>
 858         <refmeta>
 859           <refentrytitle><phrase id="API-template-init-obj-data">template_init_obj_data</phrase></refentrytitle>
 860         </refmeta>
 861
 862         <refnamediv>
 863           <refname>template_init_obj_data</refname>
 864
 865           <refpurpose>Initialize message buffers</refpurpose>
 866         </refnamediv>
 867
 868         <refsynopsisdiv>
 869           <title>Synopsis</title>
 870
 871           <funcsynopsis>
 872             <funcprototype>
 873               <funcdef>int <function>template_init_obj_data </function></funcdef>
 874
 875               <paramdef>int <parameter>chipnr</parameter></paramdef>
 876
 877               <paramdef>int <parameter>objnr</parameter></paramdef>
 878             </funcprototype>
 879           </funcsynopsis>
 880         </refsynopsisdiv>
 881
 882         <refsect1>
 883           <title>Arguments</title>
 884
 885           <variablelist>
 886             <varlistentry>
 887               <term><parameter>chipnr</parameter></term>
 888
 889               <listitem>
 890                 <para>Number of the CAN chip</para>
 891               </listitem>
 892             </varlistentry>
 893
 894             <varlistentry>
 895               <term><parameter>objnr</parameter></term>
 896
 897               <listitem>
 898                 <para>Number of the message buffer</para>
 899               </listitem>
 900             </varlistentry>
 901           </variablelist>
 902         </refsect1>
 903
 904         <refsect1>
 905           <title>Description</title>
 906
 907           <para>The function <function>template_init_obj_data</function>
 908           is used to initialize the hardware structure containing
 909           information about the different message objects on the CAN chip.
 910           In case of the sja1000 there&#39;s only one message object but
 911           on the i82527 chip there are 15. The code below is for a i82527
 912           chip and initializes the object base addresses The entry
 913           <parameter>obj_base_addr</parameter> represents the first memory
 914           address of the message object. In case of the sja1000
 915           <parameter>obj_base_addr</parameter> is taken the same as the
 916           chips base address. Unless the hardware uses a segmented memory
 917           map, flags can be set zero.</para>
 918         </refsect1>
 919
 920         <refsect1>
 921           <title>Return Value</title>
 922
 923           <para>The function always returns zero</para>
 924         </refsect1>
 925
 926         <refsect1>
 927           <title>File</title>
 928
 929           <para>src/template.c</para>
 930         </refsect1>
 931       </refentry>
 932
 933       <refentry>
 934         <refmeta>
 935           <refentrytitle><phrase id="API-template-program-irq">template_program_irq</phrase></refentrytitle>
 936         </refmeta>
 937
 938         <refnamediv>
 939           <refname>template_program_irq</refname>
 940
 941           <refpurpose>program interrupts</refpurpose>
 942         </refnamediv>
 943
 944         <refsynopsisdiv>
 945           <title>Synopsis</title>
 946
 947           <funcsynopsis>
 948             <funcprototype>
 949               <funcdef>int <function>template_program_irq </function></funcdef>
 950
 951               <paramdef>int <parameter>card</parameter></paramdef>
 952             </funcprototype>
 953           </funcsynopsis>
 954         </refsynopsisdiv>
 955
 956         <refsect1>
 957           <title>Arguments</title>
 958
 959           <variablelist>
 960             <varlistentry>
 961               <term><parameter>card</parameter></term>
 962
 963               <listitem>
 964                 <para>Number of the hardware card.</para>
 965               </listitem>
 966             </varlistentry>
 967           </variablelist>
 968         </refsect1>
 969
 970         <refsect1>
 971           <title>Description</title>
 972
 973           <para>The function <function>template_program_irq</function> is
 974           used for hardware that uses programmable interrupts. If your
 975           hardware doesn&#39;t use programmable interrupts you should not
 976           set the <parameter>candevices_t</parameter>-&#62;flags entry to
 977           <constant>PROGRAMMABLE_IRQ</constant> and leave this function
 978           unedited. Again this function is hardware specific so
 979           there&#39;s no example code.</para>
 980         </refsect1>
 981
 982         <refsect1>
 983           <title>Return value</title>
 984
 985           <para>The function returns zero on success or
 986           <constant>-ENODEV</constant> on failure</para>
 987         </refsect1>
 988
 989         <refsect1>
 990           <title>File</title>
 991
 992           <para>src/template.c</para>
 993         </refsect1>
 994       </refentry>
 995
 996       <refentry>
 997         <refmeta>
 998           <refentrytitle><phrase id="API-template-write-register">template_write_register</phrase></refentrytitle>
 999         </refmeta>
1000
1001         <refnamediv>
1002           <refname>template_write_register</refname>
1003
1004           <refpurpose>Low level write register routine</refpurpose>
1005         </refnamediv>
1006
1007         <refsynopsisdiv>
1008           <title>Synopsis</title>
1009
1010           <funcsynopsis>
1011             <funcprototype>
1012               <funcdef>void <function>template_write_register </function></funcdef>
1013
1014               <paramdef>unsigned char <parameter>data</parameter></paramdef>
1015
1016               <paramdef>unsigned long <parameter>address</parameter></paramdef>
1017             </funcprototype>
1018           </funcsynopsis>
1019         </refsynopsisdiv>
1020
1021         <refsect1>
1022           <title>Arguments</title>
1023
1024           <variablelist>
1025             <varlistentry>
1026               <term><parameter>data</parameter></term>
1027
1028               <listitem>
1029                 <para>data to be written</para>
1030               </listitem>
1031             </varlistentry>
1032
1033             <varlistentry>
1034               <term><parameter>address</parameter></term>
1035
1036               <listitem>
1037                 <para>memory address to write to</para>
1038               </listitem>
1039             </varlistentry>
1040           </variablelist>
1041         </refsect1>
1042
1043         <refsect1>
1044           <title>Description</title>
1045
1046           <para>The function <function>template_write_register</function>
1047           is used to write to hardware registers on the CAN chip. You
1048           should only have to edit this function if your hardware uses
1049           some specific write process.</para>
1050         </refsect1>
1051
1052         <refsect1>
1053           <title>Return Value</title>
1054
1055           <para>The function does not return a value</para>
1056         </refsect1>
1057
1058         <refsect1>
1059           <title>File</title>
1060
1061           <para>src/template.c</para>
1062         </refsect1>
1063       </refentry>
1064
1065       <refentry>
1066         <refmeta>
1067           <refentrytitle><phrase id="API-template-read-register">template_read_register</phrase></refentrytitle>
1068         </refmeta>
1069
1070         <refnamediv>
1071           <refname>template_read_register</refname>
1072
1073           <refpurpose>Low level read register routine</refpurpose>
1074         </refnamediv>
1075
1076         <refsynopsisdiv>
1077           <title>Synopsis</title>
1078
1079           <funcsynopsis>
1080             <funcprototype>
1081               <funcdef>unsigned <function>template_read_register
1082               </function></funcdef>
1083
1084               <paramdef>unsigned long <parameter>address</parameter></paramdef>
1085             </funcprototype>
1086           </funcsynopsis>
1087         </refsynopsisdiv>
1088
1089         <refsect1>
1090           <title>Arguments</title>
1091
1092           <variablelist>
1093             <varlistentry>
1094               <term><parameter>address</parameter></term>
1095
1096               <listitem>
1097                 <para>memory address to read from</para>
1098               </listitem>
1099             </varlistentry>
1100           </variablelist>
1101         </refsect1>
1102
1103         <refsect1>
1104           <title>Description</title>
1105
1106           <para>The function <function>template_read_register</function>
1107           is used to read from hardware registers on the CAN chip. You
1108           should only have to edit this function if your hardware uses
1109           some specific read process.</para>
1110         </refsect1>
1111
1112         <refsect1>
1113           <title>Return Value</title>
1114
1115           <para>The function returns the value stored in
1116           <parameter>address</parameter></para>
1117         </refsect1>
1118
1119         <refsect1>
1120           <title>File</title>
1121
1122           <para>src/template.c</para>
1123         </refsect1>
1124       </refentry>
1125     </section>
1126
1127     <section id="lincan-api-chip" xreflabel="lincan-api-chip">
1128       <title>Driver Chip Support Interface</title>
1129
1130       <refentry>
1131         <refmeta>
1132           <refentrytitle><phrase id="API-sja1000p-chip-config">sja1000p_chip_config</phrase></refentrytitle>
1133         </refmeta>
1134
1135         <refnamediv>
1136           <refname>sja1000p_chip_config</refname>
1137
1138           <refpurpose>can chip configuration</refpurpose>
1139         </refnamediv>
1140
1141         <refsynopsisdiv>
1142           <title>Synopsis</title>
1143
1144           <funcsynopsis>
1145             <funcprototype>
1146               <funcdef>int <function>sja1000p_chip_config </function></funcdef>
1147
1148               <paramdef>struct chip_t * <parameter>chip</parameter></paramdef>
1149             </funcprototype>
1150           </funcsynopsis>
1151         </refsynopsisdiv>
1152
1153         <refsect1>
1154           <title>Arguments</title>
1155
1156           <variablelist>
1157             <varlistentry>
1158               <term><parameter>chip</parameter></term>
1159
1160               <listitem>
1161                 <para>pointer to chip state structure</para>
1162               </listitem>
1163             </varlistentry>
1164           </variablelist>
1165         </refsect1>
1166
1167         <refsect1>
1168           <title>Description</title>
1169
1170           <para>This function configures chip and prepares it for message
1171           transmission and reception. The function resets chip, resets
1172           mask for acceptance of all messages by call to
1173           <function>sja1000p_extended_mask</function> function and then
1174           computes and sets baudrate with use of function
1175           <function>sja1000p_baud_rate</function>.</para>
1176         </refsect1>
1177
1178         <refsect1>
1179           <title>Return Value</title>
1180
1181           <para>negative value reports error.</para>
1182         </refsect1>
1183
1184         <refsect1>
1185           <title>File</title>
1186
1187           <para>src/sja1000p.c</para>
1188         </refsect1>
1189       </refentry>
1190
1191       <refentry>
1192         <refmeta>
1193           <refentrytitle><phrase id="API-sja1000p-extended-mask">sja1000p_extended_mask</phrase></refentrytitle>
1194         </refmeta>
1195
1196         <refnamediv>
1197           <refname>sja1000p_extended_mask</refname>
1198
1199           <refpurpose>setup of extended mask for message filtering</refpurpose>
1200         </refnamediv>
1201
1202         <refsynopsisdiv>
1203           <title>Synopsis</title>
1204
1205           <funcsynopsis>
1206             <funcprototype>
1207               <funcdef>int <function>sja1000p_extended_mask </function></funcdef>
1208
1209               <paramdef>struct chip_t * <parameter>chip</parameter></paramdef>
1210
1211               <paramdef>unsigned long <parameter>code</parameter></paramdef>
1212
1213               <paramdef>unsigned long <parameter>mask</parameter></paramdef>
1214             </funcprototype>
1215           </funcsynopsis>
1216         </refsynopsisdiv>
1217
1218         <refsect1>
1219           <title>Arguments</title>
1220
1221           <variablelist>
1222             <varlistentry>
1223               <term><parameter>chip</parameter></term>
1224
1225               <listitem>
1226                 <para>pointer to chip state structure</para>
1227               </listitem>
1228             </varlistentry>
1229
1230             <varlistentry>
1231               <term><parameter>code</parameter></term>
1232
1233               <listitem>
1234                 <para>can message acceptance code</para>
1235               </listitem>
1236             </varlistentry>
1237
1238             <varlistentry>
1239               <term><parameter>mask</parameter></term>
1240
1241               <listitem>
1242                 <para>can message acceptance mask</para>
1243               </listitem>
1244             </varlistentry>
1245           </variablelist>
1246         </refsect1>
1247
1248         <refsect1>
1249           <title>Return Value</title>
1250
1251           <para>negative value reports error.</para>
1252         </refsect1>
1253
1254         <refsect1>
1255           <title>File</title>
1256
1257           <para>src/sja1000p.c</para>
1258         </refsect1>
1259       </refentry>
1260
1261       <refentry>
1262         <refmeta>
1263           <refentrytitle><phrase id="API-sja1000p-baud-rate">sja1000p_baud_rate</phrase></refentrytitle>
1264         </refmeta>
1265
1266         <refnamediv>
1267           <refname>sja1000p_baud_rate</refname>
1268
1269           <refpurpose>set communication parameters.</refpurpose>
1270         </refnamediv>
1271
1272         <refsynopsisdiv>
1273           <title>Synopsis</title>
1274
1275           <funcsynopsis>
1276             <funcprototype>
1277               <funcdef>int <function>sja1000p_baud_rate </function></funcdef>
1278
1279               <paramdef>struct chip_t * <parameter>chip</parameter></paramdef>
1280
1281               <paramdef>int <parameter>rate</parameter></paramdef>
1282
1283               <paramdef>int <parameter>clock</parameter></paramdef>
1284
1285               <paramdef>int <parameter>sjw</parameter></paramdef>
1286
1287               <paramdef>int <parameter>sampl_pt</parameter></paramdef>
1288
1289               <paramdef>int <parameter>flags</parameter></paramdef>
1290             </funcprototype>
1291           </funcsynopsis>
1292         </refsynopsisdiv>
1293
1294         <refsect1>
1295           <title>Arguments</title>
1296
1297           <variablelist>
1298             <varlistentry>
1299               <term><parameter>chip</parameter></term>
1300
1301               <listitem>
1302                 <para>pointer to chip state structure</para>
1303               </listitem>
1304             </varlistentry>
1305
1306             <varlistentry>
1307               <term><parameter>rate</parameter></term>
1308
1309               <listitem>
1310                 <para>baud rate in Hz</para>
1311               </listitem>
1312             </varlistentry>
1313
1314             <varlistentry>
1315               <term><parameter>clock</parameter></term>
1316
1317               <listitem>
1318                 <para>frequency of sja1000 clock in Hz (ISA osc is
1319                 14318000)</para>
1320               </listitem>
1321             </varlistentry>
1322
1323             <varlistentry>
1324               <term><parameter>sjw</parameter></term>
1325
1326               <listitem>
1327                 <para>synchronization jump width (0-3) prescaled clock
1328                 cycles</para>
1329               </listitem>
1330             </varlistentry>
1331
1332             <varlistentry>
1333               <term><parameter>sampl_pt</parameter></term>
1334
1335               <listitem>
1336                 <para>sample point in % (0-100) sets
1337                 (TSEG1+1)/(TSEG1+TSEG2+2) ratio</para>
1338               </listitem>
1339             </varlistentry>
1340
1341             <varlistentry>
1342               <term><parameter>flags</parameter></term>
1343
1344               <listitem>
1345                 <para>fields <constant>BTR1_SAM</constant>,
1346                 <constant>OCMODE</constant>, <constant>OCPOL</constant>,
1347                 <constant>OCTP</constant>, <constant>OCTN</constant>,
1348                 <constant>CLK_OFF</constant>, <constant>CBP</constant></para>
1349               </listitem>
1350             </varlistentry>
1351           </variablelist>
1352         </refsect1>
1353
1354         <refsect1>
1355           <title>Return Value</title>
1356
1357           <para>negative value reports error.</para>
1358         </refsect1>
1359
1360         <refsect1>
1361           <title>File</title>
1362
1363           <para>src/sja1000p.c</para>
1364         </refsect1>
1365       </refentry>
1366
1367       <refentry>
1368         <refmeta>
1369           <refentrytitle><phrase id="API-sja1000p-read">sja1000p_read</phrase></refentrytitle>
1370         </refmeta>
1371
1372         <refnamediv>
1373           <refname>sja1000p_read</refname>
1374
1375           <refpurpose>reads and distributes one or more received messages</refpurpose>
1376         </refnamediv>
1377
1378         <refsynopsisdiv>
1379           <title>Synopsis</title>
1380
1381           <funcsynopsis>
1382             <funcprototype>
1383               <funcdef>void <function>sja1000p_read </function></funcdef>
1384
1385               <paramdef>struct chip_t * <parameter>chip</parameter></paramdef>
1386
1387               <paramdef>struct canfifo_t * <parameter>fifo</parameter></paramdef>
1388             </funcprototype>
1389           </funcsynopsis>
1390         </refsynopsisdiv>
1391
1392         <refsect1>
1393           <title>Arguments</title>
1394
1395           <variablelist>
1396             <varlistentry>
1397               <term><parameter>chip</parameter></term>
1398
1399               <listitem>
1400                 <para>pointer to chip state structure</para>
1401               </listitem>
1402             </varlistentry>
1403
1404             <varlistentry>
1405               <term><parameter>fifo</parameter></term>
1406
1407               <listitem>
1408                 <para>pinter to CAN message queue information</para>
1409               </listitem>
1410             </varlistentry>
1411           </variablelist>
1412         </refsect1>
1413
1414         <refsect1>
1415           <title>File</title>
1416
1417           <para>src/sja1000p.c</para>
1418         </refsect1>
1419       </refentry>
1420
1421       <refentry>
1422         <refmeta>
1423           <refentrytitle><phrase id="API-sja1000p-pre-read-config">sja1000p_pre_read_config</phrase></refentrytitle>
1424         </refmeta>
1425
1426         <refnamediv>
1427           <refname>sja1000p_pre_read_config</refname>
1428
1429           <refpurpose>prepares message object for message reception</refpurpose>
1430         </refnamediv>
1431
1432         <refsynopsisdiv>
1433           <title>Synopsis</title>
1434
1435           <funcsynopsis>
1436             <funcprototype>
1437               <funcdef>int <function>sja1000p_pre_read_config </function></funcdef>
1438
1439               <paramdef>struct chip_t * <parameter>chip</parameter></paramdef>
1440
1441               <paramdef>struct msgobj_t * <parameter>obj</parameter></paramdef>
1442             </funcprototype>
1443           </funcsynopsis>
1444         </refsynopsisdiv>
1445
1446         <refsect1>
1447           <title>Arguments</title>
1448
1449           <variablelist>
1450             <varlistentry>
1451               <term><parameter>chip</parameter></term>
1452
1453               <listitem>
1454                 <para>pointer to chip state structure</para>
1455               </listitem>
1456             </varlistentry>
1457
1458             <varlistentry>
1459               <term><parameter>obj</parameter></term>
1460
1461               <listitem>
1462                 <para>pointer to message object state structure</para>
1463               </listitem>
1464             </varlistentry>
1465           </variablelist>
1466         </refsect1>
1467
1468         <refsect1>
1469           <title>Return Value</title>
1470
1471           <para>negative value reports error. Positive value indicates
1472           immediate reception of message.</para>
1473         </refsect1>
1474
1475         <refsect1>
1476           <title>File</title>
1477
1478           <para>src/sja1000p.c</para>
1479         </refsect1>
1480       </refentry>
1481
1482       <refentry>
1483         <refmeta>
1484           <refentrytitle><phrase id="API-sja1000p-pre-write-config">sja1000p_pre_write_config</phrase></refentrytitle>
1485         </refmeta>
1486
1487         <refnamediv>
1488           <refname>sja1000p_pre_write_config</refname>
1489
1490           <refpurpose>prepares message object for message transmission</refpurpose>
1491         </refnamediv>
1492
1493         <refsynopsisdiv>
1494           <title>Synopsis</title>
1495
1496           <funcsynopsis>
1497             <funcprototype>
1498               <funcdef>int <function>sja1000p_pre_write_config </function></funcdef>
1499
1500               <paramdef>struct chip_t * <parameter>chip</parameter></paramdef>
1501
1502               <paramdef>struct msgobj_t * <parameter>obj</parameter></paramdef>
1503
1504               <paramdef>struct canmsg_t * <parameter>msg</parameter></paramdef>
1505             </funcprototype>
1506           </funcsynopsis>
1507         </refsynopsisdiv>
1508
1509         <refsect1>
1510           <title>Arguments</title>
1511
1512           <variablelist>
1513             <varlistentry>
1514               <term><parameter>chip</parameter></term>
1515
1516               <listitem>
1517                 <para>pointer to chip state structure</para>
1518               </listitem>
1519             </varlistentry>
1520
1521             <varlistentry>
1522               <term><parameter>obj</parameter></term>
1523
1524               <listitem>
1525                 <para>pointer to message object state structure</para>
1526               </listitem>
1527             </varlistentry>
1528
1529             <varlistentry>
1530               <term><parameter>msg</parameter></term>
1531
1532               <listitem>
1533                 <para>pointer to CAN message</para>
1534               </listitem>
1535             </varlistentry>
1536           </variablelist>
1537         </refsect1>
1538
1539         <refsect1>
1540           <title>Description</title>
1541
1542           <para>This function prepares selected message object for future
1543           initiation of message transmission by <function>sja1000p_send_msg</function>
1544           function. The CAN message data and message ID are transfered
1545           from <parameter>msg</parameter> slot into chip buffer in this
1546           function.</para>
1547         </refsect1>
1548
1549         <refsect1>
1550           <title>Return Value</title>
1551
1552           <para>negative value reports error.</para>
1553         </refsect1>
1554
1555         <refsect1>
1556           <title>File</title>
1557
1558           <para>src/sja1000p.c</para>
1559         </refsect1>
1560       </refentry>
1561
1562       <refentry>
1563         <refmeta>
1564           <refentrytitle><phrase id="API-sja1000p-send-msg">sja1000p_send_msg</phrase></refentrytitle>
1565         </refmeta>
1566
1567         <refnamediv>
1568           <refname>sja1000p_send_msg</refname>
1569
1570           <refpurpose>initiate message transmission</refpurpose>
1571         </refnamediv>
1572
1573         <refsynopsisdiv>
1574           <title>Synopsis</title>
1575
1576           <funcsynopsis>
1577             <funcprototype>
1578               <funcdef>iint <function>sja1000p_send_msg </function></funcdef>
1579
1580               <paramdef>struct chip_t * <parameter>chip</parameter></paramdef>
1581
1582               <paramdef>struct msgobj_t * <parameter>obj</parameter></paramdef>
1583
1584               <paramdef>struct canmsg_t * <parameter>msg</parameter></paramdef>
1585             </funcprototype>
1586           </funcsynopsis>
1587         </refsynopsisdiv>
1588
1589         <refsect1>
1590           <title>Arguments</title>
1591
1592           <variablelist>
1593             <varlistentry>
1594               <term><parameter>chip</parameter></term>
1595
1596               <listitem>
1597                 <para>pointer to chip state structure</para>
1598               </listitem>
1599             </varlistentry>
1600
1601             <varlistentry>
1602               <term><parameter>obj</parameter></term>
1603
1604               <listitem>
1605                 <para>pointer to message object state structure</para>
1606               </listitem>
1607             </varlistentry>
1608
1609             <varlistentry>
1610               <term><parameter>msg</parameter></term>
1611
1612               <listitem>
1613                 <para>pointer to CAN message</para>
1614               </listitem>
1615             </varlistentry>
1616           </variablelist>
1617         </refsect1>
1618
1619         <refsect1>
1620           <title>Description</title>
1621
1622           <para>This function is called after <function>sja1000p_pre_write_config</function>
1623           function, which prepares data in chip buffer.</para>
1624         </refsect1>
1625
1626         <refsect1>
1627           <title>Return Value</title>
1628
1629           <para>negative value reports error.</para>
1630         </refsect1>
1631
1632         <refsect1>
1633           <title>File</title>
1634
1635           <para>src/sja1000p.c</para>
1636         </refsect1>
1637       </refentry>
1638
1639       <refentry>
1640         <refmeta>
1641           <refentrytitle><phrase id="API-sja1000p-check-tx-stat">sja1000p_check_tx_stat</phrase></refentrytitle>
1642         </refmeta>
1643
1644         <refnamediv>
1645           <refname>sja1000p_check_tx_stat</refname>
1646
1647           <refpurpose>checks state of transmission engine</refpurpose>
1648         </refnamediv>
1649
1650         <refsynopsisdiv>
1651           <title>Synopsis</title>
1652
1653           <funcsynopsis>
1654             <funcprototype>
1655               <funcdef>int <function>sja1000p_check_tx_stat </function></funcdef>
1656
1657               <paramdef>struct chip_t * <parameter>chip</parameter></paramdef>
1658             </funcprototype>
1659           </funcsynopsis>
1660         </refsynopsisdiv>
1661
1662         <refsect1>
1663           <title>Arguments</title>
1664
1665           <variablelist>
1666             <varlistentry>
1667               <term><parameter>chip</parameter></term>
1668
1669               <listitem>
1670                 <para>pointer to chip state structure</para>
1671               </listitem>
1672             </varlistentry>
1673           </variablelist>
1674         </refsect1>
1675
1676         <refsect1>
1677           <title>Return Value</title>
1678
1679           <para>negative value reports error. Positive return value
1680           indicates transmission under way status. Zero value indicates
1681           finishing of all issued transmission requests.</para>
1682         </refsect1>
1683
1684         <refsect1>
1685           <title>File</title>
1686
1687           <para>src/sja1000p.c</para>
1688         </refsect1>
1689       </refentry>
1690
1691       <refentry>
1692         <refmeta>
1693           <refentrytitle><phrase id="API-sja1000p-set-btregs">sja1000p_set_btregs</phrase></refentrytitle>
1694         </refmeta>
1695
1696         <refnamediv>
1697           <refname>sja1000p_set_btregs</refname>
1698
1699           <refpurpose>configures bitrate registers</refpurpose>
1700         </refnamediv>
1701
1702         <refsynopsisdiv>
1703           <title>Synopsis</title>
1704
1705           <funcsynopsis>
1706             <funcprototype>
1707               <funcdef>int <function>sja1000p_set_btregs </function></funcdef>
1708
1709               <paramdef>struct chip_t * <parameter>chip</parameter></paramdef>
1710
1711               <paramdef>unsigned short <parameter>btr0</parameter></paramdef>
1712
1713               <paramdef>unsigned short <parameter>btr1</parameter></paramdef>
1714             </funcprototype>
1715           </funcsynopsis>
1716         </refsynopsisdiv>
1717
1718         <refsect1>
1719           <title>Arguments</title>
1720
1721           <variablelist>
1722             <varlistentry>
1723               <term><parameter>chip</parameter></term>
1724
1725               <listitem>
1726                 <para>pointer to chip state structure</para>
1727               </listitem>
1728             </varlistentry>
1729
1730             <varlistentry>
1731               <term><parameter>btr0</parameter></term>
1732
1733               <listitem>
1734                 <para>bitrate register 0</para>
1735               </listitem>
1736             </varlistentry>
1737
1738             <varlistentry>
1739               <term><parameter>btr1</parameter></term>
1740
1741               <listitem>
1742                 <para>bitrate register 1</para>
1743               </listitem>
1744             </varlistentry>
1745           </variablelist>
1746         </refsect1>
1747
1748         <refsect1>
1749           <title>Return Value</title>
1750
1751           <para>negative value reports error.</para>
1752         </refsect1>
1753
1754         <refsect1>
1755           <title>File</title>
1756
1757           <para>src/sja1000p.c</para>
1758         </refsect1>
1759       </refentry>
1760
1761       <refentry>
1762         <refmeta>
1763           <refentrytitle><phrase id="API-sja1000p-start-chip">sja1000p_start_chip</phrase></refentrytitle>
1764         </refmeta>
1765
1766         <refnamediv>
1767           <refname>sja1000p_start_chip</refname>
1768
1769           <refpurpose>starts chip message processing</refpurpose>
1770         </refnamediv>
1771
1772         <refsynopsisdiv>
1773           <title>Synopsis</title>
1774
1775           <funcsynopsis>
1776             <funcprototype>
1777               <funcdef>int <function>sja1000p_start_chip </function></funcdef>
1778
1779               <paramdef>struct chip_t * <parameter>chip</parameter></paramdef>
1780             </funcprototype>
1781           </funcsynopsis>
1782         </refsynopsisdiv>
1783
1784         <refsect1>
1785           <title>Arguments</title>
1786
1787           <variablelist>
1788             <varlistentry>
1789               <term><parameter>chip</parameter></term>
1790
1791               <listitem>
1792                 <para>pointer to chip state structure</para>
1793               </listitem>
1794             </varlistentry>
1795           </variablelist>
1796         </refsect1>
1797
1798         <refsect1>
1799           <title>Return Value</title>
1800
1801           <para>negative value reports error.</para>
1802         </refsect1>
1803
1804         <refsect1>
1805           <title>File</title>
1806
1807           <para>src/sja1000p.c</para>
1808         </refsect1>
1809       </refentry>
1810
1811       <refentry>
1812         <refmeta>
1813           <refentrytitle><phrase id="API-sja1000p-stop-chip">sja1000p_stop_chip</phrase></refentrytitle>
1814         </refmeta>
1815
1816         <refnamediv>
1817           <refname>sja1000p_stop_chip</refname>
1818
1819           <refpurpose>stops chip message processing</refpurpose>
1820         </refnamediv>
1821
1822         <refsynopsisdiv>
1823           <title>Synopsis</title>
1824
1825           <funcsynopsis>
1826             <funcprototype>
1827               <funcdef>int <function>sja1000p_stop_chip </function></funcdef>
1828
1829               <paramdef>struct chip_t * <parameter>chip</parameter></paramdef>
1830             </funcprototype>
1831           </funcsynopsis>
1832         </refsynopsisdiv>
1833
1834         <refsect1>
1835           <title>Arguments</title>
1836
1837           <variablelist>
1838             <varlistentry>
1839               <term><parameter>chip</parameter></term>
1840
1841               <listitem>
1842                 <para>pointer to chip state structure</para>
1843               </listitem>
1844             </varlistentry>
1845           </variablelist>
1846         </refsect1>
1847
1848         <refsect1>
1849           <title>Return Value</title>
1850
1851           <para>negative value reports error.</para>
1852         </refsect1>
1853
1854         <refsect1>
1855           <title>File</title>
1856
1857           <para>src/sja1000p.c</para>
1858         </refsect1>
1859       </refentry>
1860
1861       <refentry>
1862         <refmeta>
1863           <refentrytitle><phrase id="API-sja1000p-remote-request">sja1000p_remote_request</phrase></refentrytitle>
1864         </refmeta>
1865
1866         <refnamediv>
1867           <refname>sja1000p_remote_request</refname>
1868
1869           <refpurpose>configures message object and asks for RTR message</refpurpose>
1870         </refnamediv>
1871
1872         <refsynopsisdiv>
1873           <title>Synopsis</title>
1874
1875           <funcsynopsis>
1876             <funcprototype>
1877               <funcdef>int <function>sja1000p_remote_request </function></funcdef>
1878
1879               <paramdef>struct chip_t * <parameter>chip</parameter></paramdef>
1880
1881               <paramdef>struct msgobj_t * <parameter>obj</parameter></paramdef>
1882             </funcprototype>
1883           </funcsynopsis>
1884         </refsynopsisdiv>
1885
1886         <refsect1>
1887           <title>Arguments</title>
1888
1889           <variablelist>
1890             <varlistentry>
1891               <term><parameter>chip</parameter></term>
1892
1893               <listitem>
1894                 <para>pointer to chip state structure</para>
1895               </listitem>
1896             </varlistentry>
1897
1898             <varlistentry>
1899               <term><parameter>obj</parameter></term>
1900
1901               <listitem>
1902                 <para>pointer to message object structure</para>
1903               </listitem>
1904             </varlistentry>
1905           </variablelist>
1906         </refsect1>
1907
1908         <refsect1>
1909           <title>Return Value</title>
1910
1911           <para>negative value reports error.</para>
1912         </refsect1>
1913
1914         <refsect1>
1915           <title>File</title>
1916
1917           <para>src/sja1000p.c</para>
1918         </refsect1>
1919       </refentry>
1920
1921       <refentry>
1922         <refmeta>
1923           <refentrytitle><phrase id="API-sja1000p-standard-mask">sja1000p_standard_mask</phrase></refentrytitle>
1924         </refmeta>
1925
1926         <refnamediv>
1927           <refname>sja1000p_standard_mask</refname>
1928
1929           <refpurpose>setup of mask for message filtering</refpurpose>
1930         </refnamediv>
1931
1932         <refsynopsisdiv>
1933           <title>Synopsis</title>
1934
1935           <funcsynopsis>
1936             <funcprototype>
1937               <funcdef>int <function>sja1000p_standard_mask </function></funcdef>
1938
1939               <paramdef>struct chip_t * <parameter>chip</parameter></paramdef>
1940
1941               <paramdef>unsigned short <parameter>code</parameter></paramdef>
1942
1943               <paramdef>unsigned short <parameter>mask</parameter></paramdef>
1944             </funcprototype>
1945           </funcsynopsis>
1946         </refsynopsisdiv>
1947
1948         <refsect1>
1949           <title>Arguments</title>
1950
1951           <variablelist>
1952             <varlistentry>
1953               <term><parameter>chip</parameter></term>
1954
1955               <listitem>
1956                 <para>pointer to chip state structure</para>
1957               </listitem>
1958             </varlistentry>
1959
1960             <varlistentry>
1961               <term><parameter>code</parameter></term>
1962
1963               <listitem>
1964                 <para>can message acceptance code</para>
1965               </listitem>
1966             </varlistentry>
1967
1968             <varlistentry>
1969               <term><parameter>mask</parameter></term>
1970
1971               <listitem>
1972                 <para>can message acceptance mask</para>
1973               </listitem>
1974             </varlistentry>
1975           </variablelist>
1976         </refsect1>
1977
1978         <refsect1>
1979           <title>Return Value</title>
1980
1981           <para>negative value reports error.</para>
1982         </refsect1>
1983
1984         <refsect1>
1985           <title>File</title>
1986
1987           <para>src/sja1000p.c</para>
1988         </refsect1>
1989       </refentry>
1990
1991       <refentry>
1992         <refmeta>
1993           <refentrytitle><phrase id="API-sja1000p-clear-objects">sja1000p_clear_objects</phrase></refentrytitle>
1994         </refmeta>
1995
1996         <refnamediv>
1997           <refname>sja1000p_clear_objects</refname>
1998
1999           <refpurpose>clears state of all message object residing in chip</refpurpose>
2000         </refnamediv>
2001
2002         <refsynopsisdiv>
2003           <title>Synopsis</title>
2004
2005           <funcsynopsis>
2006             <funcprototype>
2007               <funcdef>int <function>sja1000p_clear_objects </function></funcdef>
2008
2009               <paramdef>struct chip_t * <parameter>chip</parameter></paramdef>
2010             </funcprototype>
2011           </funcsynopsis>
2012         </refsynopsisdiv>
2013
2014         <refsect1>
2015           <title>Arguments</title>
2016
2017           <variablelist>
2018             <varlistentry>
2019               <term><parameter>chip</parameter></term>
2020
2021               <listitem>
2022                 <para>pointer to chip state structure</para>
2023               </listitem>
2024             </varlistentry>
2025           </variablelist>
2026         </refsect1>
2027
2028         <refsect1>
2029           <title>Return Value</title>
2030
2031           <para>negative value reports error.</para>
2032         </refsect1>
2033
2034         <refsect1>
2035           <title>File</title>
2036
2037           <para>src/sja1000p.c</para>
2038         </refsect1>
2039       </refentry>
2040
2041       <refentry>
2042         <refmeta>
2043           <refentrytitle><phrase id="API-sja1000p-config-irqs">sja1000p_config_irqs</phrase></refentrytitle>
2044         </refmeta>
2045
2046         <refnamediv>
2047           <refname>sja1000p_config_irqs</refname>
2048
2049           <refpurpose>tunes chip hardware interrupt delivery</refpurpose>
2050         </refnamediv>
2051
2052         <refsynopsisdiv>
2053           <title>Synopsis</title>
2054
2055           <funcsynopsis>
2056             <funcprototype>
2057               <funcdef>int <function>sja1000p_config_irqs </function></funcdef>
2058
2059               <paramdef>struct chip_t * <parameter>chip</parameter></paramdef>
2060
2061               <paramdef>short <parameter>irqs</parameter></paramdef>
2062             </funcprototype>
2063           </funcsynopsis>
2064         </refsynopsisdiv>
2065
2066         <refsect1>
2067           <title>Arguments</title>
2068
2069           <variablelist>
2070             <varlistentry>
2071               <term><parameter>chip</parameter></term>
2072
2073               <listitem>
2074                 <para>pointer to chip state structure</para>
2075               </listitem>
2076             </varlistentry>
2077
2078             <varlistentry>
2079               <term><parameter>irqs</parameter></term>
2080
2081               <listitem>
2082                 <para>requested chip IRQ configuration</para>
2083               </listitem>
2084             </varlistentry>
2085           </variablelist>
2086         </refsect1>
2087
2088         <refsect1>
2089           <title>Return Value</title>
2090
2091           <para>negative value reports error.</para>
2092         </refsect1>
2093
2094         <refsect1>
2095           <title>File</title>
2096
2097           <para>src/sja1000p.c</para>
2098         </refsect1>
2099       </refentry>
2100
2101       <refentry>
2102         <refmeta>
2103           <refentrytitle><phrase id="API-sja1000p-irq-write-handler">sja1000p_irq_write_handler</phrase></refentrytitle>
2104         </refmeta>
2105
2106         <refnamediv>
2107           <refname>sja1000p_irq_write_handler</refname>
2108
2109           <refpurpose>part of ISR code responsible for transmit events</refpurpose>
2110         </refnamediv>
2111
2112         <refsynopsisdiv>
2113           <title>Synopsis</title>
2114
2115           <funcsynopsis>
2116             <funcprototype>
2117               <funcdef>void <function>sja1000p_irq_write_handler
2118               </function></funcdef>
2119
2120               <paramdef>struct chip_t * <parameter>chip</parameter></paramdef>
2121
2122               <paramdef>struct canfifo_t * <parameter>fifo</parameter></paramdef>
2123             </funcprototype>
2124           </funcsynopsis>
2125         </refsynopsisdiv>
2126
2127         <refsect1>
2128           <title>Arguments</title>
2129
2130           <variablelist>
2131             <varlistentry>
2132               <term><parameter>chip</parameter></term>
2133
2134               <listitem>
2135                 <para>pointer to chip state structure</para>
2136               </listitem>
2137             </varlistentry>
2138
2139             <varlistentry>
2140               <term><parameter>fifo</parameter></term>
2141
2142               <listitem>
2143                 <para>pointer to attached queue description</para>
2144               </listitem>
2145             </varlistentry>
2146           </variablelist>
2147         </refsect1>
2148
2149         <refsect1>
2150           <title>Description</title>
2151
2152           <para>The main purpose of this function is to read message from
2153           attached queues and transfer message contents into CAN
2154           controller chip. This subroutine is called by
2155           <function>sja1000p_irq_write_handler</function> for transmit
2156           events.</para>
2157         </refsect1>
2158
2159         <refsect1>
2160           <title>File</title>
2161
2162           <para>src/sja1000p.c</para>
2163         </refsect1>
2164       </refentry>
2165
2166       <refentry>
2167         <refmeta>
2168           <refentrytitle><phrase id="API-sja1000p-irq-handler">sja1000p_irq_handler</phrase></refentrytitle>
2169         </refmeta>
2170
2171         <refnamediv>
2172           <refname>sja1000p_irq_handler</refname>
2173
2174           <refpurpose>interrupt service routine</refpurpose>
2175         </refnamediv>
2176
2177         <refsynopsisdiv>
2178           <title>Synopsis</title>
2179
2180           <funcsynopsis>
2181             <funcprototype>
2182               <funcdef>void <function>sja1000p_irq_handler </function></funcdef>
2183
2184               <paramdef>int <parameter>irq</parameter></paramdef>
2185
2186               <paramdef>void * <parameter>dev_id</parameter></paramdef>
2187
2188               <paramdef>struct pt_regs * <parameter>regs</parameter></paramdef>
2189             </funcprototype>
2190           </funcsynopsis>
2191         </refsynopsisdiv>
2192
2193         <refsect1>
2194           <title>Arguments</title>
2195
2196           <variablelist>
2197             <varlistentry>
2198               <term><parameter>irq</parameter></term>
2199
2200               <listitem>
2201                 <para>interrupt vector number, this value is system
2202                 specific</para>
2203               </listitem>
2204             </varlistentry>
2205
2206             <varlistentry>
2207               <term><parameter>dev_id</parameter></term>
2208
2209               <listitem>
2210                 <para>driver private pointer registered at time of
2211                 <function>request_irq</function> call. The CAN driver uses
2212                 this pointer to store relationship of interrupt to chip
2213                 state structure - <parameter>struct</parameter> chip_t</para>
2214               </listitem>
2215             </varlistentry>
2216
2217             <varlistentry>
2218               <term><parameter>regs</parameter></term>
2219
2220               <listitem>
2221                 <para>system dependent value pointing to registers stored
2222                 in exception frame</para>
2223               </listitem>
2224             </varlistentry>
2225           </variablelist>
2226         </refsect1>
2227
2228         <refsect1>
2229           <title>Description</title>
2230
2231           <para>Interrupt handler is activated when state of CAN
2232           controller chip changes, there is message to be read or there is
2233           more space for new messages or error occurs. The receive events
2234           results in reading of the message from CAN controller chip and
2235           distribution of message through attached message queues.</para>
2236         </refsect1>
2237
2238         <refsect1>
2239           <title>File</title>
2240
2241           <para>src/sja1000p.c</para>
2242         </refsect1>
2243       </refentry>
2244     </section>
2245   </section>
2246
2247   <section>
2248     <title>Implementation issues</title>
2249
2250     <para>The development of the CAN drivers for Linux has long history.
2251     We have been faced before two basic alternatives, start new project
2252     from scratch or use some other project as basis of our development.
2253     The first approach would probably lead faster to more simple and clean
2254     internal architecture but it would mean to introduce new driver with
2255     probably incompatible interface unusable for already existing
2256     applications. The support of many types of cards is thing which takes
2257     long time as well. More existing projects aimed to development of
2258     a Linux CAN driver has been analyzed:</para>
2259
2260     <variablelist>
2261       <varlistentry>
2262         <term>Original LDDK CAN driver project</term>
2263
2264         <listitem>
2265           <para>The driver project aborted on the kernel evolution and LDDK
2266           concept. The LDDK tried to prepare infrastructure for
2267           development of the kernel version independent character device
2268           drivers written in meta code. The goal was top-ranking, but it
2269           proves, that well written &#34;C&#34; language driver can be
2270           more portable than the LDDK complex infrastructure.</para>
2271         </listitem>
2272       </varlistentry>
2273
2274       <varlistentry>
2275         <term>can4linux-0.9 by PORT GmbH</term>
2276
2277         <listitem>
2278           <para>This is version of the above LDDK driver maintained by Port
2279           GmbH. The card type is hard compiled into the driver by selected
2280           defines and only Philips 82c200 chips are supported.</para>
2281         </listitem>
2282       </varlistentry>
2283
2284       <varlistentry>
2285         <term>CanFestival</term>
2286
2287         <listitem>
2288           <para>The big advantage of this driver is an integrated support for
2289           the RT-Linux, but driver implementation is highly coupled to one
2290           card. Some concepts of the driver are interesting but the driver has
2291           the hardcoded number of message queues.</para>
2292         </listitem>
2293       </varlistentry>
2294
2295       <varlistentry>
2296         <term>can-0.7.1 by Arnaud Westenberg</term>
2297
2298         <listitem>
2299           <para>This driver has its roots in the LDDK project as well. The
2300           original LDDK concept has been eliminated in the driver source
2301           and necessary adaptation of the driver for the different Linux kernel
2302           versions is achieved by the controllable number of defines and
2303           conditional compilation. There is more independent contributors.
2304           The main advantages of the driver are support of many cards working
2305           in parallel, IO and memory space chip connection support and more
2306           cards of different types can be selected at module load time.
2307           There exist more users and applications compatible with the driver
2308           interface. Disadvantages of the original version of this driver are
2309           non-optimal infrastructure, non-portable make system and lack of the
2310           select support.</para>
2311         </listitem>
2312       </varlistentry>
2313     </variablelist>
2314
2315     <para>The responsible OCERA developers selected the
2316     <interfacename>can-0.7.1</interfacename> driver as a base of their
2317     development for next reasons:</para>
2318
2319     <itemizedlist>
2320       <listitem>
2321         <para>Best support for more cards in system</para>
2322       </listitem>
2323
2324       <listitem>
2325         <para>Supports for many types of cards</para>
2326       </listitem>
2327
2328       <listitem>
2329         <para>The internal abstraction of the peripheral access method and
2330         the chip support</para>
2331       </listitem>
2332     </itemizedlist>
2333
2334     <para>The most important features added in the first stage of OCERA
2335     development are:</para>
2336
2337     <itemizedlist>
2338       <listitem>
2339         <para>Added the select system call support</para>
2340       </listitem>
2341
2342       <listitem>
2343         <para>The support for our memory mapped ISA card added, which proved
2344         simplicity of addition of the support for new type of CAN cards</para>
2345       </listitem>
2346
2347       <listitem>
2348         <para>Revised and bug-fixed the IRQ support</para>
2349       </listitem>
2350
2351       <listitem>
2352         <para>Rebuilt the make system to compile options fully follow the running
2353         kernel options, cross-compilation still possible when the kernel
2354         location and compiler is specified. The driver checked with more 2.2.x
2355         and 2.4.x kernels and hardware configurations. (compiles even with
2356         latest 2.5.x kernels for UP, but needs more work to be ready for
2357         2.6.x kernels)</para>
2358       </listitem>
2359
2360       <listitem>
2361         <para>Added devfs support</para>
2362       </listitem>
2363     </itemizedlist>
2364
2365     <para>We are planning next changes in the driver in the next stage of
2366     the development</para>
2367
2368     <itemizedlist>
2369       <listitem>
2370         <para>Full support for 2.6.x kernels</para>
2371       </listitem>
2372
2373       <listitem>
2374         <para>The second deeper rebuilt of the driver infrastructure to enable porting to
2375         more systems (most important RT-Linux). The big advantage of continuous
2376         development should be ability to keep compatibility with many
2377         cards and applications</para>
2378       </listitem>
2379
2380       <listitem>
2381         <para>Support for multiple opening of the single minor device</para>
2382       </listitem>
2383
2384       <listitem>
2385         <para>Support for intelligent CAN/CANopen cards</para>
2386       </listitem>
2387
2388       <listitem>
2389         <para>PCI and USB hardware hot-swapping and PnP recognition</para>
2390       </listitem>
2391     </itemizedlist>
2392
2393     <para>The</para>
2394   </section>
2395
2396   <section>
2397     <title>Tests</title>
2398
2399     <para>No heavy tests have been run yet. The driver has been used with
2400     more CAN devices (commercial and CTU made) on more Linux system setups
2401     (different kernels 2.4.18, 2.4.19, 2.2.19, 2.2.22) with more compilers
2402     (GCC 2.95.3 and 3.2.x). The test application from the driver sources
2403     and VCA API sources has been tested. The driver is used for the CanMonitor
2404     development and other CTU CAN related projects. The success has been
2405     reported from the BFAD company as well.</para>
2406   </section>
2407
2408   <section>
2409     <title>Examples</title>
2410
2411     <para>The simple test utilities can be found in the <filename>utils</filename>
2412     subdirectory of the LINCAN driver source subtree. These utilities can
2413     be used as base for user programs directly communicating with the LINCAN
2414     driver. We do not suggest to build applications directly dependent on
2415     the driver operating system specific interface. We suggest to use the VCA
2416     API library for communication with the driver which brings higher level of
2417     system interface abstraction and ensures compatibility with the future
2418     versions of LINCAN driver and RT-Linux driver clone versions.</para>
2419
2420     <para>The basic utilities provided with LINCAN driver are:</para>
2421
2422     <variablelist>
2423       <varlistentry>
2424         <term>rxtx</term>
2425
2426         <listitem>
2427           <para>the simple utility to receive or send message which guides
2428           user through operation, the message type, the message ID and the
2429           message contents by simple prompts</para>
2430         </listitem>
2431       </varlistentry>
2432
2433       <varlistentry>
2434         <term>send</term>
2435
2436         <listitem>
2437           <para>even more simplistic message sending program</para>
2438         </listitem>
2439       </varlistentry>
2440
2441       <varlistentry>
2442         <term>readburst</term>
2443
2444         <listitem>
2445           <para>the utility for continuous messages reception and printing of
2446           the message contents. This utility can be used as an example of the
2447           <function>select</function> system call usage.</para>
2448         </listitem>
2449       </varlistentry>
2450
2451       <varlistentry>
2452         <term>sendburst</term>
2453
2454         <listitem>
2455           <para>the periodic message generator. Each message is filled by
2456           the constant pattern and the message sequence number. This utility
2457           can be used for throughput and message drops tests.</para>
2458         </listitem>
2459       </varlistentry>
2460
2461       <varlistentry>
2462         <term>can-proxy</term>
2463
2464         <listitem>
2465           <para>the simple TCP/IP to CAN proxy. The proxy receives simple
2466           commands from IP datagrams and processes command sending and
2467           state manipulations. Received messages are packed into IP
2468           datagrams and send back to the client.</para>
2469         </listitem>
2470       </varlistentry>
2471     </variablelist>
2472   </section>
2473
2474   <section>
2475     <title>Installation Instructions</title>
2476
2477     <section>
2478       <title>Installation Prerequisites</title>
2479
2480       <para>The next basic conditions are necessary for the LINCAN driver
2481       usage</para>
2482
2483       <itemizedlist>
2484         <listitem>
2485           <para>some of supported types of CAN interface boards (high or
2486           low speed)</para>
2487         </listitem>
2488       </itemizedlist>
2489
2490       <itemizedlist>
2491         <listitem>
2492           <para>cables and at least one device compatible with the board or
2493           the second computer with an another CAN interface board</para>
2494         </listitem>
2495       </itemizedlist>
2496
2497       <itemizedlist>
2498         <listitem>
2499           <para>working Linux system with any recent 2.4.x or 2.2.x kernel
2500           (successfully tested on 2.4.18, 2.4.19, 2.2.19, 2.2.20, 2.2.22
2501           kernels) or working setup for kernel cross-compilation</para>
2502         </listitem>
2503       </itemizedlist>
2504
2505       <itemizedlist>
2506         <listitem>
2507           <para>installed native and or target specific development tools
2508           (GCC and binutils) and pre-configured kernel sources
2509           corresponding to the running kernel or intended target for
2510           cross-compilation</para>
2511         </listitem>
2512       </itemizedlist>
2513
2514       <para>Every non-archaic Linux distribution should provide good
2515       starting point for the LINCAN driver installation.</para>
2516     </section>
2517
2518     <section>
2519       <title>Quick Installation Instructions</title>
2520
2521       <para>Change current directory into the LINCAN driver source root
2522       directory <programlisting>cd lincan-dir</programlisting>invoke make
2523       utility. Just type &#39;<command>make</command>&#39; at the command
2524       line and driver should compile without errors<programlisting>make</programlisting></para>
2525
2526       <para>If there is problem with compilation, look at first lines
2527       produced by &#39;make&#39; command or store make output in file.
2528       More about possible problems and more complex compilation examples
2529       is in the next subsection.</para>
2530
2531       <para>Install built LINCAN driver object file (<filename>can.o</filename>)
2532       into Linux kernel loadable module directory (<filename>/lib/modules/2.<replaceable>x</replaceable>.<replaceable>y</replaceable>/kernel/drivers/char</filename>).
2533       This and next commands needs root privileges to proceed
2534       successfully.<programlisting>make install</programlisting>If device
2535       filesystem (devfs) is not used on the computer, device nodes have to
2536       be created manually.<programlisting>
2537       mknod -m666 /dev/can0 c 91 0
2538       mknod -m666 /dev/can1 c 91 1
2539       ...
2540       mknod -m666 /dev/can7 c 97 7
2541       </programlisting></para>
2542
2543       <para>The parameters, IO address and interrupt line of inserted CAN
2544       interface card need to be determined and configured. The manual
2545       driver load can be invoked from the command line with parameters
2546       similar to example below
2547       <programlisting>
2548       insmod can.o hw=pip5 irq=4 io=0x8000
2549       </programlisting>This commands loads module with selected
2550       one card support for PIP5 board type with IO port base address
2551       <constant>0x8000</constant> and interrupt line <constant>4</constant>.
2552       The full description of module parameters is in the next subsection.
2553       If module starts correctly utilities from <filename>utils</filename>
2554       subdirectory can be used to test CAN message interchange with device
2555       or another computer. The parameters should be written into file
2556       <filename>/etc/modules.conf </filename>for subsequent module startup
2557       by modprobe command.</para>
2558
2559       <para>Line added to file <filename>/etc/modules.conf</filename>
2560       follows<programlisting>options can hw=pip5 irq=4 io=0x8000</programlisting>The
2561       module dependencies should be updated by command
2562       <programlisting>depmod -a</programlisting>The driver can be now stopped and started by
2563       simple <command>modprobe</command> command
2564       <programlisting>modprobe -r can modprobe can</programlisting></para>
2565     </section>
2566
2567     <section>
2568       <title>Installation instructions</title>
2569
2570       <para>The LINCAN make solutions tries to fully automate native
2571       kernel out of tree module compilation. Make system recurses through
2572       kernel <filename>Makefile</filename> to achieve selection of right
2573       preprocessor, compiler and linker directives. The description of
2574       make targets after make invocation in driver top directory follows</para>
2575
2576       <variablelist>
2577         <varlistentry>
2578           <term>lincan-drv/Makefile (all)</term>
2579
2580           <listitem>
2581             <para>LINCAN driver top makefile</para>
2582           </listitem>
2583         </varlistentry>
2584
2585         <varlistentry>
2586           <term>lincan-drv/src/Makefile (default or all -&#62;
2587           make_this_module)</term>
2588
2589           <listitem>
2590             <para>Needs to resolve target system kernel sources location.
2591             This can be selected manually by uncommenting the
2592             <filename>Makefile</filename> definition <command>KERNEL_LOCATION=/usr/src/linux-2.2.22</command>.
2593             The default behavior is to find the running kernel version and
2594             look for path to sources of found kernel version in
2595             <filename>/lib/modules/2.<replaceable>x</replaceable>.<replaceable>y</replaceable>/build</filename>
2596             directory. If no such directory exists, older version of
2597             kernel is assumed and makefile tries the <filename>/usr/src/linux</filename>
2598             directory.</para>
2599           </listitem>
2600         </varlistentry>
2601
2602         <varlistentry>
2603           <term>lib/modules/2.<replaceable>x</replaceable>.<replaceable>y</replaceable>/build/Makefile
2604           <envar>SUBDIRS</envar>=.../lincan-drv/src (modules)</term>
2605
2606           <listitem>
2607             <para>The kernel supplied <filename>Makefile</filename> is
2608             responsible for defining of right defines for preprocessor,
2609             compiler and linker. If the Linux kernel is cross-compiled,
2610             Linux kernel sources root <filename>Makefile</filename> needs
2611             be edited before Linux kernel compilation. The variable
2612             <envar>CROSS_COMPILE</envar> should contain development
2613             toolchain prefix, for example <command>arm-linux-</command>.
2614             The Linux kernel make process recurses back into LINCAN driver
2615             <filename>src/Makefile</filename>.</para>
2616           </listitem>
2617         </varlistentry>
2618
2619         <varlistentry>
2620           <term>lincan-drv/src/Makefile (modules)</term>
2621
2622           <listitem>
2623             <para>This pass starts real LINCAN driver build actions.</para>
2624           </listitem>
2625         </varlistentry>
2626       </variablelist>
2627
2628       <para>If there is problem with automatic build process, the next
2629       commands can help to diagnose the problem.</para>
2630
2631       <para><programlisting>make clean make &#62;make.out 2&#62;&#38;1</programlisting></para>
2632
2633       <para>The first lines of file <filename>make.out</filename>
2634       indicates autodetected values and can help with resolving of
2635       possible problems.</para>
2636
2637       <screen>
2638       make -C src default ;
2639       make -C utils default ;
2640       make[1]: /scripts/pathdown.sh: Command not found
2641       make[1]: Entering directory `/usr/src/can-0.7.1-pi3.4/src&#39;
2642       echo &#62;.supported_cards.h echo \#define ENABLE_CARD_pip 1 &#62;&#62;.supported_cards.h ; ...
2643       Linux kernel version 2.4.19
2644       echo Linux kernel sources /lib/modules/2.4.19/build
2645       Linux kernel sources /lib/modules/2.4.19/build
2646       echo Module target can.o
2647       Module target can.o
2648       echo Module objects proc.o pip.o pccan.o smartcan.o nsi.o ...
2649       make[2]: Entering directory `/usr/src/linux-2.4.19&#39;</screen>
2650
2651       <para>The driver size can be decreased by restricting of number of
2652       supported types of boards. This can be done by editing of definition
2653       for <envar>SUPPORTED_CARDS</envar> variable.</para>
2654
2655       <para> There is complete description of driver supported parameters.
2656       <programlisting>
2657       insmod can.o hw=<replaceable>&#39;your hardware&#39;</replaceable> irq=<replaceable>&#39;irq number&#39;</replaceable> io=<replaceable>&#39;io address&#39;</replaceable> <replaceable>&#60;more options&#62;</replaceable>
2658       </programlisting>
2659       </para>
2660       <para>The more values can be specified for <parameter>hw</parameter>,
2661       <parameter>irq</parameter> and <parameter>io</parameter> parameters
2662       if more cards is used. Values are separated by commas in such case.
2663       The <parameter>hw</parameter> argument can be one of:</para>
2664
2665       <itemizedlist>
2666         <listitem>
2667           <para><option>pip5</option>, for the PIP5 computer by MPL AG</para>
2668         </listitem>
2669
2670         <listitem>
2671           <para><option>pip6</option>, for the PIP6 computer by MPL AG</para>
2672         </listitem>
2673
2674         <listitem>
2675           <para><option>pip7</option>, for the PIP7 computer by MPL AG</para>
2676         </listitem>
2677
2678         <listitem>
2679           <para><option>pip8</option>, for the PIP8 computer by MPL AG</para>
2680         </listitem>
2681
2682         <listitem>
2683           <para><option>pccan-q</option>, for the PCcan-Q ISA card by
2684           KVASER</para>
2685         </listitem>
2686
2687         <listitem>
2688           <para><option>pccan-f</option>, for the PCcan-F ISA card by
2689           KVASER</para>
2690         </listitem>
2691
2692         <listitem>
2693           <para><option>pccan-s</option>, for the PCcan-S ISA card by
2694           KVASER</para>
2695         </listitem>
2696
2697         <listitem>
2698           <para><option>pccan-d</option>, for the PCcan-D ISA card by
2699           KVASER</para>
2700         </listitem>
2701
2702         <listitem>
2703           <para><option>nsican</option>, for the CAN104 PC/104 card by NSI</para>
2704         </listitem>
2705
2706         <listitem>
2707           <para><option>cc104</option>, for the CAN104 PC/104 card by
2708           Contemporary Controls</para>
2709         </listitem>
2710
2711         <listitem>
2712           <para><option>aim104</option>, for the AIM104CAN PC/104 card by
2713           Arcom Control Systems </para>
2714         </listitem>
2715
2716         <listitem>
2717           <para><option>pc-i03</option>, for the PC-I03 ISA card by IXXAT</para>
2718         </listitem>
2719
2720         <listitem>
2721           <para><option>pcm3680</option>, for the PCM-3680 PC/104 card by
2722           Advantech </para>
2723         </listitem>
2724
2725         <listitem>
2726           <para><option>m437</option>, for the M436 PC/104 card by SECO</para>
2727         </listitem>
2728
2729         <listitem>
2730           <para><option>bfadcan</option> for sja1000 CAN embedded card
2731           made by BFAD GmbH</para>
2732         </listitem>
2733
2734         <listitem>
2735           <para><option>pikronisa</option> for ISA memory mapped sja1000
2736           CAN card made by PiKRON Ltd.</para>
2737         </listitem>
2738
2739         <listitem>
2740           <para><option>template</option>, for yet unsupported hardware
2741           (you need to edit <filename>src/template.c</filename>)</para>
2742         </listitem>
2743       </itemizedlist>
2744
2745       <para>The <parameter>&#60;more options&#62;</parameter> can be one
2746       or more of:</para>
2747
2748       <itemizedlist>
2749         <listitem>
2750           <para><parameter>major</parameter>=<replaceable>&#60;nr&#62;</replaceable>,
2751           major specifies the major number of the driver.</para>
2752         </listitem>
2753
2754         <listitem>
2755           <para><parameter>minor</parameter>=<replaceable>&#60;nr&#62;</replaceable>,
2756           you can specify which minor numbers the driver should use for
2757           your hardware</para>
2758         </listitem>
2759
2760         <listitem>
2761           <para><parameter>extended</parameter>=<replaceable>[</replaceable>1<replaceable>|</replaceable>0<replaceable>]</replaceable>,
2762           configures the driver to use extended message format</para>
2763         </listitem>
2764
2765         <listitem>
2766           <para><parameter>pelican</parameter>=<replaceable>[</replaceable>1<replaceable>|</replaceable>0<replaceable>]</replaceable>,
2767           configures the driver to set the CAN chips into pelican mode.</para>
2768         </listitem>
2769
2770         <listitem>
2771           <para><parameter>baudrate</parameter>=<replaceable>&#60;nr&#62;</replaceable>,
2772           sets the baudrate of the device(s) </para>
2773         </listitem>
2774
2775         <listitem>
2776           <para><parameter>clock_freq</parameter>=<replaceable>&#60;nr&#62;</replaceable>,
2777           the frequency of the CAN quartz </para>
2778         </listitem>
2779
2780         <listitem>
2781           <para><parameter>stdmask</parameter>=<replaceable>&#60;nr&#62;</replaceable>,
2782           sets the standard mask of the device </para>
2783         </listitem>
2784
2785         <listitem>
2786           <para><parameter>mo15mask</parameter>=<replaceable>&#60;nr&#62;</replaceable>,
2787           sets the mask for message object 15 (i82527 only)</para>
2788         </listitem>
2789       </itemizedlist>
2790     </section>
2791   </section>
2792 </section>