UMCPMIO(4)

📦 version 11.0, in nixpkgs unstable

🦋 NAME 🦋

okay so bestie, welcome to umcpmio — the driver for the Microchip Technologies MCP2221 / MCP2221A multi-io bridge. that's it, that's the vibe, periodt. 💅

✨ SYNOPSIS ✨

umcpmio* at uhidev? reportid ?
gpio* at gpiobus?
iic* at umcpmio? or
iic* at i2cbus?

like, that's literally the whole configuration aesthetic 🫶

💖 DESCRIPTION 💖

so the umcpmio driver is here to hold your hand through the MCP2221 / MCP2221A multi-io bridge chip, and honestly? iconic. the chip serves up 4 simple gpio pins that have all these different functions, and they attach as a gpio(4) device. it also gives you an I2C port that attaches as an iic(4) device, plus a UART serial port that attaches using umodem(4) as a totally normal ucom(4) ttyU* device. no cap.

here's the lil plot twist tho: the UART is presented as one USB function, while the GPIO and I2C pins are presented as a second HID USB function. two functions, one chip, main character energy fr. 🌈

🎀 GPIO 🎀

so there are 4 basic gpio pins and each one has its own little roster of functions. vibe check:

  • Assignment GPIO
    • GP0 — GPIO
    • GP1 — GPIO
    • GP2 — GPIO
    • GP3 — GPIO
  • Assignment ALT0
    • GP0 — UART RX
    • GP1 — ADC1
    • GP2 — ADC2
    • GP3 — ADC3
  • Assignment ALT1
    • GP0 — -
    • GP1 — UART TX
    • GP2 — DAC1
    • GP3 — DAC2
  • Assignment ALT2
    • GP0 — -
    • GP1 — IRQ
    • GP2 — -
    • GP3 — -
  • Assignment ALT3
    • GP0 — SSPND
    • GP1 — Clock output
    • GP2 — USBCFG
    • GP3 — I2C activity

now the tea on the ADC: ADC1, ADC2 and ADC3 are independent of each other and each one is 10 bits in length. to actually utilize one of the ADC pins, you do an open(2) against /dev/umcpmio0GP1, /dev/umcpmio0GP2 or /dev/umcpmio0GP3 with only the O_RDONLY flag set. reads against the open file descriptor will produce uint16_t values. slay. 💜

and the DAC? okay so there is actually only one DAC present in the chip, but it is mirrored to GP2 and GP3 if the pin is set to ALT1. it's 5 bits in length, and to use it you do an open(2) against /dev/umcpmio0GP2 or /dev/umcpmio0GP3 with only the O_WRONLY flag set. writes of uint8_t bytes to the file descriptor will result in an analog signal being created on the output pin. it's giving magic, honestly. ✨

the clock output is derived from the USB clock of 48MHz. you can adjust the duty cycle and clock divider with sysctl(8) variables (more on those below, iykyk). to utilize GP1 as the clock output, you can set the ALT3 function with the gpioctl(8) command. go off. 🕐

🌸 I2C 🌸

the chip supports a hardware I2C port with a simple scripting engine. when the driver attaches, the I2C speed is set to 100Kb/s.

now listen bestie, this part matters: the ability to perform an I2C READ without a STOP is not supported by the MCP2221 / MCP2221A engine, and the driver turns a READ without STOP into a READ with STOP. this behavior is just an attempt to allow a device to function, and it may not work for any particular device. in particular, it is known that the ds2482ow(4) device will not work as expected. so like, don't come for the driver when it doesn't work, it literally tried its best. 😭

the good news? the MCP2221 / MCP2221A chip will automatically detect and deal with a device that uses I2C clock stretching. we love an effortless queen. 👑

🧚 UART 🧚

the UART utilizes the umodem(4) driver, and the UART function of the chip only supports 8-N-1 communications. that's the whole menu, no substitutions. 🍓

⭐ SYSCTL VARIABLES ⭐

