Introduction

This is the documentation for the vcan CAN-Bus driver for the VxWorks operating system developed at Helmholtz-Zentrum Berlin. This documentation describes basic concepts of the driver and the types and constants defined vcan.h. The driver is accessed with the usual io-functions such as read, write and ioctl that are part of the operating system. For these reasons, vcan.h defines almost no functions but only types and constants that have to be used with the operating system-functions.

Although the driver has one set of source files compiling it creates two binaries, “vcan.o” and “vcan4.o”. “vcan.o” is the driver version for the VME-CAN2 card while “vcan4.o” is the driver version for the VME-CAN4 card. Both can co-exist on an IOC meaning that both object files can be loaded without conflicts with respect to exported symbols. “vcan.o” creates a driver with the device filename “/dev/vcan” while “vcan4.o” creates a driver with the device filename “/dev/vcan4”. Note that although both drivers may be loaded on one IOC the IOC can only have one kind of CAN bus cards, either all VME-CAN2 or all VME-CAN4.

Here are some explanations of terms used in this document:

Frame

This is a single CAN message. Logically, a frame consists of the CAN-Object Id and 0 up to 8 data bytes. The actual bits that make up a frame on the CAN bus are a few more, consisting of a 16 Bit CRC, sync. bits and some other informations. As a rule of thumb, the data bits (except the CAN Id) make up only half of the bits of the whole frame.

CAN Id

This is the Id of the data frame. This is also called CAN-object Id or object-Id for short. CAN Id’s can range from 0 to 2047.

Object

Since CAN can only transfer broadcast messages, in principle each CAN device receives all CAN frames that are sent. However, in order to filter out information that is not needed, a device usually sets up CAN objects. A CAN object is a data buffer that is coupled with a certain CAN Id. The object receives only frames with the same CAN Id and stores the information in the internal buffer. CAN objects are also used for sending data, in this case the data bytes are written to the object’s data buffer, the actual (serial) sending of the data to the CAN bus is performed by the CAN hardware.

Thread

This is the name for a user-thread. The VCAN driver is capable to handle more than one user-thread at a time (in this context ‘thread’ is synonym to ‘process’). Different threads are distinguished by the driver by an internal thread-id. This is a number that the driver puts into the file-structure that is created by the system when the system-function ‘open’ is called.

Owner of an Object

An object becomes owned, when a thread assigns a type and a length to that object with the VCAN_INIT sub-function. From that moment on no other thread is not allowed to access that object. Each object has an internal owner-number that equals the thread-id of the owner. When a thread deletes his object by calling the VCAN_INIT sub-function to set the object-mode to VCAN_MODE_FREE, the object becomes unowned again. Each thread is only allowed to access unowned or it’s own objects.

Length

As mentioned before, a CAN frame and a CAN object have a certain length that is in the range of 0 to 8. It is not defined what will happen when a data frame is received with a number of data bytes that is different from the number defined in the CAN object. The VME-CAN2 card stores all data bytes of the frame anyway. Although there is a length specified for each object, the length of the internal data buffer is always 8 bytes. When data is written to the can-bus, the length that was set up when the object was defined, will be used.

Net

A net is one of the CAN ports of the VME-CAN2 card. One VME-CAN2 card supports the independent access to 2 CAN nets. The driver supports up to 4 VME-CAN2 cards at a time, so up to 8 ports at a time. In this documentation a synonym for net is port.

Port

A synonym for “net” (see above).

Card-Number

The vcan-driver supports up to 4 VME-CAN2 cards in a single system. The cards, however, must be configured to use different VME-addresses and VME interrupt vectors in order to avoid address-conflicts. For this purpose, a scheme has been defined how to configure each card. Each card in a system gets a card-number between 0 and 3 that is unique in that system. The card is the configured according to the section “Addresses and Jumpers” in this manual. The port-numbers that the vcan-driver uses to access this card are then (card_number)*2 and (card_number)*2+1.

Semaphore

Although this term does not show up in the constants and data types needed by the driver, it has a meaning for event-objects. There is a driver-function, VCAN_QUEUE_READ, that waits on a semaphore that is given when an event takes place on one of several event-objects.

Event-Object

The term ‘event-object’, the older term for this is ‘signal-object’, describes a CAN object that is not directly read. Instead, the user-program waits for an event, usually the arrival of new data, on several event-objects. If there is an event detected, the user program is notified by the semaphore mechanism (see ‘semaphore’).