Module Name: src
Committed By: uwe
Date: Mon Dec 16 17:25:09 UTC 2024
Modified Files:
src/share/man/man4: umcpmio.4
Log Message:
umcpmio(4): fix markup
New sentence - new line. Misc formatting make up. Fix a typo in
sysctl variable name.
To generate a diff of this commit:
cvs rdiff -u -r1.1 -r1.2 src/share/man/man4/umcpmio.4
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/share/man/man4/umcpmio.4
diff -u src/share/man/man4/umcpmio.4:1.1 src/share/man/man4/umcpmio.4:1.2
--- src/share/man/man4/umcpmio.4:1.1 Mon Dec 16 16:37:38 2024
+++ src/share/man/man4/umcpmio.4 Mon Dec 16 17:25:09 2024
@@ -1,4 +1,4 @@
-.\" $NetBSD: umcpmio.4,v 1.1 2024/12/16 16:37:38 brad Exp $
+.\" $NetBSD: umcpmio.4,v 1.2 2024/12/16 17:25:09 uwe Exp $
.\"
.\" Copyright (c) 2024 Brad Spencer <b...@anduin.eldar.org>
.\"
@@ -36,10 +36,15 @@ device, a I2C port that attaches as a
.Xr iic 4
device and a UART serial port that attaches using
.Xr umodem 4
-as a normal ttyUx device. The UART is presented as one USB function, while the
-GPIO and I2C pins are presented as a second HID USB function.
-.Sh GPIO
+as a normal
+.Xr ucom 4
+.Pa ttyU Ns Ar \&*
+device.
+The UART is presented as one USB function, while the GPIO and I2C pins
+are presented as a second HID USB function.
+.Ss GPIO
There are 4 basic gpio pins available with the following functions:
+.Bd -filled -offset indent
.TS
box tab(:);
l | l | l | l | l
@@ -55,89 +60,143 @@ ALT1:-:UART TX:DAC1:DAC2
ALT2:-:IRQ:-:-
ALT3:SSPND:Clock output:USBCFG:I2C activity
.TE
+.Ed
.Pp
ADC1, ADC2 and ADC3 are independent of each other and each 10 bits in
-length. To utilize one of the ADC pins an
+length.
+To utilize one of the ADC pins an
.Xr open 2
-is performed 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.
+is performed against
+.Pa /dev/umcpmio0GP1 ,
+.Pa /dev/umcpmio0GP2
+or
+.Pa /dev/umcpmio0GP3
+with only the
+.Dv O_RDONLY
+flag set.
+Reads against the open file descriptor will produce
+.Vt uint16_t
+values.
.Pp
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. The DAC is 5 bits in length
-and to use it an
+to GP2 and GP3 if the pin is set to ALT1.
+The DAC is 5 bits in length and to use it an
.Xr open 2
-is performed aginst /dev/umcpmio0GP2 or /dev/umcpmio0GP3 with only the
-O_WRONLY flag set. Writes of uint8_t bytes to the file descriptor
-will result in a analog signal being created on the output pin.
+is performed aginst
+.Pa /dev/umcpmio0GP2
+or
+.Pa /dev/umcpmio0GP3
+with only the
+.Dv O_WRONLY
+flag set.
+Writes of
+.Vt uint8_t
+bytes to the file descriptor will result in a analog signal being
+created on the output pin.
.Pp
-The clock output is derived from the USB clock of 48MHZ. The duty
-cycle and clock divider can be adjusted with
+The clock output is derived from the USB clock of 48MHZ.
+The duty cycle and clock divider can be adjusted with
.Xr sysctl 8
-variables. To utilize GP1 as the clock output, the ALT3 function can
-be set with
+variables.
+To utilize GP1 as the clock output, the ALT3 function can be set with
.Xr gpioctl 8
command.
-.Sh I2C
+.Ss 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. The
-ability to perform a 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 a attempt to allow a
-device to function and it may not work for any particular device. In
-particular, it is known that the
+When the driver attaches, the I2C speed is set to 100Kb/s.
+The ability to perform a 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 a attempt to allow a device to function and it
+may not work for any particular device.
+In particular, it is known that the
.Xr si70xxtemp 4
and
.Xr ds2482ow 4
devices will not work as expected.
-.Sh UART
+.Ss UART
The UART utilizes the
.Xr umodem 4
-driver. The UART function of the chip only support 8-N-1 communications.
+driver.
+The UART function of the chip only support
+.Tn 8-N-1
+communications.
.Sh SYSCTL VARIABLES
The following
.Xr sysctl 3
variables are provided:
-.Bl -tag -width indent
+.
+.Pp
+.Bl -tag -width Li -compact
+.
.It Li hw.umcpmio0.debug
.It Li hw.umcpmio0.dump_buffers
-If UMCPMIO_DEBUG is defined, additional debugging output can be
-enabled.
+If
+.Dv UMCPMIO_DEBUG
+is defined, additional debugging output can be enabled.
+.
+.Pp
.It Li hw.umcpmio0.response_wait
.It Li 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 reponse_errcnt number of errors when
-waiting for a reponse from a HID report. This includes timeouts due
-to exceeding response_wait.
+from the chip.
+This variable is in microseconds and defaults to 2500.
+The driver will only allow
+.Li response_errcnt
+number of errors when waiting for a reponse from a HID report.
+This includes timeouts due to exceeding response_wait.
+.
+.Pp
.It Li hw.umcpmio0.i2c.reportreadnostop
Report on the console if a driver attempts to use a 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.
+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.
+.
+.Pp
.It Li 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.
+.
+.Pp
.It Li hw.umcpmio0.i2c.retry_busy_read
The number of times to try to do a I2C READ when the engine is busy.
+.
+.Pp
.It Li hw.umcpmio0.i2c.retry_busy_write
The number of times to try to do a I2C WRITE when the engine is busy.
+.
+.Pp
.It Li hw.umcpmio0.gpio.clock_duty_cycle
.It Li 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 values for clock_divider are 375kHz,
-750kHz, 1.5MHz, 3MHz, 6MHz, 12MHz and 24MHz.
+pulse.
+The valid values for
+.Li 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 values for
+.Li clock_divider
+are 375kHz, 750kHz, 1.5MHz, 3MHz, 6MHz, 12MHz and 24MHz.
+.
+.Pp
.It Li hw.umcpmio0.dac.vref
.It Li 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.
+Sets the VREF value for the DAC or ADC.
+The valid values are 4.096V, 2.048V, 1.024V,
+.Ql OFF ,
+and
+.Ql VDD .
+.
.El
+.
.Sh FILES
-.Bl -tag -width "/dev/umcpmio0ctl" -compact
+.Bl -tag -width Pa -compact
.It Pa /dev/umcpmio0ctl
A control device for the chip instance that allows for a number of
IOCTLs.
+.Pp
.It Pa /dev/umcpmio0GP1
.It Pa /dev/umcpmio0GP2
.It Pa /dev/umcpmio0GP3
@@ -162,33 +221,47 @@ driver was written by
.An Brad Spencer Aq Mt b...@anduin.eldar.org .
.Sh BUGS
The gpio pins on the MCP2221 / MCP2221A are very slow and one should
-not expect to be able 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
+not expect to be able 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
.Xr gpioiic 4
or
.Xr gpioow 4 .
.Pp
The interrupt function on GP1 can not currently be used because it is
-currently not possible to attach though the driver. There may be
-two possible problems going on: 1) The
+currently not possible to attach though the driver.
+There may be two possible problems going on:
+.Bl -bullet
+.It
+The
.Xr gpio 4
-framework runs at IPL_VM with a spin lock and when it attempts to
-establish an interrupt that uses the gpio from
+framework runs at
+.Dv IPL_VM
+with a spin lock and when it attempts to establish an interrupt that
+uses the gpio from
.Xr 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. 2)
+is not allowed while holding a spin lock.
+.
+.It
.Xr 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_LOGK. Either or both of these may be
+runs with
+.Dv 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
+.Dv KERNEL_LOGK .
+.El
+
+.Pp
+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 though
.Xr umcpmio 4 .
.Pp
-Likewise, a "gpioctl gpio1 attach ..." type call will also panic for
-for the same reason.
+Likewise, a
+.Ql \|gpioctl gpio1 attach ...\|
+type call will also panic for for the same reason.
.Pp
The end result is that
.Xr gpioirq 4 ,
@@ -202,11 +275,13 @@ Please note that the
.Xr 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
-drivers attachment that there is a problem.
+configurations.
+It is only when the driver is a target during another drivers
+attachment that there is a problem.
.Pp
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.
+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.
