documentation

canbus4linux,来自www.sourceforge.net

                     D O C U M E N T A T I O N

            C A N B U S 4 L I N U X   V E R S I O N   0 . 3


Copyright 2001 by Juergen Eder <[e-mail]>


No liability for the contents of this document can be accepted. Use the concepts, 
examples and other content at your own risk. 

All copyrights are held by their respective owners, unless specifically noted otherwise. 
Use of a term in this document should not be regarded as affecting the validity of
any trademark or service mark. 

The file elektor_canpar.o is a driver for the can card from 
"Elektor magazine june, 2000". 
Homepage: http://www.elektor.de

The file can200par.o is a driver for the can card from CAN200 Project (it's also a card for the
parallelport)
Homepage: http://private.addcom.de/horo/can200/index.html

The file cantronik.o is a driver for the can card from cantronik.com

The canbus4linux driver is completely new written and use no part from
Elektor or CAN200 project!

****************************************************************************
Installation:
see file: INSTALL

****************************************************************************
Licence:
see file: COPYING

****************************************************************************
Features:
- interrupt driven
- should work with kernel 2.2.16 or newer
  (tested with 2.6.6)
- support CAN200 card and elektor CAN card (both for the parallelport)
  other cards can easily added with mini driver
- support CAN 2.0A and 2.0B (PeliCAN) of SJA1000 chip
- support /proc filesystem (/proc/canbus/...)
- parameters can be controlled by: IOCTL's and /proc filesystem
- read and write are implemented
  => example: echo "1234 0 12 34 55" > /dev/can0
     send a can message with:
       can id = 0x1234 
       rtr = 0
       data bytes = 0x12 0x34 0x55
  => cat /dev/can0
     shows the can messages
