i2c(3): Add documentation for kernels devi2c

sys/man/3/i2c

@@ -0,0 +1,99 @@
+.TH I2C 3
+.SH NAME
+i2c \- I²C Bus Interface
+.SH SYNOPSIS
+.nf
+.B bind -a #J /dev
+.PP
+.nf
+.BI /dev/ bus /i2c. n .ctl
+.BI /dev/ bus /i2c. n .data
+.fi
+.SH DESCRIPTION
+The I²C (Inter-Integrated Circuit) bus is a serial bus standard
+invented by Philips.
+It is used to connect chips over short-distances like on a motherboard
+or between boards.
+The bus requires only a single data signal 
+.IR SDA ,
+a clock signal
+.I SDC
+and ground.
+Devices on the bus have 7-bit or 10-bit addreesses, which is
+determined by the device (see the datasheet).
+Every device monitors the bus and waits for the master to initiate
+a transaction.
+Each transaction starts with the master sending the target device address
+and direction bit and the device is acknowledging each byte
+received if its address matched.
+Depending on the device, more bytes must be transmitted after the
+.IR device-address .
+For example, to encode a register number an memory offset.
+We refer to these bytes as the
+.IR sub-address .
+After the address phase, the data phase begins where
+zero or more data bytes are eigther transmitted or received
+depending on the transactoin direction.
+.PP
+This driver supports multiple buses (controllers) to be registered
+by platform specific code in the kernel.
+Each bus is represented as a directory with a platform specific name.
+.PP
+Because all received bytes are acknowledged by target devices,
+it is possible for the master to enumerate all existing addresses
+on a bus, which is done when accessing the
+.I bus
+directory.
+.PP
+Platform specific code can also register individual devices,
+supplying a meaningfull device configuration.
+It can also be neccesary to manually register devices if
+the device has been disabled by a enable signal or
+otherwise inhibited during enumeration.
+.PP
+Each device appears as a control (
+.BI i2c. n .ctl
+)
+and a data file (
+.BI i2c. n .data
+) in the
+.I bus
+directory
+where
+.I n
+is the device-address in hexadecimal.
+.PP
+The data file is used to initiate transactions to the device.
+The initial
+.I sub-address
+bytes sent are derived from the file position according to the device
+configuration and the length of the data phase is controlled by
+the requested read or write size.
+The requested size might be truncated by the driver if
+the request exceeds the logical file-size.
+.PP
+The control-file provides access the device configuration.
+When read,
+it reproduces this configuration in text form.
+The following text lines are accepted when written to the control-file:
+.TF "subaddress n"
+.TP
+.BI "subaddress " n
+Sets the length
+.IR n ,
+in bytes, of the sub-address for the device
+that is derived from the file-position of the data-file.
+This can be set to zero if no sub-address bytes should
+be generated by the driver.
+By default, the sub-address length is 1.
+.TP
+.BI "size " n
+Changes the logical size of the data-file to
+.IR n .
+Making sure the file-position is not exceeding this size.
+.SH SOURCE
+.B /sys/src/9/port/devi2c.c
+.SH HISTORY
+The file-interface has been inspired by infernos devi2c,
+but with the addition of supporting multiple buses
+and device enumeration.