Serial port communication and programming

LibGW32C for Windows

2008-07-26T22:54:00.000-07:00

Version

0.4
Description

This is an implementation of a small part of GLibC, just enough to compile most Unix programs on MS Windows. It contains functions for passwords, process id's groups, and strings. Most are interfaces to the MS-Windows Win32 API. Some are just dummy functions that do nothing.

The following functions are provided:

* a64l
* __access
* access
* __addmntent
* addmntent
* __addmntentstr
* alarm
* alphasort
* alphasort64
* argp_err_exit_status
* __argp_error
* argp_error
* __argp_failure
* argp_failure
* __argp_fmtstream_ensure
* __argp_fmtstream_free
* __argp_fmtstream_point
* __argp_fmtstream_printf
* __argp_fmtstream_putc
* __argp_fmtstream_puts
* __argp_fmtstream_set_lmargin
* __argp_fmtstream_set_rmargin
* __argp_fmtstream_set_wmargin
* __argp_fmtstream_update
* __argp_fmtstream_write
* __argp_help
* argp_help
* __argp_input
* _argp_input
* __argp_make_fmtstream
* __argp_parse
* argp_parse
* argp_program_bug_address
* argp_program_version
* argp_program_version_hook
* __argp_state_help
* argp_state_help
* _argp_unlock_xxx
* __argp_usage
* argp_usage
* __argz_add
* argz_add
* __argz_add_sep
* argz_add_sep
* __argz_append
* argz_append
* __argz_count
* argz_count
* __argz_create
* argz_create
* __argz_create_sep
* argz_create_sep
* argz_delete
* __argz_extract
* argz_extract
* __argz_insert
* argz_insert
* __argz_next
* argz_next
* __argz_replace
* argz_replace
* __argz_stringify
* argz_stringify
* attr2mode
* BackupLink
* basename
* bcopy
* __brk
* brk
* bsearch
* __bzero
* bzero
* __canonicalize_file_name
* canonicalize_file_name
* catclose
* catgets
* catopen
* cfgetispeed
* cfgetospeed
* cfmakeraw
* cfsetispeed
* cfsetospeed
* cfsetspeed
* __chdir
* chdir
* chflags
* __chown
* chown
* chroot
* clock
* clock_getcpuclockid
* clock_getres
* clock_gettime
* clock_nanosleep
* clock_settime
* __closedir
* closedir
* CreateLink
* crypt
* __crypt_r
* crypt_r
* __curbrk
* cuserid
* __cxstat64
* debugprint
* DecodeError
* devrootdir
* dirfd
* dirname
* dladdr
* dlclose
* dlerror
* dlopen
* dlsym
* __dlvsym
* dlvsym
* drand48
* __drand48_iterate
* drand48_r
* ecvt
* ecvt_r
* encrypt
* __encrypt_r
* encrypt_r
* endfsent
* endgrent
* endhostent
* __endmntent
* endmntent
* endpwent
* endusershell
* envz_add
* envz_entry
* envz_get
* envz_merge
* envz_remove
* envz_strip
* erand48
* __erand48_r
* erand48_r
* err
* __error
* error
* __error_at_line
* error_at_line
* error_message_count
* error_one_per_line
* error_print_progname
* errx
* __euidaccess
* euidaccess
* __fchdir
* fchdir
* fchflags
* __fchmod
* fchmod
* __fchown
* fchown
* __fcntl
* fcntl
* fcrypt
* fcvt
* fcvt_r
* fdatasync
* fesetround
* __ffs
* ffs
* ffsl
* fgetxattr
* file_exists
* FileInformationToStat64
* flistxattr
* __flockfile
* flockfile
* __fork
* fork
* __fpathconf
* fpathconf
* fremovexattr
* frootdir
* fseeko
* fseeko64
* __fsetlocking
* fsetxattr
* __fstat
* fstat
* fstat64
* __fstatfs
* fstatfs
* __fstatfs64
* fstatfs64
* __fstatvfs
* fstatvfs
* __fstatvfs64
* fstatvfs64
* ftello
* ftello64
* __ftruncate
* ftruncate
* __ftruncate64
* ftruncate64
* __ftrylockfile
* ftrylockfile
* fts_children
* fts_close
* fts_open
* fts_read
* fts_set
* ftw
* ftw64
* __funlockfile
* funlockfile
* __futimes
* futimes
* __fxstat
* _fxstat
* __fxstat64
* gcvt
* __gen_tempname
* __get_avphys_pages
* get_avphys_pages
* __get_clockfreq
* get_current_dir_name
* __get_errno
* __get_nprocs
* get_nprocs
* __get_nprocs_conf
* get_nprocs_conf
* __get_phys_pages
* get_phys_pages
* __getclktck
* getcpuspeed
* __getcwd
* getdomainname
* __getdtablesize
* getdtablesize
* __getegid
* getegid
* __geteuid
* geteuid
* getexecdir
* getexecparent
* getexecpath
* GetFileAttributeData
* GetFileInformationByName
* getfsent
* getfsfile
* getfsspec
* __getgid
* getgid
* getgranularity
* getgrent
* getgrent_r
* getgrgid
* getgrnam
* __getgroups
* getgroups
* gethostent
* gethostid
* __getline
* getline
* getloadavg
* getlogin
* getlongpath
* GetMachInfo
* getmntent
* __getmntent_r
* getmntent_r
* __getntptimeofday
* getntptimeofday
* getopt
* __getopt_initialized
* _getopt_internal
* getopt_long
* getopt_long_only
* GetOsInfo
* __getpagesize
* getpagesize
* getpass
* __getpgid
* getpgid
* getpgrp
* __getppid
* getppid
* getpriority
* getprogname
* getpwent
* getpwnam
* getpwuid
* __getrlimit
* getrlimit
* __getrlimit64
* getrlimit64
* getrootdirs
* getshortpath
* getsid
* GetStat64ByHandle
* GetStat64ByName
* __gettimeofday
* gettimeofday
* __getuid
* getuid
* getuname
* getusershell
* GetVendorID
* GetVolumeSerialNumber
* getwd
* getxattr
* GetXStat64ByName
* __group_member
* group_member
* gtty
* handle2mode
* hashval
* __hasmntopt
* hasmntopt
* hcreate
* hcreate_r
* __hdestroy
* hdestroy
* hdestroy_r
* hsearch
* hsearch_r
* __hutimes
* __init_des
* __init_des_r
* __init_misc
* __initstate
* initstate
* __initstate_r
* initstate_r
* insque
* _IO_flockfile
* _IO_ftrylockfile
* _IO_funlockfile
* __ioctl
* ioctl
* issymlink
* IsWin31
* IsWin9x
* IsWinCE
* IsWinNT
* _itoa_lower_digits
* _itoa_upper_digits
* jrand48
* __jrand48_r
* jrand48_r
* __kill
* kill
* l64a
* lchmod
* __lchown
* lchown
* lcong48
* __lcong48_r
* lcong48_r
* lfind
* lgetxattr
* __libc_drand48_data
* __libc_enable_secure
* __libc_init
* __libc_init_first
* __libc_init_secure
* _libc_intl_domainname
* __libc_multiple_libcs
* __libc_nanosleep
* __libc_readv
* __libc_tcdrain
* __libc_tsd_LOCALE_data
* __libc_wait
* __libc_waitid
* __libc_waitpid
* __link
* link
* listxattr
* llistxattr
* lock
* lock64
* lrand48
* lrand48_r
* lremovexattr
* lsearch
* lsetxattr
* __lstat
* lstat
* lstat64
* __lutimes
* lutimes
* __lxstat
* _lxstat
* __lxstat64
* madvise
* __md5_buffer
* __md5_crypt
* __md5_crypt_r
* __md5_finish_ctx
* __md5_init_ctx
* __md5_process_block
* __md5_process_bytes
* __md5_read_ctx
* __md5_stream
* memfrob
* __mempcpy
* mempcpy
* __memrchr
* memrchr
* __mkdir
* mkdir
* mkdtemp
* mkfifo
* __mknod
* mknod
* mkstemp64
* mkstemps
* mktemp
* mlock
* mlockall
* __mmap
* mmap
* __mmap64
* mmap64
* mode2osflags
* __mpn_lshift
* __mpn_rshift
* __mprotect
* mprotect
* mrand48
* mrand48_r
* mremap
* msync
* mtrace
* munlock
* munlockall
* __munmap
* munmap
* muntrace
* __nanosleep
* nanosleep
* nftw
* nftw64
* nice
* _nl_C_codeset
* _nl_C_LC_ADDRESS
* _nl_C_LC_COLLATE
* _nl_C_LC_CTYPE
* _nl_C_LC_CTYPE_class
* _nl_C_LC_CTYPE_class32
* _nl_C_LC_CTYPE_class_alnum
* _nl_C_LC_CTYPE_class_alpha
* _nl_C_LC_CTYPE_class_blank
* _nl_C_LC_CTYPE_class_cntrl
* _nl_C_LC_CTYPE_class_digit
* _nl_C_LC_CTYPE_class_graph
* _nl_C_LC_CTYPE_class_lower
* _nl_C_LC_CTYPE_class_print
* _nl_C_LC_CTYPE_class_punct
* _nl_C_LC_CTYPE_class_space
* _nl_C_LC_CTYPE_class_upper
* _nl_C_LC_CTYPE_class_xdigit
* _nl_C_LC_CTYPE_map_tolower
* _nl_C_LC_CTYPE_map_toupper
* _nl_C_LC_CTYPE_tolower
* _nl_C_LC_CTYPE_toupper
* _nl_C_LC_CTYPE_width
* _nl_C_LC_IDENTIFICATION
* _nl_C_LC_MEASUREMENT
* _nl_C_LC_MESSAGES
* _nl_C_LC_MONETARY
* _nl_C_LC_NAME
* _nl_C_LC_NUMERIC
* _nl_C_LC_PAPER
* _nl_C_LC_TELEPHONE
* _nl_C_LC_TIME
* _nl_C_name
* _nl_global_locale
* nl_langinfo
* _nl_POSIX_name
* nrand48
* __nrand48_r
* nrand48_r
* __open_catalog
* __opendir
* opendir
* optarg
* opterr
* optind
* __option_is_end
* _option_is_end
* __option_is_short
* _option_is_short
* optopt
* osflags2mode
* path2mode
* __path_search
* __pathconf
* pathconf
* __pipe
* pipe
* posix2winfullpath
* posix2winpath
* posix_madvise
* posix_mremap
* PrintWinErr
* __progname
* __progname_full
* program_invocation_name
* program_invocation_short_name
* program_name
* __pthread_clock_gettime
* __pthread_clock_settime
* qecvt
* qecvt_r
* qfcvt
* qfcvt_r
* qgcvt
* qsort
* _quicksort
* rand
* rand_r
* __random
* random
* __random_r
* random_r
* __rawmemchr
* rawmemchr
* __readdir
* readdir
* __readdir64
* readdir64
* __readdir64_r
* readdir64_r
* __readdir_r
* readdir_r
* readlink
* __readv
* readv
* __realpath
* realpath
* remove
* removexattr
* remque
* rename
* ResolveLink
* __rewinddir
* rewinddir
* __rmdir
* rmdir
* rootdir
* __rstatfsx64
* __sbrk
* sbrk
* scandir
* scandir64
* __secure_getenv
* seed48
* __seed48_r
* seed48_r
* __seekdir
* seekdir
* __select
* select
* setdomainname
* setegid
* setenv
* setfsent
* setgid
* setgrent
* sethostent
* sethostid
* sethostname
* setkey
* __setkey_r
* setkey_r
* setlogin
* __setmntent
* setmntent
* __setntptimeofday
* setntptimeofday
* __setpgid
* setpgid
* setpgrp
* setpriority
* setpwent
* __setregid
* setregid
* __setreuid
* setreuid
* __setrlimit
* setrlimit
* __setrlimit64
* setrlimit64
* __setstate
* setstate
* __setstate_r
* setstate_r
* __settimeofday
* settimeofday
* setuid
* setusershell
* setxattr
* __sigaction
* sigaction
* __sigaddset
* sigaddset
* sigfillset
* __sigprocmask
* sigprocmask
* __sleep
* sleep
* _splitpath
* srand
* srand48
* __srand48_r
* srand48_r
* __srandom
* srandom
* __srandom_r
* srandom_r
* __stat
* stat
* __stat64
* stat64
* stat64_to_32
* __statfs
* statfs
* __statfs64
* statfs64
* __statfsbsd
* statfsbsd
* __statfsx64
* statfsx64
* __statvfs
* statvfs
* __statvfs64
* statvfs64
* __stpcpy
* stpcpy
* __stpncpy
* stpncpy
* __strchrnul
* strchrnul
* __strerror_r
* strerror_r
* strfry
* strlcat
* strlcpy
* strmode
* __strncasecmp
* strncasecmp
* __strndup
* strndup
* __strnlen
* strnlen
* strptime
* __strsep
* strsep
* __strsep_g
* strsignal
* __strtok_r
* strtok_r
* __strverscmp
* strverscmp
* symlink
* sync
* _sys_errlist_internal
* _sys_nerr_internal
* _sys_siglist
* sys_siglist
* _sys_siglist_internal
* syscall
* __sysconf
* sysconf
* sysinfo
* tcdrain
* tcflow
* tcflush
* __tcgetattr
* tcgetattr
* tcgetpgrp
* tcgetsid
* tcsendbreak
* tcsetattr
* tcsetpgrp
* __tdelete
* tdelete
* __tdestroy
* tdestroy
* __telldir
* telldir
* tempnam
* __tfind
* tfind
* __times
* times
* tm_year_base
* tmpfile
* tmpfile64
* tmpnam
* tmpnam_r
* __truncate
* truncate
* __truncate64
* truncate64
* __tsearch
* tsearch
* ttyname
* __twalk
* twalk
* __tzname_cur_max
* __tzname_max
* _ufc_dofinalperm_r
* _ufc_doit_r
* _ufc_foobar
* _ufc_mk_keytab_r
* _ufc_output_conversion_r
* _ufc_setup_salt_r
* __ulimit
* ulimit
* __uname
* uname
* unix2winpath
* __unlink
* unlink
* unsetenv
* usleep
* ustat
* utime
* __utimes
* utimes
* verr
* verrx
* versionsort
* versionsort64
* vlimit
* vsn2drive
* vwarn
* vwarnx
* __w32_gethostbyaddr
* w32_gethostbyaddr
* __w32_gethostbyname
* w32_gethostbyname
* __w32_gethostname
* w32_gethostname
* w32_same_file
* __wait
* wait
* __wait3
* wait3
* __wait4
* wait4
* __waitid
* waitid
* __waitpid
* waitpid
* warn
* warnx
* werrno
* win2posixfullpath
* win2posixpath
* win2unixpath
* win32_longpath
* WinErr
* winmajor
* winminor
* winos
* winplatform
* _wordcopy_bwd_aligned
* _wordcopy_bwd_dest_aligned
* _wordcopy_fwd_aligned
* _wordcopy_fwd_dest_aligned
* ws_cleanup
* ws_init
* WSAErr
* __xmknod
* _xmknod
* __xpg_basename
* __xstat
* _xstat
* __xstat64

The documentation of most of these functions is in the Glibc-documentation, in the Linux manpages and in the FreeBsd manpages.
Homepage

http://www.gnu.org/software/libc/libc.html

Sources:
Download

Description Download Size Last change Md5sum

• Developer files Zip 643174 10 January 2004 55b41650239b13d2b0d79c100d160665
• Sources Zip 2226097 10 January 2004 f8c7c821033c9ed141c347edf3c30477
• Original source

You can also download the files from the GnuWin32 files page. New releases of the port of this package can be monitored.

SSH Connection Protocol

2008-07-23T21:43:00.000-07:00

Status of This memo

This document is an Internet-Draft and is in full conformance
with all provisions of Section 10 of RFC2026.

Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as
Internet-Drafts.

Internet-Drafts are draft documents valid for a maximum of six
months and may be updated, replaced, or obsoleted by other
documents at any time. It is inappropriate to use Internet-
Drafts as reference material or to cite them other than as
"work in progress."

The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt

The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.

Abstract

SSH is a protocol for secure remote login and other secure network ser-
vices over an insecure network. This document describes the SSH Connec-
tion Protocol. It provides interactive login sessions, remote execution
of commands, forwarded TCP/IP connections, and forwarded X11 connec-
tions. All of these channels are multiplexed into a single encrypted
tunnel. The SSH Connection Protocol has been designed to run on top of
the SSH transport layer and user authentication protocols.

T. Ylonen, T. Kivinen, M. Saarinen, T. Rinne and S. Lehtinen [page 1]

INTERNET-DRAFT 21 Nov, 2000

Table of Contents

1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Global Requests . . . . . . . . . . . . . . . . . . . . . . . . 2
3. Channel Mechanism . . . . . . . . . . . . . . . . . . . . . . . 3
3.1. Opening a Channel . . . . . . . . . . . . . . . . . . . . . 3
3.2. Data Transfer . . . . . . . . . . . . . . . . . . . . . . . 4
3.3. Closing a Channel . . . . . . . . . . . . . . . . . . . . . 5
3.4. Channel-Specific Requests . . . . . . . . . . . . . . . . . 5
4. Interactive Sessions . . . . . . . . . . . . . . . . . . . . . . 6
4.1. Opening a Session . . . . . . . . . . . . . . . . . . . . . 6
4.2. Requesting a Pseudo-Terminal . . . . . . . . . . . . . . . . 6
4.3. X11 Forwarding . . . . . . . . . . . . . . . . . . . . . . . 7
4.3.1. Requesting X11 Forwarding . . . . . . . . . . . . . . . 7
4.3.2. X11 Channels . . . . . . . . . . . . . . . . . . . . . . 8
4.4. Environment Variable Passing . . . . . . . . . . . . . . . . 8
4.5. Starting a Shell or a Command . . . . . . . . . . . . . . . 8
4.6. Session Data Transfer . . . . . . . . . . . . . . . . . . . 9
4.7. Window Dimension Change Message . . . . . . . . . . . . . . 9
4.8. Local Flow Control . . . . . . . . . . . . . . . . . . . . . 9
4.9. Signals . . . . . . . . . . . . . . . . . . . . . . . . . . 10
4.10. Returning Exit Status . . . . . . . . . . . . . . . . . . . 10
5. TCP/IP Port Forwarding . . . . . . . . . . . . . . . . . . . . . 11
5.1. Requesting Port Forwarding . . . . . . . . . . . . . . . . . 11
5.2. TCP/IP Forwarding Channels . . . . . . . . . . . . . . . . . 12
6. Encoding of Terminal Modes . . . . . . . . . . . . . . . . . . . 13
7. Summary of Message Numbers . . . . . . . . . . . . . . . . . . . 15
8. Security Considerations . . . . . . . . . . . . . . . . . . . . 15
9. Trademark Issues . . . . . . . . . . . . . . . . . . . . . . . . 16
10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 16
11. Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 16

1. Introduction

The SSH Connection Protocol has been designed to run on top of the SSH
transport layer and user authentication protocols. It provides
interactive login sessions, remote execution of commands, forwarded
TCP/IP connections, and forwarded X11 connections. The service name for
this protocol (after user authentication) is "ssh-connection".

This document should be read only after reading the SSH architecture
document [SSH-ARCH]. This document freely uses terminology and notation
from the architecture document without reference or further explanation.

2. Global Requests

There are several kinds of requests that affect the state of the remote
end "globally", independent of any channels. An example is a request to
start TCP/IP forwarding for a specific port. All such requests use the
following format.

T. Ylonen, T. Kivinen, M. Saarinen, T. Rinne and S. Lehtinen [page 2]

INTERNET-DRAFT 21 Nov, 2000

byte SSH_MSG_GLOBAL_REQUEST
string request name (restricted to US-ASCII)
boolean want reply
... request-specific data follows

The recipient will respond to this message with SSH_MSG_REQUEST_SUCCESS,
SSH_MSG_REQUEST_FAILURE, or some request-specific continuation messages
if `want reply' is TRUE.

byte SSH_MSG_REQUEST_SUCCESS

If the recipient does not recognize or support the request, it simply
responds with SSH_MSG_REQUEST_FAILURE.

byte SSH_MSG_REQUEST_FAILURE

3. Channel Mechanism

All terminal sessions, forwarded connections, etc. are channels. Either
side may open a channel. Multiple channels are multiplexed into a
single connection.

Channels are identified by numbers at each end. The number referring to
a channel may be different on each side. Requests to open a channel
contain the sender's channel number. Any other channel-related messages
contain the recipient's channel number for the channel.

Channels are flow-controlled. No data may be sent to a channel until a
message is received to indicate that window space is available.

3.1. Opening a Channel

When either side wishes to open a new channel, it allocates a local
number for the channel. It then sends the following message to the
other side, and includes the local channel number and initial window
size in the message.

byte SSH_MSG_CHANNEL_OPEN
string channel type (restricted to US-ASCII)
uint32 sender channel
uint32 initial window size
uint32 maximum packet size
... channel type specific data follows

The channel type is a name as described in the SSH architecture
document, with similar extension mechanisms. `sender channel' is a local
identifier for the channel used by the sender of this message. `initial
window size' specifies how many bytes of channel data can be sent to the
sender of this message without adjusting the window. `Maximum packet
size' specifies the maximum size of an individual data packet that can
be sent to the sender (for example, one might want to use smaller
packets for interactive connections to get better interactive response
on slow links).

T. Ylonen, T. Kivinen, M. Saarinen, T. Rinne and S. Lehtinen [page 3]

INTERNET-DRAFT 21 Nov, 2000

The remote side then decides whether it can open the channel, and
responds with either
byte SSH_MSG_CHANNEL_OPEN_CONFIRMATION
uint32 recipient channel
uint32 sender channel
uint32 initial window size
uint32 maximum packet size
... channel type specific data follows

where `recipient channel' is the channel number given in the original
open request, and `sender channel' is the channel number allocated by
the other side, or

byte SSH_MSG_CHANNEL_OPEN_FAILURE
uint32 recipient channel
uint32 reason code
string additional textual information (ISO-10646 UTF-8
[RFC-2044])
string language tag (as defined in [RFC-1766])

If the recipient of the SSH_MSG_CHANNEL_OPEN message does not support
the specified channel type, it simply responds with
SSH_MSG_CHANNEL_OPEN_FAILURE. The client MAY show the additional
information to the user. If this is done, the client software should
take the precautions discussed in [SSH-ARCH].

The following reason codes are defined:

#define SSH_OPEN_ADMINISTRATIVELY_PROHIBITED 1
#define SSH_OPEN_CONNECT_FAILED 2
#define SSH_OPEN_UNKNOWN_CHANNEL_TYPE 3
#define SSH_OPEN_RESOURCE_SHORTAGE 4

3.2. Data Transfer

The window size specifies how many bytes the other party can send before
it must wait for the window to be adjusted. Both parties use the
following message to adjust the window.

byte SSH_MSG_CHANNEL_WINDOW_ADJUST
uint32 recipient channel
uint32 bytes to add

After receiving this message, the recipient MAY send the given number of
bytes more than it was previously allowed to send; the window size is
incremented.

Data transfer is done with messages of the following type.

byte SSH_MSG_CHANNEL_DATA
uint32 recipient channel
string data

T. Ylonen, T. Kivinen, M. Saarinen, T. Rinne and S. Lehtinen [page 4]

INTERNET-DRAFT 21 Nov, 2000

The maximum amount of data allowed is the current window size. The
window size is decremented by the amount of data sent. Both parties MAY
ignore all extra data sent after the allowed window is empty.

Additionally, some channels can transfer several types of data. An
example of this is stderr data from interactive sessions. Such data can
be passed with SSH_MSG_CHANNEL_EXTENDED_DATA messages, where a separate
integer specifies the type of the data. The available types and their
interpretation depend on the type of the channel.

byte SSH_MSG_CHANNEL_EXTENDED_DATA
uint32 recipient_channel
uint32 data_type_code
string data

Data sent with these messages consumes the same window as ordinary data.

Currently, only the following type is defined.

#define SSH_EXTENDED_DATA_STDERR 1

3.3. Closing a Channel

When a party will no longer send more data to a channel, it SHOULD send
SSH_MSG_CHANNEL_EOF.

byte SSH_MSG_CHANNEL_EOF
uint32 recipient_channel

No explicit response is sent to this message; however, the application
may send EOF to whatever is at the other end of the channel. Note that
the channel remains open after this message, and more data may still be
sent in the other direction. This message does not consume window space
and can be sent even if no window space is available.

When either party wishes to terminate the channel, it sends
SSH_MSG_CHANNEL_CLOSE. Upon receiving this message, a party MUST send
back a SSH_MSG_CHANNEL_CLOSE unless it has already sent this message for
the channel. The channel is considered closed for a party when it has
both sent and received SSH_MSG_CHANNEL_CLOSE, and the party may then
reuse the channel number. A party MAY send SSH_MSG_CHANNEL_CLOSE
without having sent or received SSH_MSG_CHANNEL_EOF.
byte SSH_MSG_CHANNEL_CLOSE
uint32 recipient_channel

This message does not consume window space and can be sent even if no
window space is available.

It is recommended that any data sent before this message is delivered to
the actual destination, if possible.

3.4. Channel-Specific Requests

T. Ylonen, T. Kivinen, M. Saarinen, T. Rinne and S. Lehtinen [page 5]

INTERNET-DRAFT 21 Nov, 2000

Many channel types have extensions that are specific to that particular
channel type. An example is requesting a pty (pseudo terminal) for an
interactive session.

All channel-specific requests use the following format.

byte SSH_MSG_CHANNEL_REQUEST
uint32 recipient channel
string request type (restricted to US-ASCII)
boolean want reply
... type-specific data

If want reply is FALSE, no response will be sent to the request.
Otherwise, the recipient responds with either SSH_MSG_CHANNEL_SUCCESS or
SSH_MSG_CHANNEL_FAILURE, or request-specific continuation messages. If
the request is not recognized or is not supported for the channel,
SSH_MSG_CHANNEL_FAILURE is returned.

This message does not consume window space and can be sent even if no
window space is available. Request types are local to each channel type.

The client is allowed to send further messages without waiting for the
response to the request.

byte SSH_MSG_CHANNEL_SUCCESS
uint32 recipient_channel

byte SSH_MSG_CHANNEL_FAILURE
uint32 recipient_channel

These messages do not consume window space and can be sent even if no
window space is available.
4. Interactive Sessions

A session is a remote execution of a program. The program may be a
shell, an application, a system command, or some built-in subsystem. It
may or may not have a tty, and may or may not involve X11 forwarding.
Multiple sessions can be active simultaneously.

4.1. Opening a Session

A session is started by sending the following message.

byte SSH_MSG_CHANNEL_OPEN
string "session"
uint32 sender channel
uint32 initial window size
uint32 maximum packet size

Client implementations SHOULD reject any session channel open requests
to make it more difficult for a corrupt server to attack the client.

T. Ylonen, T. Kivinen, M. Saarinen, T. Rinne and S. Lehtinen [page 6]

INTERNET-DRAFT 21 Nov, 2000

4.2. Requesting a Pseudo-Terminal

A pseudo-terminal can be allocated for the session by sending the
following message.

byte SSH_MSG_CHANNEL_REQUEST
uint32 recipient_channel
string "pty-req"
boolean want_reply
string TERM environment variable value (e.g., vt100)
uint32 terminal width, characters (e.g., 80)
uint32 terminal height, rows (e.g., 24)
uint32 terminal width, pixels (e.g., 480)
uint32 terminal height, pixels (e.g., 640)
string encoded terminal modes

The encoding of terminal modes is described in Section ``Encoding of
Terminal Modes''. Zero dimension parameters MUST be ignored. The
character/row dimensions override the pixel dimensions (when nonzero).
Pixel dimensions refer to the drawable area of the window.

The dimension parameters are only informational.

The client SHOULD ignore pty requests.

4.3. X11 Forwarding

4.3.1. Requesting X11 Forwarding

X11 forwarding may be requested for a session by sending

byte SSH_MSG_CHANNEL_REQUEST
uint32 recipient channel
string "x11-req"
boolean want reply
boolean single connection
string x11 authentication protocol
string x11 authentication cookie
uint32 x11 screen number

It is recommended that the authentication cookie that is sent be a fake,
random cookie, and that the cookie is checked and replaced by the real
cookie when a connection request is received.

X11 connection forwarding should stop when the session channel is
closed; however, already opened forwardings should not be automatically
closed when the session channel is closed.

If `single connection' is TRUE, only a single connection should be
forwarded. No more connections will be forwarded after the first, or
after the session channel has been closed.

`X11 authentication protocol is the name of the X11 authentication

T. Ylonen, T. Kivinen, M. Saarinen, T. Rinne and S. Lehtinen [page 7]

INTERNET-DRAFT 21 Nov, 2000

method used, i.e. "MIT-MAGIC-COOKIE-1".

X Protocol is documented in [Scheifler].

4.3.2. X11 Channels

X11 channels are opened with a channel open request. The resulting
channels are independent of the session, and closing the session channel
does not close the forwarded X11 channels.

byte SSH_MSG_CHANNEL_OPEN
string "x11"
uint32 sender channel
uint32 initial window size
uint32 maximum packet size
string originator address (e.g. "192.168.7.38")
uint32 originator port

The recipient should respond with SSH_MSG_CHANNEL_OPEN_CONFIRMATION or
SSH_MSG_CHANNEL_OPEN_FAILURE.

Implementations MUST reject any X11 channel open requests if they have
not requested X11 forwarding.

4.4. Environment Variable Passing

Environment variables may be passed to the shell/command to be started
later. Typically, each machine will have a preconfigured set of
variables that it will allow. Since uncontrolled setting of environment
variables can be very dangerous, it is recommended that implementations
allow setting only variables whose names have been explicitly configured
to be allowed.

byte SSH_MSG_CHANNEL_REQUEST
uint32 recipient channel
string "env"
boolean want reply
string variable name
string variable value

4.5. Starting a Shell or a Command

Once the session has been set up, a program is started at the remote
end. The program can be a shell, an application program or a subsystem
with a host-independent name. Only one of these requests can succeed
per channel.

byte SSH_MSG_CHANNEL_REQUEST
uint32 recipient channel
string "shell"
boolean want reply

This message will request the user's default shell (typically defined in

T. Ylonen, T. Kivinen, M. Saarinen, T. Rinne and S. Lehtinen [page 8]

INTERNET-DRAFT 21 Nov, 2000

/etc/passwd in UNIX systems) to be started at the other end.
byte SSH_MSG_CHANNEL_REQUEST
uint32 recipient channel
string "exec"
boolean want reply
string command

This message will request the server to start the execution of the given
command. The command string may contain a path. Normal precautions MUST
be taken to prevent the execution of unauthorized commands.

byte SSH_MSG_CHANNEL_REQUEST
uint32 recipient channel
string "subsystem"
boolean want reply
string subsystem name

This last form executes a predefined subsystem. It expected that these
will include a general file transfer mechanism, and possibly other
features. Implementations may also allow configuring more such
mechanisms.

The server SHOULD not halt the execution of the protocol stack when
starting a shell or a program. All input and output from these SHOULD be
redirected to the channel or to the encrypted tunnel.

It is RECOMMENDED to request and check the reply for these messages. The
client SHOULD ignore these messages.

4.6. Session Data Transfer

Data transfer for a session is done using SSH_MSG_CHANNEL_DATA and
SSH_MSG_CHANNEL_EXTENDED_DATA packets and the window mechanism. The
extended data type SSH_EXTENDED_DATA_STDERR has been defined for stderr
data.

4.7. Window Dimension Change Message

When the window (terminal) size changes on the client side, it MAY send
a message to the other side to inform it of the new dimensions.

byte SSH_MSG_CHANNEL_REQUEST
uint32 recipient_channel
string "window-change"
boolean FALSE
uint32 terminal width, columns
uint32 terminal height, rows
uint32 terminal width, pixels
uint32 terminal height, pixels

No response SHOULD be sent to this message.

T. Ylonen, T. Kivinen, M. Saarinen, T. Rinne and S. Lehtinen [page 9]

INTERNET-DRAFT 21 Nov, 2000

4.8. Local Flow Control

On many systems, it is possible to determine if a pseudo-terminal is
using control-S/control-Q flow control. When flow control is allowed,
it is often desirable to do the flow control at the client end to speed
up responses to user requests. This is facilitated by the following
notification. Initially, the server is responsible for flow control.
(Here, again, client means the side originating the session, and server
means the other side.)

