1.\" $NetBSD: uftdi.4,v 1.5 2002/02/07 03:15:08 ross Exp $ 2.\" 3.\" Copyright (c) 2000 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Lennart Augustsson. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd April 26, 2017 31.Dt UFTDI 4 32.Os 33.Sh NAME 34.Nm uftdi 35.Nd USB support for serial adapters based on the FTDI family of USB 36serial adapter chips. 37.Sh SYNOPSIS 38To compile this driver into the kernel, 39place the following lines in your 40kernel configuration file: 41.Bd -ragged -offset indent 42.Cd "device usb" 43.Cd "device ucom" 44.Cd "device uftdi" 45.Ed 46.Pp 47Alternatively, to load the driver as a 48module at boot time, place the following line in 49.Xr loader.conf 5 : 50.Bd -literal -offset indent 51uftdi_load="YES" 52.Ed 53.Sh DESCRIPTION 54The 55.Nm 56driver provides support for various serial adapters based on the 57following FTDI chips: 58.Pp 59.Bl -bullet -compact 60.It 61FT8U100AX 62.It 63FT8U232AM 64.It 65FT8U232BM 66.It 67FT232R 68.It 69FT2232C 70.It 71FT2232D 72.It 73FT2232H 74.It 75FT4232H 76.It 77FT230X 78.El 79.Pp 80The device is accessed through the 81.Xr ucom 4 82driver which makes it behave like a 83.Xr tty 4 . 84.Pp 85Many of the supported chips provide additional functionality 86such as bitbang mode and the MPSSE engine for serial bus emulation. 87The 88.Nm 89driver provides access to that functionality with the following 90.Xr ioctl 2 91calls, defined in 92.In dev/usb/uftdiio.h : 93.Bl -tag -width indent 94.It Dv UFTDIIOC_RESET_IO Pq Vt int 95Reset the channel to its default configuration, flush RX and TX FIFOs. 96.It Dv UFTDIIOC_RESET_RX Pq Vt int 97Flush the RX FIFO. 98.It Dv UFTDIIOC_RESET_TX Pq Vt int 99Flush the TX FIFO. 100.It Dv UFTDIIOC_SET_BITMODE Pq Vt "struct uftdi_bitmode" 101Put the channel into the operating mode specified in 102.Va mode , 103and set the pins indicated by ones in 104.Va iomask 105to output mode. 106The 107.Va mode 108must be one of the 109.Va uftdi_bitmodes 110values. 111Setting 112.Va mode 113to 114.Dv UFTDI_BITMODE_NONE 115returns the channel to standard UART mode. 116.Bd -literal 117enum uftdi_bitmodes 118{ 119 UFTDI_BITMODE_ASYNC = 0, 120 UFTDI_BITMODE_MPSSE = 1, 121 UFTDI_BITMODE_SYNC = 2, 122 UFTDI_BITMODE_CPU_EMUL = 3, 123 UFTDI_BITMODE_FAST_SERIAL = 4, 124 UFTDI_BITMODE_CBUS = 5, 125 UFTDI_BITMODE_NONE = 0xff, 126}; 127 128struct uftdi_bitmode 129{ 130 uint8_t mode; 131 uint8_t iomask; 132}; 133.Ed 134.Pp 135Manuals and application notes published by FTDI describe these 136modes in detail. 137To use most of these modes, you first put the channel into 138the desired mode, then you 139.Xr read 2 140and 141.Xr write 2 142data which either reflects pin state or is interpreted 143as MPSSE commands and parameters, depending on the mode. 144.It Dv UFTDIIOC_GET_BITMODE Pq Vt "struct uftdi_bitmode" 145Return the current bitbang mode in the 146.Va mode 147member, and the state of the DBUS0..DBUS7 pins at the time 148of the call in the 149.Va iomask 150member. 151The pin state can be read while the chip is in any mode, including 152.Dv UFTDI_BITMODE_NONE 153(UART) mode. 154.It Dv UFTDIIOC_SET_ERROR_CHAR Pq Vt int 155Set the character which is inserted into the buffer to mark 156the point of an error such as FIFO overflow. 157.It Dv UFTDIIOC_SET_EVENT_CHAR Pq Vt int 158Set the character which causes a partial FIFO full of data 159to be returned immediately even if the FIFO is not full. 160.It Dv UFTDIIOC_SET_LATENCY Pq Vt int 161Set the amount of time to wait for a full FIFO, 162in milliseconds. 163If more than this much time elapses without receiving a new 164character, any characters in the FIFO are returned. 165.It Dv UFTDIIOC_GET_LATENCY Pq Vt int 166Get the current value of the latency timer. 167.It Dv UFTDIIOC_GET_HWREV Pq Vt int 168Get the hardware revision number. 169This is the 170.Va bcdDevice 171value from the 172.Va usb_device_descriptor . 173.It Dv UFTDIIOC_READ_EEPROM Pq Vt "struct uftdi_eeio" 174Read one or more words from the configuration eeprom. 175The FTDI chip performs eeprom I/O in 16-bit words. 176Set 177.Va offset 178and 179.Va length 180to values evenly divisible by two before the call, and the 181.Va data 182array will contain the requested values from eeprom after the call. 183.Bd -literal 184struct uftdi_eeio 185{ 186 uint16_t offset; 187 uint16_t length; 188 uint16_t data[64]; 189}; 190.Ed 191.Pp 192The FT232R chip has an internal eeprom. 193An external serial eeprom is optional on other FTDI chips. 194The eeprom may contain 64, 128, or 256 words, 195depending on the part used. 196Multiple calls may be needed to read or write the larger parts. 197When no eeprom is present, all words in the returned data are 0xffff. 198An erased eeprom also reads as all 0xffff. 199.It Dv UFTDIIOC_WRITE_EEPROM Pq Vt "struct uftdi_eeio" 200Write one or more words to the configuration eeprom. 201The 202.Va uftdi_eeio 203values are as described for 204.Dv UFTDIIOC_READ_EEPROM . 205.Pp 206The FTDI chip does a blind write to the eeprom, and it will appear 207to succeed even when no eeprom is present. 208To ensure a good write you must read back and verify the data. 209It is 210.Em not 211necessary to erase before writing. 212Any position within the eeprom can be overwritten at any time. 213.It Dv UFTDIIOC_ERASE_EEPROM Pq Vt int 214Erase the entire eeprom. 215This is useful primarily for test and debugging, as there is no 216need to erase before writing. 217To help prevent accidental erasure caused by calling the wrong 218ioctl, you must pass the special value 219.Dv UFTDI_CONFIRM_ERASE 220as the argument to this ioctl. 221.El 222.Sh HARDWARE 223The 224.Nm 225driver supports the following adapters: 226.Pp 227.Bl -bullet -compact 228.It 229B&B Electronics USB->RS422/485 adapter 230.It 231Elexol USB MOD1 and USB MOD3 232.It 233HP USB-Serial adapter shipped with some HP laptops 234.It 235Inland UAS111 236.It 237QVS USC-1000 238.It 239Buffalo PC-OP-RS / Kurouto-shikou KURO-RS universal remote 240.It 241Prologix GPIB-USB Controller 242.El 243.Sh FILES 244.Bl -tag -width "/dev/ttyU*.init" -compact 245.It Pa /dev/ttyU* 246for callin ports 247.It Pa /dev/ttyU*.init 248.It Pa /dev/ttyU*.lock 249corresponding callin initial-state and lock-state devices 250.Pp 251.It Pa /dev/cuaU* 252for callout ports 253.It Pa /dev/cuaU*.init 254.It Pa /dev/cuaU*.lock 255corresponding callout initial-state and lock-state devices 256.El 257.Sh SEE ALSO 258.Xr tty 4 , 259.Xr ucom 4 , 260.Xr usb 4 261.Sh HISTORY 262The 263.Nm 264driver 265appeared in 266.Fx 4.8 267from 268.Nx 1.5 . 269