Link cable library
Reference manual

What in this manual ?

This documentation is for those who want use the library under Linux or Windows. This library is being ported under BeOS and is going to be ported on Macintosh computers.
The documentation is divided into six chapters:

Chapter 1: Introduction discusses adding the library to your system and provides an overview of handled link cables and available functions.

Chapter 2: Data types tells about the different definition of types which are provided to the user.

Chapter 3: Setting up link cables guides you through the steps to set up link cables on your computer.

Chapter 4: General functions details the software functions that are not specific to link cable.

Chapter 5: Link cable functions details functions that are specific to link cable.

Chapter 6: Appendices include installation instructions for the libTIcable library and procedures to add the lib to your system. In addition the Appendix D explains the procedure for compiling programs which use this library. For your convenience separate Appendices cover "Flags for use", a "Code Index" and a list of "Error messages".

I Introduction

Chapter 1 provides an overview of the libTicable library. The topics covered are:

• overview,

• functions,

• conventions used in this manual.

Overview

The library contains routines to handle the different link cables designed for the TI calculators under different platforms. It can also manage virtual linking. This feature is discussed further in the text.

The supported platform are: Linux, Windows9x and WindowsNT4. The use of this library under Windows NT4 requires a special I/O driver: DriverLYNX DLPortIO driver. This driver can also be used under Windows9x. I did not test the library under the Windows 2000 platform and I do not think that it will work.

The supported link cables are:
- the home-made parallel (alias 5$-cable),
- the home-made serial (alias 4$-cable),
- the Black TIGraphLink,
- and Grey/Gray TIGraphLink cable.
There is also an experimental support for the AVRlink cable (it is my own link cable: Grey TIGL compatible, 4 times faster) but it is still in development.
At last, there is a full support for the TI device kernel module (Linux only).
The library provides also two virtual link cables for connecting an emulator to a linking software for instance.

Remark: it is not necessary to be 'root' under Linux for using the cables but all cables except for the Grey TIGL requires a direct access to I/O ports which limits the portability of code under others UNIXes.

Functions

The libTIcable is a set of 'C' languages subroutines designed to handle the different link cables through a same set of functions. This is a kind of driver even if this is not one.

The libTIcable library (Linux version) was written and tested using gcc under Linux. It was ported under Windows and tested using the Microsoft Visual C++ version 5.0. It seems that others compilers such as Borland C++ 4.0 or DJGPP do not work because they do not support long filenames ! In my mind, Microsoft compiler is a good choice (hmm, I prefer Linux !).

The functions are supplied both in source form and linked as a DLL. The source code is released under the GPL licence and the libraries under the LGPL license.

Each function is presented with its formal definition, including data types of all input and output variables. A brief description of the purpose of the function is provided along with the legal values for inputs where applicable. All structures and flags used by the libTIcable library are in Appendix G: "Flags for use".

Functions are written as "C" functions, i.e. they return values. A non zero value signifies an error.


Conventions used

To help differentiate between different kinds of information, the following text styles are used in the Reference Manual.

Functions look like this (charter font).
Variables look like this (courier font).
Parameter look like this (helmet font).
File names look like this (timmons font, bold).
FLAGS look like this (timmons font).

II Data types

Chapter 2 details the different data types provided to the user. These types are defined in the cable_defs.h file.

The most important type is a structure and is defined as below:

struct ticable_link
{
int (*init_port) (uint io_addr, char *device);
int (*open_port) ();
int (*put) (byte data);
int (*get) (byte *data);
int (*probe_port) (); // -> do not change the structure order !!!
int (*close_port) ();
int (*term_port) ();
int (*check_port) (int *status);
};
typedef struct ticable_link LINK_CABLE;

This structure contains a set of functions. These functions are used to handle a link cable. You will find more explanations on these functions further in the documentation.

The other data type is not used by the libTicable but is provided for your convenience.

struct ticable_param
{
int calc_type;
int link_type;
unsigned int io_addr;
char device[16];
int timeout;
int delay;
int tidev;
int dlportio;
int baud_rate;
};
typedef struct ticable_param LINK_PARAM;

It contains all variables required for setting up a link cable.

III Setting up link cables

Chapter 2 guides you through the steps to set up a link cable on your computer. Detailed operating instructions for the functions are described in Chapter 3.

