1.\" $NetBSD: umcpmio.4,v 1.5 2025/01/23 19:15:49 brad Exp $ 2.\" 3.\" Copyright (c) 2024 Brad Spencer <brad@anduin.eldar.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd December 16, 2024 18.Dt UMCPMIO 4 19.Os 20.Sh NAME 21.Nm umcpmio 22.Nd Driver for Microchip Technologies MCP2221 / MCP2221A multi-io bridge. 23.Sh SYNOPSIS 24.Cd "umcpmio* at uhidev? reportid ?" 25.Cd "gpio* at gpiobus?" 26.Cd "iic* at umcpmio?" or 27.Cd "iic* at i2cbus?" 28.Sh DESCRIPTION 29The 30.Nm 31driver provides support for the MCP2221 / MCP2221A multi-io bridge chip. 32The chip provides 4 simple gpio pins with multiple functions 33that attach as a 34.Xr gpio 4 35device, an I2C port that attaches as an 36.Xr iic 4 37device and a UART serial port that attaches using 38.Xr umodem 4 39as a normal 40.Xr ucom 4 41.Pa ttyU Ns Ar \&* 42device. 43The UART is presented as one USB function, while the GPIO and I2C pins 44are presented as a second HID USB function. 45.Ss GPIO 46There are 4 basic gpio pins available with the following functions: 47.Bd -filled -offset indent 48.TS 49box tab(:); 50l | l | l | l | l 51= | = | = | = | = 52l | l | l | l | l 53l | l | l | l | l 54l | l | l | l | l 55l | l | l | l | l. 56Assignment:GP0:GP1:GP2:GP3 57GPIO:GPIO:GPIO:GPIO:GPIO 58ALT0:UART RX:ADC1:ADC2:ADC3 59ALT1:-:UART TX:DAC1:DAC2 60ALT2:-:IRQ:-:- 61ALT3:SSPND:Clock output:USBCFG:I2C activity 62.TE 63.Ed 64.Pp 65ADC1, ADC2 and ADC3 are independent of each other and each 10 bits in 66length. 67To utilize one of the ADC pins, an 68.Xr open 2 69is performed against 70.Pa /dev/umcpmio0GP1 , 71.Pa /dev/umcpmio0GP2 72or 73.Pa /dev/umcpmio0GP3 74with only the 75.Dv O_RDONLY 76flag set. 77Reads against the open file descriptor will produce 78.Vt uint16_t 79values. 80.Pp 81There is actually only one DAC present in the chip, but it is mirrored 82to GP2 and GP3 if the pin is set to ALT1. 83The DAC is 5 bits in length, and to use it, an 84.Xr open 2 85is performed against 86.Pa /dev/umcpmio0GP2 87or 88.Pa /dev/umcpmio0GP3 89with only the 90.Dv O_WRONLY 91flag set. 92Writes of 93.Vt uint8_t 94bytes to the file descriptor will result in an analog signal being 95created on the output pin. 96.Pp 97The clock output is derived from the USB clock of 48MHz. 98The duty cycle and clock divider can be adjusted with 99.Xr sysctl 8 100variables. 101To utilize GP1 as the clock output, the ALT3 function can be set with 102.Xr gpioctl 8 103command. 104.Ss I2C 105The chip supports a hardware I2C port with a simple scripting engine. 106When the driver attaches, the I2C speed is set to 100Kb/s. 107The ability to perform an I2C READ without a STOP is not supported by 108the MCP2221 / MCP2221A engine and the driver turns a READ without STOP 109into a READ with STOP. 110This behavior is just an attempt to allow a device to function, and it 111may not work for any particular device. 112In particular, it is known that the 113.Xr ds2482ow 4 114device will not work as expected. 115.Pp 116The MCP2221 / MCP2221A chip will automatically detact and deal with a 117device that uses I2C clock stretching. 118.Ss UART 119The UART utilizes the 120.Xr umodem 4 121driver. 122The UART function of the chip only supports 123.Tn 8-N-1 124communications. 125.Sh SYSCTL VARIABLES 126The following 127.Xr sysctl 3 128variables are provided: 129. 130.Pp 131.Bl -tag -width Li -compact 132. 133.It Li hw.umcpmio0.debug 134.It Li hw.umcpmio0.dump_buffers 135If 136.Dv UMCPMIO_DEBUG 137is defined, additional debugging output can be enabled. 138. 139.Pp 140.It Li hw.umcpmio0.response_wait 141.It Li hw.umcpmio0.response_errcnt 142This is how long the driver will wait for a HID response to come back 143from the chip. 144This variable is in microseconds and defaults to 2500. 145The driver will only allow 146.Li response_errcnt 147number of errors when waiting for a reponse from a HID report. 148This includes timeouts due to exceeding 149.Li response_wait . 150. 151.Pp 152.It Li hw.umcpmio0.i2c.reportreadnostop 153Report on the console if a driver attempts to use an I2C READ without 154STOP. 155A READ without STOP is not supported by the MCP2221 / MCP2221A I2C 156engine and will be turned into a READ with STOP by the driver. 157. 158.Pp 159.It Li hw.umcpmio0.i2c.busy_delay 160The driver checks in a number of cases if the I2C engine is busy and 161will wait for 162.Li busy_delay 163microseconds before checking again. 164. 165.Pp 166.It Li hw.umcpmio0.i2c.retry_busy_read 167The number of times to try to do an I2C READ when the engine is busy. 168. 169.Pp 170.It Li hw.umcpmio0.i2c.retry_busy_write 171The number of times to try to do an I2C WRITE when the engine is busy. 172. 173.Pp 174.It Li hw.umcpmio0.gpio.clock_duty_cycle 175.It Li hw.umcpmio0.gpio.clock_divider 176When GP1 is configured to use function ALT3, it will output a clock 177pulse. 178The valid values for 179.Li clock_duty_cycle 180are 181.Ql 75% , 182.Ql 50% , 183.Ql 25% , 184and 185.Ql \^0% . 186That is, 75% of the time a high and 25% of the time a low will be 187present on the GP1 pin. 188The valid values for 189.Li clock_divider 190are 191.Ql 375kHz , 192.Ql 750kHz , 193.Ql 1.5MHz , 194.Ql 3MHz , 195.Ql 6MHz , 196.Ql 12MHz , 197and 198.Ql 24MHz . 199. 200.Pp 201.It Li hw.umcpmio0.dac.vref 202.It Li hw.umcpmio0.adc.vref 203Sets the VREF value for the DAC or ADC. 204The valid values are 205.Ql 4.096V , 206.Ql 2.048V , 207.Ql 1.024V , 208.Ql OFF , 209and 210.Ql VDD . 211. 212.El 213. 214.Sh FILES 215.Bl -tag -width Pa -compact 216.It Pa /dev/umcpmio0ctl 217A control device for the chip instance that allows for a number of 218IOCTLs. 219.Pp 220.It Pa /dev/umcpmio0GP1 221.It Pa /dev/umcpmio0GP2 222.It Pa /dev/umcpmio0GP3 223Device files that allow access to the ADC or DAC functions of the 224associated gpio pin. 225.El 226.Sh SEE ALSO 227.Xr gpio 4 , 228.Xr iic 4 , 229.Xr sysctl 8 , 230.Xr umcpmioctl 8 231.Sh HISTORY 232The 233.Nm 234driver first appeared in 235.Nx 11.0 . 236.Sh AUTHORS 237.An -nosplit 238The 239.Nm 240driver was written by 241.An Brad Spencer Aq Mt brad@anduin.eldar.org . 242.Sh BUGS 243The gpio pins on the MCP2221 / MCP2221A are very slow and one should 244not expect to be able to rapidly change their state. 245Even if the problem mentioned below did not exist, one should not 246expect to be able to use any of the gpio bit banger drivers such as 247.Xr gpioiic 4 248or 249.Xr gpioow 4 . 250.Pp 251The interrupt function on GP1 cannot currently be used because it is 252currently not possible to attach through the driver. 253There may be two possible problems going on: 254.Bl -bullet 255.It 256The 257.Xr gpio 4 258framework runs at 259.Dv IPL_VM 260with a spin lock and when it attempts to establish an interrupt that 261uses the gpio from 262.Xr umcpmio 4 , 263calls are made into the USB stack that will want to wait in a way that 264is not allowed while holding a spin lock. 265. 266.It 267.Xr autoconf 9 268runs with 269.Dv KERNEL_LOCK 270and during the attachment, this lock is held when calls are made into 271the USB stack that will cause a wait that is not allowed while holding 272.Dv KERNEL_LOCK . 273.El 274. 275.Pp 276Either or both of these may be 277going on, but the end result is that the kernel will panic while 278attempting to perform a USB transfer while another driver is 279attempting to attach through 280.Xr umcpmio 4 . 281.Pp 282Likewise, a 283.Ql \|gpioctl gpio1 attach ...\| 284type call will also panic for the same reason. 285.Pp 286The end result is that 287.Xr gpioirq 4 , 288.Xr gpiopps 4 289and 290.Xr gpioow 4 291will not work with the gpio from 292.Xr umcpio 4 . 293.Pp 294Please note that the 295.Xr umcpmio 4 296driver itself can use the USB stack during attachment and there does 297not appear to be any problems using the GPIO pins or setting GPIO pin 298configurations. 299It is only when the driver is a target during another driver's 300attachment that there is a problem. 301.Pp 302The ability to set or change values in most of the chip's FLASH memory 303is not supported. 304This includes changing the configuration protection password. 305Likewise, support for entering the configuration protection password 306does not exist, should a particular chip have password protection 307enabled. 308