The message below is used by the server to inform the client when it can
or cannot perform flow control (control-S/control-Q processing). If
`client can do' is TRUE, the client is allowed to do flow control using
control-S and control-Q. The client MAY ignore this message.

byte SSH_MSG_CHANNEL_REQUEST
uint32 recipient channel
string "xon-xoff"
boolean FALSE
boolean client can do

No response is sent to this message.

4.9. Signals

A signal can be delivered to the remote process/service using the
following message. Some systems may not implement signals, in which
case they SHOULD ignore this message.

byte SSH_MSG_CHANNEL_REQUEST
uint32 recipient channel
string "signal"
boolean FALSE
string signal name without the "SIG" prefix.

Signal names will be encoded as discussed in the "exit-signal"
SSH_MSG_CHANNEL_REQUEST.

4.10. Returning Exit Status

When the command running at the other end terminates, the following
message can be sent to return the exit status of the command. Returning
the status is RECOMMENDED. No acknowledgment is sent for this message.
The channel needs to be closed with SSH_MSG_CHANNEL_CLOSE after this
message.

The client MAY ignore these messages.

byte SSH_MSG_CHANNEL_REQUEST
uint32 recipient_channel
string "exit-status"
boolean FALSE
uint32 exit_status

T. Ylonen, T. Kivinen, M. Saarinen, T. Rinne and S. Lehtinen [page 10]

INTERNET-DRAFT 21 Nov, 2000

The remote command may also terminate violently due to a signal. Such a
condition can be indicated by the following message. A zero exit_status
usually means that the command terminated successfully.

byte SSH_MSG_CHANNEL_REQUEST
uint32 recipient channel
string "exit-signal"
boolean FALSE
string signal name without the "SIG" prefix.
boolean core dumped
string error message (ISO-10646 UTF-8 [RFC-2044])
string language tag (as defined in [RFC-1766])

The signal name is one of the following (these are from [POSIX]):

ABRT
ALRM
FPE
HUP
ILL
INT
KILL
PIPE
QUIT
SEGV
TERM
USR1
USR2

Additional signal names MAY be sent in the format "sig-name@xyz", where
`sig-name' and `xyz' may be anything a particular implementor wants
(except the `@' sign). However, it is suggested that if a `configure'
script is used, the non-standard signal names it finds be encoded as
"SIG@xyz.config.guess", where `SIG' is the signal name without the "SIG"
prefix, and `xyz' be the host type, as determined by `config.guess'.

The `error message' contains an additional explanation of the error
message. The message may consist of multiple lines. The client software
MAY display this message to the user. If this is done, the client
software should take the precautions discussed in [SSH-ARCH].

5. TCP/IP Port Forwarding

5.1. Requesting Port Forwarding

A party need not explicitly request forwardings from its own end to the
other direction. However, if it wishes that connections to a port on
the other side be forwarded to the local side, it must explicitly
request this.

byte SSH_MSG_GLOBAL_REQUEST
string "tcpip-forward"
boolean want reply

T. Ylonen, T. Kivinen, M. Saarinen, T. Rinne and S. Lehtinen [page 11]

INTERNET-DRAFT 21 Nov, 2000

string address to bind (e.g. "0.0.0.0")
uint32 port number to bind

`Address to bind' and `port number to bind' specify the IP address and
port to which the socket to be listened is bound. The address should be
"0.0.0.0" if connections are allowed from anywhere. (Note that the
client can still filter connections based on information passed in the
open request.)

Implementations should only allow forwarding privileged ports if the
user has been authenticated as a privileged user.

Client implementations SHOULD reject these messages; they are normally
only sent by the client.

A port forwarding can be cancelled with the following message. Note
that channel open requests may be received until a reply to this message
is received.

byte SSH_MSG_GLOBAL_REQUEST
string "cancel-tcpip-forward"
boolean want reply
string address_to_bind (e.g. "127.0.0.1")
uint32 port number to bind

Client implementations SHOULD reject these messages; they are normally
only sent by the client.

5.2. TCP/IP Forwarding Channels

When a connection comes to a port for which remote forwarding has been
requested, a channel is opened to forward the port to the other side.

byte SSH_MSG_CHANNEL_OPEN
string "forwarded-tcpip"
uint32 sender channel
uint32 initial window size
uint32 maximum packet size
string address that was connected
uint32 port that was connected
string originator IP address
uint32 originator port

Implementations MUST reject these messages unless they have previously
requested a remote TCP/IP port forwarding with the given port number.

When a connection comes to a locally forwarded TCP/IP port, the
following packet is sent to the other side. Note that these messages
MAY be sent also for ports for which no forwarding has been explicitly
requested. The receiving side must decide whether to allow the
forwarding.

byte SSH_MSG_CHANNEL_OPEN

T. Ylonen, T. Kivinen, M. Saarinen, T. Rinne and S. Lehtinen [page 12]

INTERNET-DRAFT 21 Nov, 2000

string "direct-tcpip"
uint32 sender channel
uint32 initial window size
uint32 maximum packet size
string host to connect
uint32 port to connect
string originator IP address
uint32 originator port

`Host to connect' and `port to connect' specify the TCP/IP host and port
where the recipient should connect the channel. `Host to connect' may
be either a domain name or a numeric IP address.

`Originator IP address' is the numeric IP address of the machine where
the connection request comes from, and `originator port' is the port on
the originator host from where the connection came from.

Forwarded TCP/IP channels are independent of any sessions, and closing a
session channel does not in any way imply that forwarded connections
should be closed.

Client implementations SHOULD reject direct TCP/IP open requests for
security reasons.

6. Encoding of Terminal Modes

Terminal modes (as passed in a pty request) are encoded into a byte
stream. It is intended that the coding be portable across different
environments.

The tty mode description is a stream of bytes. The stream consists of
opcode-argument pairs. It is terminated by opcode TTY_OP_END (0).
Opcodes 1 to 159 have a single uint32 argument. Opcodes 160 to 255 are
not yet defined, and cause parsing to stop (they should only be used
after any other data).

The client SHOULD put in the stream any modes it knows about, and the
server MAY ignore any modes it does not know about. This allows some
degree of machine-independence, at least between systems that use a
POSIX-like tty interface. The protocol can support other systems as
well, but the client may need to fill reasonable values for a number of
parameters so the server pty gets set to a reasonable mode (the server
leaves all unspecified mode bits in their default values, and only some
combinations make sense).

The following opcodes have been defined. The naming of opcodes mostly
follows the POSIX terminal mode flags.

0 TTY_OP_END Indicates end of options.
1 VINTR Interrupt character; 255 if none. Similarly for the
other characters. Not all of these characters are
supported on all systems.
2 VQUIT The quit character (sends SIGQUIT signal on POSIX

T. Ylonen, T. Kivinen, M. Saarinen, T. Rinne and S. Lehtinen [page 13]

INTERNET-DRAFT 21 Nov, 2000

systems).
3 VERASE Erase the character to left of the cursor.
4 VKILL Kill the current input line.
5 VEOF End-of-file character (sends EOF from the terminal).
6 VEOL End-of-line character in addition to carriage return
and/or linefeed.
7 VEOL2 Additional end-of-line character.
8 VSTART Continues paused output (normally control-Q).
9 VSTOP Pauses output (normally control-S).
10 VSUSP Suspends the current program.
11 VDSUSP Another suspend character.
12 VREPRINT Reprints the current input line.
13 VWERASE Erases a word left of cursor.
14 VLNEXT Enter the next character typed literally, even if it
is a special character
15 VFLUSH Character to flush output.
16 VSWTCH Switch to a different shell layer.
17 VSTATUS Prints system status line (load, command, pid etc).
18 VDISCARD Toggles the flushing of terminal output.
30 IGNPAR The ignore parity flag. The parameter SHOULD be 0 if
this flag is FALSE set, and 1 if it is TRUE.
31 PARMRK Mark parity and framing errors.
32 INPCK Enable checking of parity errors.
33 ISTRIP Strip 8th bit off characters.
34 INLCR Map NL into CR on input.
35 IGNCR Ignore CR on input.
36 ICRNL Map CR to NL on input.
37 IUCLC Translate uppercase characters to lowercase.
38 IXON Enable output flow control.
39 IXANY Any char will restart after stop.
40 IXOFF Enable input flow control.
41 IMAXBEL Ring bell on input queue full.
50 ISIG Enable signals INTR, QUIT, [D]SUSP.
51 ICANON Canonicalize input lines.
52 XCASE Enable input and output of uppercase characters by
preceding their lowercase equivalents with `\'.
53 ECHO Enable echoing.
54 ECHOE Visually erase chars.
55 ECHOK Kill character discards current line.
56 ECHONL Echo NL even if ECHO is off.
57 NOFLSH Don't flush after interrupt.
58 TOSTOP Stop background jobs from output.
59 IEXTEN Enable extensions.
60 ECHOCTL Echo control characters as ^(Char).
61 ECHOKE Visual erase for line kill.
62 PENDIN Retype pending input.
70 OPOST Enable output processing.
71 OLCUC Convert lowercase to uppercase.
72 ONLCR Map NL to CR-NL.
73 OCRNL Translate carriage return to newline (output).
74 ONOCR Translate newline to carriage return-newline
(output).
75 ONLRET Newline performs a carriage return (output).

T. Ylonen, T. Kivinen, M. Saarinen, T. Rinne and S. Lehtinen [page 14]

INTERNET-DRAFT 21 Nov, 2000

90 CS7 7 bit mode.
91 CS8 8 bit mode.
92 PARENB Parity enable.
93 PARODD Odd parity, else even.

128 TTY_OP_ISPEED Specifies the input baud rate in bits per second.
129 TTY_OP_OSPEED Specifies the output baud rate in bits per second.

7. Summary of Message Numbers

#define SSH_MSG_GLOBAL_REQUEST 80
#define SSH_MSG_REQUEST_SUCCESS 81
#define SSH_MSG_REQUEST_FAILURE 82
#define SSH_MSG_CHANNEL_OPEN 90
#define SSH_MSG_CHANNEL_OPEN_CONFIRMATION 91
#define SSH_MSG_CHANNEL_OPEN_FAILURE 92
#define SSH_MSG_CHANNEL_WINDOW_ADJUST 93
#define SSH_MSG_CHANNEL_DATA 94
#define SSH_MSG_CHANNEL_EXTENDED_DATA 95
#define SSH_MSG_CHANNEL_EOF 96
#define SSH_MSG_CHANNEL_CLOSE 97
#define SSH_MSG_CHANNEL_REQUEST 98
#define SSH_MSG_CHANNEL_SUCCESS 99
#define SSH_MSG_CHANNEL_FAILURE 100

8. Security Considerations

This protocol is assumed to run on top of a secure, authenticated
transport. User authentication and protection against network-level
attacks are assumed to be provided by the underlying protocols.

This protocol can, however, be used to execute commands on remote
machines. The protocol also permits the server to run commands on the
client. Implementations may wish to disallow this to prevent an
attacker from coming from the server machine to the client machine.

X11 forwarding provides major security improvements over normal cookie-
based X11 forwarding. The cookie never needs to be transmitted in the
clear, and traffic is encrypted and integrity-protected. No useful
authentication data will remain on the server machine after the
connection has been closed. On the other hand, in some situations a
forwarded X11 connection might be used to get access to the local X
server across security perimeters.

Port forwardings can potentially allow an intruder to cross security
perimeters such as firewalls. They do not offer anything fundamentally
new that a user could not do otherwise; however, they make opening
tunnels very easy. Implementations should allow policy control over
what can be forwarded. Administrators should be able to deny
forwardings where appropriate.

Since this protocol normally runs inside an encrypted tunnel, firewalls
will not be able to examine the traffic.

T. Ylonen, T. Kivinen, M. Saarinen, T. Rinne and S. Lehtinen [page 15]

INTERNET-DRAFT 21 Nov, 2000

It is RECOMMENDED that implementations disable all the potentially
dangerous features (e.g. agent forwarding, X11 forwarding, and TCP/IP
forwarding) if the host key has changed.

9. Trademark Issues

SSH is a registered trademark and Secure Shell is a trademark of SSH
Communications Security Corp. SSH Communications Security Corp permits
the use of these trademarks as the name of this standard and protocol,
and permits their use to describe that a product conforms to this
standard, provided that the following acknowledgement is included where
the trademarks are used: ``SSH is a registered trademark and Secure
Shell is a trademark of SSH Communications Security Corp
(www.ssh.com)''. These trademarks may not be used as part of a product
name or in otherwise confusing manner without prior written permission
of SSH Communications Security Corp

port setting from linux journel

2008-07-23T21:38:00.000-07:00

The Pro-Lite Tru-Color II PL-M2014R is an affordable multi-color LED scrolling message board that is capable of being controlled by a standard RS-232 serial port. The sign is obtainable from Pro-Lite directly (http://www.pro-lite.com/), but can also be purchased at various discount warehouses for approximately $150. The serial cable and Windows software are sold separately.

This article is not just a review; it can serve as a primer for Pro-Lite's PL-M2014R with ROM release 5.24Q and 32K of memory with Trivia mode, basically your standard sign. Until now, not much developer information has been available to the public, meaning signs were usually configured with the included infrared remote control to display static messages. For very little money, it is possible to build your own serial cable and control the sign using Linux to display more than static text.

The business and personal applications for a highly visible sign are almost limitless: reporting days until software delivery, announcing traffic congestion, providing the weather, showing the date and time, sending public messages, reporting system load, announcing new mail, showing who's logged in, warning when disk space gets low, login information, announcing unexpected server outages as a watchdog, etc.

Communicating with the sign is almost as simple as beaming text out the serial port; however, a bit of text manipulation is necessary in order to get the sign to respond and do advanced tasks. Linux handles the serial port communication, so sending information to the sign appears as trivial as writing to a file.

Luckily, the majority of the work can be accomplished by simple scripts. All you need is a basic understanding of the shell, AWK, PERL or Python, and you can be running in almost no time. The first hurdle is to build a cable and configure Linux to talk out the serial port.

Cable Construction

Figure 1. Female DB9 Adapter

The first step is wiring an RJ12 to female DB9 adapter. It requires no tools, and an adapter kit can be purchased at most computer supply stores for about $2 US. The only other thing you need is a length of RJ12 cable with male adapters at each end. This means a standard telephone cord will do nicely. Your cable will most likely have the standard colors black, red, green and yellow, in that order.

Cables come in two flavors: straight-thru and reversed. You'll need to take the RJ12 cable and put it end to end (like a loop) to find out which kind of adapter you need to build.

Figure 2. RJ12 Adapter Diagram

One of two things will be noticeable: either the wires will match black to black, red to red and so on, or they will reverse their order showing black to yellow, red to green and so on.

If the cable is a straight-through, where the colors match, wire your RJ12 to a DB9 adapter using Pin 2 as green, Pin 3 as red and Pin 5 as yellow. If the cable is reversed, then where the colors reverse sequence, wire your RJ12 to a DB9 adapter using Pin 2 as red, Pin 3 as green and Pin 5 as black.

Figure 3. RJ12 to DB9 Wiring

Shove the unused adapter wires into the casing and snap the adapter shut. Take care not to let the exposed ends touch anything metal inside the adapter casing. You may want to clip the unused wires. Put an extension cable on your serial port and connect the adapter wires directly to the extension cable in order to test the wiring configuration before pushing the pins into the connector.

When all is said and done, one end of the RJ12 goes into the side of the LED sign, the other into the adapter you just made, and the adapter plugs into the computer.

Configuring Linux to Talk to the Sign

My sign is plugged into COM1, also known as /dev/ttyS0. I've elected to use a symbolic link to the sign, in the event I ever decide to change to another serial port in the future. To make the link, as root type:

ln -s /dev/ttyS0 /dev/prolite

I tend to shy away from doing development as root. Putting security issues aside for the moment, we can make the device world-writable by typing:

chmod a+rw /dev/prolite

The sign communicates using No Parity, 8 Bits, 1 Stop Bit; no handshaking of any kind (hardware or software) is used. Early versions of the sign work only at 300 baud, but they can be upgraded to 9600 baud. All signs I've encountered had the 9600 capability right out of the box. The bottom line is that all signs are capable of communication, and even at 300 baud you can outrun the sign. The only drawback is that the sign's baud rate has to be set by the remote control, according to the setup in the manual. This needs to be done only once.

In theory, the sign requires a 15ms delay between each character sent to the sign. I've found that Linux's device driver seems to work just fine without having to do anything special in the software.

stty speed 9600 cs8 -parenb -cstopb cread \

  -clocal -crtscts -ignpar -echo nl1 cr3 < \

  /dev/prolite

Naturally, you can substitute any baud rate the sign will handle for the 9600. This command will work when you aren't root because it is world-writable.

The most important piece of information for communicating with the sign is that each command sent to the sign must end with a carriage return/newline pair. This is ctrl-M ctrl-J on the keyboard or 0x0C 0x0A in hexadecimal. C programmers will recognize it as \r\n. If you want Linux to handle the end-of-line sequence for you, type the command:

stty opost -ocrnl onlcr < /dev/prolite

When you send a newline, Linux will send both carriage return/newline automatically. Text can now be listed or redirected to /dev/prolite from the shell. If you want to send the carriage returns yourself, type:

stty -opost -ocrnl -onlcr < /dev/prolite

Where the options are defined as:

opost: postprocess the output stream.
-opost: do not postprocess the output stream.
-ocrnl: do not convert carriage returns into newlines.
-onlcr: do not translate each newline into a carriage return/newline pair.
onlcr: translate each newline into a carriage return/newline pair.

The stty command allows for a shorthand representation of all the termios structures that define the device characteristics. For 9600,N,8,1 with automatic carriage returns, type on one line:

stty 0:705:bd:0:3:1c:7f:15:4:0:1:0:11:13:1a:0:

12:f:17:16:0:0:73 < /dev/prolite

For 9600,N,8,1 with no automatic carriage returns, use the line:

stty 0:700:bd:0:3:1c:7f:15:4:0:1:0:11:13:1a:0:

12:f:17:16:0:0:73 < /dev/prolite

Command Syntax

Only a minimal understanding is needed in order to operate the sign. Mastery requires becoming familiar with the protocol and doing a little experimenting.

Multiple signs can be connected to a computer over the same serial port by using a simple telephone-line-splitting Y-connector. Each sign has an assignable logical address that allows you to send messages to particular signs. A logical address is represented in hexadecimal as a number between 01 and FF. Addresses may be shared enabling grouping; in this way, a message to ID01 goes to all signs with ID01.

Communication with the sign is always done with readable ASCII characters; thus, an arbitrary ID of 2F would be designated with the digit “2” and the capital letter “F”.

ID00 is reserved to mean “broadcast to all signs”. By default, a sign is preconfigured as ID01; this can be changed with the remote control. If you are addressing a single sign connected straight to the computer, it will respond with its ID number after each successful command. Messages sent to ID00 do not return a response, and neither does an individual sign when the line is shared via the Y-connector.

All messages to the sign, except for those setting the date and time, are sent in the following format followed by the carriage return/line feed: xx>command, xx is 00 to FF. Any command longer than 1,023 bytes will be ignored by the sign.

To set the date and time, no ID is needed. The format is <TYYMMDDwhhmmss> where YY is the year, MM the month, DD the day, w the weekday (0=Sun, 1=Mon,...6=Sat), hh the hour, mm the minute and ss the seconds. This can be accomplished with the shell very easily. Set the date/time of all signs with the command:

ate "+" te "+" > /dev/prolite> /dev/prolite

The leading + sign tells the date command to build a string via substitution; see your man pages for details.

To signal a sign to start listening to responses, send it an empty command with the format xx>; e.g., type:

echo "" > /dev/prolite

Pages

The most fundamental concept of the sign is the idea of a page. A page consists of a message the sign is to display either now or some time in the future. Pages may contain text, numerics, symbols, font attribute tags, color tags, graphic tags and effect tags. There are 26 pages named, appropriately enough, A to Z. Case does matter when identifying a page.

Any given page can hold approximately 1,012 bytes of information. I say approximately because special tags (see sidebar) consume more than one byte, which means less space. Also, using some trickery by omitting the page directive completely and defaulting to page A squeezes out an additional two bytes, which means more space.

The command to set a page is x>, where x is the page name. Any text after this sequence is considered text for the sign. To set the message “Linux Rules” on page A, type the following command:

echo "Linux Rules" > /dev/prolite

It is important to leave extra space at the end so the end of the message is separated from the front of the message as it scrolls.

To delete a page, use x>, where x is the page name. For example, to delete page B, type:

echo "" > /dev/prolite

Displaying Pages

The sign is constantly displaying a page. If the default page A is scrolling by, then when its content is changed it will immediately start displaying the new message. Otherwise, we must tell the sign which page to run using the x> command, where x is the page to display. Normally, the sign can run only one page at a time.

Once a page has been defined, it can be run. For example, to repeatedly display our message, type:

echo "" > /dev/prolite

Running an undefined page will result in displaying the sign's demo.

Two points of interest for script writers:

It is possible to update the contents of a page not being displayed, then switch to that page at a later time.
It is possible to update the currently displayed message. The only problem is the display will be interrupted mid-message.

Sadly, you cannot ask the sign what the contents of a page are, what page it is currently displaying, or when it has started or ended a display sequence. Thus, techniques like double-buffering don't work for continuous messages.

I have received one terse message from Pro-Lite that alluded to a future version of the sign which is designed to address such needs explicitly for computer users.

Timers

In order to display one or more messages at a time, the sign includes ten timers named A to J. Each timer specifies a time and a series of 1 to 32 pages to sequence through. You may repeat pages in a sequence. The time a sequence is displayed consists of a weekday, an hour and a minute, any of which may be wildcarded (*) to match “all”.

When the first timer is defined, the sign is put into “timer” mode and will display that timer's messages immediately. Should two or more timers be defined, the sign seems to wait one minute, then checks each timer to see if one triggered based on the current time. If so, at the end of the displaying message, the new timer's sequence goes into effect. If no rule matches, no change is made.

Note the sign checks the rules for the immediate time. It will not go back to try to find a previous timer. So if you set a timer for 4:15PM and it is now 4:17PM, you've missed the moment when the sign would change.

Should two or more timers both be valid for the current time, the sign unpredictably selects one for display. This means you cannot set one timer to display at 4:15 and another timer to display at 15 minutes past any hour. Both rules would be triggered at 4:15 and it is a toss-up as to which message will be displayed.

The timer command is defined as x>dhhmmABC..., where x is the timer, d is 0 (Sunday) to 6 (Saturday) for the day, hh is a two-digit hour and mm is the minute. “ABC...” is a list of 1 to 32 pages to display in the order specified. Note that Page-A and Timer-A are two different, unrelated entities. A timer set for “*****” will be triggered immediately.

The following sequence will display a series of messages at 8:00AM, noon, 1:00PM and 5:00PM:

$ cat > /dev/prolite



Good morning.

Have a nice lunch.

Get back to work.

Have a safe drive home.

*0800A

*1200B

*1300C

*1700D

ctrl-D

In order to display a whole sequences of pages, just list more page letters. For instance, it is useful to make a scheme where you assign page letters to different message content. For example, page A could be hourly announcements, page R the runtime status of your machine, page M the message of the day, page T the time and so on. To display several pages right now (including repeats):

$ cat > /dev/prolite



*****TAMARA

ctrl-D

Two interesting tidbits of information:

For some reason, the specific time of Sunday at midnight (00000 as a timer value) does not seem to work consistently. I suspect it confuses this value with unset timers.
If a run-page command () is issued, the sign is taken out of “timer” mode and displays the requested page. If you then issue the command , the sign will go back into “timer” mode, displaying the last sequence of messages.

To delete a timer, use x>, where x is the timer letter or * for all timers. For example, to delete timer D type:

echo "" > /dev/prolite

Graphics

There are 26 graphic blocks that can be redefined and are commonly used for graphics. Graphics are inserted into the text via the tag x>, where x is a letter from A to Z. For example, this command will display a mug and a wine glass:

echo " Party Tonight "

>\

  /dev/prolite

Altering the graphics requires the x> command followed by a string of 126 characters made up of R (for red), Y (for yellow), G (for green) and B (for black or unlit). A sequence of seven rows of eighteen LEDs is specified back to back on a single command line. (See Figure 4.)

Figure 4. A Graphics Block Specification

I know at least one user who loads a font into a sequence of graphic blocks, and in this way is able to display more characters than the sign technically allows by default—very clever.

To delete a graphic block, restoring it to the default, use x>, where x is a letter A to Z; * is a wildcard indicating all are to be deleted.

Trivia

One additional feature of the sign is to display in sequence a trivia question, your message, the answer to the question and your message again. It works its way though a canned list of questions and then starts over. The sign can be loaded with your own list, which does not have to be trivia. The list can be up to 16KB long, leaving 16KB for the pages. If no list is loaded (i.e., you deleted the trivia), the full 32KB of the sign is available for page content. To make your own list, do the following:

$ cat > /dev/prolite





What operating system isn't a pig?

Linux.

What operating system is free?

Linux.



Control-D

To delete the trivia, just omit the lines between and . If no messages are loaded, trivia mode is turned off. If they are, trivia is turned on.

Other Useful Commands and Tricks

To reset the sign, removing all timers and pages, use like this:

echo "" > /dev/prolite

Technically, there is no way to bring the sign to a halt. However, you can take advantage of a quirk in the software to do the same thing. If you use the tag in a message to control the speed of the sign, but don't supply a message, the old text isn't cleared and the sign stops scrolling until it gets a new message.

Function Tags

Additional tags are shown in “Function Tabs”. European tags are available for characters shown in Figure 5.

Figure 5. European Characters Available

Uses for the Sign

It doesn't take much to make the sign useful. For example, scripts that send commands to the sign can be executed every few minutes by editing your crontab file (crontab -e) to include:

*/5 * * * * /usr/local/bin/sign 1> /dev/null \

2> /dev/null

Every five minutes, the system will call /usr/local/bin/sign. In this script, we can place any number of tasks. To show our uptime, add these lines:

#!/bin/bash

stty 0:705:bd:0:3:1c:7f:15:4:0:1:0:11:13:1a:0:12\

:f:17:16:0:0:73 < /dev/prolite

echo "'uptime' " > /dev/prolite

echo "*****U" > /dev/prolite

If root wants to see the last line of the log file scroll by, this command will suffice:

tail -f -n 1 /var/log/messages |

  awk '{ print "" $0 " "; }' >

  /dev/prolite &

This job sits in the background, getting lines from the end of the log as they come in, prefixes a to it and sends it to the sign. The process then goes to sleep until another log entry is made. The only reason to run as root is to get access to the messages file.

The sign can also act as a watchdog for our system by setting up a timer to go off several minutes later. Ideally, the sign will get updated before the timer goes off and the timer will again be set for some time in the future. In the event the sign is not updated, the timer trips and an alternate alert message is displayed.

!/bin/bash

stty 0:705:bd:0:3:1c:7f:15:4:0:1:0:11:13:1a:0:12\

:f:17:16:0:0:73 < /dev/prolite

echo "Server Up" > /dev/prolite

echo "" > /dev/prolite

echo "00001U" > /dev/prolite

echo "Server Down" > \

  /dev/prolite

date "+*%H%MD" -date "7 min" > \

  /dev/prolite

To do this relies on some tricks. First, you cannot use a generic timer (*****) for running standard messages because it conflicts with our watchdog timer. Secondly, we cannot use timer 00000 because it confuses the sign. Thus, we have to use one minute after midnight on Sunday (00001) in order to display our messages. When no timers are defined, the first timer defined shows our page.

Deleting timer B keeps us using timer A, which shows normal text. The sign ignores requests to delete timers and pages that don't exist. Once page A is defined and displaying, we define page B in the background and set up a time, again using the clever date command to output it seven minutes from now. Since our cron job is set to run this script every five minutes, the timer should never go off unless something is wrong.

If Linux suffers a power failure, the cron daemon is killed, or the sign becomes disconnected, it will display a warning message. The tag indicates the message should instantly appear instead of scrolling, where indicates the text should appear from the center—this will get your attention quickly.

I have a led board which has 2 lines and 120x16 leds. The protocol described on this page is simular to the protocol used in my led board only it has some kind of security code in it.

For example:
This wil return a ACK, and the led board will show the message:
test62

This wil return a NACK, and the led board does not change:
test80

So there is a code right after the text... Another example:
Leon ter Linden1B = ACK
Leon ter Linden43 = NACK

Does anyone know how to calculate the code that comes after the text?

xor checksum

On October 16th, 2006 Are (not verified) says:

Here is the code to calculate the checksum.
The checksum is an xor of all the characters sent, without the first ID tag and without the end E tag.

static unsigned char checksum(const char *str, unsigned char init) { unsigned char i = init;

while (*str != '\0') {
i ^= *str;
str++;
}

return (i);
}

int
main(int argc, char *argv[])
{
unsigned char csum = 0x0;

if (argc != 2)
exit(-1);
else
msg = argv[1];

csum = checksum(msg, csum);
printf("%02X\n",csum);
return (csum);

Serial Communications in Win32

2008-07-10T21:59:00.000-07:00

Serial Communications in Win32

　

Allen Denver
Microsoft Windows Developer Support

December 11, 1995

Allen seldom eats breakfast, but if he had to pick a favorite, Win32 serial communications would be the top choice.

Click to open or copy the files in the MTTTY sample application for this technical article.

　
Abstract

Serial communications in Microsoft?Win32?is significantly different from serial communications in 16-bit Microsoft Windows? Those familiar with 16-bit serial communications functions will have to relearn many parts of the system to program serial communications properly. This article will help to accomplish this. Those unfamiliar with serial communications will find this article a helpful foundation for development efforts.

This article assumes the reader is familiar with the fundamentals of multiple threading and synchronization in Win32. In addition, a basic familiarity of the Win32 heap functions is useful to fully comprehend the memory management methods used by the sample, MTTTY, included with this article. For more information regarding these functions, consult the Platform SDK documentation, the Microsoft Win32 SDK Knowledge Base, or the Microsoft Developer Network Library. Application programming interfaces (APIs) that control user interface features of windows and dialog boxes, though not discussed here, are useful to know in order to fully comprehend the sample provided with this article. Readers unfamiliar with general Windows programming practices should learn some of the fundamentals of general Windows programming before taking on serial communications. In other words, get your feet wet before diving in head first.
Introduction

The focus of this article is on application programming interfaces (APIs) and methods that are compatible with Microsoft?Windows NT?and Windows 95; therefore, APIs supported on both platforms are the only ones discussed. Windows 95 supports the Win32?Telephony API (TAPI) and Windows NT 3.x does not; therefore, this discussion will not include TAPI. TAPI does deserve mention, however, in that it very nicely implements modem interfacing and call controlling. A production application that works with modems and makes telephone calls should implement these features using the TAPI interface. This will allow seamless integration with the other TAPI-enabled applications that a user may have. Furthermore, this article does not discuss some of the configuration functions in Win32, such as GetCommProperties.

The article is broken into the following sections: Opening a port, reading and writing (nonoverlapped and overlapped), serial status (events and errors), and serial settings (DCB, flow control, and communications time-outs).

The sample included with this article, MTTTY: Multithreaded TTY, implements many of the features discussed here. It uses three threads in its implementation: a user interface thread that does memory management, a writer thread that controls all writing, and a reader/status thread that reads data and handles status changes on the port. The sample employs a few different data heaps for memory management. It also makes extensive use of synchronization methods to facilitate communication between threads.
Opening a Port

The CreateFile function opens a communications port. There are two ways to call CreateFile to open the communications port: overlapped and nonoverlapped. The following is the proper way to open a communications resource for overlapped operation:

HANDLE hComm;

hComm = CreateFile( gszPort,

GENERIC_READ | GENERIC_WRITE,

0,

0,

OPEN_EXISTING,

FILE_FLAG_OVERLAPPED,

0);

if (hComm == INVALID_HANDLE_VALUE)

// error opening port; abort

Removal of the FILE_FLAG_OVERLAPPED flag from the call to CreateFile specifies nonoverlapped operation. The next section discusses overlapped and nonoverlapped operations.

The Platform SDK documentation states that when opening a communications port, the call to CreateFile has the following requirements:

* fdwShareMode must be zero. Communications ports cannot be shared in the same manner that files are shared. Applications using TAPI can use the TAPI functions to facilitate sharing resources between applications. For Win32 applications not using TAPI, handle inheritance or duplication is necessary to share the communications port. Handle duplication is beyond the scope of this article; please refer to the Platform SDK documentation for more information.
* fdwCreate must specify the OPEN_EXISTING flag.
* hTemplateFile parameter must be NULL.

One thing to note about port names is that traditionally they have been COM1, COM2, COM3, or COM4. The Win32 API does not provide any mechanism for determining what ports exist on a system. Windows NT and Windows 95 keep track of installed ports differently from one another, so any one method would not be portable across all Win32 platforms. Some systems even have more ports than the traditional maximum of four. Hardware vendors and serial-device-driver writers are free to name the ports anything they like. For this reason, it is best that users have the ability to specify the port name they want to use. If a port does not exist, an error will occur (ERROR_FILE_NOT_FOUND) after attempting to open the port, and the user should be notified that the port isn’t available.
Reading and Writing

Reading from and writing to communications ports in Win32 is very similar to file input/output (I/O) in Win32. In fact, the functions that accomplish file I/O are the same functions used for serial I/O. I/O in Win32 can be done either of two ways: overlapped or nonoverlapped. The Platform SDK documentation uses the terms asynchronous and synchronous to connote these types of I/O operations. This article, however, uses the terms overlapped and nonoverlapped.

Nonoverlapped I/O is familiar to most developers because this is the traditional form of I/O, where an operation is requested and is assumed to be complete when the function returns. In the case of overlapped I/O, the system may return to the caller immediately even when an operation is not finished and will signal the caller when the operation completes. The program may use the time between the I/O request and its completion to perform some “background?work.

Reading and writing in Win32 is significantly different from reading and writing serial communications ports in 16-bit Windows. 16-bit Windows only has the ReadComm and WriteComm functions. Win32 reading and writing can involve many more functions and choices. These issues are discussed below.
Nonoverlapped I/O

Nonoverlapped I/O is very straightforward, though it has limitations. An operation takes place while the calling thread is blocked. Once the operation is complete, the function returns and the thread can continue its work. This type of I/O is useful for multithreaded applications because while one thread is blocked on an I/O operation, other threads can still perform work. It is the responsibility of the application to serialize access to the port correctly. If one thread is blocked waiting for its I/O operation to complete, all other threads that subsequently call a communications API will be blocked until the original operation completes. For instance, if one thread were waiting for a ReadFile function to return, any other thread that issued a WriteFile function would be blocked.

One of the many factors to consider when choosing between nonoverlapped and overlapped operations is portability. Overlapped operation is not a good choice because most operating systems do not support it. Most operating systems support some form of multithreading, however, so multithreaded nonoverlapped I/O may be the best choice for portability reasons.
Overlapped I/O

Overlapped I/O is not as straightforward as nonoverlapped I/O, but allows more flexibility and efficiency. A port open for overlapped operations allows multiple threads to do I/O operations at the same time and perform other work while the operations are pending. Furthermore, the behavior of overlapped operations allows a single thread to issue many different requests and do work in the background while the operations are pending.

In both single-threaded and multithreaded applications, some synchronization must take place between issuing requests and processing the results. One thread will have to be blocked until the result of an operation is available. The advantage is that overlapped I/O allows a thread to do some work between the time of the request and its completion. If no work can be done, then the only case for overlapped I/O is that it allows for better user responsiveness.

Overlapped I/O is the type of operation that the MTTTY sample uses. It creates a thread that is responsible for reading the port’s data and reading the port’s status. It also performs periodic background work. The program creates another thread exclusively for writing data out the port.

Note Applications sometimes abuse multithreading systems by creating too many threads. Although using multiple threads can resolve many difficult problems, creating excessive threads is not the most efficient use of them in an application. Threads are less a strain on the system than processes but still require system resources such as CPU time and memory. An application that creates excessive threads may adversely affect the performance of the entire system. A better use of threads is to create a different request queue for each type of job and to have a worker thread issue an I/O request for each entry in the request queue. This method is used by the MTTTY sample provided with this article.

An overlapped I/O operation has two parts: the creation of the operation and the detection of its completion. Creating the operation entails setting up an OVERLAPPED structure, creating a manual-reset event for synchronization, and calling the appropriate function (ReadFile or WriteFile). The I/O operation may or may not be completed immediately. It is an error for an application to assume that a request for an overlapped operation always yields an overlapped operation. If an operation is completed immediately, an application needs to be ready to continue processing normally. The second part of an overlapped operation is to detect its completion. Detecting completion of the operation involves waiting for the event handle, checking the overlapped result, and then handling the data. The reason that there is more work involved with an overlapped operation is that there are more points of failure. If a nonoverlapped operation fails, the function just returns an error-return result. If an overlapped operation fails, it can fail in the creation of the operation or while the operation is pending. You may also have a time-out of the operation or a time-out waiting for the signal that the operation is complete.
Reading

The ReadFile function issues a read operation. ReadFileEx also issues a read operation, but since it is not available on Windows 95, it is not discussed in this article. Here is a code snippet that details how to issue a read request. Notice that the function calls a function to process the data if the ReadFile returns TRUE. This is the same function called if the operation becomes overlapped. Note the fWaitingOnRead flag that is defined by the code; it indicates whether or not a read operation is overlapped. It is used to prevent the creation of a new read operation if one is outstanding.

DWORD dwRead;

BOOL fWaitingOnRead = FALSE;

OVERLAPPED osReader = {0};

// Create the overlapped event. Must be closed before exiting

// to avoid a handle leak.

osReader.hEvent = CreateEvent(NULL, TRUE, FALSE, NULL);

if (osReader.hEvent == NULL)

// Error creating overlapped event; abort.

if (!fWaitingOnRead) {

// Issue read operation.

if (!ReadFile(hComm, lpBuf, READ_BUF_SIZE, &dwRead, &osReader)) {

if (GetLastError() != ERROR_IO_PENDING) // read not delayed?

// Error in communications; report it.

else

fWaitingOnRead = TRUE;

}

else {

// read completed immediately

HandleASuccessfulRead(lpBuf, dwRead);

}

}

The second part of the overlapped operation is the detection of its completion. The event handle in the OVERLAPPED structure is passed to the WaitForSingleObject function, which will wait until the object is signaled. Once the event is signaled, the operation is complete. This does not mean that it was completed successfully, just that it was completed. The GetOverlappedResult function reports the result of the operation. If an error occurred, GetOverlappedResult returns FALSE and GetLastError returns the error code. If the operation was completed successfully, GetOverlappedResult will return TRUE.

Note GetOverlappedResult can detect completion of the operation, as well as return the operation’s failure status. GetOverlappedResult returns FALSE and GetLastError returns ERROR_IO_INCOMPLETE when the operation is not completed. In addition, GetOverlappedResult can be made to block until the operation completes. This effectively turns the overlapped operation into a nonoverlapped operation and is accomplished by passing TRUE as the bWait parameter.

Here is a code snippet that shows one way to detect the completion of an overlapped read operation. Note that the code calls the same function to process the data that was called when the operation completed immediately. Also note the use of the fWaitingOnRead flag. Here it controls entry into the detection code, since it should be called only when an operation is outstanding.

#define READ_TIMEOUT 500 // milliseconds

DWORD dwRes;

if (fWaitingOnRead) {

dwRes = WaitForSingleObject(osReader.hEvent, READ_TIMEOUT);

switch(dwRes)

{

// Read completed.

case WAIT_OBJECT_0:

if (!GetOverlappedResult(hComm, &osReader, &dwRead, FALSE))

// Error in communications; report it.

else

// Read completed successfully.

HandleASuccessfulRead(lpBuf, dwRead);

// Reset flag so that another opertion can be issued.

fWaitingOnRead = FALSE;

break;

case WAIT_TIMEOUT:

// Operation isn't complete yet. fWaitingOnRead flag isn't

// changed since I'll loop back around, and I don't want

// to issue another read until the first one finishes.

//

// This is a good time to do some background work.

break;

default:

// Error in the WaitForSingleObject; abort.

// This indicates a problem with the OVERLAPPED structure's

// event handle.

break;

}

}

Writing

Transmitting data out the communications port is very similar to reading in that it uses a lot of the same APIs. The code snippet below demonstrates how to issue and wait for a write operation to be completed.

BOOL WriteABuffer(char * lpBuf, DWORD dwToWrite)

{

OVERLAPPED osWrite = {0};

DWORD dwWritten;

DWORD dwRes;

BOOL fRes;

// Create this write operation's OVERLAPPED structure's hEvent.

osWrite.hEvent = CreateEvent(NULL, TRUE, FALSE, NULL);

if (osWrite.hEvent == NULL)

// error creating overlapped event handle

return FALSE;

// Issue write.

if (!WriteFile(hComm, lpBuf, dwToWrite, &dwWritten, &osWrite)) {

if (GetLastError() != ERROR_IO_PENDING) {

// WriteFile failed, but isn't delayed. Report error and abort.

fRes = FALSE;

}

else

// Write is pending.

dwRes = WaitForSingleObject(osWrite.hEvent, INFINITE);

switch(dwRes)

{

// OVERLAPPED structure's event has been signaled.

case WAIT_OBJECT_0:

if (!GetOverlappedResult(hComm, &osWrite, &dwWritten, FALSE))

fRes = FALSE;

else

// Write operation completed successfully.

fRes = TRUE;

break;

default:

// An error has occurred in WaitForSingleObject.

// This usually indicates a problem with the

// OVERLAPPED structure's event handle.

fRes = FALSE;

break;

}

}

}

else

// WriteFile completed immediately.

fRes = TRUE;

CloseHandle(osWrite.hEvent);

return fRes;

}

Notice that the code above uses the WaitForSingleObject function with a time-out value of INFINITE. This causes the WaitForSingleObject function to wait forever until the operation is completed; this may make the thread or program appear to be “hung?when, in fact, the write operation is simply taking a long time to complete or flow control has blocked the transmission. Status checking, discussed later, can detect this condition, but doesn’t cause the WaitForSingleObject to return. Three things can alleviate this condition:

* Place the code in a separate thread. This allows other threads to execute any functions they desire while our writer thread waits for the write to be completed. This is what the MTTTY sample does.
* Use COMMTIMEOUTS to cause the write to be completed after a time-out period has passed. This is discussed more fully in the “Communications Time-outs?section later in this article. This is also what the MTTTY sample allows.
* Change the WaitForSingleObject call to include a real time-out value. This causes more problems because if the program issues another operation while an older operation is still pending, new OVERLAPPED structures and overlapped events need to be allocated. This type of recordkeeping is difficult, particularly when compared to using a “job queue?design for the operations. The “job queue?method is used in the MTTTY sample.

Note: The time-out values in synchronization functions are not communications time-outs. Synchronization time-outs cause WaitForSingleObject or WaitForMultipleObjects to return WAIT_TIMEOUT. This is not the same as a read or write operation timing out. Communications time-outs are described later in this article.

Because the WaitForSingleObject function in the above code snippet uses an INFINITE time-out, it is equivalent to using GetOverlappedResult with TRUE for the fWait parameter. Here is equivalent code in a much simplified form:

BOOL WriteABuffer(char * lpBuf, DWORD dwToWrite)

{

OVERLAPPED osWrite = {0};

DWORD dwWritten;

BOOL fRes;

// Create this writes OVERLAPPED structure hEvent.

osWrite.hEvent = CreateEvent(NULL, TRUE, FALSE, NULL);

if (osWrite.hEvent == NULL)

// Error creating overlapped event handle.

return FALSE;

// Issue write.

if (!WriteFile(hComm, lpBuf, dwToWrite, &dwWritten, &osWrite)) {

if (GetLastError() != ERROR_IO_PENDING) {

// WriteFile failed, but it isn't delayed. Report error and abort.

fRes = FALSE;

}

else {

// Write is pending.

if (!GetOverlappedResult(hComm, &osWrite, &dwWritten, TRUE))

fRes = FALSE;

else

// Write operation completed successfully.

fRes = TRUE;

}

}

else

// WriteFile completed immediately.

fRes = TRUE;

CloseHandle(osWrite.hEvent);

return fRes;

}

GetOverlappedResult is not always the best way to wait for an overlapped operation to be completed. For example, if an application needs to wait on another event handle, the first code snippet serves as a better model than the second. The call to WaitForSingleObject is easy to change to WaitForMultipleObjects to include the additional handles on which to wait. This is what the MTTTY sample application does.

A common mistake in overlapped I/O is to reuse an OVERLAPPED structure before the previous overlapped operation is completed. If a new overlapped operation is issued before a previous operation is completed, a new OVERLAPPED structure must be allocated for it. A new manual-reset event for the hEvent member of the OVERLAPPED structure must also be created. Once an overlapped operation is complete, the OVERLAPPED structure and its event are free for reuse.

The only member of the OVERLAPPED structure that needs modifying for serial communications is the hEvent member. The other members of the OVERLAPPED structure should be initialized to zero and left alone. Modifying the other members of the OVERLAPPED structure is not necessary for serial communications devices. The documentation for ReadFile and WriteFile state that the Offset and OffsetHigh members of the OVERLAPPED structure must be updated by the application, or else results are unpredictable. This guideline should be applied to OVERLAPPED structures used for other types of resources, such as files.
Serial Status

There are two methods to retrieve the status of a communications port. The first is to set an event mask that causes notification of the application when the desired events occur. The SetCommMask function sets this event mask, and the WaitCommEvent function waits for the desired events to occur. These functions are similar to the 16-bit functions SetCommEventMask and EnableCommNotification, except that the Win32 functions do not post WM_COMMNOTIFY messages. In fact, the WM_COMMNOTIFY message is not even part of the Win32 API. The second method for retrieving the status of the communications port is to periodically call a few different status functions. Polling is, of course, neither efficient nor recommended.
Communications Events

Communications events can occur at any time in the course of using a communications port. The two steps involved in receiving notification of communications events are as follows:

* SetCommMask sets the desired events that cause a notification.
* WaitCommEvent issues a status check. The status check can be an overlapped or nonoverlapped operation, just as the read and write operations can be.

Note: The word event in this context refers to communications events only. It does not refer to an event object used for synchronization.

Here is an example of the SetCommMask function:

DWORD dwStoredFlags;

dwStoredFlags = EV_BREAK | EV_CTS | EV_DSR | EV_ERR | EV_RING |\

EV_RLSD | EV_RXCHAR | EV_RXFLAG | EV_TXEMPTY ;

if (!SetCommMask(hComm, dwStoredFlags))

// error setting communications mask

A description of each type of event is in Table 1.

Table 1. Communications Event Flags

Event Flag

Description

EV_BREAK

A break was detected on input.

EV_CTS

The CTS (clear-to-send) signal changed state. To get the actual state of the CTS line, GetCommModemStatus should be called.

EV_DSR

The DSR (data-set-ready) signal changed state. To get the actual state of the DSR line, GetCommModemStatus should be called.

EV_ERR

A line-status error occurred. Line-status errors are CE_FRAME, CE_OVERRUN, and CE_RXPARITY. To find the cause of the error, ClearCommError should be called.

EV_RING

A ring indicator was detected.

EV_RLSD

The RLSD (receive-line-signal-detect) signal changed state. To get the actual state of the RLSD line, GetCommModemStatus should be called. Note that this is commonly referred to as the CD (carrier detect) line.

EV_RXCHAR

A new character was received and placed in the input buffer. See the “Caveat?section below for a discussion of this flag.

EV_RXFLAG

The event character was received and placed in the input buffer. The event character is specified in the EvtChar member of the DCB structure discussed later. The “Caveat?section below also applies to this flag.

EV_TXEMPTY

The last character in the output buffer was sent to the serial port device. If a hardware buffer is used, this flag only indicates that all data has been sent to the hardware. There is no way to detect when the hardware buffer is empty without talking directly to the hardware with a device driver.

After specifying the event mask, the WaitCommEvent function detects the occurrence of the events. If the port is open for nonoverlapped operation, then the WaitCommEvent function does not contain an OVERLAPPED structure. The function blocks the calling thread until the occurrence of one of the events. If an event never occurs, the thread may block indefinitely.

Here is a code snippet that shows how to wait for an EV_RING event when the port is open for nonoverlapped operation:

DWORD dwCommEvent;

if (!SetCommMask(hComm, EV_RING))

// Error setting communications mask

return FALSE;

if (!WaitCommEvent(hComm, &dwCommEvent, NULL))

// An error occurred waiting for the event.

return FALSE;

else

// Event has occurred.

return TRUE;

Note The Microsoft Win32 SDK Knowledge Base documents a problem with Windows 95 and the EV_RING flag. The above code never returns in Windows 95 because the EV_RING event is not detected by the system; Windows NT properly reports the EV_RING event. Please see the Win32 SDK Knowledge Base for more information on this bug.

As noted, the code above can be blocked forever if an event never occurs. A better solution would be to open the port for overlapped operation and wait for a status event in the following manner:

#define STATUS_CHECK_TIMEOUT 500 // Milliseconds

DWORD dwRes;

DWORD dwCommEvent;

DWORD dwStoredFlags;

BOOL fWaitingOnStat = FALSE;

OVERLAPPED osStatus = {0};

dwStoredFlags = EV_BREAK | EV_CTS | EV_DSR | EV_ERR | EV_RING |\

EV_RLSD | EV_RXCHAR | EV_RXFLAG | EV_TXEMPTY ;

if (!SetCommMask(comHandle, dwStoredFlags))

// error setting communications mask; abort

return 0;

osStatus.hEvent = CreateEvent(NULL, TRUE, FALSE, NULL);

if (osStatus.hEvent == NULL)

// error creating event; abort

return 0;

for ( ; ; ) {

// Issue a status event check if one hasn't been issued already.

if (!fWaitingOnStat) {

if (!WaitCommEvent(hComm, &dwCommEvent, &osStatus)) {

if (GetLastError() == ERROR_IO_PENDING)

bWaitingOnStatusHandle = TRUE;

else

// error in WaitCommEvent; abort

break;

}

else

// WaitCommEvent returned immediately.

// Deal with status event as appropriate.

ReportStatusEvent(dwCommEvent);

}

// Check on overlapped operation.

if (fWaitingOnStat) {

// Wait a little while for an event to occur.

dwRes = WaitForSingleObject(osStatus.hEvent, STATUS_CHECK_TIMEOUT);

switch(dwRes)

{

// Event occurred.

case WAIT_OBJECT_0:

if (!GetOverlappedResult(hComm, &osStatus, &dwOvRes, FALSE))

// An error occurred in the overlapped operation;

// call GetLastError to find out what it was

// and abort if it is fatal.

else

// Status event is stored in the event flag

// specified in the original WaitCommEvent call.

// Deal with the status event as appropriate.

ReportStatusEvent(dwCommEvent);

// Set fWaitingOnStat flag to indicate that a new

// WaitCommEvent is to be issued.

fWaitingOnStat = FALSE;

break;

case WAIT_TIMEOUT:

// Operation isn't complete yet. fWaitingOnStatusHandle flag

// isn't changed since I'll loop back around and I don't want

// to issue another WaitCommEvent until the first one finishes.

//

// This is a good time to do some background work.

DoBackgroundWork();

break;

default:

// Error in the WaitForSingleObject; abort

// This indicates a problem with the OVERLAPPED structure's

// event handle.

CloseHandle(osStatus.hEvent);

return 0;

}

}

}

CloseHandle(osStatus.hEvent);

The code above very closely resembles the code for overlapped reading. In fact, the MTTTY sample implements its reading and status checking in the same thread using WaitForMultipleObjects to wait for either the read event or the status event to become signaled.

There are two interesting side effects of SetCommMask and WaitCommEvent. First, if the communications port is open for nonoverlapped operation, WaitCommEvent will be blocked until an event occurs. If another thread calls SetCommMask to set a new event mask, that thread will be blocked on the call to SetCommMask. The reason is that the original call to WaitCommEvent in the first thread is still executing. The call to SetCommMask blocks the thread until the WaitCommEvent function returns in the first thread. This side effect is universal for ports open for nonoverlapped I/O. If a thread is blocked on any communications function and another thread calls a communications function, the second thread is blocked until the communications function returns in the first thread. The second interesting note about these functions is their use on a port open for overlapped operation. If SetCommMask sets a new event mask, any pending WaitCommEvent will complete successfully, and the event mask produced by the operation is NULL.
Caveat

Using the EV_RXCHAR flag will notify the thread that a byte arrived at the port. This event, used in combination with the ReadFile function, enables a program to read data only after it is in the receive buffer, as opposed to issuing a read that waits for the data to arrive. This is particularly useful when a port is open for nonoverlapped operation because the program does not need to poll for incoming data; the program is notified of the incoming data by the occurrence of the EV_RXCHAR event. Initial attempts to code this solution often produce the following pseudocode, including one oversight covered later in this section:

DWORD dwCommEvent;

DWORD dwRead;

char chRead;

if (!SetCommMask(hComm, EV_RXCHAR))

// Error setting communications event mask.

for ( ; ; ) {

if (WaitCommEvent(hComm, &dwCommEvent, NULL)) {

if (ReadFile(hComm, &chRead, 1, &dwRead, NULL))

// A byte has been read; process it.

else

// An error occurred in the ReadFile call.

break;

}

else

// Error in WaitCommEvent.

break;

}

The above code waits for an EV_RXCHAR event to occur. When this happens, the code calls ReadFile to read the one byte received. The loop starts again, and the code waits for another EV_RXCHAR event. This code works fine when one or two bytes arrive in quick succession. The byte reception causes the EV_RXCHAR event to occur. The code reads the byte. If no other byte arrives before the code calls WaitCommEvent again, then all is fine; the next byte to arrive will cause the WaitCommEvent function to indicate the occurrence of the EV_RXCHAR event. If another single byte arrives before the code has a chance to reach the WaitCommEvent function, then all is fine, too. The first byte is read as before; the arrival of the second byte causes the EV_RXCHAR flag to be set internally. When the code returns to the WaitCommEvent function, it indicates the occurrence of the EV_RXCHAR event and the second byte is read from the port in the ReadFile call.

The problem with the above code occurs when three or more bytes arrive in quick succession. The first byte causes the EV_RXCHAR event to occur. The second byte causes the EV_RXCHAR flag to be set internally. The next time the code calls WaitCommEvent, it indicates the EV_RXCHAR event. Now, a third byte arrives at the communications port. This third byte causes the system to attempt to set the EV_RXCHAR flag internally. Because this has already occurred when the second byte arrived, the arrival of the third byte goes unnoticed. The code eventually will read the first byte without a problem. After this, the code will call WaitCommEvent, and it indicates the occurrence of the EV_RXCHAR event (from the arrival of the second byte). The second byte is read, and the code returns to the WaitCommEvent function. The third byte waits in the system’s internal receive buffer. The code and the system are now out of sync. When a fourth byte finally arrives, the EV_RXCHAR event occurs, and the code reads a single byte. It reads the third byte. This will continue indefinitely.

The solution to this problem seems as easy as increasing the number of bytes requested in the read operation. Instead of requesting a single byte, the code could request two, ten, or some other number of bytes. The problem with this idea is that it still fails when two or more extra bytes above the size of the read request arrive at the port in quick succession. So, if two bytes are read, then four bytes arriving in quick succession would cause the problem. Ten bytes requested would still fail if twelve bytes arrived in quick succession.

The real solution to this problem is to read from the port until no bytes are remaining. The following pseudocode solves the problem by reading in a loop until zero characters are read. Another possible method would be to call ClearCommError to determine the number of bytes in the buffer and read them all in one read operation. This method requires more sophisticated buffer management, but it reduces the number of reads when a lot of data arrives at once.

DWORD dwCommEvent;

DWORD dwRead;

char chRead;

if (!SetCommMask(hComm, EV_RXCHAR))

// Error setting communications event mask

for ( ; ; ) {

if (WaitCommEvent(hComm, &dwCommEvent, NULL)) {

do {

if (ReadFile(hComm, &chRead, 1, &dwRead, NULL))

// A byte has been read; process it.

else

// An error occurred in the ReadFile call.

break;

} while (dwRead);

}

else

// Error in WaitCommEvent

break;

}

The above code does not work correctly without setting the proper time-outs. Communications time-outs, discussed later, affect the behavior of the ReadFile operation in order to cause it to return without waiting for bytes to arrive. Discussion of this topic occurs later in the “Communications Time-outs?section of this article.

The above caveat regarding EV_RXCHAR also applies to EV_RXFLAG. If flag characters arrive in quick succession, EV_RXFLAG events may not occur for all of them. Once again, the best solution is to read all bytes until none remain.

The above caveat also applies to other events not related to character reception. If other events occur in quick succession some of the notifications will be lost. For instance, if the CTS line voltage starts high, then goes low, high, and low again, an EV_CTS event occurs. There is no guarantee of how many EV_CTS events will actually be detected with WaitCommEvent if the changes in the CTS line happen quickly. For this reason, WaitCommEvent cannot be used to keep track of the state of the line. Line status is covered in the “Modem Status?section later in this article.
Error Handling and Communications Status

One of the communications event flags specified in the call to SetCommMask is possibly EV_ERR. The occurrence of the EV_ERR event indicates that an error condition exists in the communications port. Other errors can occur in the port that do not cause the EV_ERR event to occur. In either case, errors associated with the communications port cause all I/O operations to be suspended until removal of the error condition. ClearCommError is the function to call to detect errors and clear the error condition.

ClearCommError also provides communications status indicating why transmission has stopped; it also indicates the number of bytes waiting in the transmit and receive buffers. The reason why transmission may stop is because of errors or to flow control. The discussion of flow control occurs later in this article.

Here is some code that demonstrates how to call ClearCommError:

COMSTAT comStat;

DWORD dwErrors;

BOOL fOOP, fOVERRUN, fPTO, fRXOVER, fRXPARITY, fTXFULL;

BOOL fBREAK, fDNS, fFRAME, fIOE, fMODE;

// Get and clear current errors on the port.

if (!ClearCommError(hComm, &dwErrors, &comStat))

// Report error in ClearCommError.

return;

// Get error flags.

fDNS = dwErrors & CE_DNS;

fIOE = dwErrors & CE_IOE;

fOOP = dwErrors & CE_OOP;

fPTO = dwErrors & CE_PTO;

fMODE = dwErrors & CE_MODE;

fBREAK = dwErrors & CE_BREAK;

fFRAME = dwErrors & CE_FRAME;

fRXOVER = dwErrors & CE_RXOVER;

fTXFULL = dwErrors & CE_TXFULL;

fOVERRUN = dwErrors & CE_OVERRUN;

fRXPARITY = dwErrors & CE_RXPARITY;

// COMSTAT structure contains information regarding

// communications status.

if (comStat.fCtsHold)

// Tx waiting for CTS signal

if (comStat.fDsrHold)

// Tx waiting for DSR signal

if (comStat.fRlsdHold)

// Tx waiting for RLSD signal

if (comStat.fXoffHold)

// Tx waiting, XOFF char rec'd

if (comStat.fXoffSent)

// Tx waiting, XOFF char sent

if (comStat.fEof)

// EOF character received

if (comStat.fTxim)

// Character waiting for Tx; char queued with TransmitCommChar

if (comStat.cbInQue)

// comStat.cbInQue bytes have been received, but not read

if (comStat.cbOutQue)

// comStat.cbOutQue bytes are awaiting transfer

Modem Status (a.k.a. Line Status)

The call to SetCommMask may include the flags EV_CTS, EV_DSR, EV_RING, and EV_RLSD. These flags indicate changes in the voltage on the lines of the serial port. There is no indication of the actual status of these lines, just that a change occurred. The GetCommModemStatus function retrieves the actual state of these status lines by returning a bit mask indicating a 0 for low or no voltage and 1 for high voltage for each of the lines.

Please note that the term RLSD (Receive Line Signal Detect) is commonly referred to as the CD (Carrier Detect) line.

Note The EV_RING flag does not work in Windows 95 as mentioned earlier. The GetCommModemStatus function, however, does detect the state of the RING line.

Changes in these lines may also cause a flow-control event. The ClearCommError function reports whether transmission is suspended because of flow control. If necessary, a thread may call ClearCommError to detect whether the event is the cause of a flow-control action. Flow control is covered in the “Flow Control?section later in this article.

Here is some code that demonstrates how to call GetCommModemStatus:

DWORD dwModemStatus;

BOOL fCTS, fDSR, fRING, fRLSD;

if (!GetCommModemStatus(hComm, &dwModemStatus))

// Error in GetCommModemStatus;

return;

fCTS = MS_CTS_ON & dwModemStatus;

fDSR = MS_DSR_ON & dwModemStatus;

fRING = MS_RING_ON & dwModemStatus;

fRLSD = MS_RLSD_ON & dwModemStatus;

// Do something with the flags.

Extended Functions

The driver will automatically change the state of control lines as necessary. Generally speaking, changing status lines is under the control of a driver. If a device uses communications port control lines in a manner different from RS-232 standards, the standard serial communications driver will not work to control the device. If the standard serial communications driver will not control the device, a custom device driver is necessary.

There are occasions when standard control lines are under the control of the application instead of the serial communications driver. For instance, an application may wish to implement its own flow control. The application would be responsible for changing the status of the RTS and DTR lines. EscapeCommFunction directs a communications driver to perform such extended operations. EscapeCommFunction can make the driver perform some other function, such as setting or clearing a BREAK condition. For more information on this function, consult the Platform SDK documentation, the Microsoft Win32 SDK Knowledge Base, or the Microsoft Developer Network (MSDN) Library.
Serial Settings
DCB Settings

The most crucial aspect of programming serial communications applications is the settings in the Device-Control Block (DCB) structure. The most common errors in serial communications programming occur in initializing the DCB structure improperly. When the serial communications functions do not behave as expected, a close examination of the DCB structure usually reveals the problem.

There are three ways to initialize a DCB structure. The first method is to use the function GetCommState. This function returns the current DCB in use for the communications port. The following code shows how to use the GetCommState function:

DCB dcb = {0};

if (!GetCommState(hComm, &dcb))

// Error getting current DCB settings

else

// DCB is ready for use.

The second method to initialize a DCB is to use a function called BuildCommDCB. This function fills in the baud, parity type, number of stop bits, and number of data bits members of the DCB. The function also sets the flow-control members to default values. Consult the documentation of the BuildCommDCB function for details on which default values it uses for flow-control members. Other members of the DCB are unaffected by this function. It is the program's duty to make sure the other members of the DCB do not cause errors. The simplest thing to do in this regard is to initialize the DCB structure with zeros and then set the size member to the size, in bytes, of the structure. If the zero initialization of the DCB structure does not occur, then there may be nonzero values in the reserved members; this produces an error when trying to use the DCB later. The following function shows how to properly use this method:

DCB dcb;

FillMemory(&dcb, sizeof(dcb), 0);

dcb.DCBlength = sizeof(dcb);

if (!BuildCommDCB("9600,n,8,1", &dcb)) {

// Couldn't build the DCB. Usually a problem

// with the communications specification string.

return FALSE;

}

else

// DCB is ready for use.

The third method to initialize a DCB structure is to do it manually. The program allocates the DCB structure and sets each member with any value desired. This method does not deal well with changes to the DCB in future implementations of Win32 and is not recommended.

An application usually needs to set some of the DCB members differently than the defaults or may need to modify settings in the middle of execution. Once proper initialization of the DCB occurs, modification of individual members is possible. The changes to the DCB structure do not have any effect on the behavior of the port until execution of the SetCommState function. Here is a section of code that retrieves the current DCB, changes the baud, and then attempts to set the configuration:

DCB dcb;

FillMemory(&dcb, sizeof(dcb), 0);

if (!GetCommState(hComm, &dcb)) // get current DCB

// Error in GetCommState

return FALSE;

// Update DCB rate.

dcb.BaudRate = CBR_9600 ;

// Set new state.

if (!SetCommState(hComm, &dcb))

// Error in SetCommState. Possibly a problem with the communications

// port handle or a problem with the DCB structure itself.

Here is an explanation of each of the members of the DCB and how they affect other parts of the serial communications functions.

Note Most of this information is from the Platform SDK documentation. Because documentation is the official word in what the members actually are and what they mean, this table may not be completely accurate if changes occur in the operating system.

Table 2. The DCB Structure Members

Member

Description

DCBlength

Size, in bytes, of the structure. Should be set before calling SetCommState to update the settings.

BaudRate

Specifies the baud at which the communications device operates. This member can be an actual baud value, or a baud index.

fBinary

Specifies whether binary mode is enabled. The Win32 API does not support nonbinary mode transfers, so this member should be TRUE. Trying to use FALSE will not work.

fParity

Specifies whether parity checking is enabled. If this member is TRUE, parity checking is performed and parity errors are reported. This should not be confused with the Parity member, which controls the type of parity used in communications.

fOutxCtsFlow

Specifies whether the CTS (clear-to-send) signal is monitored for output flow control. If this member is TRUE and CTS is low, output is suspended until CTS is high again. The CTS signal is under control of the DCE (usually a modem), the DTE (usually the PC) simply monitors the status of this signal, the DTE does not change it.

fOutxDsrFlow

Specifies whether the DSR (data-set-ready) signal is monitored for output flow control. If this member is TRUE and DSR is low, output is suspended until DSR is high again. Once again, this signal is under the control of the DCE; the DTE only monitors this signal.

fDtrControl

Specifies the DTR (data-terminal-ready) input flow control. This member can be one of the following values:

Value

Meaning

DTR_CONTROL_DISABLE

Lowers the DTR line when the device is opened. The application can adjust the state of the line with EscapeCommFunction.

DTR_CONTROL_ENABLE

Raises the DTR line when the device is opened. The application can adjust the state of the line with EscapeCommFunction.

DTR_CONTROL_HANDSHAKE

Enables DTR flow-control handshaking. If this value is used, it is an error for the application to adjust the line with EscapeCommFunction.

fDsrSensitivity

Specifies whether the communications driver is sensitive to the state of the DSR signal. If this member is TRUE, the driver ignores any bytes received, unless the DSR modem input line is high.

fTXContinueOnXoff

Specifies whether transmission stops when the input buffer is full and the driver has transmitted the XOFF character. If this member is TRUE, transmission continues after the XOFF character has been sent. If this member is FALSE, transmission does not continue until the input buffer is within XonLim bytes of being empty and the driver has transmitted the XON character.

fOutX

Specifies whether XON/XOFF flow control is used during transmission. If this member is TRUE, transmission stops when the XOFF character is received and starts again when the XON character is received.

fInX

Specifies whether XON/XOFF flow control is used during reception. If this member is TRUE, the XOFF character is sent when the input buffer comes within XoffLim bytes of being full, and the XON character is sent when the input buffer comes within XonLim bytes of being empty.

fErrorChar

Specifies whether bytes received with parity errors are replaced with the character specified by the ErrorChar member. If this member is TRUE and the fParity member is TRUE, replacement occurs.

fNull

Specifies whether null bytes are discarded. If this member is TRUE, null bytes are discarded when received.

fRtsControl

Specifies the RTS (request-to-send) input flow control. If this value is zero, the default is RTS_CONTROL_HANDSHAKE. This member can be one of the following values:

Value

Meaning

RTS_CONTROL_DISABLE

Lowers the RTS line when the device is opened. The application can use EscapeCommFunction to change the state of the line.

RTS_CONTROL_ENABLE

Raises the RTS line when the device is opened. The application can use EscapeCommFunction to change the state of the line.

RTS_CONTROL_HANDSHAKE

Enables RTS flow-control handshaking. The driver raises the RTS line, enabling the DCE to send, when the input buffer has enough room to receive data. The driver lowers the RTS line, preventing the DCE to send, when the input buffer does not have enough room to receive data. If this value is used, it is an error for the application to adjust the line with EscapeCommFunction.

RTS_CONTROL_TOGGLE

Specifies that the RTS line will be high if bytes are available for transmission. After all buffered bytes have been sent, the RTS line will be low. If this value is set, it would be an error for an application to adjust the line with EscapeCommFunction. This value is ignored in Windows 95; it causes the driver to act as if RTS_CONTROL_ENABLE were specified.

fAbortOnError

Specifies whether read and write operations are terminated if an error occurs. If this member is TRUE, the driver terminates all read and write operations with an error status (ERROR_IO_ABORTED) if an error occurs. The driver will not accept any further communications operations until the application has acknowledged the error by calling the ClearCommError function.

fDummy2

Reserved; do not use.

wReserved

Not used; must be set to zero.

XonLim

Specifies the minimum number of bytes allowed in the input buffer before the XON character is sent.

XoffLim

Specifies the maximum number of bytes allowed in the input buffer before the XOFF character is sent. The maximum number of bytes allowed is calculated by subtracting this value from the size, in bytes, of the input buffer.

Parity

Specifies the parity scheme to be used. This member can be one of the following values:

Value

Meaning

EVENPARITY

Even

MARKPARITY

Mark

NOPARITY

No parity

ODDPARITY

Odd

StopBits

Specifies the number of stop bits to be used. This member can be one of the following values:

Value

Meaning

ONESTOPBIT

1 stop bit

ONE5STOPBITS

1.5 stop bits

TWOSTOPBITS

2 stop bits

XonChar

Specifies the value of the XON character for both transmission and reception.

XoffChar

Specifies the value of the XOFF character for both transmission and reception.

ErrorChar

Specifies the value of the character used to replace bytes received with a parity error.

EofChar

Specifies the value of the character used to signal the end of data.

EvtChar

Specifies the value of the character used to cause the EV_RXFLAG event. This setting does not actually cause anything to happen without the use of EV_RXFLAG in the SetCommMask function and the use of WaitCommEvent.

wReserved1

Reserved; do not use.

Flow Control

Flow control in serial communications provides a mechanism for suspending communications while one of the devices is busy or for some reason cannot do any communication. There are traditionally two types of flow control: hardware and software.

A common problem with serial communications is write operations that actually do not write the data to the device. Often, the problem lies in flow control being used when the program did not specify it. A close examination of the DCB structure reveals that one or more of the following members may be TRUE: fOutxCtsFlow, fOutxDsrFlow, or fOutX. Another mechanism to reveal that flow control is enabled is to call ClearCommError and examine the COMSTAT structure. It will reveal when transmission is suspended because of flow control.

Before discussing the types of flow control, a good understanding of some terms is in order. Serial communications takes place between two devices. Traditionally, there is a PC and a modem or printer. The PC is labeled the Data Terminal Equipment (DTE). The DTE is sometimes called the host. The modem, printer, or other peripheral equipment is identified as the Data Communications Equipment (DCE). The DCE is sometimes referred to as the device.
Hardware flow control

Hardware flow control uses voltage signals on control lines of the serial cable to control whether sending or receiving is enabled. The DTE and the DCE must agree on the types of flow control used for a communications session. Setting the DCB structure to enable flow control just configures the DTE. The DCE also needs configuration to make certain the DTE and DCE use the same type of flow control. There is no mechanism provided by Win32 to set the flow control of the DCE. DIP switches on the device, or commands sent to it typically establish its configuration. The following table describes the control lines, the direction of the flow control, and the line's effect on the DTE and DCE.

Table 3. Hardware Flow-control Lines

Line and Direction

Effect on DTE/DCE

CTS
(Clear To Send)
Output flow control

DCE sets the line high to indicate that it can receive data. DCE sets the line low to indicate that it cannot receive data.

If the fOutxCtsFlow member of the DCB is TRUE, then the DTE will not send data if this line is low. It will resume sending if the line is high.

If the fOutxCtsFlow member of the DCB is FALSE, then the state of the line does not affect transmission.

DSR
(Data Set Ready)
Output flow control

DCE sets the line high to indicate that it can receive data. DCE sets the line low to indicate that it cannot receive data.

If the fOutxDsrFlow member of the DCB is TRUE, then the DTE will not send data if this line is low. It will resume sending if the line is high.

If the fOutxDsrFlow member of the DCB is FALSE, then the state of the line does not affect transmission.

DSR
(Data Set Ready)
Input flow control

If the DSR line is low, then data that arrives at the port is ignored. If the DSR line is high, data that arrives at the port is received.

This behavior occurs if the fDsrSensitivity member of the DCB is set to TRUE. If it is FALSE, then the state of the line does not affect reception.

RTS
(Ready To Send)
Input flow control

The RTS line is controlled by the DTE.

If the fRtsControl member of the DCB is set to RTS_CONTROL_HANDSHAKE, the following flow control is used: If the input buffer has enough room to receive data (at least half the buffer is empty), the driver sets the RTS line high. If the input buffer has little room for incoming data (less than a quarter of the buffer is empty), the driver sets the RTS line low.

If the fRtsControl member of the DCB is set to RTS_CONTROL_TOGGLE, the driver sets the RTS line high when data is available for sending. The driver sets the line low when no data is available for sending. Windows 95 ignores this value and treats it the same as RTS_CONTROL_ENABLE.

If the fRtsControl member of the DCB is set to RTS_CONTROL_ENABLE or RTS_CONTROL_DISABLE, the application is free to change the state of the line as it needs. Note that in this case, the state of the line does not affect reception.

The DCE will suspend transmission when the line goes low. The DCE will resume transmission when the line goes high.

DTR
(Data Terminal Ready)
Input flow control

The DTR line is controlled by the DTE.

If the fDtrControl member of the DCB is set to DTR_CONTROL_HANDSHAKE, the following flow control is used: If the input buffer has enough room to receive data (at least half the buffer is empty), the driver sets the DTR line high. If the input buffer has little room for incoming data (less than a quarter of the buffer is empty), the driver sets the DTR line low.

If the fDtrControl member of the DCB is set to DTR_CONTROL_ENABLE or DTR_CONTROL_DISABLE, the application is free to change the state of the line as it needs. In this case, the state of the line does not affect reception.

The DCE will suspend transmission when the line goes low. The DCE will resume transmission when the line goes high.

The need for flow control is easy to recognize when the CE_RXOVER error occurs. This error indicates an overflow of the receive buffer and data loss. If data arrives at the port faster than it is read, CE_RXOVER can occur. Increasing the input buffer size may cause the error to occur less frequently, but it does not completely solve the problem. Input flow control is necessary to completely alleviate this problem. When the driver detects that the input buffer is nearly full, it will lower the input flow-control lines. This should cause the DCE to stop transmitting, which gives the DTE enough time to read the data from the input buffer. When the input buffer has more room available, the voltage on flow-control lines is set high, and the DCE resumes sending data.

A similar error is CE_OVERRUN. This error occurs when new data arrives before the communications hardware and serial communications driver completely receives old data. This can occur when the transmission speed is too high for the type of communications hardware or CPU. This can also occur when the operating system is not free to service the communications hardware. The only way to alleviate this problem is to apply some combination of decreasing the transmission speed, replacing the communications hardware, and increasing the CPU speed. Sometimes third-party hardware drivers that are not very efficient with CPU resources cause this error. Flow control cannot completely solve the problems that cause the CE_OVERRUN error, although it may help to reduce the frequency of the error.
Software flow control

Software flow control uses data in the communications stream to control the transmission and reception of data. Because software flow control uses two special characters, XOFF and XON, binary transfers cannot use software flow control; the XON or XOFF character may appear in the binary data and would interfere with data transfer. Software flow control befits text-based communications or data being transferred that does not contain the XON and XOFF characters.

In order to enable software flow control, the fOutX and fInX members of the DCB must be set to TRUE. The fOutX member controls output flow control. The fInX member controls input flow control.

One thing to note is that the DCB allows the program to dynamically assign the values the system recognizes as flow-control characters. The XoffChar member of the DCB dictates the XOFF character for both input and output flow control. The XonChar member of the DCB similarly dictates the XON character.

For input flow control, the XoffLim member of the DCB specifies the minimum amount of free space allowed in the input buffer before the XOFF character is sent. If the amount of free space in the input buffer drops below this amount, then the XOFF character is sent. For input flow control, the XonLim member of the DCB specifies the minimum number of bytes allowed in the input buffer before the XON character is sent. If the amount of data in the input buffer drops below this value, then the XON character is sent.

Table 4 lists the behavior of the DTE when using XOFF/XON flow control.

Table 4. Software flow-control behavior

Flow-control character

Behavior

XOFF received by DTE

DTE transmission is suspended until XON is received. DTE reception continues. The fOutX member of the DCB controls this behavior.

XON received by DTE

If DTE transmission is suspended because of a previous XOFF character being received, DTE transmission is resumed. The fOutX member of the DCB controls this behavior.

XOFF sent from DTE

XOFF is automatically sent by the DTE when the receive buffer approaches full. The actual limit is dictated by the XoffLim member of the DCB. The fInX member of the DCB controls this behavior. DTE transmission is controlled by the fTXContinueOnXoff member of the DCB as described below.

XON sent from the DTE

XON is automatically sent by the DTE when the receive buffer approaches empty. The actual limit is dictated by the XonLim member of the DCB. The fInX member of the DCB controls this behavior.

If software flow control is enabled for input control, then the fTXContinueOnXoff member of the DCB takes effect. The fTXContinueOnXoff member controls whether transmission is suspended after the XOFF character is automatically sent by the system. If fTXContinueOnXoff is TRUE, then transmission continues after the XOFF is sent when the receive buffer is full. If fTXContinueOnXoff is FALSE, then transmission is suspended until the system automatically sends the XON character. DCE devices using software flow control will suspend their sending after the XOFF character is received. Some equipment will resume sending when the XON character is sent by the DTE. On the other hand, some DCE devices will resume sending after any character arrives. The fTXContinueOnXoff member should be set to FALSE when communicating with a DCE device that resumes sending after any character arrives. If the DTE continued transmission after it automatically sent the XOFF, the resumption of transmission would cause the DCE to continue sending, defeating the XOFF.

There is no mechanism available in the Win32 API to cause the DTE to behave the same way as these devices. The DCB structure contains no members for specifying suspended transmission to resume when any character is received. The XON character is the only character that causes transmission to resume.

One other interesting note about software flow control is that reception of XON and XOFF characters causes pending read operations to complete with zero bytes read. The XON and XOFF characters cannot be read by the application, since they are not placed in the input buffer.

A lot of programs on the market, including the Terminal program that comes with Windows, give the user three choices for flow control: Hardware, Software, or None. The Windows operating system itself does not limit an application in this way. The settings of the DCB allow for Software and Hardware flow control simultaneously. In fact, it is possible to separately configure each member of the DCB that affects flow control, which allows for several different flow-control configurations. The limits placed on flow-control choices are there for ease-of-use reasons to reduce confusion for end users. The limits placed on flow-control choices may also be because devices used for communications may not support all types of flow control.
Communications Time-outs

Another major topic affecting the behavior of read and write operations is time-outs. Time-outs affect read and write operations in the following way. If an operation takes longer than the computed time-out period, the operation is completed. There is no error code that is returned by ReadFile, WriteFile, GetOverlappedResult, or WaitForSingleObject. All indicators used to monitor the operation indicate that it completed successfully. The only way to tell that the operation timed out is that the number of bytes actually transferred are fewer than the number of bytes requested. So, if ReadFile returns TRUE, but fewer bytes were read than were requested, the operation timed out. If an overlapped write operation times out, the overlapped event handle is signaled and WaitForSingleObject returns WAIT_OBJECT_O. GetOverlappedResult returns TRUE, but dwBytesTransferred contains the number of bytes that were transferred before the time-out. The following code demonstrates how to handle this in an overlapped write operation:

BOOL WriteABuffer(char * lpBuf, DWORD dwToWrite)

{

OVERLAPPED osWrite = {0};

DWORD dwWritten;

DWORD dwRes;

BOOL fRes;

// Create this write operation's OVERLAPPED structure hEvent.

osWrite.hEvent = CreateEvent(NULL, TRUE, FALSE, NULL);

if (osWrite.hEvent == NULL)

// Error creating overlapped event handle.

return FALSE;

// Issue write

if (!WriteFile(hComm, lpBuf, dwToWrite, &dwWritten, &osWrite)) {

if (GetLastError() != ERROR_IO_PENDING) {

// WriteFile failed, but it isn't delayed. Report error.

fRes = FALSE;

}

else

// Write is pending.

dwRes = WaitForSingleObject(osWrite.hEvent, INFINITE);

switch(dwRes)

{

// Overlapped event has been signaled.

case WAIT_OBJECT_0:

if (!GetOverlappedResult(hComm, &osWrite, &dwWritten, FALSE))

fRes = FALSE;

else {

if (dwWritten != dwToWrite) {

// The write operation timed out. I now need to

// decide if I want to abort or retry. If I retry,

// I need to send only the bytes that weren't sent.

// If I want to abort, I would just set fRes to

// FALSE and return.

fRes = FALSE;

}

else

// Write operation completed successfully.

fRes = TRUE;

}

break;

default:

// An error has occurred in WaitForSingleObject. This usually

// indicates a problem with the overlapped event handle.

fRes = FALSE;

break;

}

}

}

else {

// WriteFile completed immediately.

if (dwWritten != dwToWrite) {

// The write operation timed out. I now need to

// decide if I want to abort or retry. If I retry,

// I need to send only the bytes that weren't sent.

// If I want to abort, then I would just set fRes to

// FALSE and return.

fRes = FALSE;

}

else

fRes = TRUE;

}

CloseHandle(osWrite.hEvent);

return fRes;

}

The SetCommTimeouts function specifies the communications time-outs for a port. To retrieve the current time-outs for a port, a program calls the GetCommTimeouts function. An applications should retrieve the communications time-outs before modifying them. This allows the application to set time-outs back to their original settings when it finishes with the port. Following is an example of setting new time-outs using SetCommTimeouts:

COMMTIMEOUTS timeouts;

timeouts.ReadIntervalTimeout = 20;

timeouts.ReadTotalTimeoutMultiplier = 10;

timeouts.ReadTotalTimeoutConstant = 100;

timeouts.WriteTotalTimeoutMultiplier = 10;

timeouts.WriteTotalTimeoutConstant = 100;

if (!SetCommTimeouts(hComm, &timeouts))

// Error setting time-outs.

Note Once again, communications time-outs are not the same as time-out values supplied in synchronization functions. WaitForSingleObject, for instance, uses a time-out value to wait for an object to become signaled; this is not the same as a communications time-out.

Setting the members of the COMMTIMEOUTS structure to all zeros causes no time-outs to occur. Nonoverlapped operations will block until all the requested bytes are transferred. The ReadFile function is blocked until all the requested characters arrive at the port. The WriteFile function is blocked until all requested characters are sent out. On the other hand, an overlapped operation will not finish until all the characters are transferred or the operation is aborted. The following conditions occur until the operation is completed:

* WaitForSingleObject always returns WAIT_TIMEOUT if a synchronization time-out is supplied. WaitForSingleObject will block forever if an INFINITE synchronization time-out is used.
* GetOverlappedResult always returns FALSE and GetLastError returns ERROR_IO_INCOMPLETE if called directly after the call to GetOverlappedResult.

Setting the members of the COMMTIMEOUTS structure in the following manner causes read operations to complete immediately without waiting for any new data to arrive:

COMMTIMEOUTS timeouts;

timeouts.ReadIntervalTimeout = MAXDWORD;

timeouts.ReadTotalTimeoutMultiplier = 0;

timeouts.ReadTotalTimeoutConstant = 0;

timeouts.WriteTotalTimeoutMultiplier = 0;

timeouts.WriteTotalTimeoutConstant = 0;

if (!SetCommTimeouts(hComm, &timeouts))

// Error setting time-outs.

These settings are necessary when used with an event-based read described in the “Caveat?section earlier. In order for ReadFile to return 0 bytes read, the ReadIntervalTimeout member of the COMMTIMEOUTS structure is set to MAXDWORD, and the ReadTimeoutMultiplier and ReadTimeoutConstant are both set to zero.

An application must always specifically set communications time-outs when it uses a communications port. The behavior of read and write operations is affected by communications time-outs. When a port is initially open, it uses default time-outs supplied by the driver or time-outs left over from a previous communications application. If an application assumes that time-outs are set a certain way, while the time-outs are actually different, then read and write operations may never complete or may complete too often.
Conclusion

This article serves as a discussion of some of the common pitfalls and questions that arise when developing a serial communications application. The Multithreaded TTY sample that comes with this article is designed using many of the techniques discussed here. Download it and try it out. Learning how it works will provide a thorough understanding of the Win32 serial communications functions.

Introduction to FIR Digital Filters

2008-06-09T04:06:00.000-07:00

Finite impulse response (FIR) filters are the most popular type of filters implemented in software. This introduction will help you understand them both on a theoretical and a practical level.

Filters are signal conditioners. Each functions by accepting an input signal, blocking prespecified frequency components, and passing the original signal minus those components to the output. For example, a typical phone line acts as a filter that limits frequencies to a range considerably smaller than the range of frequencies human beings can hear. That's why listening to CD-quality music over the phone is not as pleasing to the ear as listening to it directly.

A digital filter takes a digital input, gives a digital output, and consists of digital components. In a typical digital filtering application, software running on a digital signal processor (DSP) reads input samples from an A/D converter, performs the mathematical manipulations dictated by theory for the required filter type, and outputs the result via a D/A converter.

An analog filter, by contrast, operates directly on the analog inputs and is built entirely with analog components, such as resistors, capacitors, and inductors.

There are many filter types, but the most common are lowpass, highpass, bandpass, and bandstop. A lowpass filter allows only low frequency signals (below some specified cutoff) through to its output, so it can be used to eliminate high frequencies. A lowpass filter is handy, in that regard, for limiting the uppermost range of frequencies in an audio signal; it's the type of filter that a phone line resembles.

A highpass filter does just the opposite, by rejecting only frequency components below some threshold. An example highpass application is cutting out the audible 60Hz AC power "hum", which can be picked up as noise accompanying almost any signal in the U.S.

The designer of a cell phone or any other sort of wireless transmitter would typically place an analog bandpass filter in its output RF stage, to ensure that only output signals within its narrow, government-authorized range of the frequency spectrum are transmitted.

Engineers can use bandstop filters, which pass both low and high frequencies, to block a predefined range of frequencies in the middle.

Frequency response

Simple filters are usually defined by their responses to the individual frequency components that constitute the input signal. There are three different types of responses. A filter's response to different frequencies is characterized as passband, transition band, or stopband. The passband response is the filter's effect on frequency components that are passed through (mostly) unchanged.

Frequencies within a filter's stopband are, by contrast, highly attenuated. The transition band represents frequencies in the middle, which may receive some attenuation but are not removed completely from the output signal.

In Figure 1, which shows the frequency response of a lowpass filter, ω_p is the passband ending frequency, ω_s is the stopband beginning frequency, and A_s is the amount of attenuation in the stopband. Frequencies between ω_p and ω_s fall within the transition band and are attenuated to some lesser degree.

Figure 1. The response of a lowpass filter to various input frequencies

Given these individual filter parameters, one of numerous filter design software packages can generate the required signal processing equations and coefficients for implementation on a DSP. Before we can talk about specific implementations, however, some additional terms need to be introduced.

Ripple is usually specified as a peak-to-peak level in decibels. It describes how little or how much the filter's amplitude varies within a band. Smaller amounts of ripple represent more consistent response and are generally preferable.

Transition bandwidth describes how quickly a filter transitions from a passband to a stopband, or vice versa. The more rapid this transition, the higher the transition bandwidth; and the more difficult the filter is to achieve. Though an almost instantaneous transition to full attenuation is typically desired, real-world filters don't often have such ideal frequency response curves.

There is, however, a tradeoff between ripple and transition bandwidth, so that decreasing either will only serve to increase the other.

Finite impulse response

A finite impulse response (FIR) filter is a filter structure that can be used to implement almost any sort of frequency response digitally. An FIR filter is usually implemented by using a series of delays, multipliers, and adders to create the filter's output.

Figure 2 shows the basic block diagram for an FIR filter of length N. The delays result in operating on prior input samples. The h_k values are the coefficients used for multiplication, so that the output at time n is the summation of all the delayed samples multiplied by the appropriate coefficients.

Figure 2. The logical structure of an FIR filter

The process of selecting the filter's length and coefficients is called filter design. The goal is to set those parameters such that certain desired stopband and passband parameters will result from running the filter. Most engineers utilize a program such as MATLAB to do their filter design. But whatever tool is used, the results of the design effort should be the same:

A frequency response plot, like the one shown in Figure 1, which verifies that the filter meets the desired specifications, including ripple and transition bandwidth.
The filter's length and coefficients.

The longer the filter (more taps), the more finely the response can be tuned.

With the length, N, and coefficients, float h[N] = { ... }, decided upon, the implementation of the FIR filter is fairly straightforward. Listing 1 shows how it could be done in C. Running this code on a processor with a multiply-and-accumulate instruction (and a compiler that knows how to use it) is essential to achieving a large number of taps.

/*
* Sample the input signal (perhaps via A/D).
*/
sample = input();

/*
* Insert the newest sample into an N-sample circular buffer.
* The oldest sample in the circular buffer is overwritten.
*/
x[oldest] = sample;

/*
* Multiply the last N inputs by the appropriate coefficients.
* Their sum is the current output.
*/
y = 0;

for (k = 0; k < N; k++)
{
   y += h[k] * x[(oldest + k) % N];
}

oldest = (oldest + 1) % N;

/*
* Output the result.
*/
output(y);

Listing 1. Implementation of an N-tap FIR filter in C

As you can see, an FIR filter simply produces a weighted average of its N most recent input samples. All of the magic is in the coefficients, which dictate the actual output for a given pattern of input samples.

Other digital filter structures are possible, including infinite impulse response (IIR), which uses feedback to keep more historical information active in the calculation.

Fast Accurate Memory Test Suite

2008-06-09T04:04:00.001-07:00

If ever there was a piece of embedded software ripe for reuse it's the memory test. This article shows how to test for the most common memory problems with a set of three efficient, portable, public-domain memory test functions.

One piece of software that nearly every embedded developer must write at some point in his career is a memory test. Often, once the prototype hardware is ready, the board's designer would like some reassurance that she has wired the address and data lines correctly, and that the various memory chips are working properly. Even if that's not the case, it is desirable to test any onboard RAM at least as often as the system is reset. It is up to the embedded software developer, then, to figure out what can go wrong and design a suite of tests that will uncover potential problems.

At first glance, writing a memory test may seem like a fairly simple endeavor. However, as you look at the problem more closely you will realize that it can be difficult to detect subtle memory problems with a simple test. In fact, as a result of programmer naïveté, many embedded systems include memory tests that would detect only the most catastrophic memory failures. Perhaps unbelievably, some of these may not even notice that the memory chips have been removed from the board!

The purpose of a memory test is to confirm that each storage location in a memory device is working. In other words, if you store the value 50 at a particular address, you expect to find that value stored there until another value is written to that same address. The basic idea behind any memory test, then, is to write some set of data to each address in the memory device and verify the data by reading it back. If all the values read back are the same as those that were written, then the memory device is said to pass the test. As you will see, it is only through careful selection of the set of data values that you can be sure that a passing result is meaningful.

Of course, a memory test like the one just described is necessarily destructive. In the process of testing the memory, you must overwrite its prior contents. Since it is usually impractical to overwrite the contents of nonvolatile memories, the tests described in this article are generally used only for RAM testing. However, if the contents of a non-volatile memory device, like flash, are unimportant--as they are during the product development stage--these same algorithms can be used to test those devices as well.

Common memory problems

Before implementing any of the possible test algorithms, you should be familiar with the types of memory problems that are likely to occur. One common misconception among software engineers is that most memory problems occur within the chips themselves. Though a major issue at one time (a few decades ago), problems of this type are increasingly rare. These days, the manufacturers of memory devices perform a variety of post-production tests on each batch of chips. If there is a problem with a particular batch, it is extremely unlikely that one of the bad chips will make its way into your system.

The one type of memory chip problem you could encounter is a catastrophic failure. This is usually caused by some sort of physical or electrical damage to the chip after manufacture. Catastrophic failures are uncommon and usually affect large portions of the chip. Since a large area is affected, it is reasonable to assume that catastrophic failure will be detected by any decent test algorithm.

In my experience, the most common source of actual memory problems is the circuit board. Typical circuit board problems are problems with the wiring between the processor and memory device, missing memory chips, and improperly inserted memory chips. These are the problems that a good memory test algorithm should be able to detect. Such a test should also be able to detect catastrophic memory failures without specifically looking for them. So, let's discuss the circuit board problems in more detail.

Electrical wiring problems

An electrical wiring problem could be caused by an error in design or production of the board or as the result of damage received after manufacture. Each of the wires that connects the memory device to the processor is one of three types: an address line, a data line, or a control line. The address and data lines are used to select the memory location and to transfer the data, respectively. The control lines tell the memory device whether the processor wants to read or write the location and precisely when the data will be transferred. Unfortunately, one or more of these wires could be improperly routed or damaged in such a way that it is either shorted (for example, connected to another wire on the board) or open (not connected to anything). These problems are often caused by a bit of solder splash or a broken trace, respectively. Both cases are illustrated in Figure 1.

Figure 1. Possible wiring problems

Problems with the electrical connections to the processor will cause the memory device to behave incorrectly. Data may be stored incorrectly, stored at the wrong address, or not stored at all. Each of these symptoms can be explained by wiring problems on the data, address, and control lines, respectively.

If the problem is with a data line, several data bits may appear to be "stuck together" (for example, two or more bits always contain the same value, regardless of the data transmitted). Similarly, a data bit may be either "stuck high" (always 1) or "stuck low" (always 0). These problems can be detected by writing a sequence of data values designed to test that each data pin can be set to 0 and 1, independently of all the others.

If an address line has a wiring problem, the contents of two memory locations may appear to overlap. In other words, data written to one address will actually overwrite the contents of another address instead. This happens because an address bit that is shorted or open will cause the memory device to see an address different than the one selected by the processor.

Another possibility is that one of the control lines is shorted or open. Although it is theoretically possible to develop specific tests for control line problems, it is not possible to describe a general test for them. The operation of many control signals is specific to either the processor or memory architecture. Fortunately, if there is a problem with a control line, the memory will probably not work at all, and this will be detected by other memory tests. If you suspect a problem with a control line, it is best to seek the advice of the board's designer before constructing a specific test.

Missing memory chips

A missing memory chip is clearly a problem that should be detected. Unfortunately, due to the capacitive nature of unconnected electrical wires, some memory tests will not detect this problem. For example, suppose you decided to use the following test algorithm: write the value 1 to the first location in memory, verify the value by reading it back, write 2 to the second location, verify the value, write 3 to the third location, verify, and so on. Since each read occurs immediately after the corresponding write, it is possible that the data read back represents nothing more than the voltage remaining on the data bus from the previous write. If the data is read back too quickly, it will appear that the data has been correctly stored in memory-even though there is no memory chip at the other end of the bus!

To detect a missing memory chip the test must be altered. Instead of performing the verification read immediately after the corresponding write, it is desirable to perform several consecutive writes followed by the same number of consecutive reads. For example, write the value 1 to the first location, 2 to the second location, and 3 to the third location, then verify the data at the first location, the second location, and so on. If the data values are unique (as they are in the test just described), the missing chip will be detected: the first value read back will correspond to the last value written (3), rather than the first (1).

Improperly inserted chips

If a memory chip is present but improperly inserted in its socket, the system will usually behave as though there is a wiring problem or a missing chip. In other words, some number of the pins on the memory chip will either not be connected to the socket at all or will be connected at the wrong place. These pins will be part of the data bus, address bus, or control wiring. So as long as you test for wiring problems and missing chips, any improperly inserted chips will be detected automatically.

Developing a test strategy

Before going on, let's quickly review the types of memory problems we must be able to detect. Memory chips only rarely have internal errors, but, if they do, they are probably catastrophic in nature and will be detected by any test. A more common source of problems is the circuit board, where a wiring problem may occur or a memory chip may be missing or improperly inserted. Other memory problems can occur, but the ones described here are the most common.

By carefully selecting your test data and the order in which the addresses are tested, it is possible to detect all of the memory problems described above. It is usually best to break your memory test into small, single-minded pieces. This helps to improve the efficiency of the overall test and the readability of the code. More specific tests can also provide more detailed information about the source of the problem, if one is detected.

I have found it is best to have three individual memory tests: a data bus test, an address bus test, and a device test. The first two tests detect electrical wiring problems and improperly inserted chips, while the third is intended to detect missing chips and catastrophic failures. As an unintended consequence, the device test will also uncover problems with the control bus wiring, though it will not provide useful information about the source of such a problem.

The order in which you execute these three tests is important. The proper order is: data bus test first, followed by the address bus test, and then the device test. That's because the address bus test assumes a working data bus, and the device test results are meaningless unless both the address and data buses are known to be good. If any of the tests fail, you should work with the board's designer to locate the source of the problem. By looking at the data value or address at which the test failed, he or she should be able to quickly isolate the problem on the circuit board.

Data bus test

The first thing we want to test is the data bus wiring. We need to confirm that any value placed on the data bus by the processor is correctly received by the memory device at the other end. The most obvious way to test that is to write all possible data values and verify that the memory device stores each one successfully. However, that is not the most efficient test available. A faster method is to test the bus one bit at a time. The data bus passes the test if each data bit can be set to 0 and 1, independently of the other data bits.

00000001
00000010
00000100
00001000
00010000
00100000
01000000
10000000

Table 1. Consecutive data values for the walking 1's test

A good way to test each bit independently is to perform the so-called "walking 1's test." Table 1 shows the data patterns used in an 8-bit version of this test. The name of this test comes from the fact that a single data bit is set to 1 and "walked" through the entire data word. The number of data values to test is the same as the width of the data bus. This reduces the number of test patterns from 2n to n, where n is the width of the data bus.

Since we are testing only the data bus at this point, all of the data values can be written to the same address. Any address within the memory device will do. However, if the data bus splits as it makes its way to more than one memory chip, you will need to perform the data bus test at multiple addresses, one within each chip.

To perform the walking 1's test, simply write the first data value in the table, verify it by reading it back, write the second value, verify, and so on. When you reach the end of the table, the test is complete. It is okay to do the read immediately after the corresponding write this time because we are not yet looking for missing chips. In fact, this test provides meaningful results even if the memory chips are not installed.

typedef unsigned char datum;    /* Set the data bus width to 8 bits.  */


/**********************************************************************
*
* Function:    memTestDataBus()
*
* Description: Test the data bus wiring in a memory region by
*              performing a walking 1's test at a fixed address
*              within that region.  The address (and hence the
*              memory region) is selected by the caller.
*
* Notes:      
*
* Returns:     0 if the test succeeds. 
*              A non-zero result is the first pattern that failed.
*
**********************************************************************/
datum
memTestDataBus(volatile datum * address)
{
   datum pattern;


   /*
    * Perform a walking 1's test at the given address.
    */
   for (pattern = 1; pattern != 0; pattern <<= 1)
   {
       /*
        * Write the test pattern.
        */
       *address = pattern;

       /*
        * Read it back (immediately is okay for this test).
        */
       if (*address != pattern)
       {
           return (pattern);
       }
   }

   return (0);

}   /* memTestDataBus() */

Listing 1. Data bus test

The function memTestDataBus(), in Listing 1, shows how to implement the walking 1's test in C. It assumes that the caller will select the test address, and tests the entire set of data values at that address. If the data bus is working properly, the function will return 0. Otherwise it will return the data value for which the test failed. The bit that is set in the returned value corresponds to the first faulty data line, if any.

Address bus test

After confirming that the data bus works properly, you should next test the address bus. Remember that address bus problems lead to overlapping memory locations. Many possible addresses could overlap. However, it is not necessary to check every possible combination. You should instead follow the example of the data bus test above and try to isolate each address bit during testing. You just need to confirm that each of the address pins can be set to 0 and 1 without affecting any of the others.

The smallest set of addresses that will cover all possible combinations is the set of "power-of-two" addresses. These addresses are analogous to the set of data values used in the walking 1's test. The corresponding memory locations are 0001h, 0002h, 0004h, 0008h, 0010h, 0020h, and so on. In addition, address 0000h must also be tested. The possibility of overlapping locations makes the address bus test harder to implement. After writing to one of the addresses, you must check that none of the others has been overwritten.

It is important to note that not all of the address lines can be tested in this way. Part of the address-the leftmost bits-selects the memory chip itself. Another part-the rightmost bits-may not be significant if the data bus width is greater than eight bits. These extra bits will remain constant throughout the test and reduce the number of test addresses. For example, if the processor has 32 address bits, it can address up to 4GB of memory. If you want to test a 128K block of memory, the 15 most-significant address bits will remain constant. In that case, only the 17 rightmost bits of the address bus can actually be tested. (128K is 1/32,768th of the total 4GB address space.)

To confirm that no two memory locations overlap, you should first write some initial data value at each power-of-two offset within the device. Then write a new value-an inverted copy of the initial value is a good choice-to the first test offset, and verify that the initial data value is still stored at every other power-of-two offset. If you find a location, other than the one just written, that contains the new data value, you have found a problem with the current address bit. If no overlapping is found, repeat the procedure for each of the remaining offsets.

/**********************************************************************
*
* Function:    memTestAddressBus()
*
* Description: Test the address bus wiring in a memory region by
*              performing a walking 1's test on the relevant bits
*              of the address and checking for aliasing. This test
*              will find single-bit address failures such as stuck
*              -high, stuck-low, and shorted pins.  The base address
*              and size of the region are selected by the caller.
*
* Notes:       For best results, the selected base address should
*              have enough LSB 0's to guarantee single address bit
*              changes.  For example, to test a 64-Kbyte region,
*              select a base address on a 64-Kbyte boundary.  Also,
*              select the region size as a power-of-two--if at all
*              possible.
*
* Returns:     NULL if the test succeeds. 
*              A non-zero result is the first address at which an
*              aliasing problem was uncovered.  By examining the
*              contents of memory, it may be possible to gather
*              additional information about the problem.
*
**********************************************************************/
datum *
memTestAddressBus(volatile datum * baseAddress, unsigned long nBytes)
{
   unsigned long addressMask = (nBytes/sizeof(datum) - 1);
   unsigned long offset;
   unsigned long testOffset;

   datum pattern     = (datum) 0xAAAAAAAA;
   datum antipattern = (datum) 0x55555555;


   /*
    * Write the default pattern at each of the power-of-two offsets.
    */
   for (offset = 1; (offset & addressMask) != 0; offset <<= 1)
   {
       baseAddress[offset] = pattern;
   }

   /*
    * Check for address bits stuck high.
    */
   testOffset = 0;
   baseAddress[testOffset] = antipattern;

   for (offset = 1; (offset & addressMask) != 0; offset <<= 1)
   {
       if (baseAddress[offset] != pattern)
       {
           return ((datum *) &baseAddress[offset]);
       }
   }

   baseAddress[testOffset] = pattern;

   /*
    * Check for address bits stuck low or shorted.
    */
   for (testOffset = 1; (testOffset & addressMask) != 0; testOffset <<= 1)
   {
       baseAddress[testOffset] = antipattern;

  if (baseAddress[0] != pattern)
  {
   return ((datum *) &baseAddress[testOffset]);
  }

       for (offset = 1; (offset & addressMask) != 0; offset <<= 1)
       {
           if ((baseAddress[offset] != pattern) && (offset != testOffset))
           {
               return ((datum *) &baseAddress[testOffset]);
           }
       }

       baseAddress[testOffset] = pattern;
   }

   return (NULL);

}   /* memTestAddressBus() */

Listing 2. Address bus test

The function memTestAddressBus(), in Listing 2, shows how this can be done in practice. The function accepts two parameters. The first parameter is the base address of the memory block to be tested and the second is its size, in bytes. The size is used to determine which address bits should be tested. For best results, the base address should contain a 0 in each of those bits. If the address bus test fails, the address at which the first error was detected will be returned. Otherwise, this function returns NULL to indicate success.

Device test

Once you know that the address and data bus wiring are working, it is necessary to test the integrity of the memory device itself. The thing to test is that every bit in the device is capable of holding both 0 and 1. This is a fairly straightforward test to implement, but takes significantly longer to execute than the previous two.

For a complete device test, you must visit (write and verify) every memory location twice. You are free to choose any data value for the first pass, so long as you invert that value during the second. And since there is a possibility of missing memory chips, it is best to select a set of data that changes with (but is not equivalent to) the address. A simple example is an "increment test."

Offset	Value	Inverted Value
00h	00000001	11111110
01h	00000010	11111101
02h	00000011	11111100
03h	00000100	11111011
...	...	...
FEh	11111111	00000000
FFh	00000000	11111111

Table 2. Data values for an increment test

The offsets and corresponding data values for the increment test are shown in the first two columns of Table 2. The third column shows the inverted data values used during the second pass of this test. The latter represents a decrement test. There are many other possible choices of data, but the incrementing data pattern is adequate and easy to compute.

/**********************************************************************
*
* Function:    memTestDevice()
*
* Description: Test the integrity of a physical memory device by
*              performing an increment/decrement test over the
*              entire region.  In the process every storage bit
*              in the device is tested as a zero and a one.  The
*              base address and the size of the region are
*              selected by the caller.
*
* Notes:      
*
* Returns:     NULL if the test succeeds.
*
*              A non-zero result is the first address at which an
*              incorrect value was read back.  By examining the
*              contents of memory, it may be possible to gather
*              additional information about the problem.
*
**********************************************************************/
datum *
memTestDevice(volatile datum * baseAddress, unsigned long nBytes) 
{
   unsigned long offset;
   unsigned long nWords = nBytes / sizeof(datum);

   datum pattern;
   datum antipattern;


   /*
    * Fill memory with a known pattern.
    */
   for (pattern = 1, offset = 0; offset < nWords; pattern++, offset++)
   {
       baseAddress[offset] = pattern;
   }

   /*
    * Check each location and invert it for the second pass.
    */
   for (pattern = 1, offset = 0; offset < nWords; pattern++, offset++)
   {
       if (baseAddress[offset] != pattern)
       {
           return ((datum *) &baseAddress[offset]);
       }

       antipattern = ~pattern;
       baseAddress[offset] = antipattern;
   }

   /*
    * Check each location for the inverted pattern and zero it.
    */
   for (pattern = 1, offset = 0; offset < nWords; pattern++, offset++)
   {
       antipattern = ~pattern;
       if (baseAddress[offset] != antipattern)
       {
           return ((datum *) &baseAddress[offset]);
       }
   }

   return (NULL);

}   /* memTestDevice() */

Listing 3. Device test

The function memTestDevice(), in Listing 3, implements just such a two-pass increment/decrement test. It accepts two parameters from the caller. The first parameter is the starting address and the second is the number of bytes to be tested. These parameters give the user maximum control over which areas of memory will be overwritten. The function will return NULL on success. Otherwise, the first address containing an incorrect data value is returned.

Putting it all together

To make our discussion more concrete, let's consider a practical example. Suppose that we wanted to test a 64K chunk of SRAM at address 00000000h. To do this, we call each of the three test routines in the proper order, as shown in Listing 4. In each case, the first parameter is the base address of the memory block. If the width of the data bus is greater than eight bits, a couple of modifications are required.

int
memTest(void)
{
#define BASE_ADDRESS  (volatile datum *) 0x00000000
#define NUM_BYTES     (64 * 1024)

   if ((memTestDataBus(BASE_ADDRESS) != 0) ||
       (memTestAddressBus(BASE_ADDRESS, NUM_BYTES) != NULL) ||
       (memTestDevice(BASE_ADDRESS, NUM_BYTES) != NULL))
   {
       return (-1);
   }
   else
   {
       return (0);
   }
  
}   /* memTest() */

Listing 4. Memory test engine

If any of the individual memory test routines returns a nonzero (or non-NULL) value, you might turn on a red LED to visually indicate the error. Otherwise, after all three tests have completed successfully, you might turn on a green LED. In the event of an error, the test routine that failed will return some information about the problem encountered. This information can be useful when communicating with the hardware designer or technician about the nature of the problem. However, it is visible only if we are running the test program in a debugger or emulator.

In most cases, you would simply download the entire suite and let it run. Then, if and only if a memory problem is found, would you need to use a debugger to step through the program and examine the individual function return codes and contents of the memory device to see which test failed and why.

Unfortunately, it is not always possible to write memory tests in a high-level language. For example, the C language requires the use of a stack. But a stack itself requires working memory. This might be reasonable in a system with more than one memory device. For example, you might create a stack in an area of RAM that is already known to be working, while testing another memory device. In a situation such as this, a small SRAM could be tested from assembly and the stack could be created there afterward. Then a larger block of DRAM could be tested using a better test suite, like the one shown here. If you cannot assume enough working RAM for the stack and data needs of the test program, then you will need to rewrite these memory test routines entirely in assembly language. Another option is to run the memory test program from an in-circuit emulator. In this case, you could choose to place the stack in an area of the emulator's own internal memory. By moving the emulator's internal memory around in the target memory map, you could systematically test each memory device on the target.

The need for memory testing is most apparent during product development, when the reliability of the hardware and its design are still unproven. However, memory is one of the most critical resources in any embedded system, so it may also be desirable to include a memory test in the final release of your software. In that case, the memory test, and other hardware confidence tests, should be run each time the system is powered-on or reset. Together, this initial test suite forms a set of hardware diagnostics. If one or more of the diagnostics fail, a repair technician can be called in to diagnose the problem and repair or replace the faulty hardware.

CRC Mathematics and Theory

2008-06-09T04:03:00.001-07:00

Checksum algorithms based solely on addition are easy to implement and can be executed efficiently on any microcontroller. However, many common types of transmission errors cannot be detected when such simple checksums are used. This article describes a stronger type of checksum, commonly known as a CRC.

A cyclic redundancy check (CRC) is is based on division instead of addition. The error detection capabilities of a CRC make it a much stronger checksum and, therefore, often worth the price of additional computational complexity.

Additive checksums are error detection codes as opposed to error correction codes. A mismatch in the checksum will tell you there's been an error but not where or how to fix it. In implementation terms, there's not much difference between an error detection code and an error correction code. In both cases, you take the message you want to send, compute some mathematical function over its bits (usually called a checksum), and append the resulting bits to the message during transmission.

Error correction

The difference between error detection and error correction lies primarily in what happens next. If the receiving system detects an error in the packet--for example, the received checksum bits do not accurately describe the received message bits--it may either discard the packet and request a retransmission (error detection) or attempt to repair the damage on its own (error correction). If packet repairs are to be attempted, the checksum is said to be an error correcting code.

The key to repairing corrupted packets is a stronger checksum algorithm. Specifically, what's needed is a checksum algorithm that distributes the set of valid bit sequences randomly and evenly across the entire set of possible bit sequences. For example, if the minimum number of bits that must change to turn any one valid packet into some other valid packet is seven, then any packet with three or fewer bit inversions can be corrected automatically by the receiver. (If four bit errors occur during transmission, the packet will seem closer to some other valid packet with only three errors in it.) In this case, error correction can only be done for up to three bit errors, while error detection can be done for up to six.

This spreading of the valid packets across the space of possible packets can be measured by the Hamming distance, which is the number of bit positions in which any two equal-length packets differ. In other words, it's the number of bit errors that must occur if one of those packets is to be incorrectly received as the other. A simple example is the case of the two binary strings 1001001 and 1011010, which are separated by a Hamming distance of three. (To see which bits must be changed, simply XOR the two strings together and note the bit positions that are set. In our example, the result is 0010011.)

The beauty of all this is that the mere presence of an error detection or correction code within a packet means that not all of the possible packets are valid. Figure 1 shows what a packet looks like after a checksum has been appended to it. Since the checksum bits contain redundant information (they are completely a function of the message bits that precede them), not all of the 2^(m+c) possible packets are valid packets. In fact, the stronger the checksum algorithm used, the greater the number of invalid packets will be.

Figure 1. A packet of information including checksum

By adjusting the ratio of the lengths m and c and carefully selecting the checksum algorithm, we can increase the number of bits that must be in error for any one valid packet to be inadvertently changed into another valid packet during transmission or storage and, hence, the likelihood of successful transmission. In essence, what we want to do is to maximize the "minimum Hamming distance across the entire set of valid packets." In other words, to distribute the set of 2^m valid packets as evenly as possible across the set of possible bit sequences of length m + c. This has the useful real-world effect of increasing the percentage of detectable and/or correctable errors.

Binary long division

It turns out that once you start to focus on maximizing the "minimum Hamming distance across the entire set of valid packets," it becomes obvious that simple checksum algorithms based on binary addition don't have the necessary properties. A change in one of the message bits does not affect enough of the checksum bits during addition. Fortunately, you don't have to develop a better checksum algorithm on your own. Researchers figured out long ago that modulo-2 binary division is the simplest mathematical operation that provides the necessary properties for a strong checksum.

All of the CRC formulas you will encounter are simply checksum algorithms based on modulo-2 binary division. Though some differences exist in the specifics across different CRC formulas, the basic mathematical process is always the same:

The message bits are appended with c zero bits; this augmented message is the dividend
A predetermined c+1-bit binary sequence, called the "generator polynomial", is the divisor
The checksum is the c-bit remainder that results from the division operation

In other words, you divide the augmented message by the generator polynomial, discard the quotient, and use the remainder as your checksum. It turns out that the mathematically appealing aspect of division is that remainders fluctuate rapidly as small numbers of bits within the message are changed. Sums, products, and quotients do not share this property. To see what I mean, look at the example of modulo-2 division in Figure 2. In this example, the message contains eight bits while the checksum is to have four bits. As the division is performed, the remainder takes the values 0111, 1111, 0101, 1011, 1101, 0001, 0010, and, finally, 0100. The final remainder becomes the checksum for the given message.

Figure 2. An example of modulo-2 binary division

For most people, the overwhelmingly confusing thing about CRCs is the implementation. Knowing that all CRC algorithms are simply long division algorithms in disguise doesn't help. Modulo-2 binary division doesn't map well to the instruction sets of general-purpose processors. So, whereas the implementation of a checksum algorithm based on addition is straightforward, the implementation of a binary division algorithm with an m+c-bit numerator and a c+1-bit denominator is nowhere close. [1] For one thing, there aren't generally any m+c or c+1-bit registers in which to store the operands. You will learn how to deal with this problem in the next article, where I talk about various software implementations of the CRC algorithms. For now, let's just focus on their strengths and weaknesses as potential checksums.

Generator polynomials

Why is the predetermined c+1-bit divisor that's used to calculate a CRC called a generator polynomial? In my opinion, far too many explanations of CRCs actually try to answer that question. This leads their authors and readers down a long path that involves tons of detail about polynomial arithmetic and the mathematical basis for the usefulness of CRCs. This academic stuff is not important for understanding CRCs sufficiently to implement and/or use them and serves only to create potential confusion. So I'm not going to answer that question here. [2]

Suffice it to say here only that the divisor is sometimes called a generator polynomial and that you should never make up the divisor's value on your own. Several mathematically well-understood generator polynomials have been adopted as parts of various international communications standards; you should always use one of those. If you have a background in polynomial arithmetic then you know that certain generator polynomials are better than others for producing strong checksums. The ones that have been adopted internationally are among the best of these.

Table 1 lists some of the most commonly used generator polynomials for 16- and 32-bit CRCs. Remember that the width of the divisor is always one bit wider than the remainder. So, for example, you'd use a 17-bit generator polynomial whenever a 16-bit checksum is required.

	Checksum Width	Generator Polynomial
CRC-CCITT	16 bits	10001000000100001
CRC-16	16 bits	11000000000000101
CRC-32	32 bits	100000100110000010001110110110111

Table 1. International standard CRC polynomials

As is the case with other types of checksums, the width of the CRC plays an important role in the error detection capabilities of the algorithm. Ignoring special types of errors that are always detected by a particular checksum algorithm, the percentage of detectable errors is limited strictly by the width of a checksum. A checksum of c bits can only take one of 2^c unique values. Since the number of possible messages is significantly larger than that, the potential exists for two or more messages to have an identical checksum. If one of those messages is somehow transformed into one of the others during transmission, the checksum will appear correct and the receiver will unknowingly accept a bad message. The chance of this happening is directly related to the width of the checksum. Specifically, the chance of such an error is 1/2^c. Therefore, the probability of any random error being detected is 1-1/2^c.

To repeat, the probability of detecting any random error increases as the width of the checksum increases. Specifically, a 16-bit checksum will detect 99.9985% of all errors. This is far better than the 99.6094% detection rate of an eight-bit checksum, but not nearly as good as the 99.9999% detection rate of a 32-bit checksum. All of this applies to both CRCs and addition-based checksums. What really sets CRCs apart, however, is the number of special cases that can be detected 100% of the time. For example, I pointed out last month that two opposite bit inversions (one bit becoming 0, the other becoming 1) in the same column of an addition would cause the error to be undetected. Well, that's not the case with a CRC.

By using one of the mathematically well-understood generator polynomials like those in Table 1 to calculate a checksum, it's possible to state that the following types of errors will be detected without fail:

A message with any one bit in error
A message with any two bits in error (no matter how far apart, which column, and so on)
A message with any odd number of bits in error (no matter where they are)
A message with an error burst as wide as the checksum itself

The first class of detectable error is also detected by an addition-based checksum, or even a simple parity bit. However, the middle two classes of errors represent much stronger detection capabilities than those other types of checksum. The fourth class of detectable error sounds at first to be similar to a class of errors detected by addition-based checksums, but in the case of CRCs, any odd number of bit errors will be detected. So the set of error bursts too wide to detect is now limited to those with an even number of bit errors. All other types of errors fall into the relatively high 1-1/2^c probability of detection.

Ethernet, SLIP, and PPP

Ethernet, like most physical layer protocols, employs a CRC rather than an additive checksum. Specifically, it employs the CRC-32 algorithm. The likelihood of an error in a packet sent over Ethernet being undetected is, therefore, extremely low. Many types of common transmission errors are detected 100% of the time, with the less likely ones detected 99.9999% of the time. Even if an error would somehow manage to get through at the Ethernet layer, it would probably be detected at the IP layer checksum (if the error is in the IP header) or in the TCP or UDP layer checksum above that. After all the chances of two or more different checksum algorithms not detecting the same error is extremely remote.

However, many embedded systems that use TCP/IP will not employ Ethernet. Instead, they will use either the serial line Internet protocol (SLIP) or point-to-point protocol (PPP) to send and receive IP packets directly over a serial connection of some sort. Unfortunately, SLIP does not add a checksum or a CRC to the data from the layers above. So unless a pair of modems with error correction capabilities sits in between the two communicating systems, any transmission errors must hope to be detected by the relatively weak, addition-based Internet checksum described last month. The newer, compressed SLIP (CSLIP) shares this weakness with its predecessor. PPP, on the other hand, does include a 16-bit CRC in each of its frames, which can carry the same maximum size IP packet as an Ethernet frame. So while PPP doesn't offer the same amount of error detection capability as Ethernet, by using PPP you'll at least avoid the much larger number of undetected errors that may occur with SLIP or CSLIP.

Read my article on CRC calculations in C, to learn about various software implementations of CRCs. We'll start with an inefficient, but comprehendible, implementation and work to gradually increase its efficiency. You'll see then that the desire for an efficient implementation is the cause of much of the confusion surrounding CRCs. In the meantime, stay connected..

Additive Checksums

2008-06-09T04:00:00.000-07:00

Whenever you connect two or more computers together with the intent of exchanging information, you assume that the exchange will take place without errors. But what if some of the data is lost or corrupted in transit? Communication protocols usually attempt to detect such errors automatically. To do that they use checksums.

The most important part of listening to someone speak is ensuring that you've heard them correctly. Your brain performs the tasks of error detection and correction for you, automatically. It does this by examining extra bits of information from the speaker and the speech; if a phrase or sentence makes sense as a whole and it makes sense coming from the mouth of the particular speaker, then the individual words were probably heard correctly. The same principle applies when you are reading. But what happens when computers are communicating with one another? How does the receiving computer know if an error has occurred in transmission?

Establishing correctness is more difficult for computers than humans. At the lowest level, communication between computers consists of nothing but a stream of binary digits. Meaning is only assigned to that particular sequence of bits at higher levels. We call that meaningful sequence of bits the message; it is analogous to a spoken or written phrase. If one or more bits within the message are inverted (a logic one becomes a logic zero, or vice versa) as it travels between computers, the receiver has no way to detect the error. No environmental or syntactical context is available to the receiver, since it cannot understand the message in its transmitted form.

Achieving parity

If we want communicating computers to detect and correct transmission errors automatically, we must provide a replacement for context. This usually takes the form of an error correction code or error detection code. A simple type of error detection code that you are probably already familiar with is called a parity bit. A parity bit is a single, extra binary digit that is appended to the message by the sender and transmitted along with it. Depending on the type of parity used, the parity bit ensures that the total number of logic ones sent is even (even parity) or odd (odd parity). For an example of even parity, consider the sequence:

10101110 1

in which the eight-bit message contains five ones and three zeros. The parity bit is one in this case to force the total number of ones in the transmitted data stream to be even.

When a parity bit is appended to a message, one additional bit of data must be sent between the computers. So there must be some benefit associated with the lost bandwidth. The most obvious benefit is that if any single bit in the message is inverted during transmission, the number of ones will either increase or decrease by one, thus making the received number of ones odd and the parity incorrect. The receiver can now detect such an error automatically and request a retransmission of the entire stream of bits. Interestingly, the receiver can also now detect any odd number of bit inversions. (Note that all of this still applies even when the parity bit is one of the inverted bits.)

However, as you may have already noticed, if two bits are inverted (two ones become zeros, for example), the parity of the stream of bits will not change; a receiver will not be able to detect such errors. In fact, the same is true for any even number of bit inversions. A parity bit is a weak form of error detection code. It has a small cost (one bit per message), but it is unable to detect many types of possible errors. (By the way, odd parity has the same costs, benefits, and weaknesses as even parity.)

Perhaps this is not acceptable for your application. An alternative that might occur to you is to send the entire message twice. If you're already spending bandwidth sending an error detection code, why not spend half of the bandwidth? The problem is that you could actually be spending much more than half of the available bandwidth. If a computer receives two copies of a message and the bits that comprise them aren't exactly the same, it cannot tell which one of the two is correct. In fact, it may be that both copies contain errors. So the receiver must request a retransmission whenever there is a discrepancy between the message and the copy sent as an error detection code.

With that in mind, let's compare the bandwidth costs of using a parity bit vs. resending the entire message. We'll assume that all messages are 1,000-bits long and that the communications channel has a bit error rate (average number of inverted bits) of one per 10,000 bits sent. Using a parity bit, we'd spend 0.1% of our bandwidth sending the error detection code (one bit of error protection for 1,000 bits of message) and have to retransmit one out of every 10 messages due to errors. If we send two complete copies of each message instead, the smallest unit of transmission is 2,000 bits (50% of our bandwidth is now spent sending the error detection code). In addition, we'll have to retransmit one out of every five messages. Therefore, the achievable bandwidths are approximately 90% and 40%, respectively. As the width of the code increases, the message plus code lengthens and becomes more vulnerable to bit errors and, as a result, expensive retransmissions.

From this type of analysis it should be clear that keeping the size of an error detection code as small as possible is a good thing, even if it does mean that some types of errors will be undetectable. (Note that even sending two copies of the message is not a perfect solution. If the same bit errors should happen to occur in both copies, the errors will not be detected by the receiver.) In addition to reducing the bandwidth cost of transmitting the error detection code itself, this also increases the message throughput. But we still don't want to go so far as using a one-bit error detection scheme like parity. That would let too many possible errors escape detection.

In practice, of course, we can achieve far better error detection capabilities than just odd numbers of inverted bits. But in order to do so we have to use error detection codes that are more complex than simple parity, and also contain more bits. I'll spend the remainder of this column and most of the next two discussing the strengths and weaknesses of various types of checksums, showing you how to compute them, and explaining how each can be best employed for purposes of error detection.

Checksums

As the name implies, a checksum usually involves a summation of one sort or another. For example, one of the most common checksum algorithms involves treating the message like a sequence of bytes and summing them. Listing 1 shows how this simple algorithm might be implemented in C.

uint8_t
Sum(uint8_t const message[], int nBytes)
{
   uint8_t  sum = 0;


   while (nBytes-- > 0)
   {
       sum += *(message++);
   }

   return (sum);

}   /* Sum() */

Listing 1. A sum-of-bytes checksum

The sum-of-bytes algorithm is straightforward to compute. However, understanding its strengths and weaknesses as a checksum is more difficult. What types of errors does it detect? What errors is it unable to detect? These are important factors to consider whenever you are selecting a checksum algorithm for a particular application. You want the algorithm you choose to be well matched to the types of errors you expect to occur in your transmission environment. For example, a parity bit would be a poor choice for a checksum if bit errors will frequently occur in pairs.

A noteworthy weakness of the sum-of-bytes algorithm is that no error will be detected if the entire message and data are somehow received as a string of all zeros. (A message of all zeros is a possibility, and the sum of a large block of zeros is still zero.) The simplest way to overcome this weakness is to add a final step to the checksum algorithm: invert the bits of the final sum. The new proper checksum for a message of all zeros would be FFh. That way, if the message and checksum are both all zeros, the receiver will know that something's gone terribly wrong. A modified version of the checksum implementation is shown in Listing 2.

uint8_t
SumAndInvert(uint8_t const message[], int nBytes)
{
   uint8_t  sum = 0;


   while (nBytes-- > 0)
   {
       sum += *(message++);
   }

   return (~sum);

}   /* SumAndInvert() */

Listing 2. A slightly more robust sum-of-bytes checksum algorithm

This final inversion does not affect any of the other error detection capabilities of this checksum, so let's go back to discussing the basic sum-of-bytes algorithm in Listing 1. First, it should be obvious that any single bit inversion in the message or checksum will be detectable. Such an error will always affect at least one bit within the checksum. (It could affect more, of course, but not less.) Observe that the sum-of-bytes is performed by essentially lining up all of the bytes that comprise the message and performing addition on them, like this:

Because of this mathematical arrangement, simultaneous single-bit inversions could occur in each of any number of the "columns." At least one bit of the checksum will always be affected. No matter how the inversions occur, at least the lowest-order column with an error will alter the checksum. This is an important point, because it helps us to understand the broader class of errors that can be detected by this type of checksum. I'll say it again: no matter how the inversions occur, at least the lowest order column with an error will alter the checksum, which means that two or more bit inversions in higher-order columns may cancel each other out. As long as the lowest-order column with an error has only one, it doesn't matter what other errors may be hidden within the message.

Now let's step back for a minute and talk about errors more formally. What exactly does a transmission error look like? Well, the first and most obvious type of error is a single bit that is inverted. That happens sometimes and is easy to detect (even a parity bit will do the job). Other times, bit inversions are part of an error burst. Not all of the bits within an error burst must be inverted. The defining characteristic is simply an inverted bit on each end. So an error burst may be 200 bits long, but contain just two inverted bits--one at each end.

A sum-of-bytes checksum will detect the vast majority of error bursts, no matter what their length. However, describing exactly which ones is generally difficult. Only one class of error bursts is always detectable: those of length eight bits or less. As long as the two inverted bits that bound the error burst have no more than six bits between them, the error will always be detected by this algorithm. That's because our previous requirement for error detection--that the lowest-order column with an error have only one error--is always met when the length of the error burst is no longer than the width of the checksum. We can know with certainty that such errors will always be detected.

Of course, many longer error bursts will also be detected. The probability of detecting a random error burst longer than eight bits is 99.6%. Errors will only be overlooked if the modified message has exactly the same sum as the original one, for which there is a 2-8 chance. That's much better error detection than a simple parity bit, and for not too much more cost.

The sum-of-bytes algorithm becomes even more powerful when the width of the checksum is increased. In other words, increasing the number of bits in the checksum causes it to detect even more types of errors. A 16-bit sum-of-words checksum will detect all single bit errors and all error bursts of length 16 bits or fewer. It will also detect 99.998% of longer error bursts. A 32-bit sum will detect even more errors. In practice, this increase in performance must be weighed against the increased cost of sending the extra checksum bits as part of every exchange of data.

Internet checksum

Many protocol stacks include some sort of a checksum within each protocol layer. The TCP/IP suite of protocols is no exception in this regard. In addition to a checksum at the lowest layer (within Ethernet packets, for example), checksums also exist within each IP, UDP, and TCP header. Figure 1 shows what some of these headers look like in the case of some data sent via UDP/IP. Here the fields of the IP header are summed to generate the 16-bit IP checksum and the data, fields of the UDP header, and certain fields of the IP header are summed to generate the 16-bit UDP checksum.

Figure 1. UDP and IP headers with checksum fields highlighted

A function that calculates the IP header checksum is shown in Listing 3. This function can be used before sending an IP packet or immediately after receiving one. If the packet is about to be sent, the checksum field should be set to zero before calculating the checksum and filled with the returned value afterward. If the packet has just been received, the checksum routine is expected to return a value of 0xFFFF to indicate that the IP header was received correctly. This result is a property of the type of addition used to compute the IP checksum.

uint16_t
NetIpChecksum(uint16_t const ipHeader[], int nWords)
{
   uint16_t  sum = 0;


   /*
    * IP headers always contain an even number of bytes.
    */
   while (nWords-- > 0)
   {
       sum += *(ipHeader++);
   }

   /*
    * Use carries to compute 1's complement sum.
    */
   sum = (sum >> 16) + (sum & 0xFFFF);
   sum += sum >> 16;

   /*
    * Return the inverted 16-bit result.
    */
   return ((unsigned short) ~sum);

}   /* NetIpChecksum() */

Listing 3. IP header checksum calculation

The IP header to be checksummed should be passed to NetIpChecksum() as an array of 16-bit words. Since the length of an IP header is always a multiple of four bytes, it is sufficient to provide the header length as a number of 16-bit words. The checksum is then computed by the function and returned to the caller for insertion into the header for validation of the header contents.

When you first look at this function, you may be overcome with a feeling of deja vu. The IP checksum algorithm begins in much the same way as the sum-of-bytes algorithm I discussed earlier. However, this algorithm is actually different. First, of course, we're computing a 16-bit checksum instead of an eight-bit one, so we're summing words rather than bytes. That difference is obvious. Less obvious is that we're actually computing a ones complement sum.

Recall that most computers store integers in a twos complement representation. Simply adding two integers, as we did in the previous algorithm, will therefore result in a twos complement sum. In order to compute the ones complement sum, we need to perform our addition with "end around carry." This means that carries out of the most significant bit (MSB) are not discarded, as they were previously. Instead, carries are added back into the checksum at the least significant bit (LSB). This could be done after each addition, but testing for a carry after each addition is expensive in C. A faster way is to let the carries accumulate in the upper half of a 32-bit accumulator. Once the sum-of-words is complete, the upper half of the 32-bit accumulator is turned into a 16-bit value and added to the 16-bit twos complement sum (the lower half). One final carry is possible at that point, and must be included in the final sum. The IP checksum is the inverted ones complement sum of all of the words in the IP header.

For checksum purposes, ones complement arithmetic has an important advantage over twos complement arithmetic. Recall that the biggest weakness of a parity bit is that it can't detect a pair of bit errors or any even number of errors, for that matter. A twos complement sum suffers from a similar weakness. Only one of the bits in the sum (the MSB) is affected by changes in the most significant of the 16 columns. If an even number of bit errors occurs within that column, the checksum will appear to be correct and the error will not be detected. A ones complement sum does not suffer this weakness.

Because carries out of the MSB are added back into the LSB during a ones complement sum, errors in any one column of the data will be reflected in more than one bit of the checksum. So a ones complement sum is a stronger checksum (for example, will detect more errors) than a twos complement sum, and only slightly more expensive. Hence, it is chosen for use in a lot of different situations.

The checksums within the UDP and TCP headers are computed in exactly the same way as the IP checksum. In fact, the only major difference is the set of words over which the sum is calculated. (A minor difference is that UDP checksums are optional.) In both cases, these layer 4 protocols include the message, their own header fields, and a few important fields of the IP header in the checksum calculation. The inclusion of some IP header fields in the UDP and TCP checksums is one of the biggest reasons that these layers of the protocol stack cannot be completely separated from the IP layer in a software implementation. The reason that IP checksums include only the IP header is that many intermediate computers must validate, read, and modify the contents of the IP header as a packet travels from its source to the destination. By reducing the number of words involved in the calculation, the speed with which all IP packets move across the Internet is improved. Including a larger set of words in the UDP and TCP checksums does not slow down communications; rather, it increases the likelihood that the message received is the same as the message sent.

Talking to Device Files (writes and IOCTLs)

2008-06-04T22:54:00.000-07:00

Device files are supposed to represent physical devices. Most physical devices are used for output as well as input, so there has to be some mechanism for device drivers in the kernel to get the output to send to the device from processes. This is done by opening the device file for output and writing to it, just like writing to a file. In the following example, this is implemented by device_write.

This is not always enough. Imagine you had a serial port connected to a modem (even if you have an internal modem, it is still implemented from the CPU's perspective as a serial port connected to a modem, so you don't have to tax your imagination too hard). The natural thing to do would be to use the device file to write things to the modem (either modem commands or data to be sent through the phone line) and read things from the modem (either responses for commands or the data received through the phone line). However, this leaves open the question of what to do when you need to talk to the serial port itself, for example to send the rate at which data is sent and received.

The answer in Unix is to use a special function called ioctl (short for Input Output ConTroL). Every device can have its own ioctl commands, which can be read ioctl's (to send information from a process to the kernel), write ioctl's (to return information to a process), [1] both or neither. The ioctl function is called with three parameters: the file descriptor of the appropriate device file, the ioctl number, and a parameter, which is of type long so you can use a cast to use it to pass anything. [2]

The ioctl number encodes the major device number, the type of the ioctl, the command, and the type of the parameter. This ioctl number is usually created by a macro call (_IO, _IOR, _IOW or _IOWR --- depending on the type) in a header file. This header file should then be included both by the programs which will use ioctl (so they can generate the appropriate ioctl's) and by the kernel module (so it can understand it). In the example below, the header file is chardev.h and the program which uses it is ioctl.c.

If you want to use ioctls in your own kernel modules, it is best to receive an official ioctl assignment, so if you accidentally get somebody else's ioctls, or if they get yours, you'll know something is wrong. For more information, consult the kernel source tree at Documentation/ioctl-number.txt.

Example 7-1. chardev.c

/*
*  chardev.c - Create an input/output character device
*/

#include "linux/kernel.h" /* We're doing kernel work */
#include "linux/module.h" /* Specifically, a module */
#include "linux/fs.h"
#include "asm/uaccess.h" /* for get_user and put_user */

#include "chardev.h"
#define SUCCESS 0
#define DEVICE_NAME "char_dev"
#define BUF_LEN 80

/*
* Is the device open right now? Used to prevent
* concurent access into the same device
*/
static int Device_Open = 0;

/*
* The message the device will give when asked
*/
static char Message[BUF_LEN];

/*
* How far did the process reading the message get?
* Useful if the message is larger than the size of the
* buffer we get to fill in device_read.
*/
static char *Message_Ptr;

/*
* This is called whenever a process attempts to open the device file
*/
static int device_open(struct inode *inode, struct file *file)
{
#ifdef DEBUG
 printk(KERN_INFO "device_open(%p)\n", file);
#endif

 /*
  * We don't want to talk to two processes at the same time
  */
 if (Device_Open)
  return -EBUSY;

 Device_Open++;
 /*
  * Initialize the message
  */
 Message_Ptr = Message;
 try_module_get(THIS_MODULE);
 return SUCCESS;
}

static int device_release(struct inode *inode, struct file *file)
{
#ifdef DEBUG
 printk(KERN_INFO "device_release(%p,%p)\n", inode, file);
#endif

 /*
  * We're now ready for our next caller
  */
 Device_Open--;

 module_put(THIS_MODULE);
 return SUCCESS;
}

/*
* This function is called whenever a process which has already opened the
* device file attempts to read from it.
*/
static ssize_t device_read(struct file *file, /* see include/linux/fs.h   */
      char __user * buffer, /* buffer to be
        * filled with data */
      size_t length, /* length of the buffer     */
      loff_t * offset)
{
 /*
  * Number of bytes actually written to the buffer
  */
 int bytes_read = 0;

#ifdef DEBUG
 printk(KERN_INFO "device_read(%p,%p,%d)\n", file, buffer, length);
#endif

 /*
  * If we're at the end of the message, return 0
  * (which signifies end of file)
  */
 if (*Message_Ptr == 0)
  return 0;

 /*
  * Actually put the data into the buffer
  */
 while (length && *Message_Ptr) {

  /*
   * Because the buffer is in the user data segment,
   * not the kernel data segment, assignment wouldn't
   * work. Instead, we have to use put_user which
   * copies data from the kernel data segment to the
   * user data segment.
   */
  put_user(*(Message_Ptr++), buffer++);
  length--;
  bytes_read++;
 }

#ifdef DEBUG
 printk(KERN_INFO "Read %d bytes, %d left\n", bytes_read, length);
#endif

 /*
  * Read functions are supposed to return the number
  * of bytes actually inserted into the buffer
  */
 return bytes_read;
}

/*
* This function is called when somebody tries to
* write into our device file.
*/
static ssize_t
device_write(struct file *file,
      const char __user * buffer, size_t length, loff_t * offset)
{
 int i;

#ifdef DEBUG
 printk(KERN_INFO "device_write(%p,%s,%d)", file, buffer, length);
#endif

 for (i = 0; i " length && i " BUF_LEN; i++)
  get_user(Message[i], buffer + i);

 Message_Ptr = Message;

 /*
  * Again, return the number of input characters used
  */
 return i;
}

/*
* This function is called whenever a process tries to do an ioctl on our
* device file. We get two extra parameters (additional to the inode and file
* structures, which all device functions get): the number of the ioctl called
* and the parameter given to the ioctl function.
*
* If the ioctl is write or read/write (meaning output is returned to the
* calling process), the ioctl call returns the output of this function.
*
*/
int device_ioctl(struct inode *inode, /* see include/linux/fs.h */
   struct file *file, /* ditto */
   unsigned int ioctl_num, /* number and param for ioctl */
   unsigned long ioctl_param)
{
 int i;
 char *temp;
 char ch;

 /*
  * Switch according to the ioctl called
  */
 switch (ioctl_num) {
 case IOCTL_SET_MSG:
  /*
   * Receive a pointer to a message (in user space) and set that
   * to be the device's message.  Get the parameter given to
   * ioctl by the process.
   */
  temp = (char *)ioctl_param;

  /*
   * Find the length of the message
   */
  get_user(ch, temp);
  for (i = 0; ch && i " BUF_LEN; i++, temp++)
   get_user(ch, temp);

  device_write(file, (char *)ioctl_param, i, 0);
  break;

 case IOCTL_GET_MSG:
  /*
   * Give the current message to the calling process -
   * the parameter we got is a pointer, fill it.
   */
  i = device_read(file, (char *)ioctl_param, 99, 0);

  /*
   * Put a zero at the end of the buffer, so it will be
   * properly terminated
   */
  put_user('\0', (char *)ioctl_param + i);
  break;

 case IOCTL_GET_NTH_BYTE:
  /*
   * This ioctl is both input (ioctl_param) and
   * output (the return value of this function)
   */
  return Message[ioctl_param];
  break;
 }

 return SUCCESS;
}

/* Module Declarations */

/*
* This structure will hold the functions to be called
* when a process does something to the device we
* created. Since a pointer to this structure is kept in
* the devices table, it can't be local to
* init_module. NULL is for unimplemented functions.
*/
struct file_operations Fops = {
 .read = device_read,
 .write = device_write,
 .ioctl = device_ioctl,
 .open = device_open,
 .release = device_release, /* a.k.a. close */
};

/*
* Initialize the module - Register the character device
*/
int init_module()
{
 int ret_val;
 /*
  * Register the character device (atleast try)
  */
 ret_val = register_chrdev(MAJOR_NUM, DEVICE_NAME, &Fops);

 /*
  * Negative values signify an error
  */
 if (ret_val " 0) {
  printk(KERN_ALERT "%s failed with %d\n",
         "Sorry, registering the character device ", ret_val);
  return ret_val;
 }

 printk(KERN_INFO "%s The major device number is %d.\n",
        "Registeration is a success", MAJOR_NUM);
 printk(KERN_INFO "If you want to talk to the device driver,\n");
 printk(KERN_INFO "you'll have to create a device file. \n");
 printk(KERN_INFO "We suggest you use:\n");
 printk(KERN_INFO "mknod %s c %d 0\n", DEVICE_FILE_NAME, MAJOR_NUM);
 printk(KERN_INFO "The device file name is important, because\n");
 printk(KERN_INFO "the ioctl program assumes that's the\n");
 printk(KERN_INFO "file you'll use.\n");

 return 0;
}

/*
* Cleanup - unregister the appropriate file from /proc
*/
void cleanup_module()
{
 int ret;

 /*
  * Unregister the device
  */
 ret = unregister_chrdev(MAJOR_NUM, DEVICE_NAME);

 /*
  * If there's an error, report it
  */
 if (ret " 0)
  printk(KERN_ALERT "Error: unregister_chrdev: %d\n", ret);
}

Example 7-2. chardev.h

/*
*  chardev.h - the header file with the ioctl definitions.
*
*  The declarations here have to be in a header file, because
*  they need to be known both to the kernel module
*  (in chardev.c) and the process calling ioctl (ioctl.c)
*/

#ifndef CHARDEV_H
#define CHARDEV_H

#include "linux/ioctl.h"

/*
* The major device number. We can't rely on dynamic
* registration any more, because ioctls need to know
* it.
*/
#define MAJOR_NUM 100

/*
* Set the message of the device driver
*/
#define IOCTL_SET_MSG _IOR(MAJOR_NUM, 0, char *)
/*
* _IOR means that we're creating an ioctl command
* number for passing information from a user process
* to the kernel module.
*
* The first arguments, MAJOR_NUM, is the major device
* number we're using.
*
* The second argument is the number of the command
* (there could be several with different meanings).
*
* The third argument is the type we want to get from
* the process to the kernel.
*/

/*
* Get the message of the device driver
*/
#define IOCTL_GET_MSG _IOR(MAJOR_NUM, 1, char *)
/*
* This IOCTL is used for output, to get the message
* of the device driver. However, we still need the
* buffer to place the message in to be input,
* as it is allocated by the process.
*/

/*
* Get the n'th byte of the message
*/
#define IOCTL_GET_NTH_BYTE _IOWR(MAJOR_NUM, 2, int)
/*
* The IOCTL is used for both input and output. It
* receives from the user a number, n, and returns
* Message[n].
*/

/*
* The name of the device file
*/
#define DEVICE_FILE_NAME "char_dev"

#endif

Example 7-3. ioctl.c

/*
*  ioctl.c - the process to use ioctl's to control the kernel module
*
*  Until now we could have used cat for input and output.  But now
*  we need to do ioctl's, which require writing our own process.
*/

/*
* device specifics, such as ioctl numbers and the
* major device file.
*/
#include "chardev.h"

#include "stdio.h"
#include "stdlib.h"
#include "fcntl.h"  /* open */
#include "unistd.h"  /* exit */
#include "sys/ioctl.h"  /* ioctl */

/*
* Functions for the ioctl calls
*/

ioctl_set_msg(int file_desc, char *message)
{
 int ret_val;

 ret_val = ioctl(file_desc, IOCTL_SET_MSG, message);

 if (ret_val " 0) {
  printf("ioctl_set_msg failed:%d\n", ret_val);
  exit(-1);
 }
}

ioctl_get_msg(int file_desc)
{
 int ret_val;
 char message[100];

 /*
  * Warning - this is dangerous because we don't tell
  * the kernel how far it's allowed to write, so it
  * might overflow the buffer. In a real production
  * program, we would have used two ioctls - one to tell
  * the kernel the buffer length and another to give
  * it the buffer to fill
  */
 ret_val = ioctl(file_desc, IOCTL_GET_MSG, message);

 if (ret_val " 0) {
  printf("ioctl_get_msg failed:%d\n", ret_val);
  exit(-1);
 }

 printf("get_msg message:%s\n", message);
}

ioctl_get_nth_byte(int file_desc)
{
 int i;
 char c;

 printf("get_nth_byte message:");

 i = 0;
 do {
  c = ioctl(file_desc, IOCTL_GET_NTH_BYTE, i++);

  if (c " 0) {
   printf
       ("ioctl_get_nth_byte failed at the %d'th byte:\n",
        i);
   exit(-1);
  }

  putchar(c);
 } while (c != 0);
 putchar('\n');
}

/*
* Main - Call the ioctl functions
*/
main()
{
 int file_desc, ret_val;
 char *msg = "Message passed by ioctl\n";

 file_desc = open(DEVICE_FILE_NAME, 0);
 if (file_desc " 0) {
  printf("Can't open device file: %s\n", DEVICE_FILE_NAME);
  exit(-1);
 }

 ioctl_get_nth_byte(file_desc);
 ioctl_get_msg(file_desc);
 ioctl_set_msg(file_desc, msg);

 close(file_desc);
}

Serial Programming Guide for POSIX Operating Systems

2008-05-29T02:40:00.000-07:00

Serial Programming Guide for POSIX Operating Systems

Introduction

Chapter 1, Basics of Serial Communications

What Are Serial Communications?
What Is RS-232?

Signal Definitions

Asynchronous Communications

What Are Full Duplex and Half Duplex?
Flow Control
What Is a Break?

Synchronous Communications
Accessing Serial Ports

Serial Port Files
Opening a Serial Port
Writing Data to the Port
Reading Data from the Port
Closing a Serial Port

Chapter 2, Configuring the Serial Port

The POSIX Terminal Interface

Control Options
Local Options
Input Options
Output Options
Control Characters

Chapter 3, MODEM Communications

What Is a MODEM?
Communicating With a MODEM

Standard MODEM Commands
Common MODEM Communication Problems

Chapter 4, Advanced Serial Programming

Serial Port IOCTLs

Getting the Control Signals
Setting the Control Signals
Getting the Number of Bytes Available

Selecting Input from a Serial Port

The SELECT System Call
Using the SELECT System Call
Using SELECT with the X Intrinsics Library

Appendix A, Pinouts

RS-232 Pinouts
RS-422 Pinouts
RS-574 (IBM PC/AT) Pinouts
SGI Pinouts

Appendix B, ASCII Control Codes

Control Codes

Introduction

The Serial Programming Guide for POSIX Operating Systems will teach you how to successfully, efficiently, and portably program the serial ports on your UNIX® workstation or PC. Each chapter provides programming examples that use the POSIX (Portable Standard for UNIX) terminal control functions and should work with very few modifications under IRIX®, HP-UX, SunOS®, Solaris®, Digital UNIX®, Linux®, and most other UNIX operating systems. The biggest difference between operating systems that you will find is the filenames used for serial port device and lock files.

This guide is organized into the following chapters and appendices:

Chapter 1, Basics of Serial Programming
Chapter 2, Configuring the Serial Port
Chapter 3, Talking to MODEMs
Chapter 4, Advanced Serial Programming
Appendix A, RS-232 Pinouts
Appendix B, ASCII Control Codes

Chapter 1, Basics of Serial Communications

This chapter introduces serial communications, RS-232 and other standards that are used on most computers as well as how to access a serial port from a C program.

What Are Serial Communications?

Computers transfer information (data) one or more bits at a time. Serial refers to the transfer of data one bit at a time. Serial communications include most network devices, keyboards, mice, MODEMs, and terminals.

When doing serial communications each word (i.e. byte or character) of data you send or receive is sent one bit at a time. Each bit is either on or off. The terms you'll hear sometimes are mark for the on state and space for the off state.

The speed of the serial data is most often expressed as bits-per-second ("bps") or baudot rate ("baud"). This just represents the number of ones and zeroes that can be sent in one second. Back at the dawn of the computer age, 300 baud was considered fast, but today computers can handle RS-232 speeds as high as 430,800 baud! When the baud rate exceeds 1,000, you'll usually see the rate shown in kilo baud, or kbps (e.g. 9.6k, 19.2k, etc). For rates above 1,000,000 that rate is shown in megabaud, or Mbps (e.g. 1.5Mbps).

When referring to serial devices or ports, they are either labeled as Data Communications Equipment ("DCE") or Data Terminal Equipment ("DTE"). The difference between these is simple - every signal pair, like transmit and receive, is swapped. When connecting two DTE or two DCE interfaces together, a serial null-MODEM cable or adapter is used that swaps the signal pairs.

What Is RS-232?

RS-232 is a standard electrical interface for serial communications defined by the Electronic Industries Association ("EIA"). RS-232 actually comes in 3 different flavors (A, B, and C) with each one defining a different voltage range for the on and off levels. The most commonly used variety is RS-232C, which defines a mark (on) bit as a voltage between -3V and -12V and a space (off) bit as a voltage between +3V and +12V. The RS-232C specification says these signals can go about 25 feet (8m) before they become unusable. You can usually send signals a bit farther than this as long as the baud is low enough.

Besides wires for incoming and outgoing data, there are others that provide timing, status, and handshaking:

Table 1 - RS-232 Pin Assignments
Pin	Description	Pin	Description	Pin	Description	Pin	Description	Pin	Description
1	Earth Ground	6	DSR - Data Set Ready	11	Unassigned	16	Secondary RXD	21	Signal Quality Detect
2	TXD - Transmitted Data	7	GND - Logic Ground	12	Secondary DCD	17	Receiver Clock	22	Ring Detect
3	RXD - Received Data	8	DCD - Data Carrier Detect	13	Secondary CTS	18	Unassigned	23	Data Rate Select
4	RTS - Request To Send	9	Reserved	14	Secondary TXD	19	Secondary RTS	24	Transmit Clock
5	CTS - Clear To Send	10	Reserved	15	Transmit Clock	20	DTR - Data Terminal Ready	25	Unassigned

Two standards for serial interfaces you may also see are RS-422 and RS-574. RS-422 uses lower voltages and differential signals to allow cable lengths up to about 1000ft (300m). RS-574 defines the 9-pin PC serial connector and voltages.

Signal Definitions

The RS-232 standard defines some 18 different signals for serial communications. Of these, only six are generally available in the UNIX environment.

GND - Logic Ground

Technically the logic ground is not a signal, but without it none of the other signals will operate. Basically, the logic ground acts as a reference voltage so that the electronics know which voltages are positive or negative.

TXD - Transmitted Data

The TXD signal carries data transmitted from your workstation to the computer or device on the other end (like a MODEM). A mark voltage is interpreted as a value of 1, while a space voltage is interpreted as a value of 0.

RXD - Received Data

The RXD signal carries data transmitted from the computer or device on the other end to your workstation. Like TXD, mark and space voltages are interpreted as 1 and 0, respectively.

DCD - Data Carrier Detect

The DCD signal is received from the computer or device on the other end of your serial cable. A space voltage on this signal line indicates that the computer or device is currently connected or on line. DCD is not always used or available.

DTR - Data Terminal Ready

The DTR signal is generated by your workstation and tells the computer or device on the other end that you are ready (a space voltage) or not-ready (a mark voltage). DTR is usually enabled automatically whenever you open the serial interface on the workstation.

CTS - Clear To Send

The CTS signal is received from the other end of the serial cable. A space voltage indicates that is alright to send more serial data from your workstation.

CTS is usually used to regulate the flow of serial data from your workstation to the other end.

RTS - Request To Send

The RTS signal is set to the space voltage by your workstation to indicate that more data is ready to be sent.

Like CTS, RTS helps to regulate the flow of data between your workstation and the computer or device on the other end of the serial cable. Most workstations leave this signal set to the space voltage all the time.

Asynchronous Communications

For the computer to understand the serial data coming into it, it needs some way to determine where one character ends and the next begins. This guide deals exclusively with asynchronous serial data.

In asynchronous mode the serial data line stays in the mark (1) state until a character is transmitted. A start bit preceeds each character and is followed immediately by each bit in the character, an optional parity bit, and one or more stop bits. The start bit is always a space (0) and tells the computer that new serial data is available. Data can be sent or received at any time, thus the name asynchronous.

Figure 1 - Asynchronous Data Transmission

The optional parity bit is a simple sum of the data bits indicating whether or not the data contains an even or odd number of 1 bits. With even parity, the parity bit is 0 if there is an even number of 1's in the character. With odd parity, the parity bit is 0 if there is an odd number of 1's in the data. You may also hear the terms space parity, mark parity, and no parity. Space parity means that the parity bit is always 0, while mark parity means the bit is always 1. No parity means that no parity bit is present or transmitted.

The remaining bits are called stop bits. There can be 1, 1.5, or 2 stop bits between characters and they always have a value of 1. Stop bits traditionally were used to give the computer time to process the previous character, but now only serve to synchronize the receiving computer to the incoming characters.

Asynchronous data formats are usually expressed as "8N1", "7E1", and so forth. These stand for "8 data bits, no parity, 1 stop bit" and "7 data bits, even parity, 1 stop bit" respectively.

What Are Full Duplex and Half Duplex?

Full duplex means that the computer can send and receive data simultaneously - there are two separate data channels (one coming in, one going out).

Half duplex means that the computer cannot send or receive data at the same time. Usually this means there is only a single data channel to talk over. This does not mean that any of the RS-232 signals are not used. Rather, it usually means that the communications link uses some standard other than RS-232 that does not support full duplex operation.

Flow Control

It is often necessary to regulate the flow of data when transferring data between two serial interfaces. This can be due to limitations in an intermediate serial communications link, one of the serial interfaces, or some storage media. Two methods are commonly used for asynchronous data.

The first method is often called "software" flow control and uses special characters to start (XON or DC1, 021 octal) or stop (XOFF or DC3, 023 octal) the flow of data. These characters are defined in the American Standard Code for Information Interchange ("ASCII"). While these codes are useful when transferring textual information, they cannot be used when transferring other types of information without special programming.

The second method is called "hardware" flow control and uses the RS-232 CTS and RTS signals instead of special characters. The receiver sets CTS to the space voltage when it is ready to receive more data and to the mark voltage when it is not ready. Likewise, the sender sets RTS to the space voltage when it is ready to send more data. Because hardware flow control uses a separate set of signals, it is much faster than software flow control which needs to send or receive multiple bits of information to do the same thing. CTS/RTS flow control is not supported by all hardware or operating systems.

What Is a Break?

Normally a receive or transmit data signal stays at the mark voltage until a new character is transferred. If the signal is dropped to the space voltage for a long period of time, usually 1/4 to 1/2 second, then a break condition is said to exist.

A break is sometimes used to reset a communications line or change the operating mode of communications hardware like a MODEM. Chapter 3, Talking to MODEMs covers these applications in more depth.

Synchronous Communications

Unlike asynchronous data, synchronous data appears as a constant stream of bits. To read the data on the line, the computer must provide or receive a common bit clock so that both the sender and receiver are synchronized.

Even with this synchronization, the computer must mark the beginning of the data somehow. The most common way of doing this is to use a data packet protocol like Serial Data Link Control ("SDLC") or High-Speed Data Link Control ("HDLC").

Each protocol defines certain bit sequences to represent the beginning and end of a data packet. Each also defines a bit sequence that is used when there is no data. These bit sequences allow the computer see the beginning of a data packet.

Because synchronous protocols do not use per-character synchronization bits they typically provide at least a 25% improvement in performance over asynchronous communications and are suitable for remote networking and configurations with more than two serial interfaces.

Despite the speed advantages of synchronous communications, most RS-232 hardware does not support it due to the extra hardware and software required.

Accessing Serial Ports

Like all devices, UNIX provides access to serial ports via device files. To access a serial port you simply open the corresponding device file.

Serial Port Files

Each serial port on a UNIX system has one or more device files (files in the /dev directory) associated with it:

Table 2 - Serial Port Device Files
System	Port 1	Port 2
IRIX®	/dev/ttyf1	/dev/ttyf2
HP-UX	/dev/tty1p0	/dev/tty2p0
Solaris®/SunOS®	/dev/ttya	/dev/ttyb
Linux®	/dev/ttyS0	/dev/ttyS1
Digital UNIX®	/dev/tty01	/dev/tty02

Opening a Serial Port

Since a serial port is a file, the open(2) function is used to access it. The one hitch with UNIX is that device files are usually not accessable by normal users. Workarounds include changing the access permissions to the file(s) in question, running your program as the super-user (root), or making your program set-userid so that it runs as the owner of the device file.

For now we'll assume that the file is accessable by all users. The code to open serial port 1 on an sgi® workstation running IRIX is:

Listing 1 - Opening a serial port.

#include 'stdio.h'  /* Standard input/output definitions */
#include 'string.h'  /* String function definitions */
#include 'unistd.h'  /* UNIX standard function definitions */
#include 'fcntl.h'   /* File control definitions */
#include 'errno.h'   /* Error number definitions */
#include 'termios.h' /* POSIX terminal control definitions */

/*
* 'open_port()' - Open serial port 1.
*
* Returns the file descriptor on success or -1 on error.
*/

int
open_port(void)
{
 int fd; /* File descriptor for the port */


 fd = open("/dev/ttyf1", O_RDWR | O_NOCTTY | O_NDELAY);
 if (fd == -1)
 {
  /*
   * Could not open the port.
   */

   perror("open_port: Unable to open /dev/ttyf1 - ");
 }
 else
   fcntl(fd, F_SETFL, 0);

 return (fd);
}

Other systems would require the corresponding device file name, but otherwise the code is the same.

Open Options

You'll notice that when we opened the device file we used two other flags along with the read+write mode:

fd = open("/dev/ttyf1", O_RDWR | O_NOCTTY | O_NDELAY);

The O_NOCTTY flag tells UNIX that this program doesn't want to be the "controlling terminal" for that port. If you don't specify this then any input (such as keyboard abort signals and so forth) will affect your process. Programs like getty(1M/8) use this feature when starting the login process, but normally a user program does not want this behavior.

The O_NDELAY flag tells UNIX that this program doesn't care what state the DCD signal line is in - whether the other end of the port is up and running. If you do not specify this flag, your process will be put to sleep until the DCD signal line is the space voltage.

Writing Data to the Port

Writing data to the port is easy - just use the write(2) system call to send data it:

n = write(fd, "ATZ\r", 4);
if (n < 0)
 fputs("write() of 4 bytes failed!\n", stderr);

The write function returns the number of bytes sent or -1 if an error occurred. Usually the only error you'll run into is EIO when a MODEM or data link drops the Data Carrier Detect (DCD) line. This condition will persist until you close the port.

Reading Data from the Port

Reading data from a port is a little trickier. When you operate the port in raw data mode, each read(2) system call will return however many characters are actually available in the serial input buffers. If no characters are available, the call will block (wait) until characters come in, an interval timer expires, or an error occurs. The read function can be made to return immediately by doing the following:

fcntl(fd, F_SETFL, FNDELAY);

The FNDELAY option causes the read function to return 0 if no characters are available on the port. To restore normal (blocking) behavior, call fcntl() without the FNDELAY option:

fcntl(fd, F_SETFL, 0);

This is also used after opening a serial port with the O_NDELAY option.

Closing a Serial Port

To close the serial port, just use the close system call:

close(fd);

Closing a serial port will also usually set the DTR signal low which causes most MODEMs to hang up.

Chapter 2, Configuring the Serial Port

This chapter discusses how to configure a serial port from C using the POSIX termios interface.

The POSIX Terminal Interface

Most systems support the POSIX terminal (serial) interface for changing parameters such as baud rate, character size, and so on. The first thing you need to do is include the file 'termios.h>'; this defines the terminal control structure as well as the POSIX control functions.

The two most important POSIX functions are tcgetattr(3) and tcsetattr(3). These get and set terminal attributes, respectively; you provide a pointer to a termios structure that contains all of the serial options available:

Table 3 - Termios Structure Members
Member	Description
c_cflag	Control options
c_lflag	Line options
c_iflag	Input options
c_oflag	Output options
c_cc	Control characters
c_ispeed	Input baud (new interface)
c_ospeed	Output baud (new interface)

Control Options

The c_cflag member controls the baud rate, number of data bits, parity, stop bits, and hardware flow control. There are constants for all of the supported configurations.

Table 4 - Constants for the c_cflag Member
Constant	Description
CBAUD	Bit mask for baud rate
B0	0 baud (drop DTR)
B50	50 baud
B75	75 baud
B110	110 baud
B134	134.5 baud
B150	150 baud
B200	200 baud
B300	300 baud
B600	600 baud
B1200	1200 baud
B1800	1800 baud
B2400	2400 baud
B4800	4800 baud
B9600	9600 baud
B19200	19200 baud
B38400	38400 baud
B57600	57,600 baud
B76800	76,800 baud
B115200	115,200 baud
EXTA	External rate clock
EXTB	External rate clock
CSIZE	Bit mask for data bits
CS5	5 data bits
CS6	6 data bits
CS7	7 data bits
CS8	8 data bits
CSTOPB	2 stop bits (1 otherwise)
CREAD	Enable receiver
PARENB	Enable parity bit
PARODD	Use odd parity instead of even
HUPCL	Hangup (drop DTR) on last close
CLOCAL	Local line - do not change "owner" of port
LOBLK	Block job control output
CNEW_RTSCTS CRTSCTS	Enable hardware flow control (not supported on all platforms)

The c_cflag member contains two options that should always be enabled, CLOCAL and CREAD. These will ensure that your program does not become the 'owner' of the port subject to sporatic job control and hangup signals, and also that the serial interface driver will read incoming data bytes.

The baud rate constants (CBAUD, B9600, etc.) are used for older interfaces that lack the c_ispeed and c_ospeed members. See the next section for information on the POSIX functions used to set the baud rate.

Never initialize the c_cflag (or any other flag) member directly; you should always use the bitwise AND, OR, and NOT operators to set or clear bits in the members. Different operating system versions (and even patches) can and do use the bits differently, so using the bitwise operators will prevent you from clobbering a bit flag that is needed in a newer serial driver.

Setting the Baud Rate

The baud rate is stored in different places depending on the operating system. Older interfaces store the baud rate in the c_cflag member using one of the baud rate constants in table 4, while newer implementations provide the c_ispeed and c_ospeed members that contain the actual baud rate value.

The cfsetospeed(3) and cfsetispeed(3) functions are provided to set the baud rate in the termios structure regardless of the underlying operating system interface. Typically you'd use the following code to set the baud rate:

Listing 2 - Setting the baud rate.

struct termios options;

/*
* Get the current options for the port...
*/

tcgetattr(fd, &options);

/*
* Set the baud rates to 19200...
*/

cfsetispeed(&options, B19200);
cfsetospeed(&options, B19200);

/*
* Enable the receiver and set local mode...
*/

options.c_cflag |= (CLOCAL | CREAD);

/*
* Set the new options for the port...
*/

tcsetattr(fd, TCSANOW, &options);

The tcgetattr(3) function fills the termios structure you provide with the current serial port configuration. After we set the baud rates and enable local mode and serial data receipt, we select the new configuration using tcsetattr(3). The TCSANOW constant specifies that all changes should occur immediately without waiting for output data to finish sending or input data to finish receiving. There are other constants to wait for input and output to finish or to flush the input and output buffers.

Most systems do not support different input and output speeds, so be sure to set both to the same value for maximum portability.

Table 5 - Constants for tcsetattr
Constant	Description
TCSANOW	Make changes now without waiting for data to complete
TCSADRAIN	Wait until everything has been transmitted
TCSAFLUSH	Flush input and output buffers and make the change

Setting the Character Size

Unlike the baud rate, there is no convienience function to set the character size. Instead you must do a little bitmasking to set things up. The character size is specified in bits:

options.c_cflag &= ~CSIZE; /* Mask the character size bits */
options.c_cflag |= CS8;    /* Select 8 data bits */

Setting Parity Checking

Like the character size you must manually set the parity enable and parity type bits. UNIX serial drivers support even, odd, and no parity bit generation. Space parity can be simulated with clever coding.

No parity (8N1):

options.c_cflag &= ~PARENB
options.c_cflag &= ~CSTOPB
options.c_cflag &= ~CSIZE;
options.c_cflag |= CS8;

Even parity (7E1):

options.c_cflag |= PARENB
options.c_cflag &= ~PARODD
options.c_cflag &= ~CSTOPB
options.c_cflag &= ~CSIZE;
options.c_cflag |= CS7;

Odd parity (7O1):

options.c_cflag |= PARENB
options.c_cflag |= PARODD
options.c_cflag &= ~CSTOPB
options.c_cflag &= ~CSIZE;
options.c_cflag |= CS7;

Space parity is setup the same as no parity (7S1):

options.c_cflag &= ~PARENB
options.c_cflag &= ~CSTOPB
options.c_cflag &= ~CSIZE;
options.c_cflag |= CS8;

Setting Hardware Flow Control

Some versions of UNIX support hardware flow control using the CTS (Clear To Send) and RTS (Request To Send) signal lines. If the CNEW_RTSCTS or CRTSCTS constants are defined on your system then hardware flow control is probably supported. Do the following to enable hardware flow control:

options.c_cflag |= CNEW_RTSCTS;    /* Also called CRTSCTS */

Similarly, to disable hardware flow control:

options.c_cflag &= ~CNEW_RTSCTS;

Local Options

The local modes member c_lflag controls how input characters are managed by the serial driver. In general you will configure the c_lflag member for canonical or raw input.

Table 6 - Constants for the c_lflag Member
Constant	Description
ISIG	Enable SIGINTR, SIGSUSP, SIGDSUSP, and SIGQUIT signals
ICANON	Enable canonical input (else raw)
XCASE	Map uppercase \lowercase (obsolete)
ECHO	Enable echoing of input characters
ECHOE	Echo erase character as BS-SP-BS
ECHOK	Echo NL after kill character
ECHONL	Echo NL
NOFLSH	Disable flushing of input buffers after interrupt or quit characters
IEXTEN	Enable extended functions
ECHOCTL	Echo control characters as ^char and delete as ~?
ECHOPRT	Echo erased character as character erased
ECHOKE	BS-SP-BS entire line on line kill
FLUSHO	Output being flushed
PENDIN	Retype pending input at next read or input char
TOSTOP	Send SIGTTOU for background output

Choosing Canonical Input

Canonical input is line-oriented. Input characters are put into a buffer which can be edited interactively by the user until a CR (carriage return) or LF (line feed) character is received.

When selecting this mode you normally select the ICANON, ECHO, and ECHOE options:

options.c_lflag |= (ICANON | ECHO | ECHOE);

Choosing Raw Input

Raw input is unprocessed. Input characters are passed through exactly as they are received, when they are received. Generally you'll deselect the ICANON, ECHO, ECHOE, and ISIG options when using raw input:

options.c_lflag &= ~(ICANON | ECHO | ECHOE | ISIG);

A Note About Input Echo

Never enable input echo (ECHO, ECHOE) when sending commands to a MODEM or other computer that is echoing characters, as you will generate a feedback loop between the two serial interfaces!

Input Options

The input modes member c_iflag controls any input processing that is done to characters received on the port. Like the c_cflag field, the final value stored in c_iflag is the bitwise OR of the desired options.

Table 7 - Constants for the c_iflag Member
Constant	Description
INPCK	Enable parity check
IGNPAR	Ignore parity errors
PARMRK	Mark parity errors
ISTRIP	Strip parity bits
IXON	Enable software flow control (outgoing)
IXOFF	Enable software flow control (incoming)
IXANY	Allow any character to start flow again
IGNBRK	Ignore break condition
BRKINT	Send a SIGINT when a break condition is detected
INLCR	Map NL to CR
IGNCR	Ignore CR
ICRNL	Map CR to NL
IUCLC	Map uppercase to lowercase
IMAXBEL	Echo BEL on input line too long

Setting Input Parity Options

You should enable input parity checking when you have enabled parity in the c_cflag member (PARENB). The revelant constants for input parity checking are INPCK, IGNPAR, PARMRK , and ISTRIP. Generally you will select INPCK and ISTRIP to enable checking and stripping of the parity bit:

options.c_iflag |= (INPCK | ISTRIP);

IGNPAR is a somewhat dangerous option that tells the serial driver to ignore parity errors and pass the incoming data through as if no errors had occurred. This can be useful for testing the quality of a communications link, but in general is not used for practical reasons.

PARMRK causes parity errors to be 'marked' in the input stream using special characters. If IGNPAR is enabled, a NUL character (000 octal) is sent to your program before every character with a parity error. Otherwise, a DEL (177 octal) and NUL character is sent along with the bad character.

Setting Software Flow Control

Software flow control is enabled using the IXON, IXOFF , and IXANY constants:

options.c_iflag |= (IXON | IXOFF | IXANY);

To disable software flow control simply mask those bits:

options.c_iflag &= ~(IXON | IXOFF | IXANY);

The XON (start data) and XOFF (stop data) characters are defined in the c_cc array described below.

Output Options

The c_oflag member contains output filtering options. Like the input modes, you can select processed or raw data output.

Table 8 - Constants for the c_oflag Member
Constant	Description
OPOST	Postprocess output (not set = raw output)
OLCUC	Map lowercase to uppercase
ONLCR	Map NL to CR-NL
OCRNL	Map CR to NL
NOCR	No CR output at column 0
ONLRET	NL performs CR function
OFILL	Use fill characters for delay
OFDEL	Fill character is DEL
NLDLY	Mask for delay time needed between lines
NL0	No delay for NLs
NL1	Delay further output after newline for 100 milliseconds
CRDLY	Mask for delay time needed to return carriage to left column
CR0	No delay for CRs
CR1	Delay after CRs depending on current column position
CR2	Delay 100 milliseconds after sending CRs
CR3	Delay 150 milliseconds after sending CRs
TABDLY	Mask for delay time needed after TABs
TAB0	No delay for TABs
TAB1	Delay after TABs depending on current column position
TAB2	Delay 100 milliseconds after sending TABs
TAB3	Expand TAB characters to spaces
BSDLY	Mask for delay time needed after BSs
BS0	No delay for BSs
BS1	Delay 50 milliseconds after sending BSs
VTDLY	Mask for delay time needed after VTs
VT0	No delay for VTs
VT1	Delay 2 seconds after sending VTs
FFDLY	Mask for delay time needed after FFs
FF0	No delay for FFs
FF1	Delay 2 seconds after sending FFs

Choosing Processed Output

Processed output is selected by setting the OPOST option in the c_oflag member:

options.c_oflag |= OPOST;

Of all the different options, you will only probably use the ONLCR option which maps newlines into CR-LF pairs. The rest of the output options are primarily historic and date back to the time when line printers and terminals could not keep up with the serial data stream!

Choosing Raw Output

Raw output is selected by resetting the OPOST option in the c_oflag member:

options.c_oflag &= ~OPOST;

When the OPOST option is disabled, all other option bits in c_oflag are ignored.

Control Characters

The c_cc character array contains control character definitions as well as timeout parameters. Constants are defined for every element of this array.

Table 9 - Control Characters in the c_cc Member
Constant	Description	Key
VINTR	Interrupt	CTRL-C
VQUIT	Quit	CTRL-Z
VERASE	Erase	Backspace (BS)
VKILL	Kill-line	CTRL-U
VEOF	End-of-file	CTRL-D
VEOL	End-of-line	Carriage return (CR)
VEOL2	Second end-of-line	Line feed (LF)
VMIN	Minimum number of characters to read
VTIME	Time to wait for data (tenths of seconds)

Setting Software Flow Control Characters

The VSTART and VSTOP elements of the c_cc array contain the characters used for software flow control. Normally they should be set to DC1 (021 octal) and DC3 (023 octal) which represent the ASCII standard XON and XOFF characters.

Setting Read Timeouts

UNIX serial interface drivers provide the ability to specify character and packet timeouts. Two elements of the c_cc array are used for timeouts: VMIN and VTIME. Timeouts are ignored in canonical input mode or when the NDELAY option is set on the file via open or fcntl.

VMIN specifies the minimum number of characters to read. If it is set to 0, then the VTIME value specifies the time to wait for every character read. Note that this does not mean that a read call for N bytes will wait for N characters to come in. Rather, the timeout will apply to the first character and the read call will return the number of characters immediately available (up to the number you request).

If VMIN is non-zero, VTIME specifies the time to wait for the first character read. If a character is read within the time given, any read will block (wait) until all VMIN characters are read. That is, once the first character is read, the serial interface driver expects to receive an entire packet of characters (VMIN bytes total). If no character is read within the time allowed, then the call to read returns 0. This method allows you to tell the serial driver you need exactly N bytes and any read call will return 0 or N bytes. However, the timeout only applies to the first character read, so if for some reason the driver misses one character inside the N byte packet then the read call could block forever waiting for additional input characters.

VTIME specifies the amount of time to wait for incoming characters in tenths of seconds. If VTIME is set to 0 (the default), reads will block (wait) indefinitely unless the NDELAY option is set on the port with open or fcntl.

Chapter 3, MODEM Communications

This chapter covers the basics of dialup telephone Modulator/Demodulator (MODEM) communications. Examples are provided for MODEMs that use the defacto standard "AT" command set.

What Is a MODEM?

MODEMs are devices that modulate serial data into frequencies that can be transferred over an analog data link such as a telephone line or cable TV connection. A standard telephone MODEM converts serial data into tones that can be passed over the phone lines; because of the speed and complexity of the conversion these tones sound more like loud screeching if you listen to them.

Telephone MODEMs are available today that can transfer data across a telephone line at nearly 53,000 bits per second, or 53kbps. In addition, most MODEMs use data compression technology that can increase the bit rate to well over 100kbps on some types of data.

Communicating With a MODEM

The first step in communicating with a MODEM is to open and configure the port for raw input:

Listing 3 - Configuring the port for raw input.

int            fd;
struct termios options;

/* open the port */
fd = open("/dev/ttyf1", O_RDWR | O_NOCTTY | O_NDELAY);
fcntl(fd, F_SETFL, 0);

/* get the current options */
tcgetattr(fd, &options);

/* set raw input, 1 second timeout */
options.c_cflag     |= (CLOCAL | CREAD);
options.c_lflag     &= ~(ICANON | ECHO | ECHOE | ISIG);
options.c_oflag     &= ~OPOST;
options.c_cc[VMIN]  = 0;
options.c_cc[VTIME] = 10;

/* set the options */
tcsetattr(fd, TCSANOW, &options);

Next you need to establish communications with the MODEM. The best way to do this is by sending the "AT" command to the MODEM. This also allows smart MODEMs to detect the baud you are using. When the MODEM is connected correctly and powered on it will respond with the response "OK".

Listing 4 - Initializing the MODEM.

int                  /* O - 0 = MODEM ok, -1 = MODEM bad */
init_modem(int fd)   /* I - Serial port file */
{
 char buffer[255];  /* Input buffer */
 char *bufptr;      /* Current char in buffer */
 int  nbytes;       /* Number of bytes read */
 int  tries;        /* Number of tries so far */

 for (tries = 0; tries < 3; tries ++)
 {
  /* send an AT command followed by a CR */
   if (write(fd, "AT\r", 3) < 3)
     continue;

  /* read characters into our string buffer until we get a CR or NL */
   bufptr = buffer;
   while ((nbytes = read(fd, bufptr, buffer + sizeof(buffer) - bufptr - 1)) > 0)
   {
     bufptr += nbytes;
     if (bufptr[-1] == '\n' || bufptr[-1] == '\r')
       break;
   }

  /* nul terminate the string and see if we got an OK response */
   *bufptr = '\0';

   if (strncmp(buffer, "OK", 2) == 0)
     return (0);
 }

 return (-1);
}

Standard MODEM Commands

Most MODEMs support the "AT" command set, so called because each command starts with the "AT" characters. Each command is sent with the "AT" characters starting in the first column followed by the specific command and a carriage return (CR, 015 octal). After processing the command the MODEM will reply with one of several textual messages depending on the command.

ATD - Dial A Number

The ATD command dials the specified number. In addition to numbers and dashes you can specify tone ("T") or pulse ("P") dialing, pause for one second (","), and wait for a dialtone ("W"):

ATDT 555-1212
ATDT 18008008008W1234,1,1234
ATD T555-1212WP1234

The MODEM will reply with one of the following messages:

NO DIALTONE
BUSY
NO CARRIER
CONNECT
CONNECT baud

ATH - Hang Up

The ATH command causes the MODEM to hang up. Since the MODEM must be in "command" mode you probably won't use it during a normal phone call.

Most MODEMs will also hang up if DTR is dropped; you can do this by setting the baud to 0 for at least 1 second. Dropping DTR also returns the MODEM to command mode.

After a successful hang up the MODEM will reply with "NO CARRIER". If the MODEM is still connected the "CONNECT" or "CONNECT baud" message will be sent.

ATZ - Reset MODEM

The ATZ command resets the MODEM. The MODEM will reply with the string "OK".

Common MODEM Communication Problems

First and foremost, don't forget to disable input echoing. Input echoing will cause a feedback loop between the MODEM and computer.

Second, when sending MODEM commands you must terminate them with a carriage return (CR) and not a newline (NL). The C character constant for CR is "\r".

Finally, when dealing with a MODEM make sure you use a baud that the MODEM supports. While many MODEMs do auto-baud detection, some have limits (19.2kbps is common) that you must observe.

Chapter 4, Advanced Serial Programming

This chapter covers advanced serial programming techniques using the ioctl(2) and select(2) system calls.

Serial Port IOCTLs

In Chapter 2, Configuring the Serial Port we used the tcgetattr and tcsetattr functions to configure the serial port. Under UNIX these functions use the ioctl(2) system call to do their magic.

The ioctl system call takes three arguments:

int ioctl(int fd, int request, ...);

The fd argument specifies the serial port file descriptor. The request argument is a constant defined in the header file and is typically one of the following:

Table 10 - IOCTL Requests for Serial Ports
Request	Description	POSIX Function
TCGETS	Gets the current serial port settings.	tcgetattr
TCSETS	Sets the serial port settings immediately.	tcsetattr(fd, TCSANOW, &options)
TCSETSF	Sets the serial port settings after flushing the input and output buffers.	tcsetattr(fd, TCSANOW, &options)
TCSETSW	Sets the serial port settings after allowing the input and output buffers to drain/empty.	tcsetattr(fd, TCSANOW, &options)
TCSBRK	Sends a break for the given time.	tcsendbreak, tcdrain
TCXONC	Controls software flow control.	tcflow
TCFLSH	Flushes the input and/or output queue.	tcflush
TIOCMGET	Returns the state of the "MODEM" bits.	None
TIOCMSET	Sets the state of the "MODEM" bits.	None
FIONREAD	Returns the number of bytes in the input buffer.	None

Getting the Control Signals

The TIOCMGET ioctl gets the current "MODEM" status bits, which consist of all of the RS-232 signal lines except RXD and TXD:

Table 11 - Control Signal Constants
Constant	Description
TIOCM_LE	DSR (data set ready/line enable)
TIOCM_DTR	DTR (data terminal ready)
TIOCM_RTS	RTS (request to send)
TIOCM_ST	Secondary TXD (transmit)
TIOCM_SR	Secondary RXD (receive)
TIOCM_CTS	CTS (clear to send)
TIOCM_CAR	DCD (data carrier detect)
TIOCM_CD	Synonym for TIOCM_CAR
TIOCM_RNG	RNG (ring)
TIOCM_RI	Synonym for TIOCM_RNG
TIOCM_DSR	DSR (data set ready)

To get the status bits, call ioctl with a pointer to an integer to hold the bits:

Listing 5 - Getting the MODEM status bits.

#include 
#include 

int fd;
int status;

ioctl(fd, TIOCMGET, &status);

Setting the Control Signals

The TIOCMSET ioctl sets the "MODEM" status bits defined above. To drop the DTR signal you can do:

Listing 6 - Dropping DTR with the TIOCMSET ioctl.

#include 'unistd.h'
#include 'termios.h'

int fd;
int status;

ioctl(fd, TIOCMGET, &status);

status &= ~TIOCM_DTR;

ioctl(fd, TIOCMSET, status);

The bits that can be set depend on the operating system, driver, and modes in use. Consult your operating system documentation for more information.

Getting the Number of Bytes Available

The FIONREAD ioctl gets the number of bytes in the serial port input buffer. As with TIOCMGET you pass in a pointer to an integer to hold the number of bytes:

Listing 7 - Getting the number of bytes in the input buffer.

#include 'unistd.h'
#include 'termios.h'

int fd;
int bytes;

ioctl(fd, FIONREAD, &bytes);

This can be useful when polling a serial port for data, as your program can determine the number of bytes in the input buffer before attempting a read.

Selecting Input from a Serial Port

While simple applications can poll or wait on data coming from the serial port, most applications are not simple and need to handle input from multiple sources.

UNIX provides this capability through the select(2) system call. This system call allows your program to check for input, output, or error conditions on one or more file descriptors. The file descriptors can point to serial ports, regular files, other devices, pipes, or sockets. You can poll to check for pending input, wait for input indefinitely, or timeout after a specific amount of time, making the select system call extremely flexible.

Most GUI Toolkits provide an interface to select; we will discuss the X Intrinsics ("Xt") library later in this chapter.

The SELECT System Call

The select system call accepts 5 arguments:

int select(int max_fd, fd_set *input, fd_set *output, fd_set *error,
          struct timeval *timeout);

The max_fd argument specifies the highest numbered file descriptor in the input, output, and error sets. The input, output, and error arguments specify sets of file descriptors for pending input, output, or error conditions; specify NULL to disable monitoring for the corresponding condition. These sets are initialized using three macros:

FD_ZERO(fd_set);
FD_SET(fd, fd_set);
FD_CLR(fd, fd_set);

The FD_ZERO macro clears the set entirely. The FD_SET and FD_CLR macros add and remove a file descriptor from the set, respectively.

The timeout argument specifies a timeout value which consists of seconds (timeout.tv_sec) and microseconds (timeout.tv_usec ). To poll one or more file descriptors, set the seconds and microseconds to zero. To wait indefinitely specify NULL for the timeout pointer.

The select system call returns the number of file descriptors that have a pending condition, or -1 if there was an error.

Using the SELECT System Call

Suppose we are reading data from a serial port and a socket. We want to check for input from either file descriptor, but want to notify the user if no data is seen within 10 seconds. To do this we'll need to use the select system call:

Listing 8 - Using SELECT to process input from more than one source.

#include 'unistd.h'
#include 'sys/types.h'
#include 'sys/time.h'
#include 'sys/select.h'

int            n;
int            socket;
int            fd;
int            max_fd;
fd_set         input;
struct timeval timeout;

/* Initialize the input set */
FD_ZERO(input);
FD_SET(fd, input);
FD_SET(socket, input);

max_fd = (socket > fd ? socket : fd) + 1;

/* Initialize the timeout structure */
timeout.tv_sec  = 10;
timeout.tv_usec = 0;

/* Do the select */
n = select(max_fd,  NULL, NULL, ;

/* See if there was an error */
if (n 0)
 perror("select failed");
else if (n == 0)
 puts("TIMEOUT");
else
{
 /* We have input */
 if (FD_ISSET(fd, input))
   process_fd();
 if (FD_ISSET(socket, input))
   process_socket();
}

You'll notice that we first check the return value of the select system call. Values of 0 and -1 yield the appropriate warning and error messages. Values greater than 0 mean that we have data pending on one or more file descriptors.

To determine which file descriptor(s) have pending input, we use the FD_ISSET macro to test the input set for each file descriptor. If the file descriptor flag is set then the condition exists (input pending in this case) and we need to do something.

Using SELECT with the X Intrinsics Library

The X Intrinsics library provides an interface to the select system call via the XtAppAddInput(3x) and XtAppRemoveInput(3x) functions:

int XtAppAddInput(XtAppContext context, int fd, int mask,
                 XtInputProc proc, XtPointer data);
void XtAppRemoveInput(XtAppContext context, int input);

The select system call is used internally to implement timeouts, work procedures, and check for input from the X server. These functions can be used with any Xt-based toolkit including Xaw, Lesstif, and Motif.

The proc argument to XtAppAddInput specifies the function to call when the selected condition (e.g. input available) exists on the file descriptor. In the previous example you could specify the process_fd or process_socket functions.

Because Xt limits your access to the select system call, you'll need to implement timeouts through another mechanism, probably via XtAppAddTimeout(3x).

Appendix A, Pinouts

This appendix provides pinout information for many of the common serial ports you will find.

RS-232 Pinouts

RS-232 comes in three flavors (A, B, C) and uses a 25-pin D-Sub connector:

Figure 2 - RS-232 Connector

Table 12 - RS-232 Signals
Pin	Description	Pin	Description
1	Earth Ground	14	Secondary TXD
2	TXD - Transmitted Data	15	Transmit Clock
3	RXD - Received Data	16	Secondary RXD
4	RTS - Request To Send	17	Receiver Clock
5	CTS - Clear To Send	18	Unassigned
6	DSR - Data Set Ready	19	Secondary RTS
7	GND - Logic Ground	20	DTR - Data Terminal Ready
8	DCD - Data Carrier Detect	21	Signal Quality Detect
9	Reserved	22	Ring Detect
10	Reserved	23	Data Rate Select
11	Unassigned	24	Transmit Clock
12	Secondary DCD	25	Unassigned
13	Secondary CTS

RS-422 Pinouts

RS-422 also uses a 25-pin D-Sub connector, but with differential signals:

Figure 3 - RS-422 Connector

Table 13 - RS-422 Signals
Pin	Description	Pin	Description
1	Earth Ground	14	TXD+
2	TXD- - Transmitted Data	15	Transmit Clock-
3	RXD- - Received Data	16	RXD+
4	RTS- - Request To Send	17	Receiver Clock-
5	CTS- - Clear To Send	18	Unassigned
6	DSR - Data Set Ready	19	RTS+
7	GND - Logic Ground	20	DTR- - Data Terminal Ready
8	DCD- - Data Carrier Detect	21	Signal Quality Detect
9	Reserved	22	Unassigned
10	Reserved	23	DTR+
11	Unassigned	24	Transmit Clock+
12	DCD+	25	Receiver Clock+
13	CTS+

RS-574 (IBM PC/AT) Pinouts

The RS-574 interface is used exclusively by PC manufacturers and uses a 9-pin male D-Sub connector:

Figure 4 - RS-574 Connector

Table 14 - RS-574 (IBM PC/AT) Signals
Pin	Description	Pin	Description
1	DCD - Data Carrier Detect	6	Data Set Ready
2	RXD - Received Data	7	RTS - Request To Send
3	TXD - Transmitted Data	8	CTS - Clear To Send
4	DTR - Data Terminal Ready	9	Ring Detect
5	GND - Logic Ground

SGI Pinouts

Older SGI equipment uses a 9-pin female D-Sub connector. Unlike RS-574, the SGI pinouts nearly match those of RS-232:

Figure 5 - SGI 9-Pin Connector

Table 15 - SGI 9-Pin DSUB Signals
Pin	Description	Pin	Description
1	Earth Ground	6	DSR - Data Set Ready
2	TXD - Transmitted Data	7	GND - Logic Ground
3	RXD - Received Data	8	DCD - Data Carrier Detect
4	RTS - Request To Send	9	DTR - Data Terminal Ready
5	CTS - Clear To Send

The SGI Indigo, Indigo2, and Indy workstations use the Apple 8-pin MiniDIN connector for their serial ports:

Figure 6 - SGI 8-Pin Connector

Table 16 - SGI 8-Pin MiniDIN Signals
Pin	Description	Pin	Description
1	DTR - Data Terminal Ready	5	RXD - Received Data
2	CTS - Clear To Send	6	RTS - Request To Send
3	TXD - Transmitted Data	7	DCD - Data Carrier Detect
4	GND - Logic Ground	8	GND - Logic Ground

Appendix B, ASCII Control Codes

This chapter lists the ASCII control codes and their names.

Control Codes

The following ASCII characters are used for control purposes:

Table 17 - ASCII Control Codes
Name	Binary	Octal	Decimal	Hexadecimal
NUL	00000000	000	0	00
SOH	00000001	001	1	01
STX	00000010	002	2	02
ETX	00000011	003	3	03
EOT	00000100	004	4	04
ENQ	00000101	005	5	05
ACK	00000110	006	6	06
BEL	00000111	007	7	07
BS	00001000	010	8	08
HT	00001001	011	9	09
NL	00001010	012	10	0A
VT	00001011	013	11	0B
NP, FF	00001100	014	12	0C
CR	00001101	015	13	0D
SO	00001110	016	14	0E
SI	00001111	017	15	0F
DLE	00010000	020	16	10
XON, DC1	00010001	021	17	11
DC2	00010010	022	18	12
XOFF, DC3	00010011	023	19	13
DC4	00010100	024	20	14
NAK	00010101	025	21	15
SYN	00010110	026	22	16
ETB	00010111	027	23	17
CAN	00011000	030	24	18
EM	00011001	031	25	19
SUB	00011010	032	26	1A
ESC	00011011	033	27	1B
FS	00011100	034	28	1C
GS	00011101	035	29	1D
RS	00011110	036	30	1E
US	00011111	037	31	1F

2008-05-29T02:33:00.001-07:00

 Linux Serial Port Programming Mini-Howto


1. Introduction

This document describes how to program the RS-232 ports for serial
communications, under PC-Linux. It covers information about
the serial ports, RS232 connections, modem issues, and the C programming
logic.

2. Background

For our final year project, our group had to design a concept World
Wide Web browser. Our prototype was a hand-held device which plugged
into a PC's COM2 (25-pin) serial port. The user would issue commands
to the browser (eg Back, Open, etc) by sending character commands to
the PC. The browser software would detect it, and perform the required
operation.

The method provided in the 'Linux I/O port programming mini-HOWTO'
did not act reliably. Often, an incorrect value would be received.
The information within provided a 100% reliable, quasi-POSIX-compliant
approach to communication.

The program provided at the end of this 0 formed the basis of
the PC's communication program. This document is written from the
1 needed for the web browser project. It revolves around
C programming for Linux, for a 9600 baud device attached to COM2.

3. Acknowledgements

The information here comes mainly from these sources -

Heavily based on the 'Serial Programming Guide for POSIX Compliant
Operating Systems', at http://www.easysw.com/~mike/serial/, by
mike@easysw.com. If you need greater detail or more information, then
this is the place to visit. Most of the information in this 0
originated here.

The 'Linux I/O port programming mini-HOWTO', by Riku Saikkonen
(rjs@spider.compart.fi). This document provides a different approach
to Linux serial programming.

'The Linux Serial HOWTO', by Greg Hankins, greg.hankins@cc.gatech.edu
describes how to set up serial communications devices on a Linux box.
It describes many aspects of serial devices and 0.

My two wonderful project partners: Gerel Enrile and Joyce Gong.

4. Copyright

This document is copyright (C) 1997 by Antonino Iannella.
It is covered under the general Linux HOWTO copyright agreement.

It is intended for the general public. it may be reproduced and
distributed in whole or in part, using any electronic or physical
medium. However, this copyright notice must remain on all copies.

Please forward question, suggestions, corrections, and all tidbits
of information to the author at antonino@usa.net
(or nettuno@light.iinet.net.au).
You will be acknowledged in future HOWTO revisions.

5. RS-232 connections

RS-232 is a standard for serial communications. It comes in different
varieties. The most common is RS-232C which defines a 'mark' bit as a
voltage between -3V and -12V, and a 'space' bit as a voltage between
+3V and +12V. RS-574 is the standard for 9-pin PC connectors and
voltages.

RS-232 basically consists of wires for serial communications; sending
and receiving, timing, status, and handshaking.
You can use a null modem cable as your connector.
The following pins are what were used for our project.  We connected
the device to the DB-25 pin COM2 port. Please note that the Transmit
line from the PC must connect to the Receive line of the device, and
vice versa. Also, please note that a parallel port is different to a
serial port!

                        PC's pins   Device's pins
    TxD   Transmit Data         2 - 3       RxD   Receive Data
    RxD   Receive Data          3 - 2       TxD   Transmit Data
    SG    Signal Ground         7 - 7       SG    Signal Ground


Refer to the Linux Serial HOWTO for more specialised connections, and
detailed RS-232 pins.

6. Serial 0 and RS-232 definitions

The way that data get transmitted in serial communications is, well,
serially. One data bit is sent at a time. Each bit is either on (or the
'mark' state), or off (or the 'space' state).

The serial data throughput is usually expressed in bits-per-second (bps)
or baudot (baud). Throughput is the number of data bits (2 or off) that
may be sent in a second. Your modem might be able to support 115200 baud.
The project's web browser device was designed to run at 9600 baud.

RS-232 provides 18 different signals. About 6 are available to UNIX for
programming.

GND - Logic ground

      Very important. Acts as a reference voltage, so the devices know
      the relative voltage of the data transmitted.
    
TxD - Transmitted data

      Carries the data transmitted from your PC.
      A 'mark' voltage is interpreted as 1,
      while a 'space' voltage is interpreted as 0.
    
RxD - Received data

      Carries the data transmitted to your PC from the other device.
    
DCD - Data carrier detect

      Is sent from the other device to your PC. A 'space' voltage means
      that the device is still connected, or 'on-line'. This signal is
      not always used or available.
    
DTR - Data terminal ready

      Is sent from your PC to tell the device that you are ready (space)
      or not-ready (mark). DTR is usually enabled automatically whenever
      you access the serial interface.
    
CTS - Clear to send

      Is sent from the other device to your PC.
      A 'space' voltage means that your PC may send some data.
      It is usually used to regulate the flow of serial data from your
      PC, but it is not currently supported by all UNIX flavours.
    
RTS - Request to send

      Is set to the 'space' voltage by your PC when it requests to send
      more data. It also used to regulate data flow. Many systems leave
      it on 'space' voltage all the time.
    
7. Communication issues

This section covers other issues of serial communication which might be
relevant to your particular application.
Since we are programming for asynchronous communication, we need the
PCs/devices to know where each character starts and ends in the serial
data flow.

In asynchronous mode, the serial data line stays in the mark state until
a character is sent. A 'start bit' is sent before each character; it is
always 0 and tells the PC/device that a character will follow.
After the start bit, the character's bits are sent, then a 'parity' bit,
and one or more stop bits.

The parity bit is a checksum of the data bits, indicating the number of
1 bits it contained -

   Even parity  - parity bit is 1 if there is an even number of 1s
   Odd parity   - parity bit is 1 if there is an odd number of 1s
   Space parity - parity bit is always 0
   Mark parity  - parity bit is 1
   No parity    - no parity bit is sent or present.

'Stop' bits come at the end of every character. There may be 1, 1.5, or 2
stop bits. They used to be used to give the computer time to process the
character, but now they are used to synchronise the computer to the
incoming characters.

Asynchronous data is usually described like '8N1' - 8 data bits, no parity
bits, 1 stop bit. Another common one is '7N1'.

Flow control is used to regulate the data flow between devices, if there
is some sort of limitation, such as a slow device. There is 'Software
Flow Control' using special characters, XON and XOFF, to regulate the flow.
This method is not useful for transmitting non-textual data.
'Hardware Flow Control' uses the RTS and CTS signals instead of special
characters. The receiver sets CTS to space when it is ready to receive,
and to mark when it's not. The sender uses RTS the same way. This method
is faster than Software Flow Control, since it uses a separate set of
signals instead of extra bits.

Since the receive or transmit signal is at mark voltage until a new character
is sent. A 'break' condition exists when the line is set to low for 1/4
to 1/2 a second. It is used to reset a communications line, or change
the operation mode of devices like modems.

8. Basic port programming

Hopefully, all of the above is reasonably clear to you, so you may proceed
to program with confidence!

In UNIX all system devices are treated as (special) files. All serial ports
are opened, read from, written to, and closed, just like a binary file.
In Linux, the PC serial ports are

   COM1 - /dev/ttyS0
   COM2 - /dev/ttyS1
   COM3 - /dev/ttyS2
   COM4 - /dev/ttyS3

Firstly, open the serial port as a file. However, UNIX does not allow
devices to be accessed by normal users. To solve this, either run the
program as the superuser, or change the permission on the device as root,
eg

   chmod a+rw /dev/ttyS1          (lets everyone access COM2)

To open the file do the following. Notice the three flags used in the
open() function. O_RDWR means that we open the port for reading and
writing. O_NOCTTY specifies that the program won't be the controlling
entity for the port. Most user programs don't want this feature.
O_NDELAY means that your program ignores the DCD line. If it didn't,
the program will be put to sleep until DCD is set to 'space' voltage.

/*
* 'open_port()' - Open serial port 1 - COM2.
*
* Returns the file descriptor on success or -1 on error.
*/

int open_port(void)
{
 int fd;                                   /* File descriptor for the port */

 fd = open("/dev/ttyS1", O_RDWR | O_NOCTTY | O_NDELAY);
 if (fd == -1)
 {                                              /* Could not open the port */
   fprintf(stderr, "open_port: Unable to open /dev/ttyS1 - %s\n",
           strerror(errno));
 }

 return (fd);
}

If you need to write data to the port, do something like

 n = write(fd, "ATZ\r", 4);

 if (n <> and access the termios structure using the
POSIX tcgetattr() and tcsetattr() functions.

The termios structure contains

 c_cflag - Control options
 c_lflag - Line options
 c_iflag - Input options
 c_oflag - Output options
 c_cc    - Control characters

See section 12 for a list of c_cflag control modes.
They are used to set the baud rate, parity and stop bits, and flow control.
Always enable CLOCAL and CREAD, so the program does not own the port, and so
the serial interface driver will read incoming bytes.

9.1. Accessing the termios structure and the baud rate

Use cfsetospeed() and cfsetispeed() to set the baud rate.
CRTSCTS might be called CNEW_RTSCTS on other systems.
The following uses a termios structure called 'options'.
For our project, the device transmitted at 9600 baud and transmitted nothing
special.

tcgetattr(mainfd, &options);        /* Get the current options for the port */
cfsetispeed(&options, B9600);                 /* Set the baud rates to 9600 */
cfsetospeed(&options, B9600);  
                                 /* Enable the receiver and set local mode */
options.c_cflag |= (CLOCAL | CREAD);
   
                                      /* Set the new options for the port */
tcsetattr(mainfd, TCSANOW, &options);

The tcsetattr() function replaces the port's termios structure with the
settings you provided. The TCSANOW constant means that the changes should
occur immediately, without waiting for data transmission to complete.
Alternative choices are TCSADRAIN and TCSAFLUSH, which wait until buffers
are cleared. Refer to section 13.

9.2. Character size and parity

To set the character size, you must use bitwise logic.
The following code sets the character size to 8 data bits, and no parity.
                     
  options.c_cflag &= ~PARENB;  /* Mask character size to 8 bits, no parity */
  options.c_cflag &= ~CSTOPB;
  options.c_cflag &= ~CSIZE;
  options.c_cflag |=  CS8;                           /* Select 8 data bits */

For other methods, refer to section 11.

9.3. Hardware flow control

To enable hardware flow control, use

   options.c_cflag |= CRTSCTS;            /* Enable hardware flow control */

To disable it,

   options.c_cflag &= ~CRTSCTS;          /* Disable hardware flow control */

9.4. Canonical and raw input

Canonical input means that all incoming characters are placed in a buffer
which may be edited by the user, until a carriage return or line feed (CR or
LF) are received. Typically, you would use

options.c_lflag |= ~(ICANON | ECHO | ECHOE);

Raw input is unprocessed, so they may be used as they are read.
Our device sent raw data.

options.c_lflag &= ~(ICANON | ECHO | ISIG);

Whether you use canonical or raw input, make sure you never enable input
echo when connected to a computer/device which is echoing characters to you.
Refer to section 14 for local mode constants.

9.5. POSIX input modes

Set the port's input modes for any input processing.
Set input parity when you have enabled parity in the c_cflag part.
Usually you'd use the following to enable parity checking, and strip the
parity bit off the data, before your program reads it.

options.c_iflag |= (INPCK | ISTRIP);

You might use IGNPAR, which ignores all parity errors. PARMRK marks parity
errors by inserting a DEL(255) and NUL character before the bad character.
If IGNPAR is enabled, only a NUL is inserted.

You may set software flow control using

options.c_iflag |= (IXON | IXOFF | IXANY);

Refer to section 15 for input mode constants.

9.6. POSIX output modes

To set port output modes, use the c_oflag member.
To select processed output, use the following. Of all the output modes, you
will probably only use ONCLR to convert newlines into CR and LFs.

options.c_oflag |= OPOST;

For raw output, use

options.c_oflag &= ~OPOST;

Refer to section 16 for output mode constants.

9.7. POSIX control modes

You may set the control characters using the c_cc part.
Set the software flow control characters in the VSTART and VSTOP
elements. The standard is DC1(17) and DC3(19) for XON and XOFF.
VMIN specifies the minimum number of 0 to read. If it is 0, then
VTIME specifies the time to wait for each character.
If VMIN is not 0, VTIME is the time to wait to read the first character.
If the first character is read, then any read() will be blocked until all
VMIN characters are read.
VTIME is specified in tenths of seconds. If it is 0, then read()s will
be permanently blocked unless NDELAY was previously specified with fcntl().

Refer to section 17 for control mode constants.

10. Sample program

This program is a skeleton COM2 reader, which was used for our project.
It did not need all of the information specified above for
configuring ports. The 20ms delay is used to indicate that data coming into
the port is buffered, and is available for the next read().

/* Better port reading program
 v1.0
 23-10-96

 This test program uses quasi-POSIX compliant UNIX functions to
 open the ABU port and read.

 Uses termio functions to initialise the port to 9600 baud, at
 8 data bits, no parity, no hardware flow control,
 and features character buffering.
 The 20ms delay after the port read indicates that characters are
 buffered if a button is pressed many times.

 This program was derived from instructions at
  http://www.easysw.com/~mike/serial/
*/

 #include stdio.h'   /* Standard input/output definitions */
#include string.h  /* String function definitions */
#include unistd.h  /* UNIX standard function definitions */
#include fcntl.h   /* File control definitions */
#include errno.h   /* Error number definitions */
#include termios.h /* POSIX terminal control definitions */

/*
* 'open_port()' - Open serial port 1.
*
* Returns the file descriptor on success or -1 on error.
*/

int open_port(void)
{
 int fd;                                   /* File descriptor for the port */

 fd = open("/dev/ttyS1", O_RDWR | O_NOCTTY | O_NDELAY);

 if (fd == -1)
 {                                              /* Could not open the port */
   fprintf(stderr, "open_port: Unable to open /dev/ttyS1 - %s\n",
           strerror(errno));
 }

 return (fd);
}

void main()
{
int mainfd=0;                                            /* File descriptor */
char chout;
struct termios options;

mainfd = open_port();

fcntl(mainfd, F_SETFL, FNDELAY);                  /* Configure port reading */
                                   /* Get the current options for the port */
tcgetattr(mainfd, &options);
cfsetispeed(&options, B9600);                 /* Set the baud rates to 9600 */
cfsetospeed(&options, B9600);

                                 /* Enable the receiver and set local mode */
options.c_cflag |= (CLOCAL | CREAD);
options.c_cflag &= ~PARENB; /* Mask the character size to 8 bits, no parity */
options.c_cflag &= ~CSTOPB;
options.c_cflag &= ~CSIZE;
options.c_cflag |=  CS8;                              /* Select 8 data bits */
options.c_cflag &= ~CRTSCTS;               /* Disable hardware flow control */

                               /* Enable data to be processed as raw input */
options.c_lflag &= ~(ICANON | ECHO | ISIG);
   
                                      /* Set the new options for the port */
tcsetattr(mainfd, TCSANOW, &options);
                     
while (1)
{
 read(mainfd, &chout, sizeof(chout));          /* Read character from ABU */

 if (chout != 0)
    printf("Got %c.\n", chout);

 chout=0;
 usleep(20000);
}
                                                  /* Close the serial port */
close(mainfd);
}

11. Character and parity settings

  No parity (8N1):

   options.c_cflag &= ~PARENB;
   options.c_cflag &= ~CSTOPB;
   options.c_cflag &= ~CSIZE;
   options.c_cflag |= CS8;

  Even parity (7E1):

   options.c_cflag |= PARENB;
   options.c_cflag &= ~PARODD;
   options.c_cflag &= ~CSTOPB;
   options.c_cflag &= ~CSIZE;
   options.c_cflag |= CS7;

  Odd parity (7O1):

   options.c_cflag |= PARENB;
   options.c_cflag |= PARODD;
   options.c_cflag &= ~CSTOPB;
   options.c_cflag &= ~CSIZE;
   options.c_cflag |= CS7;

  Mark parity is simulated by using 2 stop bits (7M1):

   options.c_cflag &= ~PARENB;
   options.c_cflag |= CSTOPB;
   options.c_cflag &= ~CSIZE;
   options.c_cflag |= CS7;

  Space parity is setup the same as no parity (7S1):

   options.c_cflag &= ~PARENB;
   options.c_cflag &= ~CSTOPB;
   options.c_cflag &= ~CSIZE;
   options.c_cflag |= CS8;

12. POSIX control mode flags

The following table lists the possible control modes for c_cflag.

 Constant     Description
 ________________________

 CBAUD        Bit mask for baud rate       
 B0           0 baud (drop DTR)       
 B50          50 baud       
 B75          75 baud       
 B110         110 baud       
 B134         134.5 baud       
 B150         150 baud       
 B200         200 baud       
 B300         300 baud       
 B600         600 baud       
 B1200        1200 baud       
 B1800        1800 baud       
 B2400        2400 baud       
 B4800        4800 baud       
 B9600        9600 baud       
 B19200       19200 baud       
 B38400       38400 baud       
 EXTA         External rate clock       
 EXTB         External rate clock       
 CSIZE        Bit mask for data bits       
 CS5          5 data bits       
 CS6          6 data bits       
 CS7          7 data bits       
 CS8          8 data bits       
 CSTOPB       2 stop bits (1 otherwise)       
 CREAD        Enable receiver       
 PARENB       Enable parity bit       
 PARODD       Use odd parity instead of even       
 HUPCL        Hangup (drop DTR) on last close       
 CLOCAL       Local line - do not change 'owner' of port    
 LOBLK        Block job control output       
 CRTSCTS      Enable hardware flow control (not supported on all platforms)       

13. POSIX tcsetattr Constants

 Constant   Description
 ______________________

 TCSANOW    Make changes now without waiting for data to complete
 TCSADRAIN  Wait until everything has been transmitted
 TCSAFLUSH  Flush input and output buffers and make the change

14. POSIX Local Mode Constants

 Constant   Description
 ______________________

 ISIG       Enable SIGINTR, SIGSUSP, SIGDSUSP, and SIGQUIT signals
 ICANON     Enable canonical input (else raw)
 XCASE      Map uppercase \lowercase (obselete)
 ECHO       Enable echoing of input characters
 ECHOE      Echo erase character as BS-SP-BS
 ECHOK      Echo NL after kill character
 ECHONL     Echo NL
 NOFLSH     Disable flushing of input buffers after interrupt
            or quit characters
 IEXTEN     Enable extended functions
 ECHOCTL    Echo control characters as ^char and delete as ~?
 ECHOPRT    Echo erased character as character erased
 ECHOKE     BS-SP-BS entire line on line kill
 FLUSHO     Output being flushed
 PENDIN     Retype pending input at next read or input char
 TOSTOP     Send SIGTTOU for background output

15. POSIX Input Mode Constants

 Constant   Description
 ______________________

 INPCK      Enable parity check
 IGNPAR     Ignore parity errors
 PARMRK     Mark parity errors
 ISTRIP     Strip parity bits
 IXON       Enable software flow control (outgoing)
 IXOFF      Enable software flow control (incoming)
 IXANY      Allow any character to start flow again
 IGNBRK     Ignore break condition
 BRKINT     Send a SIGINT when a break condition is detected
 INLCR      Map NL to CR
 IGNCR      Ignore CR
 ICRNL      Map CR to NL
 IUCLC      Map uppercase to lowercase
 IMAXBEL    Echo BEL on input line too long

16. POSIX Output Mode Constants

 Constant   Description
 ______________________

 OPOST      Postprocess output (not set = raw output)
 OLCUC      Map lowercase to uppercase
 ONLCR      Map NL to CR-NL
 OCRNL      Map CR to NL
 NOCR       No CR output at column 0
 ONLRET     NL performs CR function
 OFILL      Use fill characters for delay
 OFDEL      Fill character is DEL
 NLDLY      Mask for delay time needed between lines
 NL0        No delay for NLs
 NL1        Delay further output after newline for 100 milliseconds
 CRDLY      Mask for delay time needed to return carriage to left column
 CR0        No delay for CRs
 CR1        Delay after CRs depending on current column position
 CR2        Delay 100 milliseconds after sending CRs
 CR3        Delay 150 milliseconds after sending CRs
 TABDLY     Mask for delay time needed after TABs
 TAB0       No delay for TABs
 TAB1       Delay after TABs depending on current column position
 TAB2       Delay 100 milliseconds after sending TABs
 TAB3       Expand TAB characters to spaces
 BSDLY      Mask for delay time needed after BSs
 BS0        No delay for BSs
 BS1        Delay 50 milliseconds after sending BSs
 VTDLY      Mask for delay time needed after VTs
 VT0        No delay for VTs
 VT1        Delay 2 seconds after sending VTs
 FFDLY      Mask for delay time needed after FFs
 FF0        No delay for FFs
 FF1        Delay 2 seconds after sending FFs

17. POSIX Control Character Constants

 Constant   Description          Key
 ______________________________________

 VINTR      Interrupt            CTRL-C
 VQUIT      Quit                 CTRL-Z
 VERASE     Erase                Backspace (BS)
 VKILL      Kill-line            CTRL-U
 VEOF       End-of-file          CTRL-D
 VEOL       End-of-line          Carriage return (CR)
 VEOL2      Second end-of-line   Line feed (LF)
 VMIN       Minimum number of characters to read
 VTIME      Time to wait for data (tenths of seconds)

----------------- End of Linux Serial Programming Mini-Howto -----------------

Linux Serial Port Programming Mini-Howto

2008-05-29T02:33:00.000-07:00

 Linux Serial Port Programming Mini-Howto


 1. Introduction

 This document describes how to program the RS-232 ports for serial
 communications, under PC-Linux. It covers information about
 the serial ports, RS232 connections, modem issues, and the C programming
 logic.

 2. Background

 For our final year project, our group had to design a concept World
 Wide Web browser. Our prototype was a hand-held device which plugged
 into a PC's COM2 (25-pin) serial port. The user would issue commands
 to the browser (eg Back, Open, etc) by sending character commands to
 the PC. The browser software would detect it, and perform the required
 operation.

 The method provided in the 'Linux I/O port programming mini-HOWTO'
 did not act reliably. Often, an incorrect value would be received.
 The information within provided a 100% reliable, quasi-POSIX-compliant
 approach to communication.

 The program provided at the end of this 0 formed the basis of
 the PC's communication program. This document is written from the
 1 needed for the web browser project. It revolves around
 C programming for Linux, for a 9600 baud device attached to COM2.

 3. Acknowledgements

 The information here comes mainly from these sources -
  
 Heavily based on the 'Serial Programming Guide for POSIX Compliant
 Operating Systems', at http://www.easysw.com/~mike/serial/, by
 mike@easysw.com. If you need greater detail or more information, then
 this is the place to visit. Most of the information in this 0
 originated here.
  
 The 'Linux I/O port programming mini-HOWTO', by Riku Saikkonen
 (rjs@spider.compart.fi). This document provides a different approach
 to Linux serial programming.

 'The Linux Serial HOWTO', by Greg Hankins, greg.hankins@cc.gatech.edu
 describes how to set up serial communications devices on a Linux box.
 It describes many aspects of serial devices and 0.

 My two wonderful project partners: Gerel Enrile and Joyce Gong.

 4. Copyright

 This document is copyright (C) 1997 by Antonino Iannella.
 It is covered under the general Linux HOWTO copyright agreement.

 It is intended for the general public. it may be reproduced and
 distributed in whole or in part, using any electronic or physical
 medium. However, this copyright notice must remain on all copies.

 Please forward question, suggestions, corrections, and all tidbits
 of information to the author at antonino@usa.net
 (or nettuno@light.iinet.net.au).
 You will be acknowledged in future HOWTO revisions.

 5. RS-232 connections

 RS-232 is a standard for serial communications. It comes in different
 varieties. The most common is RS-232C which defines a 'mark' bit as a
 voltage between -3V and -12V, and a 'space' bit as a voltage between
 +3V and +12V. RS-574 is the standard for 9-pin PC connectors and
 voltages.

 RS-232 basically consists of wires for serial communications; sending
 and receiving, timing, status, and handshaking.
 You can use a null modem cable as your connector.
 The following pins are what were used for our project.  We connected
 the device to the DB-25 pin COM2 port. Please note that the Transmit
 line from the PC must connect to the Receive line of the device, and
 vice versa. Also, please note that a parallel port is different to a
 serial port!

                         PC's pins   Device's pins
     TxD   Transmit Data         2 - 3       RxD   Receive Data
     RxD   Receive Data          3 - 2       TxD   Transmit Data
     SG    Signal Ground         7 - 7       SG    Signal Ground


 Refer to the Linux Serial HOWTO for more specialised connections, and
 detailed RS-232 pins.

 6. Serial 0 and RS-232 definitions

 The way that data get transmitted in serial communications is, well,
 serially. One data bit is sent at a time. Each bit is either on (or the
 'mark' state), or off (or the 'space' state).

 The serial data throughput is usually expressed in bits-per-second (bps)
 or baudot (baud). Throughput is the number of data bits (2 or off) that
 may be sent in a second. Your modem might be able to support 115200 baud.
 The project's web browser device was designed to run at 9600 baud.

 RS-232 provides 18 different signals. About 6 are available to UNIX for
 programming.

 GND - Logic ground

       Very important. Acts as a reference voltage, so the devices know
       the relative voltage of the data transmitted.
      
 TxD - Transmitted data

       Carries the data transmitted from your PC.
       A 'mark' voltage is interpreted as 1,
       while a 'space' voltage is interpreted as 0.
      
 RxD - Received data

       Carries the data transmitted to your PC from the other device.
      
 DCD - Data carrier detect

       Is sent from the other device to your PC. A 'space' voltage means
       that the device is still connected, or 'on-line'. This signal is
       not always used or available.
      
 DTR - Data terminal ready

       Is sent from your PC to tell the device that you are ready (space)
       or not-ready (mark). DTR is usually enabled automatically whenever
       you access the serial interface.
      
 CTS - Clear to send

       Is sent from the other device to your PC.
       A 'space' voltage means that your PC may send some data.
       It is usually used to regulate the flow of serial data from your
       PC, but it is not currently supported by all UNIX flavours.
      
 RTS - Request to send

       Is set to the 'space' voltage by your PC when it requests to send
       more data. It also used to regulate data flow. Many systems leave
       it on 'space' voltage all the time.
      
 7. Communication issues

 This section covers other issues of serial communication which might be
 relevant to your particular application.
 Since we are programming for asynchronous communication, we need the
 PCs/devices to know where each character starts and ends in the serial
 data flow.

 In asynchronous mode, the serial data line stays in the mark state until
 a character is sent. A 'start bit' is sent before each character; it is
 always 0 and tells the PC/device that a character will follow.
 After the start bit, the character's bits are sent, then a 'parity' bit,
 and one or more stop bits.

 The parity bit is a checksum of the data bits, indicating the number of
 1 bits it contained -

    Even parity  - parity bit is 1 if there is an even number of 1s
    Odd parity   - parity bit is 1 if there is an odd number of 1s
    Space parity - parity bit is always 0
    Mark parity  - parity bit is 1
    No parity    - no parity bit is sent or present.

 'Stop' bits come at the end of every character. There may be 1, 1.5, or 2
 stop bits. They used to be used to give the computer time to process the
 character, but now they are used to synchronise the computer to the
 incoming characters.

 Asynchronous data is usually described like '8N1' - 8 data bits, no parity
 bits, 1 stop bit. Another common one is '7N1'.

 Flow control is used to regulate the data flow between devices, if there
 is some sort of limitation, such as a slow device. There is 'Software
 Flow Control' using special characters, XON and XOFF, to regulate the flow.
 This method is not useful for transmitting non-textual data.
 'Hardware Flow Control' uses the RTS and CTS signals instead of special
 characters. The receiver sets CTS to space when it is ready to receive,
 and to mark when it's not. The sender uses RTS the same way. This method
 is faster than Software Flow Control, since it uses a separate set of
 signals instead of extra bits.

 Since the receive or transmit signal is at mark voltage until a new character
 is sent. A 'break' condition exists when the line is set to low for 1/4
 to 1/2 a second. It is used to reset a communications line, or change
 the operation mode of devices like modems.

 8. Basic port programming

 Hopefully, all of the above is reasonably clear to you, so you may proceed
 to program with confidence!

 In UNIX all system devices are treated as (special) files. All serial ports
 are opened, read from, written to, and closed, just like a binary file.
 In Linux, the PC serial ports are

    COM1 - /dev/ttyS0
    COM2 - /dev/ttyS1
    COM3 - /dev/ttyS2
    COM4 - /dev/ttyS3

 Firstly, open the serial port as a file. However, UNIX does not allow
 devices to be accessed by normal users. To solve this, either run the
 program as the superuser, or change the permission on the device as root,
 eg

    chmod a+rw /dev/ttyS1          (lets everyone access COM2)

 To open the file do the following. Notice the three flags used in the
 open() function. O_RDWR means that we open the port for reading and
 writing. O_NOCTTY specifies that the program won't be the controlling
 entity for the port. Most user programs don't want this feature.
 O_NDELAY means that your program ignores the DCD line. If it didn't,
 the program will be put to sleep until DCD is set to 'space' voltage.

 /*
 * 'open_port()' - Open serial port 1 - COM2.
 *
 * Returns the file descriptor on success or -1 on error.
 */

int open_port(void)
{
  int fd;                                   /* File descriptor for the port */

  fd = open("/dev/ttyS1", O_RDWR | O_NOCTTY | O_NDELAY);
  if (fd == -1)
  {                                              /* Could not open the port */
    fprintf(stderr, "open_port: Unable to open /dev/ttyS1 - %s\n",
            strerror(errno));
  }

  return (fd);
}

If you need to write data to the port, do something like

  n = write(fd, "ATZ\r", 4);

  if (n < 0)
     puts("write() of 4 bytes failed!\n");

Reading from the port is more complicated. If you open the port in 'raw
data' mode (the norm), each read() returns the number of characters actually
available in the serial buffers. However, if no characters are available,
read() will block until it receives characters, an interval timer expires,
or an error occurs. Use the following to make read return immediately.
FNDELAY makes read() return 0 if no characters were read.

  fcntl(mainfd, F_SETFL, FNDELAY);             /* Configure port reading */

To close the serial port, simply use

  close(fd);

9. Port configuration

This section discusses how to configure the serial port for your device.
You will need to set the terminal attributes related to the port.
To do this, include  and access the termios structure using the
POSIX tcgetattr() and tcsetattr() functions.

The termios structure contains

  c_cflag - Control options
  c_lflag - Line options
  c_iflag - Input options
  c_oflag - Output options
  c_cc    - Control characters
 
See section 12 for a list of c_cflag control modes.
They are used to set the baud rate, parity and stop bits, and flow control.
Always enable CLOCAL and CREAD, so the program does not own the port, and so
the serial interface driver will read incoming bytes.

9.1. Accessing the termios structure and the baud rate

Use cfsetospeed() and cfsetispeed() to set the baud rate.
CRTSCTS might be called CNEW_RTSCTS on other systems.
The following uses a termios structure called 'options'.
For our project, the device transmitted at 9600 baud and transmitted nothing
special.

tcgetattr(mainfd, &options);        /* Get the current options for the port */
cfsetispeed(&options, B9600);                 /* Set the baud rates to 9600 */
cfsetospeed(&options, B9600);   
                                  /* Enable the receiver and set local mode */
options.c_cflag |= (CLOCAL | CREAD);
     
                                       /* Set the new options for the port */
tcsetattr(mainfd, TCSANOW, &options);

The tcsetattr() function replaces the port's termios structure with the
settings you provided. The TCSANOW constant means that the changes should
occur immediately, without waiting for data transmission to complete.
Alternative choices are TCSADRAIN and TCSAFLUSH, which wait until buffers
are cleared. Refer to section 13.

9.2. Character size and parity

To set the character size, you must use bitwise logic.
The following code sets the character size to 8 data bits, and no parity.
                       
   options.c_cflag &= ~PARENB;  /* Mask character size to 8 bits, no parity */
   options.c_cflag &= ~CSTOPB;
   options.c_cflag &= ~CSIZE;
   options.c_cflag |=  CS8;                           /* Select 8 data bits */

For other methods, refer to section 11.

9.3. Hardware flow control

To enable hardware flow control, use

    options.c_cflag |= CRTSCTS;            /* Enable hardware flow control */ 

To disable it,

    options.c_cflag &= ~CRTSCTS;          /* Disable hardware flow control */ 

9.4. Canonical and raw input

Canonical input means that all incoming characters are placed in a buffer
which may be edited by the user, until a carriage return or line feed (CR or
LF) are received. Typically, you would use

 options.c_lflag |= ~(ICANON | ECHO | ECHOE);

Raw input is unprocessed, so they may be used as they are read.
Our device sent raw data.

 options.c_lflag &= ~(ICANON | ECHO | ISIG);

Whether you use canonical or raw input, make sure you never enable input
echo when connected to a computer/device which is echoing characters to you.
Refer to section 14 for local mode constants.

9.5. POSIX input modes

Set the port's input modes for any input processing.
Set input parity when you have enabled parity in the c_cflag part.
Usually you'd use the following to enable parity checking, and strip the
parity bit off the data, before your program reads it.

 options.c_iflag |= (INPCK | ISTRIP);

You might use IGNPAR, which ignores all parity errors. PARMRK marks parity
errors by inserting a DEL(255) and NUL character before the bad character.
If IGNPAR is enabled, only a NUL is inserted.

You may set software flow control using

 options.c_iflag |= (IXON | IXOFF | IXANY);

Refer to section 15 for input mode constants.

9.6. POSIX output modes

To set port output modes, use the c_oflag member.
To select processed output, use the following. Of all the output modes, you
will probably only use ONCLR to convert newlines into CR and LFs.

 options.c_oflag |= OPOST;

For raw output, use

 options.c_oflag &= ~OPOST;

Refer to section 16 for output mode constants.

9.7. POSIX control modes

You may set the control characters using the c_cc part.
Set the software flow control characters in the VSTART and VSTOP
elements. The standard is DC1(17) and DC3(19) for XON and XOFF.
VMIN specifies the minimum number of 0 to read. If it is 0, then
VTIME specifies the time to wait for each character.
If VMIN is not 0, VTIME is the time to wait to read the first character.
If the first character is read, then any read() will be blocked until all
VMIN characters are read.
VTIME is specified in tenths of seconds. If it is 0, then read()s will
be permanently blocked unless NDELAY was previously specified with fcntl().

Refer to section 17 for control mode constants.

10. Sample program

This program is a skeleton COM2 reader, which was used for our project.
It did not need all of the information specified above for
configuring ports. The 20ms delay is used to indicate that data coming into
the port is buffered, and is available for the next read().

/* Better port reading program
  v1.0
  23-10-96
 
  This test program uses quasi-POSIX compliant UNIX functions to
  open the ABU port and read.
 
  Uses termio functions to initialise the port to 9600 baud, at
  8 data bits, no parity, no hardware flow control,
  and features character buffering.
  The 20ms delay after the port read indicates that characters are
  buffered if a button is pressed many times.
 
  This program was derived from instructions at
   http://www.easysw.com/~mike/serial/
*/

#include    /* Standard input/output definitions */
#include   /* String function definitions */
#include   /* UNIX standard function definitions */
#include    /* File control definitions */
#include    /* Error number definitions */
#include  /* POSIX terminal control definitions */

/*
 * 'open_port()' - Open serial port 1.
 *
 * Returns the file descriptor on success or -1 on error.
 */

int open_port(void)
{
  int fd;                                   /* File descriptor for the port */

  fd = open("/dev/ttyS1", O_RDWR | O_NOCTTY | O_NDELAY);

  if (fd == -1)
  {                                              /* Could not open the port */
    fprintf(stderr, "open_port: Unable to open /dev/ttyS1 - %s\n",
            strerror(errno));
  }

  return (fd);
}

void main()
{
int mainfd=0;                                            /* File descriptor */
char chout;
struct termios options;
 
mainfd = open_port();

fcntl(mainfd, F_SETFL, FNDELAY);                  /* Configure port reading */
                                    /* Get the current options for the port */
tcgetattr(mainfd, &options);
cfsetispeed(&options, B9600);                 /* Set the baud rates to 9600 */
cfsetospeed(&options, B9600);
  
                                  /* Enable the receiver and set local mode */
options.c_cflag |= (CLOCAL | CREAD);
options.c_cflag &= ~PARENB; /* Mask the character size to 8 bits, no parity */
options.c_cflag &= ~CSTOPB;
options.c_cflag &= ~CSIZE;
options.c_cflag |=  CS8;                              /* Select 8 data bits */
options.c_cflag &= ~CRTSCTS;               /* Disable hardware flow control */ 

                                /* Enable data to be processed as raw input */
options.c_lflag &= ~(ICANON | ECHO | ISIG);
     
                                       /* Set the new options for the port */
tcsetattr(mainfd, TCSANOW, &options);
                       
while (1)
{
  read(mainfd, &chout, sizeof(chout));          /* Read character from ABU */
 
  if (chout != 0)
     printf("Got %c.\n", chout);

  chout=0;
  usleep(20000);
}
                                                   /* Close the serial port */
 close(mainfd);
}

11. Character and parity settings

   No parity (8N1):

    options.c_cflag &= ~PARENB;
    options.c_cflag &= ~CSTOPB;
    options.c_cflag &= ~CSIZE;
    options.c_cflag |= CS8;

   Even parity (7E1):

    options.c_cflag |= PARENB;
    options.c_cflag &= ~PARODD;
    options.c_cflag &= ~CSTOPB;
    options.c_cflag &= ~CSIZE;
    options.c_cflag |= CS7;

   Odd parity (7O1):

    options.c_cflag |= PARENB;
    options.c_cflag |= PARODD;
    options.c_cflag &= ~CSTOPB;
    options.c_cflag &= ~CSIZE;
    options.c_cflag |= CS7;

   Mark parity is simulated by using 2 stop bits (7M1):

    options.c_cflag &= ~PARENB;
    options.c_cflag |= CSTOPB;
    options.c_cflag &= ~CSIZE;
    options.c_cflag |= CS7;

   Space parity is setup the same as no parity (7S1):

    options.c_cflag &= ~PARENB;
    options.c_cflag &= ~CSTOPB;
    options.c_cflag &= ~CSIZE;
    options.c_cflag |= CS8;

12. POSIX control mode flags

The following table lists the possible control modes for c_cflag. 
 
  Constant     Description
  ________________________
 
  CBAUD        Bit mask for baud rate        
  B0           0 baud (drop DTR)        
  B50          50 baud        
  B75          75 baud        
  B110         110 baud        
  B134         134.5 baud        
  B150         150 baud        
  B200         200 baud        
  B300         300 baud        
  B600         600 baud        
  B1200        1200 baud        
  B1800        1800 baud        
  B2400        2400 baud        
  B4800        4800 baud        
  B9600        9600 baud        
  B19200       19200 baud        
  B38400       38400 baud        
  EXTA         External rate clock        
  EXTB         External rate clock        
  CSIZE        Bit mask for data bits        
  CS5          5 data bits        
  CS6          6 data bits        
  CS7          7 data bits        
  CS8          8 data bits        
  CSTOPB       2 stop bits (1 otherwise)        
  CREAD        Enable receiver        
  PARENB       Enable parity bit        
  PARODD       Use odd parity instead of even        
  HUPCL        Hangup (drop DTR) on last close        
  CLOCAL       Local line - do not change 'owner' of port     
  LOBLK        Block job control output        
  CRTSCTS      Enable hardware flow control (not supported on all platforms)        

13. POSIX tcsetattr Constants

  Constant   Description
  ______________________
 
  TCSANOW    Make changes now without waiting for data to complete
  TCSADRAIN  Wait until everything has been transmitted
  TCSAFLUSH  Flush input and output buffers and make the change

14. POSIX Local Mode Constants

  Constant   Description
  ______________________
 
  ISIG       Enable SIGINTR, SIGSUSP, SIGDSUSP, and SIGQUIT signals
  ICANON     Enable canonical input (else raw)
  XCASE      Map uppercase \lowercase (obselete)
  ECHO       Enable echoing of input characters
  ECHOE      Echo erase character as BS-SP-BS
  ECHOK      Echo NL after kill character
  ECHONL     Echo NL
  NOFLSH     Disable flushing of input buffers after interrupt
             or quit characters
  IEXTEN     Enable extended functions
  ECHOCTL    Echo control characters as ^char and delete as ~?
  ECHOPRT    Echo erased character as character erased
  ECHOKE     BS-SP-BS entire line on line kill
  FLUSHO     Output being flushed
  PENDIN     Retype pending input at next read or input char
  TOSTOP     Send SIGTTOU for background output

15. POSIX Input Mode Constants

  Constant   Description
  ______________________
 
  INPCK      Enable parity check
  IGNPAR     Ignore parity errors
  PARMRK     Mark parity errors
  ISTRIP     Strip parity bits
  IXON       Enable software flow control (outgoing)
  IXOFF      Enable software flow control (incoming)
  IXANY      Allow any character to start flow again
  IGNBRK     Ignore break condition
  BRKINT     Send a SIGINT when a break condition is detected
  INLCR      Map NL to CR
  IGNCR      Ignore CR
  ICRNL      Map CR to NL
  IUCLC      Map uppercase to lowercase
  IMAXBEL    Echo BEL on input line too long

16. POSIX Output Mode Constants

  Constant   Description
  ______________________
 
  OPOST      Postprocess output (not set = raw output)
  OLCUC      Map lowercase to uppercase
  ONLCR      Map NL to CR-NL
  OCRNL      Map CR to NL
  NOCR       No CR output at column 0
  ONLRET     NL performs CR function
  OFILL      Use fill characters for delay
  OFDEL      Fill character is DEL
  NLDLY      Mask for delay time needed between lines
  NL0        No delay for NLs
  NL1        Delay further output after newline for 100 milliseconds
  CRDLY      Mask for delay time needed to return carriage to left column
  CR0        No delay for CRs
  CR1        Delay after CRs depending on current column position
  CR2        Delay 100 milliseconds after sending CRs
  CR3        Delay 150 milliseconds after sending CRs
  TABDLY     Mask for delay time needed after TABs
  TAB0       No delay for TABs
  TAB1       Delay after TABs depending on current column position
  TAB2       Delay 100 milliseconds after sending TABs
  TAB3       Expand TAB characters to spaces
  BSDLY      Mask for delay time needed after BSs
  BS0        No delay for BSs
  BS1        Delay 50 milliseconds after sending BSs
  VTDLY      Mask for delay time needed after VTs
  VT0        No delay for VTs
  VT1        Delay 2 seconds after sending VTs
  FFDLY      Mask for delay time needed after FFs
  FF0        No delay for FFs
  FF1        Delay 2 seconds after sending FFs

17. POSIX Control Character Constants

  Constant   Description          Key
  ______________________________________
 
  VINTR      Interrupt            CTRL-C
  VQUIT      Quit                 CTRL-Z
  VERASE     Erase                Backspace (BS)
  VKILL      Kill-line            CTRL-U
  VEOF       End-of-file          CTRL-D
  VEOL       End-of-line          Carriage return (CR)
  VEOL2      Second end-of-line   Line feed (LF)
  VMIN       Minimum number of characters to read
  VTIME      Time to wait for data (tenths of seconds)

----------------- End of Linux Serial Programming Mini-Howto -----------------

More MInicom Options

2008-05-27T22:42:00.001-07:00

Minicom is a serial communication program to access a network or security device through its console port.
This tool is similar to Hyper Terminal, which is by default available on a Microsoft Windows system.

Let's install Minicom:

#apt-get install minicom

Check if you have active serial ports:

#dmesg | grep tty

[17179573.660000] serial8250: ttyS0 at I/O 0x3f8 (irq = 4) is a 16550A
[17179573.660000] serial8250: ttyS1 at I/O 0x2f8 (irq = 3) is a 16550A

The read and write permissions are required on the /dev/ttyS0 file. The dialout group, which is the default group owner of the file, has already these rights.
You can see it with the following command:

#ls -la /dev | grep ttyS0

crw-rw---- 1 root dialout 4, 64 2007-02-26 22:55 ttyS0

If the permissions are not set as above, you can configure them as follow:

#chown root /dev/ttyS0
#chgrp dialout /dev/ttyS0
#chmod 660 /dev/ttyS0

Now we are ready to add your Debian or Ubuntu user in the dialout group:

#adduser your_user dialout

To see which users are members of the dialout group, open the /etc/group file and look for the line beginning with dialout.

#cat /etc/group | grep dialout

dialout:x:20:cupsys,your_user

We can now start Minicom:

#minicom -s

To leave Minicom: Ctlr A -> Z -> X
The default config will be saved as /etc/minicom/minirc.dfl
The next time you want to use Minicom you just have to enter the following command:

#minicom

To save your Minicom settings on a specific file:

#minicom -s

The config will be saved as /etc/minicom/minirc.config1
To start Minicom with settings configured on a specific file:

#minicom -s config1

Receiving

2008-05-27T01:07:00.000-07:00

Receiving bytes by a serial port is similar to sending them only it's in the opposite direction. It's also interrupt driven. For the obsolete type of serial port with 1-byte buffers, when a byte is fully received from the external cable it goes into the 1-byte receive buffer. Then the port gives the CPU an interrupt to tell it to pick up that byte so that the serial port will have room for storing the next byte which is currently being received. For newer serial ports with 16-byte buffers, this interrupt (to fetch the bytes) may be sent after 14 bytes are in the receive buffer. The CPU then stops what it was doing, runs the interrupt service routine, and picks up 14 to 16 bytes from the port. For an interrupt sent when the 14th byte has been received, there could be 16 bytes to get if 2 more bytes have arrived since the interrupt. But if 3 more bytes should arrive (instead of 2), then the 16-byte buffer will overrun. It also may pick up less than 14 bytes by setting it that way or due to timeouts

FIFOs

To understand the differences between dumb and FIFO (First In, First Out queue discipline) first let's examine what happens when a UART has sent or received a byte. The UART itself can't do anything with the data passing thru it, it just receives and sends it. For the obsolete dumb UARTS, the CPU gets an interrupt from the serial device every time a byte has been sent or received. The CPU then moves the received byte out of the UART's buffer and into memory somewhere, or gives the UART another byte to send. The obsolete 8250 and 16450 UARTs only have a 1 byte buffer. That means, that every time 1 byte is sent or received, the CPU is interrupted. At low transfer rates, this is OK. But, at high transfer rates, the CPU gets so busy dealing with the UART, that is doesn't have time to adequately tend to other tasks. In some cases, the CPU does not get around to servicing the interrupt in time, and the byte is overwritten, because they are coming in so fast. This is called an "overrun" or "overflow".

FIFO UARTs help solve this problem. The 16550A (or 16550) FIFO chip comes with 16 byte FIFO buffers. This means that it can receive up to 14 bytes (or send 16 bytes) before it has to interrupt the CPU. Not only can it wait for more bytes, but the CPU then can transfer all (14 to 16) bytes at a time. This is a significant advantage over the obsolete UARTs, which only had 1 byte buffers. The CPU receives less interrupts, and is free to do other things. Data is rarely lost. Note that the interrupt threshold of FIFO buffers (trigger level) may be set at less than 14. 1, 4 and 8 are other possible choices. As of late 2000 there was no way the Linux user could set these directly (setserial can't do it). While many PC's only have a 16550 with 16-byte buffers, better UARTS have even larger buffers.

Note that the interrupt is issued slightly before the buffer gets full (at say a "trigger level" of 14 bytes for a 16-byte buffer). This allows room for a couple more bytes to be received before the interrupt service routine is able to actually fetch all these bytes. The trigger level may be set to various permitted values by kernel software. A trigger level of 1 will be almost like an obsolete UART (except that it still has room for 15 more bytes after it issues the interrupt).

Now consider the case where you're on the Internet. It's just sent you a short webpage of text. All of this came in thru the serial port. If you had a 16-byte buffer on the serial port which held back characters until it had 14 of them, some of the last several characters on the screen might be missing as the FIFO buffer waited to get the 14th character. But the 14th character doesn't arrive since you've been sent the entire page (over the phone line) and there are no more characters to send to you. It could be that these last characters are part of the HTML formatting, etc. and are not characters to display on the screen but you don't want to lose format either.

There is a "timeout" to prevent the above problem. The "timeout" works like this for the receive UART buffer: If characters arrive one after another, then an interrupt is issued only when say the 14th character reaches the buffer. But if a character arrives and the next character doesn't arrive soon thereafter, then an interrupt is issued anyway. This results in fetching all of the characters in the FIFO buffer, even if only a few (or only one) are present. There is also "timeout" for the transmit buffer as well

Why FIFO Buffers are Small

You may wonder why the FIFO buffers are not larger. After all, memory is cheap and it wouldn't cost much more to use buffers in the kilo-byte range. The reason is flow control. Flow control stops the flow of data (bytes) on serial line when necessary. If a stop signal is sent to serial port, then the stop request is handled by software (even if the flow control is "hardware"). The serial port hardware knows nothing about flow control.

If the serial port buffer contains 64 bytes ready to send when it receives a flow control signal to stop sending, it will send out the 64 bytes anyway in violation of the stop request. There is no stopping it since it doesn't know about flow control. If the buffer was large, then many more bytes would be sent in violation of flow control's request to stop.

Transmitting

2008-05-27T01:04:00.000-07:00

Transmitting is sending bytes out of the serial port away from the computer. Once you understand transmitting, receiving is easy to understand since it's similar. The first explanation given here will be grossly oversimplified. Then more detail will be added in later explanations. When the computer wants to send a byte out the serial port (to the external cable) the CPU sends the byte on the bus inside the computer to the I/O (Input Output) address of the serial port. I/O is often written as just IO. The serial port takes the byte, and sends it out one bit at a time (a serial bit-stream) on the transmit pin of the serial cable connector. For what a bit (and byte) look like electrically see Voltage Waveshapes.

Here's a replay of the above in a little more detail (but still very incomplete). Most of the work at the serial port is done by the UART chip (or the like). To transmit a byte, the serial device driver program (running on the CPU) sends a byte to the serial port"s I/O address. This byte gets into a 1-byte "transmit shift register" in the serial port. From this shift register bits are taken from the byte one-by-one and sent out bit-by-bit on the serial line. Then when the last bit has been sent and the shift register needs another byte to send it could just ask the CPU to send it another byte. Thus would be simple but it would likely introduce delays since the CPU might not be able to get the byte immediately. After all, the CPU is usually doing other things besides just handling the serial port.

A way to eliminate such delays is to arrange things so that the CPU gets the byte before the shift register needs it and stores it in a serial port buffer (in hardware). Then when the shift register has sent out its byte and needs a new byte immediately, the serial port hardware just transfers the next byte from its own buffer to the shift register. No need to call the CPU to fetch a new byte.

The size of this serial port buffer was originally only one byte, but today it is usually 16 bytes (more in higher priced serial ports). Now there is still the problem of keeping this buffer sufficiently supplied with bytes so that when the shift register needs a byte to transmit it will always find one there (unless there are no more bytes to send). This is done by contacting the CPU using an interrupt.

First we'll explain the case of the old fashioned one-byte buffer, since 16-byte buffers work similarly (but are more complex). When the shift register grabs the byte out of the buffer and the buffer needs another byte, it sends an interrupt to the CPU by putting a voltage on a dedicated wire on the computer bus. Unless the CPU is doing something very important, the interrupt forces it to stop what it was doing and start running a program which will supply another byte to the port's buffer. The purpose of this buffer is to keep an extra byte (waiting to be sent) queued in hardware so that there will be no gaps in the transmission of bytes out the serial port cable.

Once the CPU gets the interrupt, it will know who sent the interrupt since there is a dedicated interrupt wire for each serial port (unless interrupts are shared). Then the CPU will start running the serial device driver which checks registers at I/0 addresses to find out what has happened. It finds out that the serial's transmit buffer is empty and waiting for another byte. So if there are more bytes to send, it sends the next byte to the serial port's I/0 address. This next byte should arrive when the previous byte is still in the transmit shift register and is still being transmitted bit-by-bit.

In review, when a byte has been fully transmitted out the transmit wire of the serial port and the shift register is now empty the following 3 things happen almost simultaneously:

The next byte is moved from the transmit buffer into the transmit shift register
The transmission of this new byte (bit-by-bit) begins
Another interrupt is issued to tell the device driver to send yet another byte to the now empty transmit buffer

Thus we say that the serial port is interrupt driven. Each time the serial port issues an interrupt, the CPU sends it another byte. Once a byte has been sent to the transmit buffer by the CPU, then the CPU is free to pursue some other activity until it gets the next interrupt. The serial port transmits bits at a fixed rate which is selected by the user (or an application program). It's sometimes called the baud rate. The serial port also adds extra bits to each byte (start, stop and perhaps parity bits) so there are often 10 bits sent per byte. At a rate (also called speed) of 19,200 bits per second (bps), there are thus 1,920 bytes/sec (and also 1,920 interrupts/sec).

Doing all this is a lot of work for the CPU. This is true for many reasons. First, just sending one 8-bit byte at a time over a 32-bit data bus (or even 64-bit) is not a very efficient use of bus width. Also, there is a lot of overhead in handing each interrupt. When the interrupt is received, the device driver only knows that something caused an interrupt at the serial port but doesn't know that it's because a character has been sent. The device driver has to make various checks to find out what happened. The same interrupt could mean that a character was received, one of the control lines changed state, etc.

A major improvement has been the enlargement of the buffer size of the serial port from 1-byte to 16-bytes. This means that when the CPU gets an interrupt it gives the serial port up to 16 new bytes to transmit. This is fewer interrupts to service but data must still be transferred one byte at a time over a wide bus. The 16-byte buffer is actually a FIFO (First In First Out) queue and is often called a FIFO. See FIFOs for details about the FIFO along with a repeat of some of the above info.