To set up the libTIcable library:
1. call the main setup function,
2. set up the timeout and delay variables,
3. set up the io_address and io_device variables,
4. set up the baud_rate variable,
5. set up the link cable.

The I/O ports

To use the setup functions, you should know some informations about the I/O ports.
A parallel link cable can use the printer ports based on 0x3BC, 0x378 or 0x278.
A serial link cable or Black/Grey TIGraphLink cable can use the serial ports based on 0x3F8, 0x2F8, 0x3E8, 0x2E8.
These addresses are standard addresses but the library let you to use any address. So, you can use your cable with strange serial board... On the other hand, you should pay attention whether the address is valid or not.

Global setup function

To implement the global setup functions call:

1. get_cable_version to check the library version number.
2. set_timeout to set the timeout delay (parallel, serial and Black TIGL cables).
3. set_delay to set the inter-bit delay (parallel, serial and Black TIGL cables).
4. set_baudrate to set the baud-rate value (fastAVRlink link cable).
5. set_cable to set the link_cable structure according to your cable type.

NOTE: under Windows NT, the use of the DLPortIO driver is required but this driver driver is not compulsory under Windows9x. Anyways the library will auto-detect if this driver is present. If yes, it will use it else it will use its own I/O routines. If the driver is not present and if you are under Windows NT, you will get an error message (access violation).

Setting up a link cable

To set a link cable, you must follow this sequence:

1. init_port: this function must be called prior to any others.
2. open_port: this function must be called before a transfer if you do not call yet or if you have closed the port with close_port.
3. close_port: this function must be called once you have finished a transfer.
4. term_port: this function must be called whenever you exit of your program or if you want change of link cable.

IV General functions

Chapter 3 details the software functions that are not specific to a link cable.
The flags included in each functions are defined in Appendix ?.

The functions listed below are described in this chapter:

ticable_get_version
ticable_set_timeout
ticable_get_timeout
ticable_set_delay
ticable_get_delay
ticable_set_baudrate
ticable_get_baudrate
ticable_set_io_address
ticable_get_io_address
ticable_set_io_device
ticable_get_io_device
ticable_set_cable
ticable_get_error


ticable_get_version

Description: This functions returns the version number of the library as a string. This string as the following format: "major.minor.release" such as "1.0.5".

Syntax: const char *ticable_get_version()

Input parameters: none.

Output Parameters: none.

Return values: const char pointer, to a string.


ticable_set_timeout

Description: This functions set up the timeout value which is used by all link cable functions for exiting when the timeout delay is elapsed.

Syntax: int ticable_set_timeout(int timeout_v)

Input parameters: timeout_v, the timeout value in tenth of seconds. Example: 20 represents 2 seconds.

Output Parameters: none.

Return values: none.


ticable_get_timeout

Description: This functions returns the timeout value which is used by all link cable functions for breaking when the timeout delay is elapsed.

Syntax: int ticable_get_timeout()

Input parameters: none.

Output Parameters: none.

Return values: int, the timeout value in tenth of seconds.


ticable_set_delay

Description: This functions set up the delay value which is used by home-made link cable functions for defining the inter-bit delay. The lower, the faster but less stable.

Syntax: int ticable_set_delay(int delay_v)

Input parameters: delay_v, the delay value in micro-seconds.

Output Parameters: none.

Return values: none.


ticable_get_delay

Description: This functions returns the delay value which is used by home-made link cable functions for defining the inter-bit delay.

Syntax: int ticable_get_timeout()

Input parameters: none.

Output Parameters: none.

Return values: int, the delay value in micro-seconds.


ticable_set_baudrate

Description: This functions set up the baud-rate value which is used by fastAVRlink cable functions for defining the transfer rate. The value must be the same as than one defined by the 'fastAVRlink Setup Utility' else the link cable will not work (different baud-rates).

Syntax: void ticable_set_baudrate(int br);

Input parameters: br, the baud-rate value which can be one of the following flags: BR9600, BR19200, BR38400 or BR57600.

Output Parameters: none.

Return values: none.


ticable_get_baudrate

Description: This functions returns the baud-rate value which is used by fastAVRlink link cable functions for defining the transfer rate.

Syntax: int ticable_get_baudrate()

Input parameters: none.

Output Parameters: none.

Return values: int, the baud-rate value such as BR9600 for 9600 bauds.


ticable_set_io_address

