Kvaser Linux CANLIB

LIN

Data Structures

struct  LinMessageInfo

Defines

#define linINVALID_HANDLE   ((LinHandle)(-1))
#define CompilerAssert(exp)   extern char _CompilerAssert[(exp) ? 1 : -1]
#define LINERROR(f)   ((f) & (LIN_NODATA | LIN_CSUM_ERROR | LIN_SYNCH_ERROR | LIN_BIT_ERROR))
#define LINLIBAPI

Typedefs

typedef int LinHandle

Functions

void linInitializeLibrary (void)
LinStatus linGetTransceiverData (int channel, unsigned char eanNo[8], unsigned char serNo[8], int *ttype)
LinHandle linOpenChannel (int channel, int flags)
LinStatus linClose (LinHandle h)
LinStatus linGetFirmwareVersion (LinHandle h, unsigned char *bootVerMajor, unsigned char *bootVerMinor, unsigned char *bootVerBuild, unsigned char *appVerMajor, unsigned char *appVerMinor, unsigned char *appVerBuild)
LinStatus linSetBitrate (LinHandle h, unsigned int bps)
LinStatus linBusOn (LinHandle h)
LinStatus linBusOff (LinHandle h)
unsigned long linReadTimer (LinHandle h)
LinStatus linWriteMessage (LinHandle h, unsigned int id, const void *msg, unsigned int dlc)
LinStatus linRequestMessage (LinHandle h, unsigned int id)
LinStatus linReadMessage (LinHandle h, unsigned int *id, void *msg, unsigned int *dlc, unsigned int *flags, LinMessageInfo *msgInfo)
LinStatus linReadMessageWait (LinHandle h, unsigned int *id, void *msg, unsigned int *dlc, unsigned int *flags, LinMessageInfo *msgInfo, unsigned long timeout)
LinStatus linUpdateMessage (LinHandle h, unsigned int id, const void *msg, unsigned int dlc)
LinStatus linSetupIllegalMessage (LinHandle h, unsigned int id, unsigned int cFlags, unsigned int delay)
LinStatus linSetupLIN (LinHandle h, unsigned int lFlags, unsigned int bps)
LinStatus linWriteWakeup (LinHandle h, unsigned int count, unsigned int interval)
LinStatus linClearMessage (LinHandle h, unsigned int id)
LinStatus linWriteSync (LinHandle h, unsigned long timeout)
LinStatus linGetCanHandle (LinHandle h, unsigned int *canHandle)

Return codes from the LINlib functions


enum  LinStatus {
  linOK = 0,
  linERR_NOMSG = -1,
  linERR_NOTRUNNING = -3,
  linERR_RUNNING = -4,
  linERR_MASTERONLY = -5,
  linERR_SLAVEONLY = -6,
  linERR_PARAM = -7,
  linERR_NOTFOUND = -8,
  linERR_NOMEM = -9,
  linERR_NOCHANNELS = -10,
  linERR_TIMEOUT = -11,
  linERR_NOTINITIALIZED = -12,
  linERR_NOHANDLES = -13,
  linERR_INVHANDLE = -14,
  linERR_CANERROR = -15,
  linERR_ERRRESP = -16,
  linERR_WRONGRESP = -17,
  linERR_DRIVER = -18,
  linERR_DRIVERFAILED = -19,
  linERR_NOCARD = -20,
  linERR_LICENSE = -21,
  linERR_INTERNAL = -22,
  linERR_NO_ACCESS = -23,
  linERR_VERSION = -24
}

LIN message flags

The following flags can be returned from linReadMessage() and linReadMessageWait().
#define LIN_TX   1
#define LIN_RX   2
#define LIN_WAKEUP_FRAME   4
#define LIN_NODATA   8
#define LIN_CSUM_ERROR   16
#define LIN_PARITY_ERROR   32
#define LIN_SYNCH_ERROR   64
#define LIN_BIT_ERROR   128

Flags for linOpenChannel()

#define LIN_MASTER   1
#define LIN_SLAVE   2

LIN illegal message flags


#define LIN_MSG_DISTURB_CSUM   1
#define LIN_MSG_DISTURB_PARITY   2

LIN message parity


#define LIN_MSG_USE_STANDARD_PARITY   0x04
#define LIN_MSG_USE_ENHANCED_PARITY   0x08

LIN setup

#define LIN_ENHANCED_CHECKSUM   1
#define LIN_VARIABLE_DLC   2

Define Documentation

