diff options
Diffstat (limited to 'static/freebsd/man4/uart.4 3.html')
| -rw-r--r-- | static/freebsd/man4/uart.4 3.html | 345 |
1 files changed, 345 insertions, 0 deletions
diff --git a/static/freebsd/man4/uart.4 3.html b/static/freebsd/man4/uart.4 3.html new file mode 100644 index 00000000..61242738 --- /dev/null +++ b/static/freebsd/man4/uart.4 3.html @@ -0,0 +1,345 @@ +<table class="head"> + <tr> + <td class="head-ltitle">UART(4)</td> + <td class="head-vol">Device Drivers Manual</td> + <td class="head-rtitle">UART(4)</td> + </tr> +</table> +<div class="manual-text"> +<section class="Sh"> +<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> +<p class="Pp"><code class="Nm">uart</code> — <span class="Nd">Universal + Asynchronous Receiver/Transmitter serial driver</span></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<p class="Pp"><code class="Cd">device uart</code></p> +<p class="Pp"> + <br/> + <code class="Cd">device puc</code> + <br/> + <code class="Cd">device uart</code></p> +<p class="Pp"> + <br/> + <code class="Cd">device scc</code> + <br/> + <code class="Cd">device uart</code></p> +<p class="Pp">In <span class="Pa">/boot/device.hints</span>: + <br/> + <code class="Cd">hint.uart.0.disabled="1"</code> + <br/> + <code class="Cd">hint.uart.0.baud="38400"</code> + <br/> + <code class="Cd">hint.uart.0.port="0x3f8"</code> + <br/> + <code class="Cd">hint.uart.0.flags="0x10"</code></p> +<p class="Pp">With <var class="Ar">flags</var> encoded as:</p> +<dl class="Bl-tag Bl-compact"> + <dt>0x00010</dt> + <dd>device is potential system console</dd> + <dt>0x00080</dt> + <dd>use this port for remote kernel debugging</dd> + <dt>0x00100</dt> + <dd>set RX FIFO trigger level to ``low'' (NS8250 only)</dd> + <dt>0x00200</dt> + <dd>set RX FIFO trigger level to ``medium low'' (NS8250 only)</dd> + <dt>0x00400</dt> + <dd>set RX FIFO trigger level to ``medium high'' (default, NS8250 only)</dd> + <dt>0x00800</dt> + <dd>set RX FIFO trigger level to ``high'' (NS8250 only)</dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The <code class="Nm">uart</code> device driver provides support + for various classes of UARTs implementing the EIA RS-232C (CCITT V.24) + serial communications interface. Each such interface is controlled by a + separate and independent instance of the <code class="Nm">uart</code> + driver. The primary support for devices that contain multiple serial + interfaces or that contain other functionality besides one or more serial + interfaces is provided by the <a class="Xr">puc(4)</a>, or + <a class="Xr">scc(4)</a> device drivers. However, the serial interfaces of + those devices that are managed by the <a class="Xr">puc(4)</a>, or + <a class="Xr">scc(4)</a> driver are each independently controlled by the + <code class="Nm">uart</code> driver. As such, the <a class="Xr">puc(4)</a>, + or <a class="Xr">scc(4)</a> driver provides umbrella functionality for the + <code class="Nm">uart</code> driver and hides the complexities that are + inherent when elementary components are packaged together.</p> +<p class="Pp">The <code class="Nm">uart</code> driver has a modular design to + allow it to be used on differing hardware and for various purposes. In the + following sections the components are discussed in detail. Options are + described in the section that covers the component to which each option + applies.</p> +<section class="Ss"> +<h2 class="Ss" id="CORE_COMPONENT"><a class="permalink" href="#CORE_COMPONENT">CORE + COMPONENT</a></h2> +<p class="Pp">At the heart of the <code class="Nm">uart</code> driver is the + core component. It contains the bus attachments and the low-level interrupt + handler.</p> +</section> +<section class="Ss"> +<h2 class="Ss" id="HARDWARE_DRIVERS"><a class="permalink" href="#HARDWARE_DRIVERS">HARDWARE + DRIVERS</a></h2> +<p class="Pp">The core component and the kernel interfaces talk to the hardware + through the hardware interface. This interface serves as an abstraction of + the hardware and allows varying UARTs to be used for serial + communications.</p> +</section> +<section class="Ss"> +<h2 class="Ss" id="SYSTEM_DEVICES"><a class="permalink" href="#SYSTEM_DEVICES">SYSTEM + DEVICES</a></h2> +<p class="Pp">System devices are UARTs that have a special purpose by way of + hardware design or software setup. For example, Sun UltraSparc machines use + UARTs as their keyboard interface. Such an UART cannot be used for general + purpose communications. Likewise, when the kernel is configured for a serial + console, the corresponding UART will in turn be a system device so that the + kernel can output boot messages early on in the boot process.</p> +</section> +<section class="Ss"> +<h2 class="Ss" id="KERNEL_INTERFACES"><a class="permalink" href="#KERNEL_INTERFACES">KERNEL + INTERFACES</a></h2> +<p class="Pp">The last but not least of the components is the kernel interface. + This component ultimately determines how the UART is made visible to the + kernel in particular and to users in general. The default kernel interface + is the TTY interface. This allows the UART to be used for terminals, modems + and serial line IP applications. System devices, with the notable exception + of serial consoles, generally have specialized kernel interfaces.</p> +</section> +</section> +<section class="Sh"> +<h1 class="Sh" id="HARDWARE"><a class="permalink" href="#HARDWARE">HARDWARE</a></h1> +<p class="Pp">The <code class="Nm">uart</code> driver supports the following + classes of UARTs:</p> +<p class="Pp"></p> +<ul class="Bl-bullet Bl-compact"> + <li>NS8250: standard hardware based on the 8250, 16450, 16550, 16650, 16750 or + the 16950 UARTs.</li> + <li>SCC: serial communications controllers supported by the + <a class="Xr">scc(4)</a> device driver.</li> +</ul> +</section> +<section class="Sh"> +<h1 class="Sh" id="Pulse_Per_Second_(PPS)_Timing_Interface"><a class="permalink" href="#Pulse_Per_Second_(PPS)_Timing_Interface">Pulse + Per Second (PPS) Timing Interface</a></h1> +<p class="Pp">The <code class="Nm">uart</code> driver can capture PPS timing + information as defined in RFC 2783. The API, accessed via + <a class="Xr">ioctl(2)</a>, is available on the tty device. To use the PPS + capture feature with <a class="Xr">ntpd(8)</a>, symlink the tty callout + device <var class="Va">/dev/cuau?</var> to + <var class="Va">/dev/pps0.</var></p> +<p class="Pp">The <var class="Va">hw.uart.pps_mode</var> tunable configures the + PPS capture mode for all uart devices; it can be set in + <a class="Xr">loader.conf(5)</a>. The + <var class="Va">dev.uart.0.pps_mode</var> sysctl configures the PPS capture + mode for a specific uart device; it can be set in + <a class="Xr">loader.conf(5)</a> or <a class="Xr">sysctl.conf(5)</a>.</p> +<p class="Pp">The following capture modes are available:</p> +<div class="Bd-indent"> +<dl class="Bl-tag Bl-compact"> + <dt>0x00</dt> + <dd>Capture disabled.</dd> + <dt>0x01</dt> + <dd>Capture pulses on the CTS line.</dd> + <dt>0x02</dt> + <dd>Capture pulses on the DCD line.</dd> +</dl> +</div> +<p class="Pp">The following values may be ORed with the capture mode to + configure capture processing options:</p> +<div class="Bd-indent"> +<dl class="Bl-tag Bl-compact"> + <dt>0x10</dt> + <dd>Invert the pulse (RS-232 logic low = ASSERT, high = CLEAR).</dd> + <dt>0x20</dt> + <dd>Attempt to capture narrow pulses.</dd> +</dl> +</div> +<p class="Pp">Add the narrow pulse option when the incoming PPS pulse width is + small enough to prevent reliable capture in normal mode. In narrow mode the + driver uses the hardware's ability to latch a line state change; not all + hardware has this capability. The hardware latch provides a reliable + indication that a pulse occurred, but prevents distinguishing between the + CLEAR and ASSERT edges of the pulse. For each detected pulse, the driver + synthesizes both an ASSERT and a CLEAR event, using the same timestamp for + each. To prevent spurious events when the hardware is intermittently able to + see both edges of a pulse, the driver will not generate a new pair of events + within a half second of the prior pair. Both normal and narrow pulse modes + work with <a class="Xr">ntpd(8)</a>.</p> +<p class="Pp">Add the invert option when the connection to the uart device uses + TTL level signals, or when the PPS source emits inverted pulses. RFC 2783 + defines an ASSERT event as a higher-voltage line level, and a CLEAR event as + a lower-voltage line level, in the context of the RS-232 protocol. The modem + control signals on a TTL-level connection are typically inverted from the + RS-232 levels. For example, carrier presence is indicated by a high signal + on an RS-232 DCD line, and by a low signal on a TTL DCD line. This is due to + the use of inverting line driver buffers to convert between TTL and RS-232 + line levels in most hardware designs. Generally speaking, a connection to a + DB-9 style connector is an RS-232 level signal at up to 12 volts. A + connection to header pins or an edge-connector on an embedded board is + typically a TTL signal at 3.3 or 5 volts.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="Special_Devices"><a class="permalink" href="#Special_Devices">Special + Devices</a></h1> +<p class="Pp">The <code class="Nm">uart</code> driver also supports an + initial-state and a lock-state control device for each of the callin and the + callout "data" devices. The termios settings of a data device are + copied from those of the corresponding initial-state device on first opens + and are not inherited from previous opens. Use <a class="Xr">stty(1)</a> in + the normal way on the initial-state devices to program initial termios + states suitable for your setup.</p> +<p class="Pp" id="stty">The lock termios state acts as flags to disable changing + the termios state. E.g., to lock a flag variable such as CRTSCTS, use + <a class="permalink" href="#stty"><i class="Em">stty crtscts</i></a> on the + lock-state device. Speeds and special characters may be locked by setting + the corresponding value in the lock-state device to any nonzero value. E.g., + to lock a speed to 115200, use “<code class="Li">stty + 115200</code>” on the initial-state device and + “<code class="Li">stty 1</code>” on the lock-state device.</p> +<p class="Pp">Correct programs talking to correctly wired external devices work + with almost arbitrary initial states and almost no locking, but other setups + may benefit from changing some of the default initial state and locking the + state. In particular, the initial states for non (POSIX) standard flags + should be set to suit the devices attached and may need to be locked to + prevent buggy programs from changing them. E.g., CRTSCTS should be locked on + for devices that support RTS/CTS handshaking at all times and off for + devices that do not support it at all. CLOCAL should be locked on for + devices that do not support carrier. HUPCL may be locked off if you do not + want to hang up for some reason. In general, very bad things happen if + something is locked to the wrong state, and things should not be locked for + devices that support more than one setting. The CLOCAL flag on callin ports + should be locked off for logins to avoid certain security holes, but this + needs to be done by getty if the callin port is used for anything else.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="Console_Tuneable"><a class="permalink" href="#Console_Tuneable">Console + Tuneable</a></h1> +<p class="Pp">The <code class="Nm">uart</code> driver can be designated as a + system console.</p> +<dl class="Bl-tag"> + <dt id="hw.uart.console"><var class="Va">hw.uart.console</var></dt> + <dd>Contains a number of <span class="Pa">/etc/remote</span> like tag:value + pairs, separated by commas. + <dl class="Bl-tag"> + <dt id="bd"><a class="permalink" href="#bd"><code class="Cm">bd</code></a></dt> + <dd>Busy Detect. Enable the so-called “Busy Detect” quirk + for the device. For NS 16550-compatible devices, this will use + heuristics to ensure that the UART is no longer busy before + manipulating line control. DesignWare-based UARTs need this due to a + design flaw in the UART.</dd> + <dt id="br"><a class="permalink" href="#br"><code class="Cm">br</code></a></dt> + <dd>Baudrate. The data rate (bits per second) used for communications on + the serial port. When the device clock rate (see below) is set to 0, + then the baud rate will be used with the divisor to compute the device + clock rate the first time the device is initialized. Only the + traditional baud rates are allowed. Rates larger than 19200 must be a + multiple of 19200. Baud rates between 1200 and 19200 must be a + multiple of 1200. Otherwise the baud rate must be a multiple of 75. A + value of '0' instructs the <code class="Nm">uart</code> driver to not + program the baud rate divisor and use the hardware as-is.</dd> + <dt id="ch"><a class="permalink" href="#ch"><code class="Cm">ch</code></a></dt> + <dd>Channel. Defaults to 0. Has no effect on UARTs with only one + channel.</dd> + <dt id="db"><a class="permalink" href="#db"><code class="Cm">db</code></a></dt> + <dd>Data bits. Defaults to 8.</dd> + <dt id="dt"><a class="permalink" href="#dt"><code class="Cm">dt</code></a></dt> + <dd>Device type. Specify the uart class to use for this device. + <dl class="Bl-tag"> + <dt>ns8250</dt> + <dd>Traditional PC UART National Semiconductor 16550 and compatible + devices.</dd> + <dt>pl011</dt> + <dd>Common ARM UART, based on ARM Limited designs.</dd> + </dl> + </dd> + <dt id="io"><a class="permalink" href="#io"><code class="Cm">io</code></a></dt> + <dd>I/O port address. Specifies the address of a UART in an Intel + processor's I/O space. Mutually exclusive with + ‘mm’.</dd> + <dt id="mm"><a class="permalink" href="#mm"><code class="Cm">mm</code></a></dt> + <dd>Memory mapped I/O address. Specifies the physical address of a + memory-mapped UART. Mutually exclusive with ‘io’.</dd> + <dt id="pa"><a class="permalink" href="#pa"><code class="Cm">pa</code></a></dt> + <dd>Parity. The type of parity to use when sending data to the host. This + may be one of ``even'', ``odd'', ``none'', ``zero'' (always set bit 8 + to zero), ``one'' (always set bit 8 to 1). The default is even + parity.</dd> + <dt id="rs"><a class="permalink" href="#rs"><code class="Cm">rs</code></a></dt> + <dd>Register shift. Number of bits to shift left the base register + offset.</dd> + <dt id="rw"><a class="permalink" href="#rw"><code class="Cm">rw</code></a></dt> + <dd>Register width. Size of operations to read and write the registers of + the device.</dd> + <dt id="sb"><a class="permalink" href="#sb"><code class="Cm">sb</code></a></dt> + <dd>Stopbits. Defaults to 1.</dd> + <dt id="xo"><a class="permalink" href="#xo"><code class="Cm">xo</code></a></dt> + <dd>Device clock (xtal oscillator). Base frequency of the oscillator to + use for the device. When set to 0, and the baud rate is also set, the + UART's initialization code will compute this the first time and use + that after. Automatically computed values can be as large as 5% when + the base frequency is a poor match to the traditional baud rates.</dd> + </dl> + </dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h1> +<dl class="Bl-tag Bl-compact"> + <dt><span class="Pa">/dev/ttyu?</span></dt> + <dd>for callin ports</dd> + <dt><span class="Pa">/dev/ttyu?.init</span></dt> + <dd style="width: auto;"> </dd> + <dt><span class="Pa">/dev/ttyu?.lock</span></dt> + <dd>corresponding callin initial-state and lock-state devices + <p class="Pp"></p> + </dd> + <dt><span class="Pa">/dev/cuau?</span></dt> + <dd>for callout ports</dd> + <dt><span class="Pa">/dev/cuau?.init</span></dt> + <dd style="width: auto;"> </dd> + <dt><span class="Pa">/dev/cuau?.lock</span></dt> + <dd>corresponding callout initial-state and lock-state devices</dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1> +<div class="Bd + Bd-indent"><code class="Li">hw.uart.console="io:0x2f8,br=115200"</code></div> +<p class="Pp">When the kernel is using a serial console port, it should use COM2 + instead of COM1 and set the baud rate to 115200.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<p class="Pp"><a class="Xr">cu(1)</a>, <a class="Xr">puc(4)</a>, + <a class="Xr">scc(4)</a>, <a class="Xr">termios(4)</a>, + <a class="Xr">tty(4)</a>, <a class="Xr">ttys(5)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">The <code class="Nm">uart</code> device driver first appeared in + <span class="Ux">FreeBSD 5.2</span>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp">The <code class="Nm">uart</code> device driver and this manual + page were written by <span class="An">Marcel Moolenaar</span> + <<a class="Mt" href="mailto:marcel@xcllnt.net">marcel@xcllnt.net</a>>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1> +<p class="Pp">Before the Internet, serial ports were primarily used for inbound + connections from terminals, either directly or through modems, these days + serial ports are primarily used for outbound connections to devices, an + evolution which unfortunately has spread the relevant documentation over + three different manual pages: <a class="Xr">termios(4)</a>, + <a class="Xr">uart(4)</a> and <a class="Xr">tty(4)</a>.</p> +<p class="Pp"></p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">December 5, 2024</td> + <td class="foot-os">FreeBSD 15.0</td> + </tr> +</table> |