sys-utils/cytune.8

   1 .\" cytune.8 --
   2 .\" Created: Sat Mar  4 17:44:53 1995 by faith@cs.unc.edu
   3 .\" Update: Sat Mar  4 18:22:24 1995 by faith@cs.unc.edu
   4 .\" Update: Sun Mar  5 06:40:12 1995 by njs@scifi.emi.net
   5 .\" Copyright 1995 Rickard E. Faith (faith@cs.unc.edu)
   6 .\"
   7 .\" Permission is granted to make and distribute verbatim copies of this
   8 .\" manual provided the copyright notice and this permission notice are
   9 .\" preserved on all copies.
  10 .\"
  11 .\" Permission is granted to copy and distribute modified versions of this
  12 .\" manual under the conditions for verbatim copying, provided that the
  13 .\" entire resulting derived work is distributed under the terms of a
  14 .\" permission notice identical to this one
  15 .\"
  16 .\" Since the Linux kernel and libraries are constantly changing, this
  17 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  18 .\" responsibility for errors or omissions, or for damages resulting from
  19 .\" the use of the information contained herein.  The author(s) may not
  20 .\" have taken the same level of care in the production of this manual,
  21 .\" which is licensed free of charge, as they might when working
  22 .\" professionally.
  23 .\"
  24 .\" Formatted or processed versions of this manual, if unaccompanied by
  25 .\" the source, must acknowledge the copyright and authors of this work.
  26 .\" "
  27 .TH CYTUNE 8 " 4 Mar 1995" "" "Linux Programmer's Manual"
  28 .SH NAME
  29 cytune \- Tune driver parameters for Cyclades-Z multiport serial card
  30 .SH SYNOPSIS
  31 .B cytune
  32 .RB [ \-q
  33 .RB [ \-i
  34 .IR interval ]]
  35 .RB [{ \-s | \-S }
  36 .IR value ]
  37 .RB [ \-g | \-G ]
  38 .RB [{ \-t | \-T }
  39 .IR timeout ]
  40 .IR tty ...
  41 .SH DESCRIPTION
  42 .B cytune
  43 queries and modifies the interruption threshold for the Cyclades driver.
  44 Each serial line on a Cyclades card has a 12-byte FIFO for input (and
  45 another 12-byte FIFO for output).  The "threshold" specifies how many input
  46 characters must be present in the FIFO before an interruption is raised.
  47 When a Cyclades tty is opened, this threshold is set to a default value
  48 based on baud rate:
  49 .sp
  50 .RS
  51     Baud        Threshold
  52 .sp
  53 50-4800            10
  54 .br
  55 9600                8
  56 .br
  57 19200               4
  58 .br
  59 38400               2
  60 .br
  61 57600-150000        1
  62 .RE
  63 .PP
  64 If the threshold is set too low, the large number of interruptions can load
  65 the machine and decrease overall system throughput.  If the threshold is set too high, the
  66 FIFO buffer can overflow, and characters will be lost.  Slower machines,
  67 however, may not be able to deal with the interrupt load, and will require
  68 that the threshold be adjusted upwards.
  69 .PP
  70 If the cyclades driver was compiled with
  71 .B ENABLE_MONITORING
  72 defined, the cytune command can be used with the
  73 .B \-q
  74 option to report interrupts over the monitoring interval and
  75 characters transferred over the monitoring interval.  It will also report
  76 the state of the FIFO.  The maximum number of characters in the FIFO when
  77 an interrupt occurred, the instantaneous count of characters in the FIFO,
  78 and how many characters are now in the FIFO are reported.  This output might
  79 look like this:
  80 .sp
  81 .RS
  82 /dev/cubC0: 830 ints, 9130 chars; fifo: 11 threshold, 11 max, 11 now
  83 .br
  84    166.259866 interrupts/second, 1828.858521 characters/second
  85 .RE
  86 .PP
  87 This output indicates that for this monitoring period, the interrupts were
  88 always being handled within one character time, because
  89 .B max
  90 never rose above
  91 .BR threshold .
  92 This is good, and you can probably run this way, provided that a large
  93 number of samples come out this way.  You will lose characters if you
  94 overrun the FIFO, as the Cyclades hardware does not seem to support
  95 the RTS RS-232 signal line for hardware flow control from the
  96 DCE to the DTE.
  97 .PP
  98 In query mode
  99 .B cytune
 100 will produce a summary report when ended with
 101 a SIGINT or when the threshold or timeout is changed.
 102 .PP
 103 There may be a responsiveness vs. throughput tradeoff.  The Cyclades card,
 104 at the higher speeds, is capable of putting a very high interrupt load on the
 105 system.  This will reduce the amount of CPU time available for other tasks
 106 on your system.  However, the time it takes to respond to a single character
 107 may be increased if you increase the threshold.  This might be noticed by
 108 monitoring
 109 .BR ping (8)
 110 times on a SLIP link controlled by a Cyclades card.  If your SLIP link is
 111 generally used for interactive work such as
 112 .BR telnet (1),
 113 you may want to leave the threshold low, so that characters are responded
 114 to as quickly as possible.  If your SLIP link is generally used for file
 115 transfer, WWW, and the like, setting the FIFO to a high value is likely to
 116 reduce the load on your system while not significantly affecting
 117 throughput.  Alternatively, see the
 118 .B \-t
 119 or
 120 .B \-T
 121 options to adjust the time that the cyclades waits before flushing its
 122 buffer.  Units are 5ms.
 123 .PP
 124 If you are running a mouse on a Cyclades port, it is likely that you would
 125 want to maintain the threshold and timeout at a low value.
 126 .PP
 127 .SH OPTIONS
 128 .TP
 129 .BI \-s " value"
 130 Set the current threshold to
 131 .I value
 132 characters.  Note that if the
 133 .I tty
 134 is not being held open by another process, the threshold will be reset on
 135 the next open.  Only values between 1 and 12, inclusive, are permitted.
 136 .TP
 137 .BI \-t " value"
 138 Set the current flush timeout to
 139 .I value
 140 units.  Note that if the
 141 .I tty
 142 is not being held open by another process, the threshold will be reset on
 143 the next open.  Only values between 0 and 255, inclusive, are permitted.
 144 Setting
 145 .I value
 146 to zero forces the default, currently 0x20 (160ms), but soon to be 0x02
 147 (10ms).  Units are 5 ms.
 148 .TP
 149 .B \-g
 150 Get the current threshold and timeout.
 151 .TP
 152 .BI \-S " value"
 153 Set the default threshold to
 154 .I value
 155 characters.  When the
 156 .I tty
 157 is next opened, this value will be used instead of the default.
 158 Only values between 1 and 12, inclusive, are permitted.
 159 .TP
 160 .BI \-T " value"
 161 Set the default flush timeout to
 162 .I value
 163 units.  When the
 164 .I tty
 165 is next opened, this value will be used instead of the default.  If
 166 .I value
 167 is zero, then the the value will default to 0x20 (160ms), soon to be 0x02
 168 (10ms).
 169 .TP
 170 .B \-G
 171 Get the default threshold and flush timeout values.
 172 .TP
 173 .B \-q
 174 Gather statistics about the
 175 .IR tty .
 176 The results are only valid if the Cyclades driver has been compiled with
 177 .B ENABLE_MONITORING
 178 defined.  This is probably not the default.
 179 .TP
 180 .BI \-i " interval"
 181 Statistics will be gathered every
 182 .I interval
 183 seconds.
 184 .SH BUGS
 185 If you run two copies of
 186 .B cytune
 187 at the same time to report statistics about the same port,
 188 the 'ints', 'chars', and 'max' value will be reset
 189 and not reported correctly.
 190 .B cytune
 191 should prevent this, but does not.
 192 .\" .SH AUTHOR
 193 .\" Nick Simicich (njs@scifi.emi.net), with modifications by
 194 .\" Rik Faith (faith@cs.unc.edu)
 195 .SH FILES
 196 .I /dev/ttyC[0-8]
 197 .br
 198 .I /dev/cubC[0-8]
 199 .SH "SEE ALSO"
 200 .BR setserial (8)
 201 .SH AVAILABILITY
 202 The cytune command is part of the util-linux-ng package and is available from
 203 ftp://ftp.kernel.org/pub/linux/utils/util-linux-ng/.