#define CompilerAssert (   exp)    extern char _CompilerAssert[(exp) ? 1 : -1]
#define LIN_BIT_ERROR   128

Bit error when transmitting.

#define LIN_CSUM_ERROR   16

Checksum error.

#define LIN_ENHANCED_CHECKSUM   1

When specified, the LIN interface will use the "enhanced" checksum according to LIN 2.0. Note that (as per the LIN 2.0 spec) the enhanced checksum is not used on the diagnostic frames even if the LIN_ENHANCED_CHECKSUM setting is in effect.

The default value is OFF.

#define LIN_MASTER   1

The LIN interface will be a LIN master.

#define LIN_MSG_DISTURB_CSUM   1

The checksum of transmitted messages will be inverted (and consequently illegal.)

#define LIN_MSG_DISTURB_PARITY   2

The two parity bits will be inverted (and consequently illegal.) Used only in master mode.

#define LIN_MSG_USE_ENHANCED_PARITY   0x08

Use standard (1.x) parity for the specified msg

#define LIN_MSG_USE_STANDARD_PARITY   0x04

Use enhanced (2.x) parity for the specified msg

#define LIN_NODATA   8

No data, only a header.

#define LIN_PARITY_ERROR   32

ID parity error.

#define LIN_RX   2

The message was something we received from the bus.

#define LIN_SLAVE   2

The LIN interface will be a LIN slave.

#define LIN_SYNCH_ERROR   64

A synch error.

#define LIN_TX   1

The message was something we transmitted on the bus.

#define LIN_VARIABLE_DLC   2

When specified, turns variable message length on, so the the message length will depend on the message ID.

The default value is ON.

#define LIN_WAKEUP_FRAME   4

A wake up frame was received. Id/msg/dlc are undefined.

#define LINERROR (   f)    ((f) & (LIN_NODATA | LIN_CSUM_ERROR | LIN_SYNCH_ERROR | LIN_BIT_ERROR))

Macro for determining if a flag field contains a LIN error flag bit.

#define linINVALID_HANDLE   ((LinHandle)(-1))

Invalid LIN handle

#define LINLIBAPI

Typedef Documentation

typedef int LinHandle

LIN handle


Enumeration Type Documentation

enum LinStatus
Enumerator:
linOK 

OK - no error.

linERR_NOMSG 

No messages available.

linERR_NOTRUNNING 
linERR_RUNNING 
linERR_MASTERONLY 
linERR_SLAVEONLY 
linERR_PARAM 

Error in parameter.

linERR_NOTFOUND 

Specified hardware not found. This error is reported when the LIN transceiver isn't powered up.

linERR_NOMEM 

Out of memory.

linERR_NOCHANNELS 

No channels avaliable.

linERR_TIMEOUT 

Timeout occurred.

linERR_NOTINITIALIZED 

Library not initialized.

linERR_NOHANDLES 

Can't get handle.

linERR_INVHANDLE 

Handle is invalid.

linERR_CANERROR 
linERR_ERRRESP 

There was an error response from the LIN interface.

linERR_WRONGRESP 

The LIN interface response wasn't the expected one.

linERR_DRIVER 

CAN driver type not supported.

linERR_DRIVERFAILED 

DeviceIOControl failed; use the Win32 GetLastError API to get the real (WIn32) error code.

linERR_NOCARD 

The card was removed or not inserted.

linERR_LICENSE 

The license is not valid.

linERR_INTERNAL 

Internal error in the driver.

linERR_NO_ACCESS 

Access denied.

linERR_VERSION 

Function not supported in this version.


Function Documentation

LinStatus linBusOff ( LinHandle  h)

This function deactivates the LIN interface. It will not participate further in the LIN bus traffic.

Parameters:
[in]hA handle to an open LIN channel.
Returns:
linOK (zero) if success
linERR_xxx (negative) if failure
See also:
linBusOn()
LinStatus linBusOn ( LinHandle  h)

This function activates the LIN interface.

Note:
It will be reset, so any setups done earlier will be lost.
Parameters:
[in]hA handle to an open LIN channel.
Returns:
linOK (zero) if success
linERR_xxx (negative) if failure
See also:
linBusOff()
LinStatus linClearMessage ( LinHandle  h,
unsigned int  id 
)

Clear a message buffer for a LIN slave. The message buffer will not answer next time it is polled.

Parameters:
[in]hA handle to an open LIN channel.
[in]idThe LIN message id for which the corresponding buffer will be cleared.
Returns:
linOK (zero) if success
linERR_xxx (negative) if failure
LinStatus linClose ( LinHandle  h)