- support poll and fsync
- support fasync
- time stamp in all events
- a virtual CAN bus is simulated, if several applications uses the same CAN channel
  => example: 2 applications (x and y) open /dev/can0
     -> application x send a message (and get the "transmission event)
     -> application y get the receive message, because of the "virtual bus structure"
  => it's possible to turn off virtualization


       ---------------                  |<------ virtual CAN bus
       |             |   send data      |
       |    App x    |---->------>----->|
       |             |                  |
       ---------------                  |
                                        |
       ---------------                  |
       |             |   get data       |
       |    App y    |<-----<--------<--|
       |             |                  |
       ---------------                  |
                                        |
                                        |
                                 ---------------
                                 |  Hardware   |
                                 ---------------
                                        |
                                        |<------- real CAN bus
                                        |

- the two drivers for the ELEKTOR CAN CARD and the CAN200 CAN CARD use
  the parport driver
- the chipset driver (SJA1000.O) calculates the BTR registers



****************************************************************************
Description:
Actually the driver has three layers:

Layer 1: elektor_canpar.o and/or can200par.o
This layer implements the hardware access to the chip registers. This layer 
is specific for every hardware.

Layer 2: SJA1000.O
It's the chipset layer and implements all features of the SJA1000
from Philips. This driver "translates" the order's from layer 3
to chip registers. For example layer 3 want 125000 baud. Layer 2 calculates 
the BTR0 and BTR1 register and set this register with layer 1.

Layer 3: canbuscore.o
It's a core driver between the hardware driver and the application. 
This layer implements all features: read/write, ioctl's, ...


---------------------------------------------
|                APPLICATION                |
---------------------------------------------
                      |
---------------------------------------------
|                CANBUSCORE.O               |
---------------------------------------------
       |                      |
---------------  ------------------------------
|  SJA1000.O  |  |  <other  hardware driver>  |      chipset driver or hardware driver
---------------  ------------------------------
        |                     |
     ------------------       -------------------
     |                |             |           |
-------------  ---------------  ---------  ---------
| ELEKTOR.O |  | CAN200PAR.O |  | <ISA> |  | <USB> |  ....
-------------  ---------------  ---------  ---------


****************************************************************************
Accessing CAN bus with scripts:
If a CAN driver is installed and started, it will create a directory:
/proc/canbus
and sub directories as many devices are available:
/proc/canbus/0
/proc/canbus/1
/proc/canbus/2
/proc/canbus/3
/proc/canbus/...

In "/proc/canbus/devices" you get the number of installed devices, for 
example 1 sub directory if you have only LPT1 and installed only elektor_canpar.o 
(or only can200par.o).

In the sub directories (./0, ./1, ...) you get information from every CAN channel. Some 
information are write only and some are read only:
- ./baudrate (read/write: one line with decimal integer value)
- ./busload (read: busload in percentage  => not implemented yet)
- ./filter (read/write: one line with 2 values hexadecimal acceptance filter)
- ./format (read/write: one line with 1 value integer: 0=default, 1=11 bit, 2=29 bit)
- ./lost (read: lost messages while receiving)
- ./mode (read/write: one line with 1 value integer: 0=CAN 2.0A   1=CAN 2.0B PeliCAN)
- ./receive (XXX: TODO)
- ./standby (read/write: one line with 1 value integer: 0=active  1=standby)
- ./transmit (write: one line with a CAN message, all values hexadecimal: <can id> <rtr> [<data bytes>])
- ./virtualize (read/write: one line with 1 value integer: 0=virtualize off   1=virtualize on)
- ./information (read: information about the CAN channel)


****************************************************************************
Access with scripts:
To set all values, you can use the /proc filesystem and the echo command:
Examples:

Baudrate:   echo 500000 > /proc/canbus/0/baudrate
Filter  :   echo "ffffffff ffffffff" > /proc/canbus/0/filter
Transmit:   echo "1234 0 11 22 33 44 55 66 77 88" > /proc/canbus/0/transmit

To receive CAN messages, you can use the "cat" command:
cat /dev/can0

If some data will received, you get a line shown below:

received  1010852408:682453  00000111   0  0  [n data bytes]  0
    |              |            |       |  |        |         |---- lost messages
    |              |            |       |  |        |-------------- n data bytes (max. 8)
    |              |            |       |  |----------------------- dlc (data length code = number of received bytes)
    |              |            |       |-------------------------- rtr (remote transmission request bit)
    |              |            |---------------------------------- CAN id
    |              |----------------------------------------------- 64 bit system time
    |-------------------------------------------------------------- meaning of this event

Of course you can write CAN messages into a simple text file and 'copy' this
file to the CAN device:
content of simple.txt:
1234 0 11 22 33 44 55 66 77 88
0188 0 11 22

(Very important is the linefeed, don't forget a linefeed at the last line!)

Copying:
cp simple.txt /dev/can0

All messages in the text file will be sent over CAN bus.



If you use scripting, it's better to turn off virtualization:
echo 0 > /proc/canbus/0/virtualize
                                                    

****************************************************************************
Accessing CAN bus using read/write and /proc - filesystem:
First open the CAN driver (for example /dev/can0). After that you
can read or write values into /proc - filesystem (see also above "Accessing CAN bus with scripts").

Example: Write one message
FILE *canbus;
canbus = fopen("/dev/can0","w");
if(canbus)
{
     fprintf(canbus,"1234 0 11 22 33 44 55 66 77 88\n");  // the \n is important !!
     fclose(canbus);
}

Example: Read one message
FILE *canbus;
canbus = fopen("/dev/can0","r");
if(canbus)
{
     char buffer[100];
     fgets(buffer,sizeof(buffer),canbus);
     printf(buffer);
     fclose(canbus);
}

Example: Set baudrate
FILE *canbus;
canbus = fopen("/proc/canbus/0/baudrate","w");
if(canbus)
{
     fprintf(canbus,"500000");
     fclose(canbus);
}

All other /proc/canbus parameters are described in "Accessing CAN bus with scripts".


****************************************************************************
Accessing CAN bus using ioctl: (recommended method)


In C or C++ programs, the header file "canbus4linux.h" can be used.

----------------------------------------------------------------------------
Open and close a CAN device with read/write access:

    int file;

    file = open("/dev/can0",O_RDWR);
    if(file == -1)
    {
        printf("can't open canbus4linux device\n");
    }
    else
    {
        // Because of following 2 lines, a signal is generated on every event 
        // (receiving, transmitting, errors, warnings,...)
        fcntl(file,F_SETOWN,getpid());
        fcntl(file,F_SETFL, FASYNC | fcntl(file,F_GETFL));
    }

Later close the CAN device:
    if(file != -1)
    {
        close(file);
    }

----------------------------------------------------------------------------
Determine CAN driver properties:

    struct canbus_properties properties;
    ioctl(file, CANBUS4LINUX_READ_PROPERTIES, &properties);



    The properties are:
    version           Version number of canbus4linux
    device_name[]     A string with the channel name, this string can displayed for 
	                  user information
    min               Minimal supported baudrate
    max               Maximal supported baudrate
    commands[]        An array with supported commands of this CAN channel, all known commands
	                  of canbus4linux are:
	                     CANBUS_CMD_ENTER_STANDBY,
	                     CANBUS_CMD_LEAVE_STANDBY,
	                     CANBUS_CMD_ABORT_TRANSMISSION,
	                     CANBUS_CMD_CLEAR_OVERRUN,
	                     CANBUS_CMD_SELF_RECEPTION_REQUEST,
	                     CANBUS_CMD_LISTEN_ON,
	                     CANBUS_CMD_LISTEN_OFF,
	                     CANBUS_CMD_VIRTUALIZE_ON,
	                     CANBUS_CMD_VIRTUALIZE_OFF,
    number_commands   Number of valid entries in "commands[]"
    baudrates[]       (Optional) An array with supported baudrates of this CAN channel
    number_baudrates  Number of valid entries in "baudrates[]"
    chipset_flags     Bit field, which describes some features of the CAN channel:
	                     CANBUS_CFS_CAN_2_0_A     channel support CAN 2.0 A (Basic CAN)
	                     CANBUS_CFS_CAN_2_0_B     channel support CAN 2.0 B
	                     CANBUS_CFS_EXT_FRAME     channel support extended frame format (only used if 
	                                              supports CAN 2.0 B too)
	                     CANBUS_CFS_POLLING       channel is not(!) interrupt driven, all
	                                              data must get with polling method
    number_registers  Number of supported registers


    Note:
    CANBUS_CFS_POLLING is not implemented yet
    number_registers is not implemented yet

----------------------------------------------------------------------------
Init CAN channel:

To init the CAN channel, this function is used:
    ioctl(file, CANBUS4LINUX_INIT, 0);

----------------------------------------------------------------------------
Read/Write acceptance filter:

Read acceptance filter
    struct canbus_acceptance_filter filter;
    ioctl(file, CANBUS4LINUX_READ_ACCEPTANCE_FILTER, &filter);

Write acceptance filter:
    struct canbus_acceptance_filter filter;
    filter.code = .....;
    filter.mask = .....;
    ioctl(file, CANBUS4LINUX_WRITE_ACCEPTANCE_FILTER, &filter);

----------------------------------------------------------------------------
Read/Write baudrate: