1. Parallel Port

• 2Opening/Closing a Serial Device
• 4Line-Control Functions
  • 4.1tcdrain
• 5Reading and Setting Parameters
• 6Modes

The sample i/o routines for VxWorks that provide packet i/o functions on the console (login) device. Copy this file. If the device is a serial port, devopen() set the speed, stop bits, flow control, etc. Int readpkt(UCHAR *p, struct k_data * k) { char x; int n, max; short flag; UCHAR c; /* Timeout not implemented in this sample. This request updates VxWorks ASIO support. Missing ifdefs for using select instead of poll VxWorks serial port support using the equivalent ioctls to the termios support VxWorks does not have.

Introduction [edit]

termios is the newer (now already a few decades old) Unix API for terminal I/O. The anatomy of a program performing serial I/O with the help of termios is as follows:

• Open serial device with standard Unix system call open(2)

• Configure communication parameters and other interface properties (line discipline, etc.) with the help of specific termios functions and data structures.

• Use standard Unix system calls read(2) and write(2) for reading from, and writing to the serial interface. Related system calls like readv(2) and writev(2) can be used, too. Multiple I/O techniques, like blocking, non-blocking, asynchronous I/O (select(2) or poll(2), or signal-driven I/O (SIGIO signal)) are also possible. The selection of the I/O technique is an important part of the application's design. The serial I/O needs to work well with other kinds of I/O performed by the application, like networking, and must not waste CPU cycles.

• Close device with the standard Unix system call close(2) when done.

An important part when starting a program for serial I/I is to decide on the I/O technique to deploy.

The necessary declarations and constants for termios can be found in the header file <termios.h>. So code for serial or terminal I/O will usually start with Golden ears audio eartraining program download.

Some additional functions and declarations can also be found in the <stdio.h>, <fcntl.h>, and <unistd.h> header files.

The termios I/O API supports two different modes: doesn't old termio do this too? if yes, move paragraphs up to the general section about serial and terminal I/O in Unix).

1. Canonical mode.
This is most useful when dealing with real terminals, or devices that provide line-by-line communication. The terminal driver returns data line-by-line.

2. Non-canonical mode.
In this mode, no special processing is done, and the terminal driver returns individual characters.

On BSD-like systems, there are three modes:

1. Cooked Mode.
Input is assembled into lines and special characters are processed.

2. Raw mode.
Input is not assembled into lines and special characters are not processed.

3. Cbreak mode.
Input is not assembled into lines but some special characters are processed.

Unless set otherwise, canonical (or cooked mode under BSD) is the default. The special characters processed in the corresponding modes are control characters, such as end-of-line or backspace. The full list for a particular Unix flavor can be found in the corresponding termios man page. For serial communication it is often advisable to use non-canonical, (raw or cbreak mode under BSD) to ensure that transmitted data is not interpreted by the terminal driver. Therefore, when setting up the communication parameters, the device should also configured for raw/non-canonical mode by setting/clearing the corresponding termios flags. It is also possible to enable or disable the processing of the special characters on an individual basis.

This configuration is done by using the struct termios data structure, defined in the termios.h header. This structure is central to both the configuration of a serial device and querying its setup. It contains a minimum of the following fields:

It should be noted that real struct termios declarations are often much more complicated. This stems from the fact that Unix vendors implement termios so that it is backward compatible with termio and integrate termio and termios behavior in the same data structure so they can avoid to have to implement the same code twice. In such a case, an application programmer may be able to intermix termio and termios code.

There are more than 45 different flags that can be set (via tcsetattr()) or got (via tcgetattr()) with the help of the struct termios. The large number of flags, and their sometimes esoteric and pathologic meaning and behavior, is one of the reasons why serial programming under Unix can be hard. In the device configuration, one must be careful not to make a mistake.

Opening/Closing a Serial Device [edit]

open(2)[edit]

A few decisions have to be made when opening a serial device. Should the device be opened for reading only, writing only, or both reading and writing? Should the device be opened for blocking or non-blocking I/O (non-blocking is recommended)? While open(2) can be called with quite anumber of different flags controlling these and other properties, the following as a typical example:

Where:

device

The path to the serial port (e.g. /dev/ttyS0)

fd

The returned file handle for the device. -1 if an error occurred

O_RDWR

Opens the port for reading and writing

O_NOCTTY

The port never becomes the controlling terminal of the process.

O_NDELAY

Use non-blocking I/O. On some systems this also means the RS232 DCD signal line is ignored.

NB: Be sure to #include <fcntl.h> as well for the constants listed above.

close(2)[edit]

Given an open file handle fd you can close it with the following system call

Basic Configuration of a Serial Interface[edit]

After a serial device has been opened, it is typical that its default configuration, like baud rate or line discipline needsto be overwritten with the desired parameters. This is done with a rather complex data structure, and the tcgetattr(3) andtcsetattr(3) functions. Before that is done, however, it is a good idea to check if the opened device isindeed a serial device (aka tty).

The following is an example of such a configuration. The details are explained later in this module.

This code is definitely not a pretty sight. It only covers the most important flags of the more than 60 termios flags. The flagsshould be revised, depending on the actual application.

Line-Control Functions [edit]

termios contains a number of line-control functions. These allow a more fine-grained control over the serial line in certain special situations. They all work on a file descriptor fildes, returned by an open(2) call to open the serial device. In the case of an error, the detailed cause can be found in the global errno variable (see errno(2)).

tcdrain[edit]

Wait until all data previously written to the serial line indicated by fildes has been sent. This means, the function will return when the UART's send buffer has cleared.
If successful, the function returns 0. Otherwise it returns -1, and the global variable errno contains the exact reason for the error.

use case[edit]

Todays computer are fast, have more cores and a lot of optimization inside. That can cause strange results because it result depends on circumstances the programmer may not aware of. See the example below:

With that code you would expect a signal going up, the write and a signal going down. But that is wrong. Perhaps optimization causes the kernel to report success to write before the data are really written.

Now the same code using tcdrain()

Suddenly the code behaves as expected, because the clr_rts(); is executed only when data really is written. Several programmers solve the problem by using sleep()/usleep() what may be not exactly what you want.

tcflow[edit]

This function suspends/restarts transmission and/or reception of data on the serial device indicated by fildes. The exact function is controlled by the action argument. action should be one of the following constants:

TCOOFF

Suspend output.

TCOON

Restarts previously suspended output.

TCIOFF

Transmit a STOP (xoff) character. Remote devices are supposed to stop transmitting data if they receive this character. This requires the remote device on the other end of the serial line to support this software flow-control.

TCION

Transmit a START (xon) character. Remote devices should restart transmitting data if they receive this character. This requires the remote device on the other end of the serial line to support this software flow-control.

If successful, the function returns 0. Otherwise it returns -1, and the global variable errno contains the exact reason for the error.

tcflush[edit]

Flushes (discards) not-sent data (data still in the UART send buffer) and/or flushes (discards) received data (data already in the UART receive buffer). The exact operation is defined by the queue_selector argument. The possible constants for queue_selector are:

TCIFLUSH

Flush received, but unread data.

TCOFLUSH

Flush written, but not send data.

TCIOFLUSH

Flush both.

If successful, the function returns 0. Otherwise it returns -1, and the global variable errno contains the exact reason for the error.

tcsendbreak[edit]

Sends a break for a certain duration. The duration_flag controls the duration of the break signal:

0

Send a break of at least 0.25 seconds, and not more than 0.5 seconds.

any other value

For other values than 0, the behavior is implementation defined. Some implementations interpret the value as some time specifications, others just let the function behave like tcdrain().

A break is a deliberately generated framing (timing) error of the serial data – the signal's timing is violated by sending a series of zero bits, which also encompasses the start/stop bits, so the framing is explicitly gone.

If successful, the function returns 0. Otherwise it returns -1, and the global variable errno contains the exact reason for the error.

Reading and Setting Parameters[edit]

Introduction[edit]

There are more than 60 parameters a serial interface in Unix can have, assuming of course the underlying hardware supports every possible parameter - which many serial devices in professional workstations and Unix servers indeed do. This plethora of parameters and the resulting different interface configuration is what make serial programming in Unix and Linux challenging. Not only are there so many parameters, but their meanings are often rather unknown to contemporary hackers, because they originated at the dawn of computing, where things were done differently and are no longer known or taught in Little-Hacker School.

Nevertheless, most of the parameters of a serial interface in Unix are controlled via just two functions:

tcgetattr()

For reading the current attributes.

and

tcsetattr()

For setting serial interface attributes.

All information about the configuration of a serial interface is stored in an instance of the struct termios data type. tcgetattr() requires a pointer to a pre-allocated struct termios where it will write to. tcsetattr() requires a pointer to a pre-allocated and initialized struct termios where it reads the values from.

Further, speed parameters are set via a separate set of functions:

cfgetispeed()

Get line-in speed.

cfgetospeed()

Get line-out speed.

cfsetispeed()

Set line-in speed.

cfsetospeed()

Set line-out speed.

The following sub-section explain the mentioned functions in more detail.

Attribute Changes[edit]

50+ attributes of a serial interface in Unix can be read with a single function: tcgetattr(). Among these parameters are all the option flags and, for example, information about which special character handling is applied. The signature of that function is as it follows:

Where the arguments are:

fd

A file handle pointing to an opened terminal device. The device has typically be opened via the open(2) system call. However, there are several more mechanisms in Unix to obtain a legitimate file handle (e.g. by inheriting it over a fork(2)/exec(2) combo). As long as the handle points to an opened terminal device things are fine.

*attribs

A pointer to a pre-allocated struct termios, where tcgetattr() will write to.

tcgetattr() returns an integer that either indicates success or failure in the way typical for Unix system calls:

0

Indicates successful completion

-1

Indicates failure. Further information about the problem can be found in the global (or thread-local) errno variable. See the errno(2), intro(2), and/or perror(3C) man page for information about the meaning of the errno values.

Note; it is a typical beginner and hacker error to not check the return value and assume everything will always work.

The following is a simple example demonstrating the use of tcgetattr(). It assumes that standard input has been redirected to a terminal device:

Once the above program is compiled and linked, let's say under the name example, it can be run as it follows:

Assuming, /dev/ttya is a valid serial device. One can run stty to verify of the output is correct.

tcsetattr()

Sets the termios struct of the file handle fd from the options defined in options. optional_actions specifies when the change will happen:

TCSANOW

the configuration is changed immediately.

TCSADRAIN

the configuration is changed after all the output written to fd has been transmitted. This prevents the change from corrupting in-transmission data.

TCSAFLUSH

same as above but any data received and not read will be discarded.

Baud-Rate Setting[edit]

Reading and setting the baud rates (the line speeds) can be done via the tcgetattr() and tcsetattr() function. This can be done by reading or writing the necessary data into the struct termios. However, this is a mess. The previous example for tcgetattr() demonstrates this.

Instead of accessing the data manually, it is highly recommended to use one of the following functions:

cfgetispeed()

Get line-in speed.

cfgetospeed()

Get line-out speed.

cfsetispeed()

Set line-in speed.

cfsetospeed()

Set line-out speed.

Which have the following signatures:

speed

The input baud rate.

attribs

The struct termios from which to extract the speed.

speed

The output baud rate.

attribs

The struct termios from which to extract the speed.

attribs

The struct termios in which the input baud rate should be set.

speed

The input baud rate that should be set.

The function returns

0

If the speed could be set (encoded).

-1

If the speed could not be set (e.g. if it is not a valid or supported speed value).

attribs

The struct termios in which the output baud rate should be set.

speed

The output baud rate that should be set.

The function returns

0

If the speed could be set (encoded).

-1

If the speed could not be set (e.g. if it is not a valid or supported speed value).

Parallel Port

Here is a simple example for cfgetispeed(). cfgetospeed() works very similar:

cfsetispeed() and cfsetospeed() work straight-forward, too. The following example sets the input speed of stdin to 9600 baud. Note, the setting will not be permanent, since the device might be reset at the end of the program:

Modes[edit]

Special Input Characters[edit]

Canonical Mode[edit]

Everything is stored into a buffer and can be edited until a carriage return or line feed is entered. After the carriage return or line feed is pressed, the buffer is sent.

where:

ICANON

Enables canonical input mode

Non-Canonical Mode[edit]

This mode will handle a fixed number of characters and allows for a character timer.In this mode input is not assembled into lines and input processing does not occur.Here we have to set two parameters time and minimum number of characters to be received before read is satisfied and these are set by setting VTIME and VMIN characters for example if we have to set Minimum number of characters as 4 and we don't want to use any timer then we can do so as follows-:

Misc.[edit]

There are a few C functions that can be useful for terminal and serial I/O programming and are not part of the terminal I/O API. These are

This function returns the device name of the current controlling terminal of the process as a string (e.g. '/dev/tty01'). This is useful for programs who want to open that terminal device directly in order to communicate with it, even if the controlling terminal association is removed later (because, for example, the process forks/execs to become a daemon process).
*s can either be NULL or should point to a character array of at least L_ctermid bytes (the constant is also defined in stdio.h). If *s is NULL, then some internal static char array is used, otherwise the provided array is used. In both cases, a pointer to the first element of the char array is returned

Checks if the provided file descriptor represents a terminal device. This can e.g. be used to figure out if a device will understand the commands send via the terminal I/O API.

This function returns the device name of a terminal device represented by a file descriptor as a string.

These I/O controls allow to get and set the window size of a terminal emulation, e.g. an xterm in pixel and character sizes. Typically the get variant (TIOCGWINSZ) is used in combination with a SIGWINCH signal handler. The signal handler gets called when the size has changed (e.g. because the user has resized the terminal emulation window), and the application uses the I/O control to get the new size.

Example terminal program[edit]

A simple terminal program with termios.h can look like this:

Warning: In this program the VMIN and VTIME flags are ignored because the O_NONBLOCK flag is set.

I am writing a vxworks task involving sending data thru serial port. Opening the serial port is successful. But when I am trying to set the baud rate of the port using ioctl() system call,it fails. I am giving the code below. can anyone please shed some light on it? The second function is failing always..

1 Answer

Maybe is a little bit too late, but the code above looks like erroneous. Assignment operator has lower priority as comparing operator, so you should write the code like:

This way it works perfect in VxWorks. The way you wrote the code was to assign f either 0 or 1 (0 in this case, because you could open the serial port), and then tried to set baud rate for file descriptor 0 (i guess is the stdout id). The same you assigned status either 0 or 1 (1 in this case, because you couldn't set the baud rate, so ioctl returned -1)

Not the answer you're looking for? Browse other questions tagged cserial-portvxworksbaud-rate or ask your own question.