busybox/docs/Serial-Programming-HOWTO.txt
<<
>>
Prefs
   1Downloaded from http://www.lafn.org/~dave/linux/Serial-Programming-HOWTO.txt
   2Seems to be somewhat old, but contains useful bits for getty.c hacking
   3============================================================================
   4
   5  The Linux Serial Programming HOWTO, Part 1 of 2
   6  By Vernon C. Hoxie
   7  v2.0 10 September 1999
   8
   9  This document describes how to program communications with devices
  10  over a serial port on a Linux box.
  11  ______________________________________________________________________
  12
  13  Table of Contents
  14
  15  1. Copyright
  16
  17  2. Introduction
  18
  19  3. Opening
  20
  21  4. Commands
  22
  23  5. Changing Baud Rates
  24
  25  6. Additional Control Calls
  26
  27     6.1 Sending a "break".
  28     6.2 Hardware flow control.
  29     6.3 Flushing I/O buffers.
  30
  31  7. Modem control
  32
  33  8. Process Groups
  34
  35     8.1 Sessions
  36     8.2 Process Groups
  37     8.3 Controlling Terminal
  38        8.3.1 Get the foreground group process id.
  39        8.3.2 Set the foreground process group id of a terminal.
  40        8.3.3 Get process group id.
  41
  42  9. Lockfiles
  43
  44  10. Additional Information
  45
  46  11. Feedback
  47
  48  ______________________________________________________________________
  49
  50  1.  Copyright
  51
  52  The Linux Serial-Programming-HOWTO is copyright (C) 1997 by Vernon
  53  Hoxie.  Linux HOWTO documents may be reproduced and distributed in
  54  whole or in part, in any medium physical or electronic, as long as
  55  this copyright notice is retained on all copies. Commercial
  56  redistribution is allowed and encouraged; however, the author would
  57  like to be notified of any such distributions.
  58
  59  All translations, derivative works, or aggregate works incorporating
  60  this Linux HOWTO document must be covered under this copyright notice.
  61  That is, you may not produce a derivative work from this HOWTO and
  62  impose additional restrictions on its distribution.
  63
  64  This version is a complete rewrite of the previous Serial-Programming-
  65  HOWTO  by Peter H. Baumann,  <mailto:Peter.Baumann@dlr.de>
  66
  67  2.  Introduction
  68
  69  This HOWTO will attempt to give hints about how to write a program
  70  which needs to access a serial port.  Its principal focus will be on
  71  the Linux implementation and what the meaning of the various library
  72  functions available.
  73
  74  Someone asked about which of several sequences of operations was
  75  right.  There is no absolute right way to accomplish an outcome.  The
  76  options available are too numerous.  If your sequences produces the
  77  desired results, then that is the right way for you.  Another
  78  programmer may select another set of options and get the same results.
  79  His method is right for him.
  80
  81  Neither of these methods may operate properly with some other
  82  implementation of UNIX.  It is strange that many of the concepts which
  83  were implemented in the SYSV version have been dumped.  Because UNIX
  84  was developed by AT&T and much code has been generated on those
  85  concepts, the AT&T version should be the standard to which others
  86  should emulate.
  87
  88  Now the standard is POSIX.
  89
  90  It was once stated that the popularity of UNIX and C was that they
  91  were created by programmers for programmers.  Not by scholars who
  92  insist on purity of style in deference to results and simplicity of
  93  use.  Not by committees with people who have diverse personal or
  94  proprietary agenda.  Now ANSI and POSIX have strayed from those
  95  original clear and simply concepts.
  96
  97  3.  Opening
  98
  99  The various serial devices are opened just as any other file.
 100  Although, the fopen(3) command may be used, the plain open(2) is
 101  preferred.  This call returns the file descriptor which is required
 102  for the various commands that configure the interface.
 103
 104  Open(2) has the format:
 105
 106       #include <fcntl.h>
 107       int open(char *path, int flags, [int mode]);
 108
 109  In addition to the obvious O_RDWR, O_WRONLY and O_RDONLY, two
 110  additional flags are available.  These are O_NONBLOCK and O_NOCTTY.
 111  Other flags listed in the open(2) manual page are not applicable to
 112  serial devices.
 113
 114  Normally, a serial device opens in "blocking" mode.  This means that
 115  the open() will not return until the Carrier Detect line from the port
 116  is active, e.g. modem, is active.  When opened with the O_NONBLOCK
 117  flag set, the open() will return immediately regardless of the status
 118  of the DCD line.  The "blocking" mode also affects the read() call.
 119
 120  The fcntl(2) command can be used to change the O_NONBLOCK flag anytime
 121  after the device has been opened.
 122
 123  The device driver and the data passing through it are controlled
 124  according to settings in the struct termios.  This structure is
 125  defined in "/usr/include/termios.h".  In the Linux tree, further
 126  reference is made to "/usr/include/asm/termbits.h".
 127  In blocking mode, a read(2) will block until data is available or a
 128  signal is received.  It is still subject to state of the ICANON flag.
 129
 130  When the termios.c_lflag ICANON bit is set, input data is collected
 131  into strings until a NL, EOF or EOL character is received.  You can
 132  define these in the termios.c_cc[] array.  Also, ERASE and KILL
 133  characters will operate on the incoming data before it is delivered to
 134  the user.
 135
 136  In non-canonical mode, incoming data is quantified by use of the
 137  c_cc[VMIN and c_cc[VTIME] values in termios.c_cc[].
 138
 139  Some programmers use the select() call to detect the completion of a
 140  read().  This is not the best way of checking for incoming data.
 141  Select() is part of the SOCKETS scheme and too complex for most
 142  applications.
 143
 144  A full explanation of the fields of the termios structure is contained
 145  in termios(7) of the Users Manual.  A version is included in Part 2 of
 146  this HOWTO document.
 147
 148  4.  Commands
 149
 150  Changes to the struct termios are made by retrieving the current
 151  settings, making the desired changes and transmitting the modified
 152  structure back to the kernel.
 153
 154  The historic means of communicating with the kernel was by use of the
 155  ioctl(fd, COMMAND, arg) system call.  Then the purists in the
 156  computer industry decided that this was not genetically consistent.
 157  Their argument was that the argument changed its stripes.  Sometimes
 158  it was an int, sometimes it was a pointer to int and other times it
 159  was a pointer to struct termios.  Then there were those times it was
 160  empty or NULL.  These variations are dependent upon the COMMAND.
 161
 162  As a alternative, the tc* series of functions were concocted.
 163
 164  These are:
 165
 166       int tcgetattr(int filedes, struct termios *termios_p);
 167       int tcsetattr(int filedes, int optional_actions,
 168                     const struct termios *termios_p);
 169
 170  instead of:
 171
 172       int ioctl(int filedes, int command,
 173                 struct termios *termios_p);
 174
 175  where command is TCGETS or one of TCSETS, TCSETSW or TCSETSF.
 176
 177  The TCSETS command is comparable to the TCSANOW optional_action for
 178  the tc* version.  These direct the kernel to adopt the changes
 179  immediately.  Other pairs are:
 180
 181    command   optional_action   Meaning
 182    TCSETSW   TCSADRAIN         Change after all output has drained.
 183    TCSETSF   TCSAFLUSH         Change after all output has drained
 184                                then discard any input characters
 185                                not read.
 186
 187  Since the return code from either the ioctl(2) or the tcsetattr(2)
 188  commands only indicate that the command was processed by the kernel.
 189  These do not indicate whether or not the changes were actually
 190  accomplished.  Either of these commands should be followed by a call
 191  to:
 192
 193       ioctl(fd, TCGETS, &new_termios);
 194
 195  or:
 196
 197       tcgetattr(fd, &new_termios);
 198
 199  A user function which makes changes to the termios structure should
 200  define two struct termios variables.  One of these variables should
 201  contain the desired configuration.  The other should contain a copy of
 202  the kernels version.  Then after the desired configuration has been
 203  sent to the kernel, another call should be made to retrieve the
 204  kernels version.  Then the two compared.
 205
 206  Here is an example of how to add RTS/CTS flow control:
 207
 208       struct termios my_termios;
 209       struct termios new_termios;
 210
 211       tcgetattr(fd, &my_termios);
 212       my_termios.c_flag |= CRTSCTS;
 213       tcsetattr(fd, TCSANOW, &my_termios);
 214       tcgetattr(fd, &new_termios);
 215       if (memcmp(my_termios, new_termios,
 216            sizeof(my_termios)) != 0) {
 217           /* do some error handling */
 218       }
 219
 220  5.  Changing Baud Rates
 221
 222  With Linux, the baud rate can be changed using a technique similar to
 223  add/delete RTS/CTS.
 224
 225  struct termios my_termios;
 226  struct termios new_termios;
 227
 228  tcgetattr(fd, &my_termios);
 229  my_termios.c_flag &= ~CBAUD;
 230  my_termios.c_flag |= B19200;
 231  tcsetattr(fd, TCSANOW, &my_termios);
 232  tcgetattr(fd, &new_termios);
 233  if (memcmp(my_termios, new_termios,
 234       sizeof(my_termios)) != 0) {
 235      /* do some error handling */
 236  }
 237
 238  POSIX adds another method.  They define:
 239
 240       speed_t cfgetispeed(const struct termios *termios_p);
 241       speed_t cfgetospeed(const struct termios *termios_p);
 242
 243  library calls to extract the current input or output speed from the
 244  struct termios pointed to with *termio_p.  This is a variable defined
 245  in the calling process.  In practice, the data contained in this
 246  termios, should be obtained by the tcgetattr() call or an ioctl() call
 247  using the TCGETS command.
 248
 249  The companion library calls are:
 250
 251       int cfsetispeed(struct termios *termios_p, speed_t speed);
 252       int cfsetospeed(struct termios *termios_p, speed_t speed);
 253
 254  which are used to change the value of the baud rate in the locally
 255  defined *termios_p.  Following either of these calls, either a call to
 256  tcsetattr() or ioctl() with one of TCSETS, TCSETSW or TCSETSF as the
 257  command to transmit the change to the kernel.
 258
 259  The cf* commands are preferred for portability.  Some weird Unices use
 260  a considerably different format of termios.
 261
 262  Most implementations of Linux use only the input speed for both input
 263  and output.  These functions are defined in the application program by
 264  reference to <termios.h>.  In reality, they are in
 265  /usr/include/asm/termbits.h.
 266
 267  6.  Additional Control Calls
 268
 269  6.1.  Sending a "break".
 270
 271       int ioctl(fd, TCSBRK, int arg);
 272       int tcsendbreak(fd, int arg);
 273
 274  Send a break:  Here the action differs between the conventional
 275  ioctl() call and the POSIX call.  For the conventional call, an arg of
 276  '0' sets the break control line of the UART for 0.25 seconds.  For the
 277  POSIX command, the break line is set for arg times 0.1 seconds.
 278
 279  6.2.  Hardware flow control.
 280
 281       int ioctl(fd, TCXONC, int action);
 282       int tcflow(fd, int action);
 283
 284  The action flags are:
 285
 286  o  TCOOFF  0  suspend output
 287
 288  o  TCOON   1  restart output
 289
 290  o  TCIOFF  2  transmit STOP character to suspend input
 291
 292  o  TCION   3  transmit START character to restart input
 293
 294  6.3.  Flushing I/O buffers.
 295
 296       int ioctl(fd, TCFLSH, queue_selector);
 297       int tcflush(fd, queue_selector);
 298
 299  The queue_selector flags are:
 300
 301  o  TCIFLUSH  0  flush any data not yet read from the input buffer
 302
 303  o  TCOFLUSH  1  flush any data written to the output buffer but not
 304     yet transmitted
 305
 306  o  TCIOFLUSH 2  flush both buffers
 307
 308  7.  Modem control
 309
 310  The hardware modem control lines can be monitored or modified by the
 311  ioctl(2) system call.  A set of comparable tc* calls apparently do not
 312  exist.  The form of this call is:
 313
 314       int ioctl(fd, COMMAND, (int *)flags);
 315
 316  The COMMANDS and their action are:
 317
 318  o  TIOCMBIS  turn on control lines depending upon which bits are set
 319     in flags.
 320
 321  o  TIOCMBIC  turn off control lines depending upon which bits are
 322     unset in flags.
 323  o  TIOCMGET  the appropriate bits are set in flags according to the
 324     current status
 325
 326  o  TIOCMSET  the state of the UART is changed according to which bits
 327     are set/unset in 'flags'
 328
 329     The bit pattern of flags refer to the following control lines:
 330
 331  o  TIOCM_LE      Line enable
 332
 333  o  TIOCM_DTR     Data Terminal Ready
 334
 335  o  TIOCM_RTS     Request to send
 336
 337  o  TIOCM_ST      Secondary transmit
 338
 339  o  TIOCM_SR      Secondary receive
 340
 341  o  TIOCM_CTS     Clear to send
 342
 343  o  TIOCM_CAR     Carrier detect
 344
 345  o  TIOCM_RNG     Ring
 346
 347  o  TIOCM_DSR     Data set ready
 348
 349  It should be noted that some of these bits are controlled by the modem
 350  and the UART cannot change them but their status can be sensed by
 351  TIOCMGET.  Also, most Personal Computers do not provide hardware for
 352  secondary transmit and receive.
 353
 354  There are also a pair of ioctl() to monitor these lines.  They are
 355  undocumented as far as I have learned.  The commands are TIOCMIWAIT
 356  and TCIOGICOUNT.  They also differ between versions of the Linux
 357  kernel.
 358
 359  See the lines.c file in my "serial_suite" for an example of how these
 360  can be used see  <ftp://scicom.alphacd.com/pub/linux/serial_suite>
 361
 362  8.  Process Groups
 363
 364  8.1.  Sessions
 365
 366  8.2.  Process Groups
 367
 368  Any newly created process inherits the Process Group of its creator.
 369  The Process Group leader has the same PID as PGID.
 370
 371  8.3.  Controlling Terminal
 372
 373  There are a series of ioctl(2) and tc*(2) calls which can be used to
 374  monitor or to change the process group to which the device is
 375  attached.
 376
 377  8.3.1.  Get the foreground group process id.
 378
 379  If there is no foreground group, a number not representing an existing
 380  process group is returned.  On error, a -1 is returned and errno is
 381  set.
 382
 383       int ioctl(fd, TIOCGPGRP, (pid_t *)pid);
 384       int tcgetpgrp(fd, (pid_t *)pid);
 385
 386  8.3.2.  Set the foreground process group id of a terminal.
 387
 388  The fd must be the controlling terminal and be associated with the
 389  session of the calling process.
 390
 391       int ioctl(fd, TIOCSPGRP, (pid_t *)pid);
 392       int tcsetpgrp(fd, (pid_t *)pid);
 393
 394  8.3.3.  Get process group id.
 395
 396       int ioctl(fd, TIOCGPGRP, &(pid_t)pid);
 397       int tcgetpgrp(fd, &(pid_t)pid);
 398
 399  9.  Lockfiles
 400
 401  Any process which accesses a serial device should first check for the
 402  existence of lock file for the desired device.  If such a lock lock
 403  file exists, this means that the device may be in use by another
 404  process.
 405
 406  Check my "libdevlocks-x.x.tgz" at
 407  <ftp://scicom.alphacdc.com/pub/linux> for an example of how these lock
 408  files should be utilized.
 409
 410  10.  Additional Information
 411
 412  Check out my "serial_suite.tgz" for more information about programming
 413  the serial ports at   <mailto:vern@zebra.alphacdc.com>.  There some
 414  examples and some blurbs about setting up modems and comments about
 415  some general considerations.
 416
 417  11.  Feedback
 418
 419  Please send me any corrections, questions, comments, suggestions, or
 420  additional material. I would like to improve this HOWTO!  Tell me
 421  exactly what you don't understand, or what could be clearer.  You can
 422  reach me at  <mailto:vern@zebra.alphacdc.com> via email.  Please
 423  include the version number of the Serial-Programming-HOWTO when
 424  writing.
 425