Closes an open handle to a LIN channel. The handle becomes invalid and can not be used in subsequent calls to the LIN functions.

Parameters:
[in]hA handle to an open LIN channel.
Returns:
linOK (zero) if success
linERR_xxx (negative) if failure
See also:
linOpenChannel()
LinStatus linGetCanHandle ( LinHandle  h,
unsigned int *  canHandle 
)

Return the CAN handle given an open LIN handle

Parameters:
[in]hA handle to an open LIN channel.
[out]canHandleA pointer to an integer where the CAN handle will be stored.
Returns:
linOK (zero) if success
linERR_xxx (negative) if failure
LinStatus linGetFirmwareVersion ( LinHandle  h,
unsigned char *  bootVerMajor,
unsigned char *  bootVerMinor,
unsigned char *  bootVerBuild,
unsigned char *  appVerMajor,
unsigned char *  appVerMinor,
unsigned char *  appVerBuild 
)

This function retrieves the firmware version from the LIN interface.

Note:
The version numbers aren't valid until linBusOn() has been called.
The firmware in the LIN interface is divided into two parts, the boot code and the application. The boot code is used only when reprogramming (reflashing) the LIN interface. The application handles all LIN communication.
Version numbers are, since the precambric era, divided into a major version number, a minor version number and a build number. These are usually written like, for example, 3.2.12. Here the major number is 3, the minor number 2 and the build number 12.
Parameters:
[in]hA handle to an open LIN channel.
[out]bootVerMajorA pointer to a byte where the major version number of the boot code is stored.
[out]bootVerMinorA pointer to a byte where the minor version number of the boot code is stored.
[out]bootVerBuildA pointer to a byte where the build number of the boot code is stored.
[out]appVerMajorA pointer to a byte where the major version number of the application code is stored.
[out]appVerMinorA pointer to a byte where the minor version number of the application code is stored.
[out]appVerBuildA pointer to a byte where the build number of the application is stored.
Returns:
linOK (zero) if success
linERR_xxx (negative) if failure
LinStatus linGetTransceiverData ( int  channel,
unsigned char  eanNo[8],
unsigned char  serNo[8],
int *  ttype 
)

Retrieves the transceiver information for a CAN channel. The application typically uses this call to find out whether a particular CAN channel has a LIN interface connected to it. For a Kvaser LIN Leaf it retrieves the transceiver type and device information.

This function call will open the CAN channel, but no CAN messages are transmitted on it. In other words, it's risk-free to use even if no LIN interface is connected, or if the channel is connected to a CAN system.

Note:
Attempts to use the channel for LIN communication will be meaningful only if linGetTransceiverData() stores canTRANSCEIVER_TYPE_LIN in ttype.
A LIN interface need not be powered for this call to succeed.
The information may not always be accurate. Especially after changing transceiver on a running LAPcan card, you should go on bus and off bus again to be sure the transceiver information is updated.
Parameters:
[in]channelThe number of a CAN channel for which the transceiver data will be retrieved.
[out]eanNoA pointer to an array of 8 bytes where the EAN number of the LIN interface will be stored.
[out]serNoA pointer to an array of 8 bytes where the serial number of the LIN interface will be stored.
[out]ttypeA pointer to an integer where the transceiver type will be stored.
Returns:
linOK (zero) if success
linERR_xxx (negative) if failure
See also:
linGetFirmwareVersion()
void linInitializeLibrary ( void  )

This function initializes the LIN library and must be called before any other LIN function is called. If this function isn't called, subsequent calls to the other LIN functions will return linERR_NOTINITIALIZED.

See also:
linOpenChannel()
LinHandle linOpenChannel ( int  channel,
int  flags 
)

Open a channel to a LIN interface.

Note:
For DRV Lin: The cable must be powered and connected to a LAPcan channel.
For Kvaser LIN Leaf: The Leaf must be powered from the LIN side.
Parameters:
[in]channelThe number of the channel. Channel numbering is hardware dependent. This is the same channel number as used by canOpenChannel().
[in]flagsEither one of the following values: LIN_MASTER or LIN_SLAVE.
Returns:
If the call succeeds, a handle to the opened channel is returned. The handle is an integer greater than or equal to zero.
If the call fails, the return value is a negative integer indicating an error code. See linERR_xxx for a list of possible error codes.
See also:
linClose()
LinStatus linReadMessage ( LinHandle  h,
unsigned int *  id,
void *  msg,
unsigned int *  dlc,
unsigned int *  flags,
LinMessageInfo msgInfo 
)

