[unix-history] / share / man / man4 / man4.i386 / sio.4

.\" Copyright (c) 1990, 1991 The Regents of the University of California.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
.\" the Systems Programming Group of the University of Utah Computer
.\" Science Department.
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     from: @(#)dca.4	5.2 (Berkeley) 3/27/91
.\"	from: com.4,v 1.1 1993/08/06 11:19:07 cgd Exp
.\"	$Id: sio.4,v 1.6 1994/02/17 17:44:07 rgrimes Exp $
.\"
.Dd February 9, 1994
.Dt SIO 4 i386
.Os FreeBSD
.Sh NAME
.Nm sio
.Nd
fast interrupt driven asynchronous serial communications interface
.Sh SYNOPSIS
For standard ports:
.Cd "device sio0 at isa? port" \&"IO_COM1\&" tty irq 4 vector siointr
.Cd "device sio1 at isa? port" \&"IO_COM2\&" tty irq 3 vector siointr
.Cd "device sio2 at isa? port" \&"IO_COM3\&" tty irq 5 vector siointr
.Cd "device sio3 at isa? port" \&"IO_COM4\&" tty irq 9 vector siointr
.sp
For multiport cards:
.Cd "options" \&"COM_MULTIPORT\&"
.Cd "device sio4 at isa? port 0x2a0 tty irq 12 flags 0x401 vector siointr"
.Cd "device sio5 at isa? port 0x2a8 tty flags 0x401 vector siointr"
.Cd "device sio6 at isa? port 0x2b0 tty flags 0x401 vector siointr"
.Cd "device sio7 at isa? port 0x2b8 tty flags 0x401 vector siointr"
.sp
For bidirectional use of ports:
.Cd "options" \&"COM_BIDIR\&"
.sp
For control FIFO trigger:
.Cd "options" \&"FIFO_TRIGGER=FIFO_TRIGGER_14\&"
.sp
Use 0x02 bit in flags field to disable FIFO on specified port.
.Sh DESCRIPTION
The
.Nm sio
driver provides support for NS8250-, NS16450-, NS16550 and NS16550A-based
.Tn EIA
.Tn RS-232C
.Pf ( Tn CCITT
.Tn V.24 )
communications interfaces.  The NS8250 and NS16450 have single character
buffers, the NS16550A has a 16 character FIFO buffer.
.Pp
Input and output for each line may set to one of following baud rates;
50, 75, 110, 134.5, 150, 300, 600, 1200, 1800, 2400, 4800, 9600,
19200, 38400, 57600, or 115200. Your hardware may limit your baud
rate choices.
.Pp
For multiport cards the 
.Nm flags
keyword in the kernel configuration file determines which port of 
your multiport card is the master device, and whether the 
port is part of a multiport card. The master device is the port which
has register through which all interrupts of the card are funneled.
All ports of a multiport card report pending interrupts using this
single register.
.sp
The master device is indicated 
.Nm bitwise
, so all sio entries in the kernel config file that are part of a 
multiport card must include the correct 
.Nm flags
specification. The bitwise assignment allows multiple multiport cards to
be configured in one system. It does 
.Nm not
imply that the hardware can share the same physical interrupt line!
.Pp
In the synopsis the 
.Nm flags 0x401
means that the 4th port (sio4) is the master
device (so the MSB of the flags), and that the ports are part of a 
multiport card (the LSB of the flags, actually only the LS 
.Nm bit
).
F.e. if you have only two standard ports in addition to multiport
card, this
.Nm flags
will be
.Nm 0x201 .
.Pp
Which port is the master device depends on the card type. Consult
the hardware documentation of your card.
.Pp
Serial ports controlled by the 
.Nm sio
driver can be used for both dialin and dialout. Use 
.Xr comcontrol 8
to enable/disable bidirectional use of the 
.Nm sio
ports. The minor number of the dialout
port is 128 higher than that of the corresponding dialin port. Use 
.Xr stty 1
to enable or disable modem control as required by your setup.
.Sh FILES
.Bl -tag -width /dev/tty0? -compact
.It Pa /dev/tty0?
for hardwired terminals
.El
or
.Bl -tag -width /dev/tty0? -compact
.It Pa /dev/ttyd?
for dialin ports (and dialout when bidirectional usage disabled)
.It Pa /dev/cua0?
for dialout ports when bidirectional usage enabled
.El
.Pp
If device number more then 10 last character of device name
belongs to [a-z] set.
/dev/tty0? and /dev/ttyd? are mutually exclusive, if you have
/dev/tty0? corresponding /dev/ttyd? must be removed and vice versa.
.Sh DIAGNOSTICS
.Bl -diag
.It sio%d: silo overflow.
The single-character input
.Dq silo
has overflowed and incoming data has been lost.
.\".It com%d: weird interrupt: %x.
.\"The device has generated an unexpected interrupt
.\"with the code listed.
.El
.Sh SEE ALSO
.Xr tty 4 ,
.Xr comcontrol 8 ,
.Xr stty 1 .
.Sh HISTORY
The
.Nm
driver is derived from the
.Nm HP9000/300
.Nm dca
driver and is
.Ud
.Sh BUGS
Data loss is not near as likely on busy systems as they are with the
.Xr com 4
driver but they still can occur at very high baud rates on slow systems. The
use of NS16550A's helps lot to handle high baud rates.
.Pp
Stay away from NS16550 (so without the trailing A). These are early 
implementations of the chip with non-functional FIFO hardware.
.Pp
The constants which define the locations
of the various serial ports are holdovers from
.Nm DOS .
As shown, hex addresses can be and for clarity probably should be used instead.
.Pp
As usual, you get what you pay for; cheap NS16550 clones generally don't work.
.Pp
The multiport example is based on an AST/4 card, your
mileage may vary however. Note that on the AST/4 the card's dipswitches should 
.Nm not
be set to use interrupt sharing. AST/4-like interrupt sharing is only used when 
.Nm multiple
AST/4 cards are installed in the same system. The sio driver does not 
support more than 1 AST/4 on one IRQ.
Commit	Line	Data
52ac9c69 RG	1	.\" Copyright (c) 1990, 1991 The Regents of the University of California.
	2	.\" All rights reserved.
	3	.\"
	4	.\" This code is derived from software contributed to Berkeley by
	5	.\" the Systems Programming Group of the University of Utah Computer
	6	.\" Science Department.
	7	.\" Redistribution and use in source and binary forms, with or without
	8	.\" modification, are permitted provided that the following conditions
	9	.\" are met:
	10	.\" 1. Redistributions of source code must retain the above copyright
	11	.\" notice, this list of conditions and the following disclaimer.
	12	.\" 2. Redistributions in binary form must reproduce the above copyright
	13	.\" notice, this list of conditions and the following disclaimer in the
	14	.\" documentation and/or other materials provided with the distribution.
	15	.\" 3. All advertising materials mentioning features or use of this software
	16	.\" must display the following acknowledgement:
	17	.\" This product includes software developed by the University of
	18	.\" California, Berkeley and its contributors.
	19	.\" 4. Neither the name of the University nor the names of its contributors
	20	.\" may be used to endorse or promote products derived from this software
	21	.\" without specific prior written permission.
	22	.\"
	23	.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
	24	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	25	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	26	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
	27	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	28	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	29	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	30	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	31	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	32	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	33	.\" SUCH DAMAGE.
	34	.\"
	35	.\" from: @(#)dca.4 5.2 (Berkeley) 3/27/91
	36	.\" from: com.4,v 1.1 1993/08/06 11:19:07 cgd Exp
750070c3	37	.\" $Id: sio.4,v 1.6 1994/02/17 17:44:07 rgrimes Exp $
52ac9c69	38	.\"
22d83443	39	.Dd February 9, 1994
52ac9c69 RG	40	.Dt SIO 4 i386
	41	.Os FreeBSD
	42	.Sh NAME
	43	.Nm sio
	44	.Nd
63ec8d43	45	fast interrupt driven asynchronous serial communications interface
52ac9c69	46	.Sh SYNOPSIS
22d83443	47	For standard ports:
52ac9c69 RG	48	.Cd "device sio0 at isa? port" \&"IO_COM1\&" tty irq 4 vector siointr
	49	.Cd "device sio1 at isa? port" \&"IO_COM2\&" tty irq 3 vector siointr
	50	.Cd "device sio2 at isa? port" \&"IO_COM3\&" tty irq 5 vector siointr
	51	.Cd "device sio3 at isa? port" \&"IO_COM4\&" tty irq 9 vector siointr
22d83443	52	.sp
63ec8d43 AC	53	For multiport cards:
63ec8d43 AC	54	.Cd "options" \&"COM_MULTIPORT\&"
87ac16c5 RG	55	.Cd "device sio4 at isa? port 0x2a0 tty irq 12 flags 0x401 vector siointr"
	56	.Cd "device sio5 at isa? port 0x2a8 tty flags 0x401 vector siointr"
	57	.Cd "device sio6 at isa? port 0x2b0 tty flags 0x401 vector siointr"
	58	.Cd "device sio7 at isa? port 0x2b8 tty flags 0x401 vector siointr"
22d83443 AC	59	.sp
22d83443 AC	60	For bidirectional use of ports:
63ec8d43	61	.Cd "options" \&"COM_BIDIR\&"
22d83443 AC	62	.sp
	63	For control FIFO trigger:
	64	.Cd "options" \&"FIFO_TRIGGER=FIFO_TRIGGER_14\&"
	65	.sp
	66	Use 0x02 bit in flags field to disable FIFO on specified port.
52ac9c69 RG	67	.Sh DESCRIPTION
	68	The
	69	.Nm sio
63ec8d43	70	driver provides support for NS8250-, NS16450-, NS16550 and NS16550A-based
52ac9c69 RG	71	.Tn EIA
	72	.Tn RS-232C
	73	.Pf ( Tn CCITT
63ec8d43	74	.Tn V.24 )
52ac9c69	75	communications interfaces. The NS8250 and NS16450 have single character
22d83443	76	buffers, the NS16550A has a 16 character FIFO buffer.
52ac9c69 RG	77	.Pp
	78	Input and output for each line may set to one of following baud rates;
	79	50, 75, 110, 134.5, 150, 300, 600, 1200, 1800, 2400, 4800, 9600,
22d83443 AC	80	19200, 38400, 57600, or 115200. Your hardware may limit your baud
22d83443 AC	81	rate choices.
63ec8d43 AC	82	.Pp
	83	For multiport cards the
	84	.Nm flags
22d83443 AC	85	keyword in the kernel configuration file determines which port of
	86	your multiport card is the master device, and whether the
	87	port is part of a multiport card. The master device is the port which
	88	has register through which all interrupts of the card are funneled.
	89	All ports of a multiport card report pending interrupts using this
	90	single register.
b99eee8c AC	91	.sp
	92	The master device is indicated
	93	.Nm bitwise
22d83443	94	, so all sio entries in the kernel config file that are part of a
b99eee8c AC	95	multiport card must include the correct
b99eee8c AC	96	.Nm flags
22d83443 AC	97	specification. The bitwise assignment allows multiple multiport cards to
22d83443 AC	98	be configured in one system. It does
b99eee8c AC	99	.Nm not
b99eee8c AC	100	imply that the hardware can share the same physical interrupt line!
22d83443 AC	101	.Pp
	102	In the synopsis the
	103	.Nm flags 0x401
	104	means that the 4th port (sio4) is the master
	105	device (so the MSB of the flags), and that the ports are part of a
63ec8d43 AC	106	multiport card (the LSB of the flags, actually only the LS
63ec8d43 AC	107	.Nm bit
22d83443 AC	108	).
	109	F.e. if you have only two standard ports in addition to multiport
	110	card, this
37d58e3c	111	.Nm flags
22d83443 AC	112	will be
	113	.Nm 0x201 .
	114	.Pp
	115	Which port is the master device depends on the card type. Consult
	116	the hardware documentation of your card.
	117	.Pp
	118	Serial ports controlled by the
63ec8d43 AC	119	.Nm sio
63ec8d43 AC	120	driver can be used for both dialin and dialout. Use
22d83443 AC	121	.Xr comcontrol 8
22d83443 AC	122	to enable/disable bidirectional use of the
63ec8d43	123	.Nm sio
22d83443 AC	124	ports. The minor number of the dialout
	125	port is 128 higher than that of the corresponding dialin port. Use
	126	.Xr stty 1
63ec8d43	127	to enable or disable modem control as required by your setup.
52ac9c69	128	.Sh FILES
750070c3 AC	129	.Bl -tag -width /dev/tty0? -compact
	130	.It Pa /dev/tty0?
	131	for hardwired terminals
52ac9c69	132	.El
750070c3 AC	133	or
	134	.Bl -tag -width /dev/tty0? -compact
	135	.It Pa /dev/ttyd?
	136	for dialin ports (and dialout when bidirectional usage disabled)
	137	.It Pa /dev/cua0?
	138	for dialout ports when bidirectional usage enabled
	139	.El
	140	.Pp
	141	If device number more then 10 last character of device name
	142	belongs to [a-z] set.
	143	/dev/tty0? and /dev/ttyd? are mutually exclusive, if you have
	144	/dev/tty0? corresponding /dev/ttyd? must be removed and vice versa.
52ac9c69 RG	145	.Sh DIAGNOSTICS
	146	.Bl -diag
	147	.It sio%d: silo overflow.
	148	The single-character input
	149	.Dq silo
	150	has overflowed and incoming data has been lost.
22d83443 AC	151	.\".It com%d: weird interrupt: %x.
	152	.\"The device has generated an unexpected interrupt
	153	.\"with the code listed.
52ac9c69 RG	154	.El
52ac9c69 RG	155	.Sh SEE ALSO
22d83443 AC	156	.Xr tty 4 ,
	157	.Xr comcontrol 8 ,
	158	.Xr stty 1 .
52ac9c69 RG	159	.Sh HISTORY
	160	The
	161	.Nm
	162	driver is derived from the
	163	.Nm HP9000/300
	164	.Nm dca
	165	driver and is
	166	.Ud
	167	.Sh BUGS
22d83443	168	Data loss is not near as likely on busy systems as they are with the
b99eee8c	169	.Xr com 4
22d83443 AC	170	driver but they still can occur at very high baud rates on slow systems. The
22d83443 AC	171	use of NS16550A's helps lot to handle high baud rates.
52ac9c69	172	.Pp
b99eee8c AC	173	Stay away from NS16550 (so without the trailing A). These are early
	174	implementations of the chip with non-functional FIFO hardware.
	175	.Pp
52ac9c69	176	The constants which define the locations
22d83443	177	of the various serial ports are holdovers from
52ac9c69	178	.Nm DOS .
b99eee8c	179	As shown, hex addresses can be and for clarity probably should be used instead.
63ec8d43	180	.Pp
22d83443	181	As usual, you get what you pay for; cheap NS16550 clones generally don't work.
63ec8d43	182	.Pp
b99eee8c	183	The multiport example is based on an AST/4 card, your
22d83443	184	mileage may vary however. Note that on the AST/4 the card's dipswitches should
b99eee8c AC	185	.Nm not
	186	be set to use interrupt sharing. AST/4-like interrupt sharing is only used when
	187	.Nm multiple
	188	AST/4 cards are installed in the same system. The sio driver does not
22d83443	189	support more than 1 AST/4 on one IRQ.