From 06d7118e946716bc69fbc7bb4197281c168d71a5 Mon Sep 17 00:00:00 2001 From: cinap_lenrek Date: Sun, 17 Jul 2022 14:22:47 +0000 Subject: [PATCH] i2c(3): Add documentation for kernels devi2c --- sys/man/3/i2c | 99 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 99 insertions(+) create mode 100644 sys/man/3/i2c diff --git a/sys/man/3/i2c b/sys/man/3/i2c new file mode 100644 index 000000000..be49d50d4 --- /dev/null +++ b/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.