Read a message from the LIN interface. If a message is available for reception, linOK is returned. This is a non-blocking call. If no message is available in the LIN interface, an error code is returned.

Note:
This call will also return echoes of what the LIN interface is transmitting with linWriteMessage. In other words, the LIN interface can hear itself.
Parameters:
[in]hA handle to an open LIN channel.
[out]idA pointer to an integer where the identifier of the received LIN message will be stored.
[out]msgA pointer to a buffer where the data of the LIN message will be stored.
[out]dlcA pointer to an integer where the length of the received LIN message will be stored.
[out]flagsA combination of zero or more of the LIN_xxx flags.
[out]msgInfoA pointer to a LinMessageInfo struct where data about the received LIN message will be stored.
Returns:
linOK (zero) if success
linERR_xxx (negative) if failure
See also:
linReadMessageWait()
LinStatus linReadMessageWait ( LinHandle  h,
unsigned int *  id,
void *  msg,
unsigned int *  dlc,
unsigned int *  flags,
LinMessageInfo msgInfo,
unsigned long  timeout 
)

Read a message from the LIN interface. If a message is available for reception, linOK is returned. This is a blocking call. It waits until a message is received in the LIN interface, or the specified timeout period elapses.

Note:
This call will also return echoes of what the LIN interface is transmitting with linWriteMessage(). In other words, the LIN interface can hear itself.
Parameters:
[in]hA handle to an open LIN channel.
[in]timeoutThe maximum number of milliseconds to wait for a message to be received by the LIN interface.
[out]idA pointer to an integer where the identifier of the received LIN message will be stored.
[out]msgA pointer to a buffer where the data of the LIN message will be stored.
[out]dlcA pointer to an integer where the length of the received LIN message will be stored.
[out]flagsA combination of zero or more of the LIN_xxx flags.
[out]msgInfoA pointer to a LinMessageInfo struct where data about the received LIN message will be stored.
Returns:
linOK (zero) if success
linERR_xxx (negative) if failure
See also:
linReadMessage()
unsigned long linReadTimer ( LinHandle  h)

Return the current timer value (used for timestamps)

