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

   1 <?xml version='1.0'?>
   2 <!DOCTYPE book PUBLIC "-//Norman Walsh//DTD DocBk XML V4.1.2//EN"
   3                "/usr/lib/sgml/dtd/docbook-xml/docbookx.dtd">
   4
   5 <book id="CANDeviceDriver">
   6  <bookinfo>
   7   <title>CAN Device Driver</title>
   8
   9   <authorgroup>
  10    <author>
  11     <firstname>Pavel</firstname>
  12     <surname>Pisa</surname>
  13     <affiliation>
  14      <address>
  15       <email>pisa@cmp.felk.cvut.cz</email>
  16      </address>
  17     </affiliation>
  18    </author>
  19   </authorgroup>
  20
  21   <copyright>
  22    <year>2002</year>
  23    <holder>Pavel Pisa</holder>
  24   </copyright>
  25
  26   <legalnotice>
  27    <para>
  28      This documentation is free software; you can redistribute
  29      it and/or modify it under the terms of the GNU General Public
  30      License as published by the Free Software Foundation; either
  31      version 2 of the License, or (at your option) any later
  32      version.
  33    </para>
  34
  35    <para>
  36      This program is distributed in the hope that it will be
  37      useful, but WITHOUT ANY WARRANTY; without even the implied
  38      warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  39      See the GNU General Public License for more details.
  40    </para>
  41
  42    <para>
  43      You should have received a copy of the GNU General Public
  44      License along with this program; if not, write to the Free
  45      Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
  46      MA 02111-1307 USA
  47    </para>
  48
  49    <para>
  50      For more details see the file COPYING in the source
  51      distribution of CAN driver.
  52    </para>
  53
  54   </legalnotice>
  55  </bookinfo>
  56
  57 <toc></toc>
  58
  59   <chapter id="intro">
  60       <title>Introduction</title>
  61   <para>
  62       The Linux CAN driver.
  63   </para>
  64   </chapter>
  65
  66   <chapter id="Basics">
  67      <title>Driver Basics</title>
  68      <sect1><title>Driver Entry and Exit points</title>
  69 <refentry>
  70 <refmeta>
  71 <refentrytitle><phrase id="API-template-request-io">template_request_io</phrase></refentrytitle>
  72 </refmeta>
  73 <refnamediv>
  74  <refname>template_request_io</refname>
  75  <refpurpose>
  76    reserve io memory
  77  </refpurpose>
  78 </refnamediv>
  79 <refsynopsisdiv>
  80  <title>Synopsis</title>
  81   <funcsynopsis><funcprototype>
  82    <funcdef>int <function>template_request_io </function></funcdef>
  83    <paramdef>unsigned long <parameter>io_addr</parameter></paramdef>
  84   </funcprototype></funcsynopsis>
  85 </refsynopsisdiv>
  86 <refsect1>
  87  <title>Arguments</title>
  88  <variablelist>
  89   <varlistentry>
  90    <term><parameter>io_addr</parameter></term>
  91    <listitem>
  92     <para>
  93       The reserved memory starts at <parameter>io_addr</parameter>, wich is the module
  94      parameter <parameter>io</parameter>.
  95     </para>
  96    </listitem>
  97   </varlistentry>
  98  </variablelist>
  99 </refsect1>
 100 <refsect1>
 101  <title>Description</title>
 102  <para>
 103    The function <function>template_request_io</function> is used to reserve the io-memory. If your
 104    hardware uses a dedicated memory range as hardware control registers you
 105    will have to add the code to reserve this memory as well.
 106    <constant>IO_RANGE</constant> is the io-memory range that gets reserved, please adjust according
 107    your hardware. Example: #define IO_RANGE 0x100 for i82527 chips or
 108    #define IO_RANGE 0x20 for sja1000 chips in basic CAN mode.
 109  </para>
 110 </refsect1>
 111 <refsect1>
 112  <title>Return Value</title>
 113  <para>
 114     The function returns zero on success or <constant>-ENODEV</constant> on failure
 115  </para>
 116 </refsect1>
 117 <refsect1>
 118  <title>File</title>
 119  <para>
 120     src/template.c
 121  </para>
 122 </refsect1>
 123 </refentry>
 124
 125 <refentry>
 126 <refmeta>
 127 <refentrytitle><phrase id="API-template-release-io">template_release_io</phrase></refentrytitle>
 128 </refmeta>
 129 <refnamediv>
 130  <refname>template_release_io</refname>
 131  <refpurpose>
 132       free reserved io-memory
 133  </refpurpose>
 134 </refnamediv>
 135 <refsynopsisdiv>
 136  <title>Synopsis</title>
 137   <funcsynopsis><funcprototype>
 138    <funcdef>int <function>template_release_io </function></funcdef>
 139    <paramdef>unsigned long <parameter>io_addr</parameter></paramdef>
 140   </funcprototype></funcsynopsis>
 141 </refsynopsisdiv>
 142 <refsect1>
 143  <title>Arguments</title>
 144  <variablelist>
 145   <varlistentry>
 146    <term><parameter>io_addr</parameter></term>
 147    <listitem>
 148     <para>
 149       Start of the memory range to be released.
 150     </para>
 151    </listitem>
 152   </varlistentry>
 153  </variablelist>
 154 </refsect1>
 155 <refsect1>
 156  <title>Description</title>
 157  <para>
 158    The function <function>template_release_io</function> is used to free reserved io-memory.
 159    In case you have reserved more io memory, don't forget to free it here.
 160    IO_RANGE is the io-memory range that gets released, please adjust according
 161    your hardware. Example: #define IO_RANGE 0x100 for i82527 chips or
 162    #define IO_RANGE 0x20 for sja1000 chips in basic CAN mode.
 163  </para>
 164 </refsect1>
 165 <refsect1>
 166  <title>Return Value</title>
 167  <para>
 168     The function always returns zero
 169  </para>
 170 </refsect1>
 171 <refsect1>
 172  <title>File</title>
 173  <para>
 174     src/template.c
 175  </para>
 176 </refsect1>
 177 </refentry>
 178
 179 <refentry>
 180 <refmeta>
 181 <refentrytitle><phrase id="API-template-reset">template_reset</phrase></refentrytitle>
 182 </refmeta>
 183 <refnamediv>
 184  <refname>template_reset</refname>
 185  <refpurpose>
 186       hardware reset routine
 187  </refpurpose>
 188 </refnamediv>
 189 <refsynopsisdiv>
 190  <title>Synopsis</title>
 191   <funcsynopsis><funcprototype>
 192    <funcdef>int <function>template_reset </function></funcdef>
 193    <paramdef>int <parameter>card</parameter></paramdef>
 194   </funcprototype></funcsynopsis>
 195 </refsynopsisdiv>
 196 <refsect1>
 197  <title>Arguments</title>
 198  <variablelist>
 199   <varlistentry>
 200    <term><parameter>card</parameter></term>
 201    <listitem>
 202     <para>
 203       Number of the hardware card.
 204     </para>
 205    </listitem>
 206   </varlistentry>
 207  </variablelist>
 208 </refsect1>
 209 <refsect1>
 210  <title>Description</title>
 211  <para>
 212    The function <function>template_reset</function> is used to give a hardware reset. This is
 213    rather hardware specific so I haven't included example code. Don't forget to
 214    check the reset status of the chip before returning.
 215  </para>
 216 </refsect1>
 217 <refsect1>
 218  <title>Return Value</title>
 219  <para>
 220     The function returns zero on success or <constant>-ENODEV</constant> on failure
 221  </para>
 222 </refsect1>
 223 <refsect1>
 224  <title>File</title>
 225  <para>
 226     src/template.c
 227  </para>
 228 </refsect1>
 229 </refentry>
 230
 231 <refentry>
 232 <refmeta>
 233 <refentrytitle><phrase id="API-template-init-hw-data">template_init_hw_data</phrase></refentrytitle>
 234 </refmeta>
 235 <refnamediv>
 236  <refname>template_init_hw_data</refname>
 237  <refpurpose>
 238       Initialze hardware cards
 239  </refpurpose>
 240 </refnamediv>
 241 <refsynopsisdiv>
 242  <title>Synopsis</title>
 243   <funcsynopsis><funcprototype>
 244    <funcdef>int <function>template_init_hw_data </function></funcdef>
 245    <paramdef>int <parameter>card</parameter></paramdef>
 246   </funcprototype></funcsynopsis>
 247 </refsynopsisdiv>
 248 <refsect1>
 249  <title>Arguments</title>
 250  <variablelist>
 251   <varlistentry>
 252    <term><parameter>card</parameter></term>
 253    <listitem>
 254     <para>
 255       Number of the hardware card.
 256     </para>
 257    </listitem>
 258   </varlistentry>
 259  </variablelist>
 260 </refsect1>
 261 <refsect1>
 262  <title>Description</title>
 263  <para>
 264    The function <function>template_init_hw_data</function> is used to initialize the hardware
 265    structure containing information about the installed CAN-board.
 266    <constant>RESET_ADDR</constant> represents the io-address of the hardware reset register.
 267    <constant>NR_82527</constant> represents the number of intel 82527 chips on the board.
 268    <constant>NR_SJA1000</constant> represents the number of philips sja1000 chips on the board.
 269    The flags entry can currently only be <constant>PROGRAMMABLE_IRQ</constant> to indicate that
 270    the hardware uses programmable interrupts.
 271  </para>
 272 </refsect1>
 273 <refsect1>
 274  <title>Return Value</title>
 275  <para>
 276     The function always returns zero
 277  </para>
 278 </refsect1>
 279 <refsect1>
 280  <title>File</title>
 281  <para>
 282     src/template.c
 283  </para>
 284 </refsect1>
 285 </refentry>
 286
 287 <refentry>
 288 <refmeta>
 289 <refentrytitle><phrase id="API-template-init-chip-data">template_init_chip_data</phrase></refentrytitle>
 290 </refmeta>
 291 <refnamediv>
 292  <refname>template_init_chip_data</refname>
 293  <refpurpose>
 294       Initialize chips
 295  </refpurpose>
 296 </refnamediv>
 297 <refsynopsisdiv>
 298  <title>Synopsis</title>
 299   <funcsynopsis><funcprototype>
 300    <funcdef>int <function>template_init_chip_data </function></funcdef>
 301    <paramdef>int <parameter>card</parameter></paramdef>
 302    <paramdef>int <parameter>chipnr</parameter></paramdef>
 303   </funcprototype></funcsynopsis>
 304 </refsynopsisdiv>
 305 <refsect1>
 306  <title>Arguments</title>
 307  <variablelist>
 308   <varlistentry>
 309    <term><parameter>card</parameter></term>
 310    <listitem>
 311     <para>
 312       Number of the hardware card
 313     </para>
 314    </listitem>
 315   </varlistentry>
 316   <varlistentry>
 317    <term><parameter>chipnr</parameter></term>
 318    <listitem>
 319     <para>
 320       Number of the CAN chip on the hardware card
 321     </para>
 322    </listitem>
 323   </varlistentry>
 324  </variablelist>
 325 </refsect1>
 326 <refsect1>
 327  <title>Description</title>
 328  <para>
 329    The function <function>template_init_chip_data</function> is used to initialize the hardware
 330    structure containing information about the CAN chips.
 331    <constant>CHIP_TYPE</constant> represents the type of CAN chip. <constant>CHIP_TYPE</constant> can be <quote>i82527</quote> or
 332    <quote>sja1000</quote>.
 333    The <parameter>chip_base_addr</parameter> entry represents the start of the 'official' memory map
 334    of the installed chip. It's likely that this is the same as the <parameter>io_addr</parameter>
 335    argument supplied at module loading time.
 336    The <parameter>clock</parameter> entry holds the chip clock value in Hz.
 337    The entry <parameter>sja_cdr_reg</parameter> holds hardware specific options for the Clock Divider
 338    register. Options defined in the <constant>sja1000</constant>.h file:
 339    <constant>CDR_CLKOUT_MASK</constant>, <constant>CDR_CLK_OFF</constant>, <constant>CDR_RXINPEN</constant>, <constant>CDR_CBP</constant>, <constant>CDR_PELICAN</constant>
 340    The entry <parameter>sja_ocr_reg</parameter> holds hardware specific options for the Output Control
 341    register. Options defined in the <constant>sja1000</constant>.h file:
 342    <constant>OCR_MODE_BIPHASE</constant>, <constant>OCR_MODE_TEST</constant>, <constant>OCR_MODE_NORMAL</constant>, <constant>OCR_MODE_CLOCK</constant>,
 343    <constant>OCR_TX0_LH</constant>, <constant>OCR_TX1_ZZ</constant>.
 344    The entry <parameter>int_clk_reg</parameter> holds hardware specific options for the Clock Out
 345    register. Options defined in the <constant>i82527</constant>.h file:
 346    <constant>iCLK_CD0</constant>, <constant>iCLK_CD1</constant>, <constant>iCLK_CD2</constant>, <constant>iCLK_CD3</constant>, <constant>iCLK_SL0</constant>, <constant>iCLK_SL1</constant>.
 347    The entry <parameter>int_bus_reg</parameter> holds hardware specific options for the Bus
 348    Configuration register. Options defined in the <constant>i82527</constant>.h file:
 349    <constant>iBUS_DR0</constant>, <constant>iBUS_DR1</constant>, <constant>iBUS_DT1</constant>, <constant>iBUS_POL</constant>, <constant>iBUS_CBY</constant>.
 350    The entry <parameter>int_cpu_reg</parameter> holds hardware specific options for the cpu interface
 351    register. Options defined in the <constant>i82527</constant>.h file:
 352    <constant>iCPU_CEN</constant>, <constant>iCPU_MUX</constant>, <constant>iCPU_SLP</constant>, <constant>iCPU_PWD</constant>, <constant>iCPU_DMC</constant>, <constant>iCPU_DSC</constant>, <constant>iCPU_RST</constant>.
 353  </para>
 354 </refsect1>
 355 <refsect1>
 356  <title>Return Value</title>
 357  <para>
 358     The function always returns zero
 359  </para>
 360 </refsect1>
 361 <refsect1>
 362  <title>File</title>
 363  <para>
 364     src/template.c
 365  </para>
 366 </refsect1>
 367 </refentry>
 368
 369 <refentry>
 370 <refmeta>
 371 <refentrytitle><phrase id="API-template-init-obj-data">template_init_obj_data</phrase></refentrytitle>
 372 </refmeta>
 373 <refnamediv>
 374  <refname>template_init_obj_data</refname>
 375  <refpurpose>
 376       Initialize message buffers
 377  </refpurpose>
 378 </refnamediv>
 379 <refsynopsisdiv>
 380  <title>Synopsis</title>
 381   <funcsynopsis><funcprototype>
 382    <funcdef>int <function>template_init_obj_data </function></funcdef>
 383    <paramdef>int <parameter>chipnr</parameter></paramdef>
 384    <paramdef>int <parameter>objnr</parameter></paramdef>
 385   </funcprototype></funcsynopsis>
 386 </refsynopsisdiv>
 387 <refsect1>
 388  <title>Arguments</title>
 389  <variablelist>
 390   <varlistentry>
 391    <term><parameter>chipnr</parameter></term>
 392    <listitem>
 393     <para>
 394       Number of the CAN chip
 395     </para>
 396    </listitem>
 397   </varlistentry>
 398   <varlistentry>
 399    <term><parameter>objnr</parameter></term>
 400    <listitem>
 401     <para>
 402       Number of the message buffer
 403     </para>
 404    </listitem>
 405   </varlistentry>
 406  </variablelist>
 407 </refsect1>
 408 <refsect1>
 409  <title>Description</title>
 410  <para>
 411    The function <function>template_init_obj_data</function> is used to initialize the hardware
 412    structure containing information about the different message objects on the
 413    CAN chip. In case of the sja1000 there's only one message object but on the
 414    i82527 chip there are 15.
 415    The code below is for a i82527 chip and initializes the object base addresses
 416    The entry <parameter>obj_base_addr</parameter> represents the first memory address of the message
 417    object. In case of the sja1000 <parameter>obj_base_addr</parameter> is taken the same as the chips
 418    base address.
 419    Unless the hardware uses a segmented memory map, flags can be set zero.
 420  </para>
 421 </refsect1>
 422 <refsect1>
 423  <title>Return Value</title>
 424  <para>
 425     The function always returns zero
 426  </para>
 427 </refsect1>
 428 <refsect1>
 429  <title>File</title>
 430  <para>
 431     src/template.c
 432  </para>
 433 </refsect1>
 434 </refentry>
 435
 436 <refentry>
 437 <refmeta>
 438 <refentrytitle><phrase id="API-template-program-irq">template_program_irq</phrase></refentrytitle>
 439 </refmeta>
 440 <refnamediv>
 441  <refname>template_program_irq</refname>
 442  <refpurpose>
 443       program interrupts
 444  </refpurpose>
 445 </refnamediv>
 446 <refsynopsisdiv>
 447  <title>Synopsis</title>
 448   <funcsynopsis><funcprototype>
 449    <funcdef>int <function>template_program_irq </function></funcdef>
 450    <paramdef>int <parameter>card</parameter></paramdef>
 451   </funcprototype></funcsynopsis>
 452 </refsynopsisdiv>
 453 <refsect1>
 454  <title>Arguments</title>
 455  <variablelist>
 456   <varlistentry>
 457    <term><parameter>card</parameter></term>
 458    <listitem>
 459     <para>
 460       Number of the hardware card.
 461     </para>
 462    </listitem>
 463   </varlistentry>
 464  </variablelist>
 465 </refsect1>
 466 <refsect1>
 467  <title>Description</title>
 468  <para>
 469    The function <function>template_program_irq</function> is used for hardware that uses
 470    programmable interrupts. If your hardware doesn't use programmable interrupts
 471    you should not set the <parameter>candevices_t</parameter>-&gt;flags entry to <constant>PROGRAMMABLE_IRQ</constant> and
 472    leave this function unedited. Again this function is hardware specific so
 473    there's no example code.
 474  </para>
 475 </refsect1>
 476 <refsect1>
 477  <title>Return value</title>
 478  <para>
 479     The function returns zero on success or <constant>-ENODEV</constant> on failure
 480  </para>
 481 </refsect1>
 482 <refsect1>
 483  <title>File</title>
 484  <para>
 485     src/template.c
 486  </para>
 487 </refsect1>
 488 </refentry>
 489
 490 <refentry>
 491 <refmeta>
 492 <refentrytitle><phrase id="API-template-write-register">template_write_register</phrase></refentrytitle>
 493 </refmeta>
 494 <refnamediv>
 495  <refname>template_write_register</refname>
 496  <refpurpose>
 497       Low level write register routine
 498  </refpurpose>
 499 </refnamediv>
 500 <refsynopsisdiv>
 501  <title>Synopsis</title>
 502   <funcsynopsis><funcprototype>
 503    <funcdef>void <function>template_write_register </function></funcdef>
 504    <paramdef>unsigned char <parameter>data</parameter></paramdef>
 505    <paramdef>unsigned long <parameter>address</parameter></paramdef>
 506   </funcprototype></funcsynopsis>
 507 </refsynopsisdiv>
 508 <refsect1>
 509  <title>Arguments</title>
 510  <variablelist>
 511   <varlistentry>
 512    <term><parameter>data</parameter></term>
 513    <listitem>
 514     <para>
 515       data to be written
 516     </para>
 517    </listitem>
 518   </varlistentry>
 519   <varlistentry>
 520    <term><parameter>address</parameter></term>
 521    <listitem>
 522     <para>
 523       memory address to write to
 524     </para>
 525    </listitem>
 526   </varlistentry>
 527  </variablelist>
 528 </refsect1>
 529 <refsect1>
 530  <title>Description</title>
 531  <para>
 532    The function <function>template_write_register</function> is used to write to hardware registers
 533    on the CAN chip. You should only have to edit this function if your hardware
 534    uses some specific write process.
 535  </para>
 536 </refsect1>
 537 <refsect1>
 538  <title>Return Value</title>
 539  <para>
 540     The function does not return a value
 541  </para>
 542 </refsect1>
 543 <refsect1>
 544  <title>File</title>
 545  <para>
 546     src/template.c
 547  </para>
 548 </refsect1>
 549 </refentry>
 550
 551 <refentry>
 552 <refmeta>
 553 <refentrytitle><phrase id="API-template-read-register">template_read_register</phrase></refentrytitle>
 554 </refmeta>
 555 <refnamediv>
 556  <refname>template_read_register</refname>
 557  <refpurpose>
 558       Low level read register routine
 559  </refpurpose>
 560 </refnamediv>
 561 <refsynopsisdiv>
 562  <title>Synopsis</title>
 563   <funcsynopsis><funcprototype>
 564    <funcdef>unsigned <function>template_read_register </function></funcdef>
 565    <paramdef>unsigned long <parameter>address</parameter></paramdef>
 566   </funcprototype></funcsynopsis>
 567 </refsynopsisdiv>
 568 <refsect1>
 569  <title>Arguments</title>
 570  <variablelist>
 571   <varlistentry>
 572    <term><parameter>address</parameter></term>
 573    <listitem>
 574     <para>
 575       memory address to read from
 576     </para>
 577    </listitem>
 578   </varlistentry>
 579  </variablelist>
 580 </refsect1>
 581 <refsect1>
 582  <title>Description</title>
 583  <para>
 584    The function <function>template_read_register</function> is used to read from hardware registers
 585    on the CAN chip. You should only have to edit this function if your hardware
 586    uses some specific read process.
 587  </para>
 588 </refsect1>
 589 <refsect1>
 590  <title>Return Value</title>
 591  <para>
 592     The function returns the value stored in <parameter>address</parameter>
 593  </para>
 594 </refsect1>
 595 <refsect1>
 596  <title>File</title>
 597  <para>
 598     src/template.c
 599  </para>
 600 </refsect1>
 601 </refentry>
 602
 603      </sect1>
 604   </chapter>
 605 </book>