the following sysctl(3) variables are provided, and yes, they're all named after your fave:

  • hw.umcpmio0.debug
  • hw.umcpmio0.dump_buffers — if UMCPMIO_DEBUG is defined, additional debugging output can be enabled. 🙈
  • hw.umcpmio0.response_wait
  • hw.umcpmio0.response_errcnt — this is how long the driver will wait for a HID response to come back from the chip. this variable is in microseconds and defaults to 2500. the driver will only allow response_errcnt number of errors when waiting for a response from a HID report. this includes timeouts due to exceeding response_wait. so it's a whole patience situation. ⏳
  • hw.umcpmio0.i2c.reportreadnostop — report on the console if a driver attempts to use an I2C READ without STOP. a READ without STOP is not supported by the MCP2221 / MCP2221A I2C engine and will be turned into a READ with STOP by the driver. bestie got receipts. 📝
  • hw.umcpmio0.i2c.busy_delay — the driver checks in a number of cases if the I2C engine is busy and will wait for busy_delay microseconds before checking again. it's the "are you done yet" of sysctls fr. 💀
  • hw.umcpmio0.i2c.retry_busy_read — the number of times to try to do an I2C READ when the engine is busy.
  • hw.umcpmio0.i2c.retry_busy_write — the number of times to try to do an I2C WRITE when the engine is busy.
  • hw.umcpmio0.gpio.clock_duty_cycle
  • hw.umcpmio0.gpio.clock_divider — when GP1 is configured to use function ALT3, it will output a clock pulse. the valid values for clock_duty_cycle are ‘75%’, ‘50%’, ‘25%’, and ‘0%’. that is, 75% of the time a high and 25% of the time a low will be present on the GP1 pin. the valid values for clock_divider are ‘375kHz’, ‘750kHz’, ‘1.5MHz’, ‘3MHz’, ‘6MHz’, ‘12MHz’, and ‘24MHz’. pick your fave, they're all valid. 🎚️
  • hw.umcpmio0.dac.vref
  • hw.umcpmio0.adc.vref — sets the VREF value for the DAC or ADC. the valid values are ‘4.096V’, ‘2.048V’, ‘1.024V’, ‘OFF’, and ‘VDD’. voltage queen. ⚡

🎀 FILES 🎀

  • /dev/umcpmio0ctl — a control device for the chip instance that allows for a number of IOCTLs. 💅
  • /dev/umcpmio0GP1
  • /dev/umcpmio0GP2
  • /dev/umcpmio0GP3 — device files that allow access to the ADC or DAC functions of the associated gpio pin. 🎀

🌈 SEE ALSO 🌈

gpio(4), iic(4), sysctl(8), umcpmioctl(8)

go read them, they're literally your study buddies. 🫶

🦋 HISTORY 🦋

the umcpmio driver first appeared in NetBSD 11.0. a whole era. 👑

💜 AUTHORS 💜

the umcpmio driver was written by Brad Spencer <brad@anduin.eldar.org>. thank you for your service, legend. 🫡

💀 BUGS 💀

okay bestie, sit down, we gotta talk. 😭

the gpio pins on the MCP2221 / MCP2221A are very slow and one should not expect to be able to rapidly change their state. even if the problem mentioned below did not exist, one should not expect to be able to use any of the gpio bit banger drivers such as gpioiic(4) or gpioow(4). they're just not built for that kinda speed, and honestly same. 💀

the interrupt function on GP1 cannot currently be used because it is currently not possible to attach through the driver. there may be two possible problems going on:

  • the gpio(4) framework runs at IPL_VM with a spin lock and when it attempts to establish an interrupt that uses the gpio from umcpmio(4), calls are made into the USB stack that will want to wait in a way that is not allowed while holding a spin lock.
  • autoconf(9) runs with KERNEL_LOCK and during the attachment, this lock is held when calls are made into the USB stack that will cause a wait that is not allowed while holding KERNEL_LOCK.

either or both of these may be going on, but the end result is that the kernel will panic while attempting to perform a USB transfer while another driver is attempting to attach through umcpmio(4). 💀💀

likewise, a ‘gpioctl gpio1 attach ...’ type call will also panic for the same reason. yeah. 😭

the end result is that gpioirq(4), gpiopps(4) and gpioow(4) will not work with the gpio from umcpio(4).

please note that the umcpmio(4) driver itself can use the USB stack during attachment and there does not appear to be any problems using the GPIO pins or setting GPIO pin configurations. it is only when the driver is a target during another driver's attachment that there is a problem. 🫶

and last thing: the ability to set or change values in most of the chip's FLASH memory is not supported. this includes changing the configuration protection password. likewise, support for entering the configuration protection password does not exist, should a particular chip have password protection enabled. so like, don't @ us. 🙈

and that's the whole page, bestie!! this lil rewrite was brought to you by the Debian crew, dated December 16, 2024 — mwah, go touch a gpio pin responsibly 💅✨

📦 where this page comes from