Note:
For convenience, this call returns the timer value instead of passing it in a parameter. This means that if the call fails, it will still return a value (which then is the error code, type casted to a long unsigned integer - e.g. 0xFFFFFFF2 for linERR_INVHANDLE. Watch out.
Parameters:
[in]hA handle to an open LIN channel.
Returns:
If the call succeeds, the present timer value is returned.
LinStatus linRequestMessage ( LinHandle  h,
unsigned int  id 
)

This function writes a LIN message header to the LIN bus. A slave in the system is then expected to fill in the header with data.

Note:
This call is only available in master mode.
Parameters:
[in]hA handle to an open LIN channel.
[in]idThe identifier of the LIN message.
Returns:
linOK (zero) if success
linERR_xxx (negative) if failure
LinStatus linSetBitrate ( LinHandle  h,
unsigned int  bps 
)

This function sets the bit rate for a master, or the initial bit rate for a slave. The LIN interface should not be on-bus when this function is called.

Note:
The LIN Interface should not be on bus.
Supported bit rates are 1000 - 20000 bits per second.
Parameters:
[in]hA handle to an open LIN channel.
[in]bpsBit rate in bits per second.
Returns:
linOK (zero) if success
linERR_xxx (negative) if failure
LinStatus linSetupIllegalMessage ( LinHandle  h,
unsigned int  id,
unsigned int  cFlags,
unsigned int  delay 
)

Using this function, it is possible to use the LIN interface to create corrupted LIN messages. You call the function once for each LIN identifier that should be affected.

To return to normal mode, either restart the LIN interface (by going off bus and on the bus again) or call the function with delay and cFlags set to zero.

Note:
The LIN Interface must be on bus for this command to work.
It is supported in firmware version 2.4.1 and later.
Parameters:
[in]hA handle to an open LIN channel.
[in]idThe identifier of the LIN message.
[in]cFlagsOne or more of the LIN_MSG_DISTURB_xxx flags.
[in]delayThe delay parameter will result in a delay of this many bittimes after the header and before the first data byte.
Returns:
linOK (zero) if success
linERR_xxx (negative) if failure
See also:
linSetupLIN()
LinStatus linSetupLIN ( LinHandle  h,
unsigned int  lFlags,
unsigned int  bps 
)

This function changes various settings on a LIN Interface that is on bus. When going on bus, the bit rate and the flag values listed below are set to the default value (either as hard-coded in the firmware, or as stored in the non-volatile memory of the LIN Interface).

With this function, you can do one or more of the following things:

  • Select checksum according to LIN 2.0
  • Turn variable message length off. The message length then will depend on the message ID.

In master mode it is also possible to change the bit rate without going off bus first.

Note:
The LIN Interface must be on bus for this command to work.
It is supported in firmware version 2.5.1 and later.
For LIN 2.0 compliance, you must specify both LIN_ENHANCED_CHECKSUM and LIN_VARIABLE_DLC.
Parameters:
[in]hA handle to an open LIN channel.
[in]lFlagsOne or more of the following flags: LIN_ENHANCED_CHECKSUM, LIN_VARIABLE_DLC
bpsSpecifies the bit rate in bits per second. This parameter can be used only in master mode. The bit rate is set without going off bus.
Returns:
linOK (zero) if success
linERR_xxx (negative) if failure
See also:
linSetupIllegalMessage()
LinStatus linUpdateMessage ( LinHandle  h,
unsigned int  id,
const void *  msg,
unsigned int  dlc 
)

This function updates a message buffer in a slave. The contents of the message buffer will be used the next time the slave is polled for the specified LIN message id.

Note:
The LIN Interface must be on bus.
Parameters:
[in]hA handle to an open LIN channel.
[in]idThe identifier of the LIN message.
[in]msgA pointer to a buffer containing the data of the LIN message.
[in]dlcThe length of the LIN message.
Returns:
linOK (zero) if success
linERR_xxx (negative) if failure
See also:
linClearMessage()
LinStatus linWriteMessage ( LinHandle  h,
unsigned int  id,
const void *  msg,
unsigned int  dlc 
)

Write a LIN message. It is advisable to wait until the message is echoed by linReadMessage() before transmitting a new message, or in case of a schedule table being used, transmit the next message when the previous one is known to be complete.

Note:
Only available in master mode.
Parameters:
[in]hA handle to an open LIN channel.
[in]idThe identifier of the LIN message.
[in]msgA pointer to a buffer containing the data of the LIN message.
[in]dlcThe length of the LIN message.
Returns:
linOK (zero) if success
linERR_xxx (negative) if failure
See also:
linWriteSync()
LinStatus linWriteSync ( LinHandle  h,
unsigned long  timeout 
)

Call this function to make sure all messages transmitted to the LIN Interface has been received by it.

When messages are transmitted to the LIN Interface, they are queued by Windows before appearing on the CAN bus.

The function returns linOK if all writes are done, linERR_TIMEOUT in case of timeout or possibly some other error code.

If the LIN Interface is in master mode and a LIN message has been transmitted with linWriteMessage(), this function will return when the LIN Interface has received the message. If another LIN messa ge is being received or transmitted, the message will not be transmitted on the LIN bus at once. And even if the LIN Interface is idle, the header of the new message will just have been started when linWriteSync() retur ns.

After calling linUpdateMessage() and linClearMessage() for a slave, this function is enough to know that the LIN Interface is updated.

After linWriteMessage(), it is advisable to wait until the message is echoed by linReadMessage() before transmitting a new message, or in case of a schedule table being used, transmit the next message when the previous one is known to be complete.

When, in master mode, a message should be transmitted after a poll (reception) is done, it might be necessary to call linWriteMessage() before the result is received via linReadMessage() as the LIN Interface waits up to the maximum frame length before knowing a received message is complete. A new message to transmit will force completion if the currently received one.

Parameters:
[in]hA handle to an open LIN channel.
[in]timeoutThe maximum number of milliseconds to wait for the queued messages to be transmitted by the LIN interface.
Returns:
linOK (zero) if success
linERR_xxx (negative) if failure
See also:
linWriteMessage()
LinStatus linWriteWakeup ( LinHandle  h,
unsigned int  count,
unsigned int  interval 
)

Write a wakeup frame.

If count is zero, one single wakeup frame is transmitted. If count > 1, several wakeup frames are transmitted spaced with 'interval' bittimes. The LIN interface will interrupt the sequence when a LIN message or another command is received. The stream of wakeups will be recived as incoming messages with the LIN_RX flag bit set.

Parameters:
[in]hA handle to an open LIN channel.
[in]countThe number of wakeup frames to send.
[in]intervalThe time, in bit times, between the wakeup frames.
Returns:
linOK (zero) if success
linERR_xxx (negative) if failure