Description: This functions set up the I/O port base address which is used by the link cable functions. The value must be a valid value. Moreover, for Linux user, this address must be an authorized address (see the tilp.access file which defines I/O permissions).

Syntax: void ticable_set_io_address(uint io_addr);

Input parameters: io_addr, an unsigned int number which contains the base address of the I/O port to access.

Output Parameters: none.

Return values: none.


ticable_get_io_address

Description: This functions returns the I/O port base address.

Syntax: uint ticable_get_io_address()

Input parameters: none.

Output Parameters: none.

Return values: int, the baud-rate value such as BR9600 for 9600 bauds.


ticable_set_io_device

Description: This functions set up the character device (Linux only) to use by the link cable functions. The value must be an existing character device else the libTIcable functions will return an error.

Syntax: void ticable_set_io_device(char * device);

Input parameters: device, a string which contains a character device name such as "/dev/ttyS0".

Output Parameters: none.

Return values: none.


ticable_get_io_device

Description: This functions returns the character device name which is used by link cable functions.

Syntax: char *ticable_get_io_device()

Input parameters: none.

Output Parameters: none.

Return values: char *, the character device name.


ticable_set_cable

Description: this functions takes as first parameter the link cable type and returns via the second parameter a structure of functions which contains the functions for the suitable link cable.

Syntax: void ticable_set_cable(int type, struct link_cable *lc)

Input parameters: type, one of the following flags: LINK_PAR, LINK_SER, LINK_TGL, LINK_AVR or LINK_VTL which can be combined (| OR) with LINK_DEV for using the 'tidev' kernel module.

Output Parameters: lc, a pointer on a structure which contains the seven functions used for manipulating transfers on the link cables and one for probing the link cable type.

Return values: none.


ticable_get_error

Description: returns the string corresponding to the error code returned by a link cable function. This function propagate the error code that is to say it returns the passed error code if it can not find the corresponding error message else it returns 0. This mechanism of propagation is useful for the libTIcalc library for instance.

Syntax: int ticable_get_error(int err_num, char *error_msg)

Input parameters: err_num, an error code returned by a link cable function.

Output Parameters: error_msg, a string which contains the corresponding error message.

Return values: int, 0 if the error code has been caught else the error code.

V Link cables functions

Chapter 4 details the software functions that are specific to link cable.

The functions listed below are described in this chapter:

init_port
open_port
put
get
close_port
term_port
probe_port
check_port

All functions described below returns an error code which can have different origins. It could be a timeout error, a byte error on the device, an error during the opening of a device or for obtaining some I/O permissions. You can get the corresponding error message with the get_cable_error function.


init_port

Description: this functions must be called prior to any of the following functions for initializing some internal variables and configuring ports or devices.

Syntax: int init_port(unsigned int io_addr, char *device)

Input parameters:
- io_addr, used by parallel, serial and Black TIGL cable. This is the base address of the I/O port where the cable is plugged. It must be a valid I/O address (often in the range 0x3ff).
This is also used for choosing the virtual link cable: either the #0 with VLINK0, either the #1 with VLINK1. By convention, the #0 is used by ab emulator for instance and the #1 is used by a linking software.
- device, used by the Grey/Gray TIGL cable.
Under Linux, this string contains the name of the character device where the cable is plugged in. Example: "/dev/ttyS0" ... "/dev/ttyS3".
Under Windows, this string contains the name of the COM port. Example: "COM1" ... "COM4".

Output Parameters: none.

Return values: an error code which can be turned into a string with the get_cable_error function.


open_port

Description: this functions must be called prior to any transfers for initializing some things and flushing some buffers.

Syntax: int open_port(void)

Input parameters: none.

Output Parameters: none.

Return values: an error code which can be turned into a string with the get_cable_error function.

put

Description: this functions send a byte (unsigned char) to the link cable.

Syntax: int put(byte data)

Input parameters: data, the byte to transmit on the link cable.

Output Parameters: none.

Return values: an error code which can be turned into a string with the get_cable_error function.

get

Description: this functions waits a byte (unsigned char) from the link cable.

Syntax: int get(byte *data)

Input parameters: none.

Output Parameters: data, the byte received from the link cable.

Return values: an error code which can be turned into a string with the get_cable_error function.

close_port

Description: this functions closes the transmission.You should call it whenever a transfer is finished.

Syntax: int close_port(void)

Input parameters: none.

Output Parameters: none.

Return values: an error code which can be turned into a string with the get_cable_error function.

term_port

Description: this functions closes the port and frees some ressources or devices. It must be called if you quit your program or if you have changed the link cable type before using init_port.

Syntax: int term_port(void)

Input parameters: none.

Output Parameters: none.

Return values: an error code which can be turned into a string with the get_cable_error function.


probe_port

Description: not useable for the moment.

Syntax: int probe_port(void)

Input parameters: none.

Output Parameters: none.

Return values: an error code which can be turned into a string with the get_cable_error function.


check_port

Description: this functions can be called to check the status of the link cable: check if a byte has been received and so on. This function is useful to check the receiving buffer without calling the 'get' function which is a blocking function.

Syntax: int check_port(int *status)

Input parameters: none.

Output Parameters: status, the status of the link cable. For the moment, this value can take only 2 values which are STATUS_NONE or STATUS_BYTE_RCV when a byte has been received.

Return values: an error code which can be turned into a string with the get_cable_error function.

VI Appendices

Appendix A: installation instructions.
Appendix B: compiling programs under Linux and/or Windows.
Appendix C: flags for use.
Appendix D: software tools library
Appendix E: Code Index.
Appendix F: Error Messages.
Appendix G: Function Index.

Appendix A: installation instructions

This appendix explains the procedure for adding/using libTIcable library on your system.

Linux procedure: retrieve a tarball of the library source code, make a 'tar xvzf libticable.tar.gz', go into the libTIcable directory. Type 'configure' to check your system and create the Makefile. Next, type 'make' to compile the library and at last, type 'make install' to install it.
By default, the shared object 'libti_cable.so' is placed in the '/usr/lib' directory and necessary links are created.
The headers files are placed in the '/usr/include/ti' directory. For including them, you just have to place a #include <ti/foo.h> on the beginning of your program.

Windows procedure: retrieve a ZIP archive of the library source code and uncompress it in the default folder. Next, place the .DLL file in the same directory than your program (local folder) or place it either in the C:\Windows\System32 directory either in the C:\WinNT\System32 directory according to your OS type.


Appendix B: compiling programs under Linux and/or Windows

Linux procedure: I provide the source of the library. Its installation as described above provides the shared object and necessary headers files. You just have to include the right headers files and compile your program during the linking/last stage with the -lti_cable option on the gcc command line.

Windows procedure: I provide a DLL for use with all versions of Windows and for the Microsoft compiler only. If you want use it with a Borland compiler, you have to recompile the library since the calling conventions are not the same (standard call calling convention ("stdcall") for Borland, C calling convention ("cdecl") for Microsoft).
To compile Windows program, to link together with the appropriate DLL, perform the following steps:
1. a .lib file is provided. Include the .lib file as part of your project.
2. include the "cable_interface.h" header files at the top of your test program. This header file include three files. The first, "typedefs.h" contains some type definitions. The second, "cable_defs.h" contains...

Appendix C: flags for use

Flags are grouped according to the function in which they are used. Some flags are used in more than one function, and they are duplicated in each section for clarity. Most flags are input parameters to the functions they are listed under.

NOTE: Always use flags where provided, rather than the value associated with it, since values may change. For example, use LINK_TGL with set_cable rather than 1.


set_timeout

set_delay

set_baudrate

set_cable

init_port

Appendix D: software tools library

Appendix E: Code Index

The libTIcable is a set of 'C' language subroutines designed to handle the different link cable types though a unique set of functions. Below is an alphabetical listing of all libTIcable functions and the name of the C file which contains its programming code.

The functions below are exported functions:

The functions below are internal functions:

Appendix F: Error Messages

All routines in the libTIcable are written as 'C' functions i.e., thery return values. A non zero value signifies an error. Full error messages may be printed using the get_cable_error function. Below is a list of all error messages, the value of each, and an explanation of the error.

L = Linux
W = Windows9x or Windows NT4

Appendix G: Function Index

To do...

---------------------

I hope this documentation to be useful. If you have comments, suggestions, and so on, feel free to mail me.
If you want additional informations, fire me an e-mail...

libTIcable, (c) 1999-2000, Romain Liévin
All code is placed under GPL license and libraries under the LGPL license.
Lib version 1.3.2.
Doc version 1.5, 21/10/2000.
This doc has been written with StarOffice 5.1 Personnal Edition for Linux. SGML could be a better choice but I have not enough time to learn it ...