From eaf7b46083a7e341a23ab3d6042e0ccc115b0914 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 26 Jul 2019 09:51:12 -0300 Subject: docs: thermal: add it to the driver API The file contents mostly describes driver internals. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- include/linux/thermal.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'include') diff --git a/include/linux/thermal.h b/include/linux/thermal.h index 681047f8cc05..e45659c75920 100644 --- a/include/linux/thermal.h +++ b/include/linux/thermal.h @@ -251,7 +251,7 @@ struct thermal_bind_params { * platform characterization. This value is relative to the * rest of the weights so a cooling device whose weight is * double that of another cooling device is twice as - * effective. See Documentation/thermal/sysfs-api.rst for more + * effective. See Documentation/driver-api/thermal/sysfs-api.rst for more * information. */ int weight; @@ -259,7 +259,7 @@ struct thermal_bind_params { /* * This is a bit mask that gives the binding relation between this * thermal zone and cdev, for a particular trip point. - * See Documentation/thermal/sysfs-api.rst for more information. + * See Documentation/driver-api/thermal/sysfs-api.rst for more information. */ int trip_mask; -- cgit v1.2.3 From ccf988b66d697efcd0ceccc2398e0d9b909cd17c Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 26 Jul 2019 09:51:16 -0300 Subject: docs: i2c: convert to ReST and add to driver-api bookset Convert each file at I2C subsystem, renaming them to .rst and adding to the driver-api book. Signed-off-by: Mauro Carvalho Chehab Acked-by: Wolfram Sang Acked-by: Alexandre Belloni Acked-by: Jonathan Cameron Signed-off-by: Jonathan Corbet --- .../devicetree/bindings/i2c/i2c-mux-gpmux.txt | 2 +- Documentation/driver-api/ipmb.rst | 2 +- Documentation/hwmon/adm1021.rst | 2 +- Documentation/hwmon/adm1275.rst | 2 +- Documentation/hwmon/hih6130.rst | 2 +- Documentation/hwmon/ibm-cffps.rst | 2 +- Documentation/hwmon/lm25066.rst | 2 +- Documentation/hwmon/max16064.rst | 2 +- Documentation/hwmon/max16065.rst | 2 +- Documentation/hwmon/max20751.rst | 2 +- Documentation/hwmon/max34440.rst | 2 +- Documentation/hwmon/max6650.rst | 2 +- Documentation/hwmon/max8688.rst | 2 +- Documentation/hwmon/menf21bmc.rst | 2 +- Documentation/hwmon/pcf8591.rst | 2 +- Documentation/hwmon/sht3x.rst | 2 +- Documentation/hwmon/shtc1.rst | 2 +- Documentation/hwmon/tmp103.rst | 2 +- Documentation/hwmon/tps40422.rst | 2 +- Documentation/hwmon/ucd9000.rst | 2 +- Documentation/hwmon/ucd9200.rst | 2 +- Documentation/hwmon/via686a.rst | 2 +- Documentation/hwmon/zl6100.rst | 2 +- Documentation/i2c/DMA-considerations | 71 ---- Documentation/i2c/busses/i2c-ali1535 | 42 -- Documentation/i2c/busses/i2c-ali1535.rst | 45 +++ Documentation/i2c/busses/i2c-ali1563 | 27 -- Documentation/i2c/busses/i2c-ali1563.rst | 30 ++ Documentation/i2c/busses/i2c-ali15x3 | 112 ------ Documentation/i2c/busses/i2c-ali15x3.rst | 122 ++++++ Documentation/i2c/busses/i2c-amd-mp2 | 23 -- Documentation/i2c/busses/i2c-amd-mp2.rst | 25 ++ Documentation/i2c/busses/i2c-amd756 | 25 -- Documentation/i2c/busses/i2c-amd756.rst | 29 ++ Documentation/i2c/busses/i2c-amd8111 | 41 -- Documentation/i2c/busses/i2c-amd8111.rst | 43 +++ Documentation/i2c/busses/i2c-diolan-u2c | 26 -- Documentation/i2c/busses/i2c-diolan-u2c.rst | 29 ++ Documentation/i2c/busses/i2c-i801 | 173 --------- Documentation/i2c/busses/i2c-i801.rst | 182 +++++++++ Documentation/i2c/busses/i2c-ismt | 36 -- Documentation/i2c/busses/i2c-ismt.rst | 44 +++ Documentation/i2c/busses/i2c-mlxcpld | 51 --- Documentation/i2c/busses/i2c-mlxcpld.rst | 57 +++ Documentation/i2c/busses/i2c-nforce2 | 50 --- Documentation/i2c/busses/i2c-nforce2.rst | 53 +++ Documentation/i2c/busses/i2c-nvidia-gpu | 18 - Documentation/i2c/busses/i2c-nvidia-gpu.rst | 20 + Documentation/i2c/busses/i2c-ocores | 68 ---- Documentation/i2c/busses/i2c-ocores.rst | 70 ++++ Documentation/i2c/busses/i2c-parport | 178 --------- Documentation/i2c/busses/i2c-parport-light | 22 -- Documentation/i2c/busses/i2c-parport-light.rst | 24 ++ Documentation/i2c/busses/i2c-parport.rst | 190 +++++++++ Documentation/i2c/busses/i2c-pca-isa | 23 -- Documentation/i2c/busses/i2c-pca-isa.rst | 26 ++ Documentation/i2c/busses/i2c-piix4 | 112 ------ Documentation/i2c/busses/i2c-piix4.rst | 114 ++++++ Documentation/i2c/busses/i2c-sis5595 | 59 --- Documentation/i2c/busses/i2c-sis5595.rst | 68 ++++ Documentation/i2c/busses/i2c-sis630 | 58 --- Documentation/i2c/busses/i2c-sis630.rst | 63 +++ Documentation/i2c/busses/i2c-sis96x | 73 ---- Documentation/i2c/busses/i2c-sis96x.rst | 82 ++++ Documentation/i2c/busses/i2c-taos-evm | 46 --- Documentation/i2c/busses/i2c-taos-evm.rst | 48 +++ Documentation/i2c/busses/i2c-via | 34 -- Documentation/i2c/busses/i2c-via.rst | 40 ++ Documentation/i2c/busses/i2c-viapro | 73 ---- Documentation/i2c/busses/i2c-viapro.rst | 77 ++++ Documentation/i2c/busses/index.rst | 33 ++ Documentation/i2c/busses/scx200_acb | 32 -- Documentation/i2c/busses/scx200_acb.rst | 37 ++ Documentation/i2c/dev-interface | 213 ----------- Documentation/i2c/dev-interface.rst | 219 +++++++++++ Documentation/i2c/dma-considerations.rst | 71 ++++ Documentation/i2c/fault-codes | 128 ------- Documentation/i2c/fault-codes.rst | 131 +++++++ Documentation/i2c/functionality | 148 ------- Documentation/i2c/functionality.rst | 156 ++++++++ Documentation/i2c/gpio-fault-injection | 136 ------- Documentation/i2c/gpio-fault-injection.rst | 136 +++++++ Documentation/i2c/i2c-protocol | 88 ----- Documentation/i2c/i2c-protocol.rst | 98 +++++ Documentation/i2c/i2c-stub | 64 ---- Documentation/i2c/i2c-stub.rst | 66 ++++ Documentation/i2c/i2c-topology | 376 ------------------ Documentation/i2c/i2c-topology.rst | 396 +++++++++++++++++++ Documentation/i2c/index.rst | 37 ++ Documentation/i2c/instantiating-devices | 248 ------------ Documentation/i2c/instantiating-devices.rst | 253 ++++++++++++ Documentation/i2c/muxes/i2c-mux-gpio | 83 ---- Documentation/i2c/muxes/i2c-mux-gpio.rst | 85 +++++ Documentation/i2c/old-module-parameters | 44 --- Documentation/i2c/old-module-parameters.rst | 49 +++ Documentation/i2c/slave-eeprom-backend | 14 - Documentation/i2c/slave-eeprom-backend.rst | 14 + Documentation/i2c/slave-interface | 193 ---------- Documentation/i2c/slave-interface.rst | 198 ++++++++++ Documentation/i2c/smbus-protocol | 283 -------------- Documentation/i2c/smbus-protocol.rst | 301 +++++++++++++++ Documentation/i2c/summary | 43 --- Documentation/i2c/summary.rst | 45 +++ Documentation/i2c/ten-bit-addresses | 28 -- Documentation/i2c/ten-bit-addresses.rst | 33 ++ Documentation/i2c/upgrading-clients | 279 -------------- Documentation/i2c/upgrading-clients.rst | 285 ++++++++++++++ Documentation/i2c/writing-clients | 403 ------------------- Documentation/i2c/writing-clients.rst | 425 +++++++++++++++++++++ Documentation/index.rst | 1 + Documentation/spi/spi-sc18is602 | 2 +- MAINTAINERS | 48 +-- drivers/hwmon/atxp1.c | 2 +- drivers/hwmon/smm665.c | 2 +- drivers/i2c/Kconfig | 4 +- drivers/i2c/busses/Kconfig | 2 +- drivers/i2c/busses/i2c-i801.c | 2 +- drivers/i2c/busses/i2c-taos-evm.c | 2 +- drivers/i2c/i2c-core-base.c | 4 +- drivers/iio/dummy/iio_simple_dummy.c | 2 +- drivers/rtc/rtc-ds1374.c | 2 +- include/linux/i2c.h | 2 +- 122 files changed, 4610 insertions(+), 4304 deletions(-) delete mode 100644 Documentation/i2c/DMA-considerations delete mode 100644 Documentation/i2c/busses/i2c-ali1535 create mode 100644 Documentation/i2c/busses/i2c-ali1535.rst delete mode 100644 Documentation/i2c/busses/i2c-ali1563 create mode 100644 Documentation/i2c/busses/i2c-ali1563.rst delete mode 100644 Documentation/i2c/busses/i2c-ali15x3 create mode 100644 Documentation/i2c/busses/i2c-ali15x3.rst delete mode 100644 Documentation/i2c/busses/i2c-amd-mp2 create mode 100644 Documentation/i2c/busses/i2c-amd-mp2.rst delete mode 100644 Documentation/i2c/busses/i2c-amd756 create mode 100644 Documentation/i2c/busses/i2c-amd756.rst delete mode 100644 Documentation/i2c/busses/i2c-amd8111 create mode 100644 Documentation/i2c/busses/i2c-amd8111.rst delete mode 100644 Documentation/i2c/busses/i2c-diolan-u2c create mode 100644 Documentation/i2c/busses/i2c-diolan-u2c.rst delete mode 100644 Documentation/i2c/busses/i2c-i801 create mode 100644 Documentation/i2c/busses/i2c-i801.rst delete mode 100644 Documentation/i2c/busses/i2c-ismt create mode 100644 Documentation/i2c/busses/i2c-ismt.rst delete mode 100644 Documentation/i2c/busses/i2c-mlxcpld create mode 100644 Documentation/i2c/busses/i2c-mlxcpld.rst delete mode 100644 Documentation/i2c/busses/i2c-nforce2 create mode 100644 Documentation/i2c/busses/i2c-nforce2.rst delete mode 100644 Documentation/i2c/busses/i2c-nvidia-gpu create mode 100644 Documentation/i2c/busses/i2c-nvidia-gpu.rst delete mode 100644 Documentation/i2c/busses/i2c-ocores create mode 100644 Documentation/i2c/busses/i2c-ocores.rst delete mode 100644 Documentation/i2c/busses/i2c-parport delete mode 100644 Documentation/i2c/busses/i2c-parport-light create mode 100644 Documentation/i2c/busses/i2c-parport-light.rst create mode 100644 Documentation/i2c/busses/i2c-parport.rst delete mode 100644 Documentation/i2c/busses/i2c-pca-isa create mode 100644 Documentation/i2c/busses/i2c-pca-isa.rst delete mode 100644 Documentation/i2c/busses/i2c-piix4 create mode 100644 Documentation/i2c/busses/i2c-piix4.rst delete mode 100644 Documentation/i2c/busses/i2c-sis5595 create mode 100644 Documentation/i2c/busses/i2c-sis5595.rst delete mode 100644 Documentation/i2c/busses/i2c-sis630 create mode 100644 Documentation/i2c/busses/i2c-sis630.rst delete mode 100644 Documentation/i2c/busses/i2c-sis96x create mode 100644 Documentation/i2c/busses/i2c-sis96x.rst delete mode 100644 Documentation/i2c/busses/i2c-taos-evm create mode 100644 Documentation/i2c/busses/i2c-taos-evm.rst delete mode 100644 Documentation/i2c/busses/i2c-via create mode 100644 Documentation/i2c/busses/i2c-via.rst delete mode 100644 Documentation/i2c/busses/i2c-viapro create mode 100644 Documentation/i2c/busses/i2c-viapro.rst create mode 100644 Documentation/i2c/busses/index.rst delete mode 100644 Documentation/i2c/busses/scx200_acb create mode 100644 Documentation/i2c/busses/scx200_acb.rst delete mode 100644 Documentation/i2c/dev-interface create mode 100644 Documentation/i2c/dev-interface.rst create mode 100644 Documentation/i2c/dma-considerations.rst delete mode 100644 Documentation/i2c/fault-codes create mode 100644 Documentation/i2c/fault-codes.rst delete mode 100644 Documentation/i2c/functionality create mode 100644 Documentation/i2c/functionality.rst delete mode 100644 Documentation/i2c/gpio-fault-injection create mode 100644 Documentation/i2c/gpio-fault-injection.rst delete mode 100644 Documentation/i2c/i2c-protocol create mode 100644 Documentation/i2c/i2c-protocol.rst delete mode 100644 Documentation/i2c/i2c-stub create mode 100644 Documentation/i2c/i2c-stub.rst delete mode 100644 Documentation/i2c/i2c-topology create mode 100644 Documentation/i2c/i2c-topology.rst create mode 100644 Documentation/i2c/index.rst delete mode 100644 Documentation/i2c/instantiating-devices create mode 100644 Documentation/i2c/instantiating-devices.rst delete mode 100644 Documentation/i2c/muxes/i2c-mux-gpio create mode 100644 Documentation/i2c/muxes/i2c-mux-gpio.rst delete mode 100644 Documentation/i2c/old-module-parameters create mode 100644 Documentation/i2c/old-module-parameters.rst delete mode 100644 Documentation/i2c/slave-eeprom-backend create mode 100644 Documentation/i2c/slave-eeprom-backend.rst delete mode 100644 Documentation/i2c/slave-interface create mode 100644 Documentation/i2c/slave-interface.rst delete mode 100644 Documentation/i2c/smbus-protocol create mode 100644 Documentation/i2c/smbus-protocol.rst delete mode 100644 Documentation/i2c/summary create mode 100644 Documentation/i2c/summary.rst delete mode 100644 Documentation/i2c/ten-bit-addresses create mode 100644 Documentation/i2c/ten-bit-addresses.rst delete mode 100644 Documentation/i2c/upgrading-clients create mode 100644 Documentation/i2c/upgrading-clients.rst delete mode 100644 Documentation/i2c/writing-clients create mode 100644 Documentation/i2c/writing-clients.rst (limited to 'include') diff --git a/Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.txt b/Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.txt index 2907dab56298..8b444b94e92f 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.txt @@ -42,7 +42,7 @@ Optional properties: This means that no unrelated I2C transactions are allowed on the parent I2C adapter for the complete multiplexed I2C transaction. The properties of mux-locked and parent-locked multiplexers are discussed - in more detail in Documentation/i2c/i2c-topology. + in more detail in Documentation/i2c/i2c-topology.rst. For each i2c child node, an I2C child bus will be created. They will be numbered based on their order in the device tree. diff --git a/Documentation/driver-api/ipmb.rst b/Documentation/driver-api/ipmb.rst index 7e2265144157..3ec3baed84c4 100644 --- a/Documentation/driver-api/ipmb.rst +++ b/Documentation/driver-api/ipmb.rst @@ -83,7 +83,7 @@ Instantiate the device ---------------------- After loading the driver, you can instantiate the device as -described in 'Documentation/i2c/instantiating-devices'. +described in 'Documentation/i2c/instantiating-devices.rst'. If you have multiple BMCs, each connected to your Satellite MC via a different I2C bus, you can instantiate a device for each of those BMCs. diff --git a/Documentation/hwmon/adm1021.rst b/Documentation/hwmon/adm1021.rst index 6cbb0f75fe00..116fb2019956 100644 --- a/Documentation/hwmon/adm1021.rst +++ b/Documentation/hwmon/adm1021.rst @@ -142,7 +142,7 @@ loading the adm1021 module, then things are good. If nothing happens when loading the adm1021 module, and you are certain that your specific Xeon processor model includes compatible sensors, you will have to explicitly instantiate the sensor chips from user-space. See -method 4 in Documentation/i2c/instantiating-devices. Possible slave +method 4 in Documentation/i2c/instantiating-devices.rst. Possible slave addresses are 0x18, 0x1a, 0x29, 0x2b, 0x4c, or 0x4e. It is likely that only temp2 will be correct and temp1 will have to be ignored. diff --git a/Documentation/hwmon/adm1275.rst b/Documentation/hwmon/adm1275.rst index 9a1913e5b4d9..49966ed70ec6 100644 --- a/Documentation/hwmon/adm1275.rst +++ b/Documentation/hwmon/adm1275.rst @@ -75,7 +75,7 @@ Usage Notes ----------- This driver does not auto-detect devices. You will have to instantiate the -devices explicitly. Please see Documentation/i2c/instantiating-devices for +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for details. The ADM1075, unlike many other PMBus devices, does not support internal voltage diff --git a/Documentation/hwmon/hih6130.rst b/Documentation/hwmon/hih6130.rst index 649bd4be4fc2..e95d373eb693 100644 --- a/Documentation/hwmon/hih6130.rst +++ b/Documentation/hwmon/hih6130.rst @@ -27,7 +27,7 @@ The devices communicate with the I2C protocol. All sensors are set to the same I2C address 0x27 by default, so an entry with I2C_BOARD_INFO("hih6130", 0x27) can be used in the board setup code. -Please see Documentation/i2c/instantiating-devices for details on how to +Please see Documentation/i2c/instantiating-devices.rst for details on how to instantiate I2C devices. sysfs-Interface diff --git a/Documentation/hwmon/ibm-cffps.rst b/Documentation/hwmon/ibm-cffps.rst index 52e74e39463a..ef8f3f806968 100644 --- a/Documentation/hwmon/ibm-cffps.rst +++ b/Documentation/hwmon/ibm-cffps.rst @@ -17,7 +17,7 @@ Usage Notes ----------- This driver does not auto-detect devices. You will have to instantiate the -devices explicitly. Please see Documentation/i2c/instantiating-devices for +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for details. Sysfs entries diff --git a/Documentation/hwmon/lm25066.rst b/Documentation/hwmon/lm25066.rst index da15e3094c8c..30e6e77fb3c8 100644 --- a/Documentation/hwmon/lm25066.rst +++ b/Documentation/hwmon/lm25066.rst @@ -76,7 +76,7 @@ Usage Notes ----------- This driver does not auto-detect devices. You will have to instantiate the -devices explicitly. Please see Documentation/i2c/instantiating-devices for +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for details. diff --git a/Documentation/hwmon/max16064.rst b/Documentation/hwmon/max16064.rst index 6d5e9538991f..c06249292557 100644 --- a/Documentation/hwmon/max16064.rst +++ b/Documentation/hwmon/max16064.rst @@ -28,7 +28,7 @@ Usage Notes ----------- This driver does not auto-detect devices. You will have to instantiate the -devices explicitly. Please see Documentation/i2c/instantiating-devices for +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for details. diff --git a/Documentation/hwmon/max16065.rst b/Documentation/hwmon/max16065.rst index fa5c852a178c..45f69f334f25 100644 --- a/Documentation/hwmon/max16065.rst +++ b/Documentation/hwmon/max16065.rst @@ -79,7 +79,7 @@ Usage Notes This driver does not probe for devices, since there is no register which can be safely used to identify the chip. You will have to instantiate -the devices explicitly. Please see Documentation/i2c/instantiating-devices for +the devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for details. WARNING: Do not access chip registers using the i2cdump command, and do not use diff --git a/Documentation/hwmon/max20751.rst b/Documentation/hwmon/max20751.rst index aa4469be6674..fe701e07eaf5 100644 --- a/Documentation/hwmon/max20751.rst +++ b/Documentation/hwmon/max20751.rst @@ -30,7 +30,7 @@ Usage Notes ----------- This driver does not auto-detect devices. You will have to instantiate the -devices explicitly. Please see Documentation/i2c/instantiating-devices for +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for details. diff --git a/Documentation/hwmon/max34440.rst b/Documentation/hwmon/max34440.rst index 939138e12b02..5744df100a5d 100644 --- a/Documentation/hwmon/max34440.rst +++ b/Documentation/hwmon/max34440.rst @@ -83,7 +83,7 @@ Usage Notes ----------- This driver does not auto-detect devices. You will have to instantiate the -devices explicitly. Please see Documentation/i2c/instantiating-devices for +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for details. For MAX34446, the value of the currX_crit attribute determines if current or diff --git a/Documentation/hwmon/max6650.rst b/Documentation/hwmon/max6650.rst index 253482add082..7952b6ecaa2d 100644 --- a/Documentation/hwmon/max6650.rst +++ b/Documentation/hwmon/max6650.rst @@ -55,7 +55,7 @@ Usage notes ----------- This driver does not auto-detect devices. You will have to instantiate the -devices explicitly. Please see Documentation/i2c/instantiating-devices for +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for details. Module parameters diff --git a/Documentation/hwmon/max8688.rst b/Documentation/hwmon/max8688.rst index 009487759c61..71e7f2cbe2e2 100644 --- a/Documentation/hwmon/max8688.rst +++ b/Documentation/hwmon/max8688.rst @@ -28,7 +28,7 @@ Usage Notes ----------- This driver does not auto-detect devices. You will have to instantiate the -devices explicitly. Please see Documentation/i2c/instantiating-devices for +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for details. diff --git a/Documentation/hwmon/menf21bmc.rst b/Documentation/hwmon/menf21bmc.rst index 1f0c6b2235ab..978691d5956d 100644 --- a/Documentation/hwmon/menf21bmc.rst +++ b/Documentation/hwmon/menf21bmc.rst @@ -28,7 +28,7 @@ Usage Notes This driver is part of the MFD driver named "menf21bmc" and does not auto-detect devices. You will have to instantiate the MFD driver explicitly. -Please see Documentation/i2c/instantiating-devices for +Please see Documentation/i2c/instantiating-devices.rst for details. Sysfs entries diff --git a/Documentation/hwmon/pcf8591.rst b/Documentation/hwmon/pcf8591.rst index e98bd542a441..5c4e85f53177 100644 --- a/Documentation/hwmon/pcf8591.rst +++ b/Documentation/hwmon/pcf8591.rst @@ -68,7 +68,7 @@ Accessing PCF8591 via /sys interface The PCF8591 is plainly impossible to detect! Thus the driver won't even try. You have to explicitly instantiate the device at the relevant address (in the interval [0x48..0x4f]) either through platform data, or -using the sysfs interface. See Documentation/i2c/instantiating-devices +using the sysfs interface. See Documentation/i2c/instantiating-devices.rst for details. Directories are being created for each instantiated PCF8591: diff --git a/Documentation/hwmon/sht3x.rst b/Documentation/hwmon/sht3x.rst index 978a7117e4b2..95a850d5b2c1 100644 --- a/Documentation/hwmon/sht3x.rst +++ b/Documentation/hwmon/sht3x.rst @@ -26,7 +26,7 @@ scaled by 1000, i.e. the value for 31.5 degrees celsius is 31500. The device communicates with the I2C protocol. Sensors can have the I2C addresses 0x44 or 0x45, depending on the wiring. See -Documentation/i2c/instantiating-devices for methods to instantiate the device. +Documentation/i2c/instantiating-devices.rst for methods to instantiate the device. There are two options configurable by means of sht3x_platform_data: diff --git a/Documentation/hwmon/shtc1.rst b/Documentation/hwmon/shtc1.rst index aa116332ba26..70c1192bbd8c 100644 --- a/Documentation/hwmon/shtc1.rst +++ b/Documentation/hwmon/shtc1.rst @@ -36,7 +36,7 @@ humidity is expressed as a percentage. Driver can be used as well for SHTW1 chip, which has the same electrical interface. The device communicates with the I2C protocol. All sensors are set to I2C -address 0x70. See Documentation/i2c/instantiating-devices for methods to +address 0x70. See Documentation/i2c/instantiating-devices.rst for methods to instantiate the device. There are two options configurable by means of shtc1_platform_data: diff --git a/Documentation/hwmon/tmp103.rst b/Documentation/hwmon/tmp103.rst index 15d25806d585..205de6148fcb 100644 --- a/Documentation/hwmon/tmp103.rst +++ b/Documentation/hwmon/tmp103.rst @@ -30,4 +30,4 @@ The driver provides the common sysfs-interface for temperatures (see Documentation/hwmon/sysfs-interface.rst under Temperatures). Please refer how to instantiate this driver: -Documentation/i2c/instantiating-devices +Documentation/i2c/instantiating-devices.rst diff --git a/Documentation/hwmon/tps40422.rst b/Documentation/hwmon/tps40422.rst index b691e30479dd..8fe3e1c3572e 100644 --- a/Documentation/hwmon/tps40422.rst +++ b/Documentation/hwmon/tps40422.rst @@ -28,7 +28,7 @@ Usage Notes ----------- This driver does not auto-detect devices. You will have to instantiate the -devices explicitly. Please see Documentation/i2c/instantiating-devices for +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for details. diff --git a/Documentation/hwmon/ucd9000.rst b/Documentation/hwmon/ucd9000.rst index ebc4f2b3bfea..746f21fcb48c 100644 --- a/Documentation/hwmon/ucd9000.rst +++ b/Documentation/hwmon/ucd9000.rst @@ -64,7 +64,7 @@ Usage Notes ----------- This driver does not auto-detect devices. You will have to instantiate the -devices explicitly. Please see Documentation/i2c/instantiating-devices for +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for details. diff --git a/Documentation/hwmon/ucd9200.rst b/Documentation/hwmon/ucd9200.rst index b819dfd75f71..4f0e7c3ca6f4 100644 --- a/Documentation/hwmon/ucd9200.rst +++ b/Documentation/hwmon/ucd9200.rst @@ -40,7 +40,7 @@ Usage Notes ----------- This driver does not auto-detect devices. You will have to instantiate the -devices explicitly. Please see Documentation/i2c/instantiating-devices for +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for details. diff --git a/Documentation/hwmon/via686a.rst b/Documentation/hwmon/via686a.rst index a343c35df740..7ab9ddebcf79 100644 --- a/Documentation/hwmon/via686a.rst +++ b/Documentation/hwmon/via686a.rst @@ -40,7 +40,7 @@ all as a 686A. The Via 686a southbridge has integrated hardware monitor functionality. It also has an I2C bus, but this driver only supports the hardware monitor. -For the I2C bus driver, see +For the I2C bus driver, see The Via 686a implements three temperature sensors, two fan rotation speed sensors, five voltage sensors and alarms. diff --git a/Documentation/hwmon/zl6100.rst b/Documentation/hwmon/zl6100.rst index 41513bb7fe51..968aff10ce0a 100644 --- a/Documentation/hwmon/zl6100.rst +++ b/Documentation/hwmon/zl6100.rst @@ -121,7 +121,7 @@ Usage Notes ----------- This driver does not auto-detect devices. You will have to instantiate the -devices explicitly. Please see Documentation/i2c/instantiating-devices for +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for details. .. warning:: diff --git a/Documentation/i2c/DMA-considerations b/Documentation/i2c/DMA-considerations deleted file mode 100644 index 203002054120..000000000000 --- a/Documentation/i2c/DMA-considerations +++ /dev/null @@ -1,71 +0,0 @@ -================= -Linux I2C and DMA -================= - -Given that i2c is a low-speed bus, over which the majority of messages -transferred are small, it is not considered a prime user of DMA access. At this -time of writing, only 10% of I2C bus master drivers have DMA support -implemented. And the vast majority of transactions are so small that setting up -DMA for it will likely add more overhead than a plain PIO transfer. - -Therefore, it is *not* mandatory that the buffer of an I2C message is DMA safe. -It does not seem reasonable to apply additional burdens when the feature is so -rarely used. However, it is recommended to use a DMA-safe buffer if your -message size is likely applicable for DMA. Most drivers have this threshold -around 8 bytes (as of today, this is mostly an educated guess, however). For -any message of 16 byte or larger, it is probably a really good idea. Please -note that other subsystems you use might add requirements. E.g., if your -I2C bus master driver is using USB as a bridge, then you need to have DMA -safe buffers always, because USB requires it. - -Clients -------- - -For clients, if you use a DMA safe buffer in i2c_msg, set the I2C_M_DMA_SAFE -flag with it. Then, the I2C core and drivers know they can safely operate DMA -on it. Note that using this flag is optional. I2C host drivers which are not -updated to use this flag will work like before. And like before, they risk -using an unsafe DMA buffer. To improve this situation, using I2C_M_DMA_SAFE in -more and more clients and host drivers is the planned way forward. Note also -that setting this flag makes only sense in kernel space. User space data is -copied into kernel space anyhow. The I2C core makes sure the destination -buffers in kernel space are always DMA capable. Also, when the core emulates -SMBus transactions via I2C, the buffers for block transfers are DMA safe. Users -of i2c_master_send() and i2c_master_recv() functions can now use DMA safe -variants (i2c_master_send_dmasafe() and i2c_master_recv_dmasafe()) once they -know their buffers are DMA safe. Users of i2c_transfer() must set the -I2C_M_DMA_SAFE flag manually. - -Masters -------- - -Bus master drivers wishing to implement safe DMA can use helper functions from -the I2C core. One gives you a DMA-safe buffer for a given i2c_msg as long as a -certain threshold is met:: - - dma_buf = i2c_get_dma_safe_msg_buf(msg, threshold_in_byte); - -If a buffer is returned, it is either msg->buf for the I2C_M_DMA_SAFE case or a -bounce buffer. But you don't need to care about that detail, just use the -returned buffer. If NULL is returned, the threshold was not met or a bounce -buffer could not be allocated. Fall back to PIO in that case. - -In any case, a buffer obtained from above needs to be released. Another helper -function ensures a potentially used bounce buffer is freed:: - - i2c_put_dma_safe_msg_buf(dma_buf, msg, xferred); - -The last argument 'xferred' controls if the buffer is synced back to the -message or not. No syncing is needed in cases setting up DMA had an error and -there was no data transferred. - -The bounce buffer handling from the core is generic and simple. It will always -allocate a new bounce buffer. If you want a more sophisticated handling (e.g. -reusing pre-allocated buffers), you are free to implement your own. - -Please also check the in-kernel documentation for details. The i2c-sh_mobile -driver can be used as a reference example how to use the above helpers. - -Final note: If you plan to use DMA with I2C (or with anything else, actually) -make sure you have CONFIG_DMA_API_DEBUG enabled during development. It can help -you find various issues which can be complex to debug otherwise. diff --git a/Documentation/i2c/busses/i2c-ali1535 b/Documentation/i2c/busses/i2c-ali1535 deleted file mode 100644 index 5d46342e486a..000000000000 --- a/Documentation/i2c/busses/i2c-ali1535 +++ /dev/null @@ -1,42 +0,0 @@ -Kernel driver i2c-ali1535 - -Supported adapters: - * Acer Labs, Inc. ALI 1535 (south bridge) - Datasheet: Now under NDA - http://www.ali.com.tw/ - -Authors: - Frodo Looijaard , - Philip Edelbrock , - Mark D. Studebaker , - Dan Eaton , - Stephen Rousset - -Description ------------ - -This is the driver for the SMB Host controller on Acer Labs Inc. (ALI) -M1535 South Bridge. - -The M1535 is a South bridge for portable systems. It is very similar to the -M15x3 South bridges also produced by Acer Labs Inc. Some of the registers -within the part have moved and some have been redefined slightly. -Additionally, the sequencing of the SMBus transactions has been modified to -be more consistent with the sequencing recommended by the manufacturer and -observed through testing. These changes are reflected in this driver and -can be identified by comparing this driver to the i2c-ali15x3 driver. For -an overview of these chips see http://www.acerlabs.com - -The SMB controller is part of the M7101 device, which is an ACPI-compliant -Power Management Unit (PMU). - -The whole M7101 device has to be enabled for the SMB to work. You can't -just enable the SMB alone. The SMB and the ACPI have separate I/O spaces. -We make sure that the SMB is enabled. We leave the ACPI alone. - - -Features --------- - -This driver controls the SMB Host only. This driver does not use -interrupts. diff --git a/Documentation/i2c/busses/i2c-ali1535.rst b/Documentation/i2c/busses/i2c-ali1535.rst new file mode 100644 index 000000000000..6941064730dc --- /dev/null +++ b/Documentation/i2c/busses/i2c-ali1535.rst @@ -0,0 +1,45 @@ +========================= +Kernel driver i2c-ali1535 +========================= + +Supported adapters: + * Acer Labs, Inc. ALI 1535 (south bridge) + + Datasheet: Now under NDA + http://www.ali.com.tw/ + +Authors: + - Frodo Looijaard , + - Philip Edelbrock , + - Mark D. Studebaker , + - Dan Eaton , + - Stephen Rousset + +Description +----------- + +This is the driver for the SMB Host controller on Acer Labs Inc. (ALI) +M1535 South Bridge. + +The M1535 is a South bridge for portable systems. It is very similar to the +M15x3 South bridges also produced by Acer Labs Inc. Some of the registers +within the part have moved and some have been redefined slightly. +Additionally, the sequencing of the SMBus transactions has been modified to +be more consistent with the sequencing recommended by the manufacturer and +observed through testing. These changes are reflected in this driver and +can be identified by comparing this driver to the i2c-ali15x3 driver. For +an overview of these chips see http://www.acerlabs.com + +The SMB controller is part of the M7101 device, which is an ACPI-compliant +Power Management Unit (PMU). + +The whole M7101 device has to be enabled for the SMB to work. You can't +just enable the SMB alone. The SMB and the ACPI have separate I/O spaces. +We make sure that the SMB is enabled. We leave the ACPI alone. + + +Features +-------- + +This driver controls the SMB Host only. This driver does not use +interrupts. diff --git a/Documentation/i2c/busses/i2c-ali1563 b/Documentation/i2c/busses/i2c-ali1563 deleted file mode 100644 index 41b1a077e4c7..000000000000 --- a/Documentation/i2c/busses/i2c-ali1563 +++ /dev/null @@ -1,27 +0,0 @@ -Kernel driver i2c-ali1563 - -Supported adapters: - * Acer Labs, Inc. ALI 1563 (south bridge) - Datasheet: Now under NDA - http://www.ali.com.tw/ - -Author: Patrick Mochel - -Description ------------ - -This is the driver for the SMB Host controller on Acer Labs Inc. (ALI) -M1563 South Bridge. - -For an overview of these chips see http://www.acerlabs.com - -The M1563 southbridge is deceptively similar to the M1533, with a few -notable exceptions. One of those happens to be the fact they upgraded the -i2c core to be SMBus 2.0 compliant, and happens to be almost identical to -the i2c controller found in the Intel 801 south bridges. - -Features --------- - -This driver controls the SMB Host only. This driver does not use -interrupts. diff --git a/Documentation/i2c/busses/i2c-ali1563.rst b/Documentation/i2c/busses/i2c-ali1563.rst new file mode 100644 index 000000000000..eec32c3ba92a --- /dev/null +++ b/Documentation/i2c/busses/i2c-ali1563.rst @@ -0,0 +1,30 @@ +========================= +Kernel driver i2c-ali1563 +========================= + +Supported adapters: + * Acer Labs, Inc. ALI 1563 (south bridge) + + Datasheet: Now under NDA + http://www.ali.com.tw/ + +Author: Patrick Mochel + +Description +----------- + +This is the driver for the SMB Host controller on Acer Labs Inc. (ALI) +M1563 South Bridge. + +For an overview of these chips see http://www.acerlabs.com + +The M1563 southbridge is deceptively similar to the M1533, with a few +notable exceptions. One of those happens to be the fact they upgraded the +i2c core to be SMBus 2.0 compliant, and happens to be almost identical to +the i2c controller found in the Intel 801 south bridges. + +Features +-------- + +This driver controls the SMB Host only. This driver does not use +interrupts. diff --git a/Documentation/i2c/busses/i2c-ali15x3 b/Documentation/i2c/busses/i2c-ali15x3 deleted file mode 100644 index 42888d8ac124..000000000000 --- a/Documentation/i2c/busses/i2c-ali15x3 +++ /dev/null @@ -1,112 +0,0 @@ -Kernel driver i2c-ali15x3 - -Supported adapters: - * Acer Labs, Inc. ALI 1533 and 1543C (south bridge) - Datasheet: Now under NDA - http://www.ali.com.tw/ - -Authors: - Frodo Looijaard , - Philip Edelbrock , - Mark D. Studebaker - -Module Parameters ------------------ - -* force_addr: int - Initialize the base address of the i2c controller - - -Notes ------ - -The force_addr parameter is useful for boards that don't set the address in -the BIOS. Does not do a PCI force; the device must still be present in -lspci. Don't use this unless the driver complains that the base address is -not set. - -Example: 'modprobe i2c-ali15x3 force_addr=0xe800' - -SMBus periodically hangs on ASUS P5A motherboards and can only be cleared -by a power cycle. Cause unknown (see Issues below). - - -Description ------------ - -This is the driver for the SMB Host controller on Acer Labs Inc. (ALI) -M1541 and M1543C South Bridges. - -The M1543C is a South bridge for desktop systems. -The M1541 is a South bridge for portable systems. -They are part of the following ALI chipsets: - - * "Aladdin Pro 2" includes the M1621 Slot 1 North bridge with AGP and - 100MHz CPU Front Side bus - * "Aladdin V" includes the M1541 Socket 7 North bridge with AGP and 100MHz - CPU Front Side bus - Some Aladdin V motherboards: - Asus P5A - Atrend ATC-5220 - BCM/GVC VP1541 - Biostar M5ALA - Gigabyte GA-5AX (** Generally doesn't work because the BIOS doesn't - enable the 7101 device! **) - Iwill XA100 Plus - Micronics C200 - Microstar (MSI) MS-5169 - - * "Aladdin IV" includes the M1541 Socket 7 North bridge - with host bus up to 83.3 MHz. - -For an overview of these chips see http://www.acerlabs.com. At this time the -full data sheets on the web site are password protected, however if you -contact the ALI office in San Jose they may give you the password. - -The M1533/M1543C devices appear as FOUR separate devices on the PCI bus. An -output of lspci will show something similar to the following: - - 00:02.0 USB Controller: Acer Laboratories Inc. M5237 (rev 03) - 00:03.0 Bridge: Acer Laboratories Inc. M7101 <= THIS IS THE ONE WE NEED - 00:07.0 ISA bridge: Acer Laboratories Inc. M1533 (rev c3) - 00:0f.0 IDE interface: Acer Laboratories Inc. M5229 (rev c1) - -** IMPORTANT ** -** If you have a M1533 or M1543C on the board and you get -** "ali15x3: Error: Can't detect ali15x3!" -** then run lspci. -** If you see the 1533 and 5229 devices but NOT the 7101 device, -** then you must enable ACPI, the PMU, SMB, or something similar -** in the BIOS. -** The driver won't work if it can't find the M7101 device. - -The SMB controller is part of the M7101 device, which is an ACPI-compliant -Power Management Unit (PMU). - -The whole M7101 device has to be enabled for the SMB to work. You can't -just enable the SMB alone. The SMB and the ACPI have separate I/O spaces. -We make sure that the SMB is enabled. We leave the ACPI alone. - -Features --------- - -This driver controls the SMB Host only. The SMB Slave -controller on the M15X3 is not enabled. This driver does not use -interrupts. - - -Issues ------- - -This driver requests the I/O space for only the SMB -registers. It doesn't use the ACPI region. - -On the ASUS P5A motherboard, there are several reports that -the SMBus will hang and this can only be resolved by -powering off the computer. It appears to be worse when the board -gets hot, for example under heavy CPU load, or in the summer. -There may be electrical problems on this board. -On the P5A, the W83781D sensor chip is on both the ISA and -SMBus. Therefore the SMBus hangs can generally be avoided -by accessing the W83781D on the ISA bus only. - diff --git a/Documentation/i2c/busses/i2c-ali15x3.rst b/Documentation/i2c/busses/i2c-ali15x3.rst new file mode 100644 index 000000000000..d4c1a2a419cb --- /dev/null +++ b/Documentation/i2c/busses/i2c-ali15x3.rst @@ -0,0 +1,122 @@ +========================= +Kernel driver i2c-ali15x3 +========================= + +Supported adapters: + * Acer Labs, Inc. ALI 1533 and 1543C (south bridge) + + Datasheet: Now under NDA + http://www.ali.com.tw/ + +Authors: + - Frodo Looijaard , + - Philip Edelbrock , + - Mark D. Studebaker + +Module Parameters +----------------- + +* force_addr: int + Initialize the base address of the i2c controller + + +Notes +----- + +The force_addr parameter is useful for boards that don't set the address in +the BIOS. Does not do a PCI force; the device must still be present in +lspci. Don't use this unless the driver complains that the base address is +not set. + +Example:: + + modprobe i2c-ali15x3 force_addr=0xe800 + +SMBus periodically hangs on ASUS P5A motherboards and can only be cleared +by a power cycle. Cause unknown (see Issues below). + + +Description +----------- + +This is the driver for the SMB Host controller on Acer Labs Inc. (ALI) +M1541 and M1543C South Bridges. + +The M1543C is a South bridge for desktop systems. + +The M1541 is a South bridge for portable systems. + +They are part of the following ALI chipsets: + + * "Aladdin Pro 2" includes the M1621 Slot 1 North bridge with AGP and + 100MHz CPU Front Side bus + * "Aladdin V" includes the M1541 Socket 7 North bridge with AGP and 100MHz + CPU Front Side bus + + Some Aladdin V motherboards: + - Asus P5A + - Atrend ATC-5220 + - BCM/GVC VP1541 + - Biostar M5ALA + - Gigabyte GA-5AX (Generally doesn't work because the BIOS doesn't + enable the 7101 device!) + - Iwill XA100 Plus + - Micronics C200 + - Microstar (MSI) MS-5169 + + * "Aladdin IV" includes the M1541 Socket 7 North bridge + with host bus up to 83.3 MHz. + +For an overview of these chips see http://www.acerlabs.com. At this time the +full data sheets on the web site are password protected, however if you +contact the ALI office in San Jose they may give you the password. + +The M1533/M1543C devices appear as FOUR separate devices on the PCI bus. An +output of lspci will show something similar to the following:: + + 00:02.0 USB Controller: Acer Laboratories Inc. M5237 (rev 03) + 00:03.0 Bridge: Acer Laboratories Inc. M7101 <= THIS IS THE ONE WE NEED + 00:07.0 ISA bridge: Acer Laboratories Inc. M1533 (rev c3) + 00:0f.0 IDE interface: Acer Laboratories Inc. M5229 (rev c1) + +.. important:: + + If you have a M1533 or M1543C on the board and you get + "ali15x3: Error: Can't detect ali15x3!" + then run lspci. + + If you see the 1533 and 5229 devices but NOT the 7101 device, + then you must enable ACPI, the PMU, SMB, or something similar + in the BIOS. + + The driver won't work if it can't find the M7101 device. + +The SMB controller is part of the M7101 device, which is an ACPI-compliant +Power Management Unit (PMU). + +The whole M7101 device has to be enabled for the SMB to work. You can't +just enable the SMB alone. The SMB and the ACPI have separate I/O spaces. +We make sure that the SMB is enabled. We leave the ACPI alone. + +Features +-------- + +This driver controls the SMB Host only. The SMB Slave +controller on the M15X3 is not enabled. This driver does not use +interrupts. + + +Issues +------ + +This driver requests the I/O space for only the SMB +registers. It doesn't use the ACPI region. + +On the ASUS P5A motherboard, there are several reports that +the SMBus will hang and this can only be resolved by +powering off the computer. It appears to be worse when the board +gets hot, for example under heavy CPU load, or in the summer. +There may be electrical problems on this board. +On the P5A, the W83781D sensor chip is on both the ISA and +SMBus. Therefore the SMBus hangs can generally be avoided +by accessing the W83781D on the ISA bus only. diff --git a/Documentation/i2c/busses/i2c-amd-mp2 b/Documentation/i2c/busses/i2c-amd-mp2 deleted file mode 100644 index 6571487171f4..000000000000 --- a/Documentation/i2c/busses/i2c-amd-mp2 +++ /dev/null @@ -1,23 +0,0 @@ -Kernel driver i2c-amd-mp2 - -Supported adapters: - * AMD MP2 PCIe interface - -Datasheet: not publicly available. - -Authors: - Shyam Sundar S K - Nehal Shah - Elie Morisse - -Description ------------ - -The MP2 is an ARM processor programmed as an I2C controller and communicating -with the x86 host through PCI. - -If you see something like this: - -03:00.7 MP2 I2C controller: Advanced Micro Devices, Inc. [AMD] Device 15e6 - -in your 'lspci -v', then this driver is for your device. diff --git a/Documentation/i2c/busses/i2c-amd-mp2.rst b/Documentation/i2c/busses/i2c-amd-mp2.rst new file mode 100644 index 000000000000..ebc2fa899325 --- /dev/null +++ b/Documentation/i2c/busses/i2c-amd-mp2.rst @@ -0,0 +1,25 @@ +========================= +Kernel driver i2c-amd-mp2 +========================= + +Supported adapters: + * AMD MP2 PCIe interface + +Datasheet: not publicly available. + +Authors: + - Shyam Sundar S K + - Nehal Shah + - Elie Morisse + +Description +----------- + +The MP2 is an ARM processor programmed as an I2C controller and communicating +with the x86 host through PCI. + +If you see something like this:: + + 03:00.7 MP2 I2C controller: Advanced Micro Devices, Inc. [AMD] Device 15e6 + +in your ``lspci -v``, then this driver is for your device. diff --git a/Documentation/i2c/busses/i2c-amd756 b/Documentation/i2c/busses/i2c-amd756 deleted file mode 100644 index 67f30874d0bf..000000000000 --- a/Documentation/i2c/busses/i2c-amd756 +++ /dev/null @@ -1,25 +0,0 @@ -Kernel driver i2c-amd756 - -Supported adapters: - * AMD 756 - * AMD 766 - * AMD 768 - * AMD 8111 - Datasheets: Publicly available on AMD website - - * nVidia nForce - Datasheet: Unavailable - -Authors: - Frodo Looijaard , - Philip Edelbrock - -Description ------------ - -This driver supports the AMD 756, 766, 768 and 8111 Peripheral Bus -Controllers, and the nVidia nForce. - -Note that for the 8111, there are two SMBus adapters. The SMBus 1.0 adapter -is supported by this driver, and the SMBus 2.0 adapter is supported by the -i2c-amd8111 driver. diff --git a/Documentation/i2c/busses/i2c-amd756.rst b/Documentation/i2c/busses/i2c-amd756.rst new file mode 100644 index 000000000000..bc93f392a4fc --- /dev/null +++ b/Documentation/i2c/busses/i2c-amd756.rst @@ -0,0 +1,29 @@ +======================== +Kernel driver i2c-amd756 +======================== + +Supported adapters: + * AMD 756 + * AMD 766 + * AMD 768 + * AMD 8111 + + Datasheets: Publicly available on AMD website + + * nVidia nForce + + Datasheet: Unavailable + +Authors: + - Frodo Looijaard , + - Philip Edelbrock + +Description +----------- + +This driver supports the AMD 756, 766, 768 and 8111 Peripheral Bus +Controllers, and the nVidia nForce. + +Note that for the 8111, there are two SMBus adapters. The SMBus 1.0 adapter +is supported by this driver, and the SMBus 2.0 adapter is supported by the +i2c-amd8111 driver. diff --git a/Documentation/i2c/busses/i2c-amd8111 b/Documentation/i2c/busses/i2c-amd8111 deleted file mode 100644 index 460dd6635fd2..000000000000 --- a/Documentation/i2c/busses/i2c-amd8111 +++ /dev/null @@ -1,41 +0,0 @@ -Kernel driver i2c-adm8111 - -Supported adapters: - * AMD-8111 SMBus 2.0 PCI interface - -Datasheets: - AMD datasheet not yet available, but almost everything can be found - in the publicly available ACPI 2.0 specification, which the adapter - follows. - -Author: Vojtech Pavlik - -Description ------------ - -If you see something like this: - -00:07.2 SMBus: Advanced Micro Devices [AMD] AMD-8111 SMBus 2.0 (rev 02) - Subsystem: Advanced Micro Devices [AMD] AMD-8111 SMBus 2.0 - Flags: medium devsel, IRQ 19 - I/O ports at d400 [size=32] - -in your 'lspci -v', then this driver is for your chipset. - -Process Call Support --------------------- - -Supported. - -SMBus 2.0 Support ------------------ - -Supported. Both PEC and block process call support is implemented. Slave -mode or host notification are not yet implemented. - -Notes ------ - -Note that for the 8111, there are two SMBus adapters. The SMBus 2.0 adapter -is supported by this driver, and the SMBus 1.0 adapter is supported by the -i2c-amd756 driver. diff --git a/Documentation/i2c/busses/i2c-amd8111.rst b/Documentation/i2c/busses/i2c-amd8111.rst new file mode 100644 index 000000000000..d08bf0a7f0ac --- /dev/null +++ b/Documentation/i2c/busses/i2c-amd8111.rst @@ -0,0 +1,43 @@ +========================= +Kernel driver i2c-adm8111 +========================= + +Supported adapters: + * AMD-8111 SMBus 2.0 PCI interface + +Datasheets: + AMD datasheet not yet available, but almost everything can be found + in the publicly available ACPI 2.0 specification, which the adapter + follows. + +Author: Vojtech Pavlik + +Description +----------- + +If you see something like this:: + + 00:07.2 SMBus: Advanced Micro Devices [AMD] AMD-8111 SMBus 2.0 (rev 02) + Subsystem: Advanced Micro Devices [AMD] AMD-8111 SMBus 2.0 + Flags: medium devsel, IRQ 19 + I/O ports at d400 [size=32] + +in your ``lspci -v``, then this driver is for your chipset. + +Process Call Support +-------------------- + +Supported. + +SMBus 2.0 Support +----------------- + +Supported. Both PEC and block process call support is implemented. Slave +mode or host notification are not yet implemented. + +Notes +----- + +Note that for the 8111, there are two SMBus adapters. The SMBus 2.0 adapter +is supported by this driver, and the SMBus 1.0 adapter is supported by the +i2c-amd756 driver. diff --git a/Documentation/i2c/busses/i2c-diolan-u2c b/Documentation/i2c/busses/i2c-diolan-u2c deleted file mode 100644 index 0d6018c316c7..000000000000 --- a/Documentation/i2c/busses/i2c-diolan-u2c +++ /dev/null @@ -1,26 +0,0 @@ -Kernel driver i2c-diolan-u2c - -Supported adapters: - * Diolan U2C-12 I2C-USB adapter - Documentation: - http://www.diolan.com/i2c/u2c12.html - -Author: Guenter Roeck - -Description ------------ - -This is the driver for the Diolan U2C-12 USB-I2C adapter. - -The Diolan U2C-12 I2C-USB Adapter provides a low cost solution to connect -a computer to I2C slave devices using a USB interface. It also supports -connectivity to SPI devices. - -This driver only supports the I2C interface of U2C-12. The driver does not use -interrupts. - - -Module parameters ------------------ - -* frequency: I2C bus frequency diff --git a/Documentation/i2c/busses/i2c-diolan-u2c.rst b/Documentation/i2c/busses/i2c-diolan-u2c.rst new file mode 100644 index 000000000000..c18cbdcdf73c --- /dev/null +++ b/Documentation/i2c/busses/i2c-diolan-u2c.rst @@ -0,0 +1,29 @@ +============================ +Kernel driver i2c-diolan-u2c +============================ + +Supported adapters: + * Diolan U2C-12 I2C-USB adapter + + Documentation: + http://www.diolan.com/i2c/u2c12.html + +Author: Guenter Roeck + +Description +----------- + +This is the driver for the Diolan U2C-12 USB-I2C adapter. + +The Diolan U2C-12 I2C-USB Adapter provides a low cost solution to connect +a computer to I2C slave devices using a USB interface. It also supports +connectivity to SPI devices. + +This driver only supports the I2C interface of U2C-12. The driver does not use +interrupts. + + +Module parameters +----------------- + +* frequency: I2C bus frequency diff --git a/Documentation/i2c/busses/i2c-i801 b/Documentation/i2c/busses/i2c-i801 deleted file mode 100644 index f426c13c63a9..000000000000 --- a/Documentation/i2c/busses/i2c-i801 +++ /dev/null @@ -1,173 +0,0 @@ -Kernel driver i2c-i801 - -Supported adapters: - * Intel 82801AA and 82801AB (ICH and ICH0 - part of the - '810' and '810E' chipsets) - * Intel 82801BA (ICH2 - part of the '815E' chipset) - * Intel 82801CA/CAM (ICH3) - * Intel 82801DB (ICH4) (HW PEC supported) - * Intel 82801EB/ER (ICH5) (HW PEC supported) - * Intel 6300ESB - * Intel 82801FB/FR/FW/FRW (ICH6) - * Intel 82801G (ICH7) - * Intel 631xESB/632xESB (ESB2) - * Intel 82801H (ICH8) - * Intel 82801I (ICH9) - * Intel EP80579 (Tolapai) - * Intel 82801JI (ICH10) - * Intel 5/3400 Series (PCH) - * Intel 6 Series (PCH) - * Intel Patsburg (PCH) - * Intel DH89xxCC (PCH) - * Intel Panther Point (PCH) - * Intel Lynx Point (PCH) - * Intel Avoton (SOC) - * Intel Wellsburg (PCH) - * Intel Coleto Creek (PCH) - * Intel Wildcat Point (PCH) - * Intel BayTrail (SOC) - * Intel Braswell (SOC) - * Intel Sunrise Point (PCH) - * Intel Kaby Lake (PCH) - * Intel DNV (SOC) - * Intel Broxton (SOC) - * Intel Lewisburg (PCH) - * Intel Gemini Lake (SOC) - * Intel Cannon Lake (PCH) - * Intel Cedar Fork (PCH) - * Intel Ice Lake (PCH) - * Intel Comet Lake (PCH) - * Intel Elkhart Lake (PCH) - * Intel Tiger Lake (PCH) - Datasheets: Publicly available at the Intel website - -On Intel Patsburg and later chipsets, both the normal host SMBus controller -and the additional 'Integrated Device Function' controllers are supported. - -Authors: - Mark Studebaker - Jean Delvare - - -Module Parameters ------------------ - -* disable_features (bit vector) -Disable selected features normally supported by the device. This makes it -possible to work around possible driver or hardware bugs if the feature in -question doesn't work as intended for whatever reason. Bit values: - 0x01 disable SMBus PEC - 0x02 disable the block buffer - 0x08 disable the I2C block read functionality - 0x10 don't use interrupts - 0x20 disable SMBus Host Notify - - -Description ------------ - -The ICH (properly known as the 82801AA), ICH0 (82801AB), ICH2 (82801BA), -ICH3 (82801CA/CAM) and later devices (PCH) are Intel chips that are a part of -Intel's '810' chipset for Celeron-based PCs, '810E' chipset for -Pentium-based PCs, '815E' chipset, and others. - -The ICH chips contain at least SEVEN separate PCI functions in TWO logical -PCI devices. An output of lspci will show something similar to the -following: - - 00:1e.0 PCI bridge: Intel Corporation: Unknown device 2418 (rev 01) - 00:1f.0 ISA bridge: Intel Corporation: Unknown device 2410 (rev 01) - 00:1f.1 IDE interface: Intel Corporation: Unknown device 2411 (rev 01) - 00:1f.2 USB Controller: Intel Corporation: Unknown device 2412 (rev 01) - 00:1f.3 Unknown class [0c05]: Intel Corporation: Unknown device 2413 (rev 01) - -The SMBus controller is function 3 in device 1f. Class 0c05 is SMBus Serial -Controller. - -The ICH chips are quite similar to Intel's PIIX4 chip, at least in the -SMBus controller. - - -Process Call Support --------------------- - -Block process call is supported on the 82801EB (ICH5) and later chips. - - -I2C Block Read Support ----------------------- - -I2C block read is supported on the 82801EB (ICH5) and later chips. - - -SMBus 2.0 Support ------------------ - -The 82801DB (ICH4) and later chips support several SMBus 2.0 features. - - -Interrupt Support ------------------ - -PCI interrupt support is supported on the 82801EB (ICH5) and later chips. - - -Hidden ICH SMBus ----------------- - -If your system has an Intel ICH south bridge, but you do NOT see the -SMBus device at 00:1f.3 in lspci, and you can't figure out any way in the -BIOS to enable it, it means it has been hidden by the BIOS code. Asus is -well known for first doing this on their P4B motherboard, and many other -boards after that. Some vendor machines are affected as well. - -The first thing to try is the "i2c-scmi" ACPI driver. It could be that the -SMBus was hidden on purpose because it'll be driven by ACPI. If the -i2c-scmi driver works for you, just forget about the i2c-i801 driver and -don't try to unhide the ICH SMBus. Even if i2c-scmi doesn't work, you -better make sure that the SMBus isn't used by the ACPI code. Try loading -the "fan" and "thermal" drivers, and check in /sys/class/thermal. If you -find a thermal zone with type "acpitz", it's likely that the ACPI is -accessing the SMBus and it's safer not to unhide it. Only once you are -certain that ACPI isn't using the SMBus, you can attempt to unhide it. - -In order to unhide the SMBus, we need to change the value of a PCI -register before the kernel enumerates the PCI devices. This is done in -drivers/pci/quirks.c, where all affected boards must be listed (see -function asus_hides_smbus_hostbridge.) If the SMBus device is missing, -and you think there's something interesting on the SMBus (e.g. a -hardware monitoring chip), you need to add your board to the list. - -The motherboard is identified using the subvendor and subdevice IDs of the -host bridge PCI device. Get yours with "lspci -n -v -s 00:00.0": - -00:00.0 Class 0600: 8086:2570 (rev 02) - Subsystem: 1043:80f2 - Flags: bus master, fast devsel, latency 0 - Memory at fc000000 (32-bit, prefetchable) [size=32M] - Capabilities: [e4] #09 [2106] - Capabilities: [a0] AGP version 3.0 - -Here the host bridge ID is 2570 (82865G/PE/P), the subvendor ID is 1043 -(Asus) and the subdevice ID is 80f2 (P4P800-X). You can find the symbolic -names for the bridge ID and the subvendor ID in include/linux/pci_ids.h, -and then add a case for your subdevice ID at the right place in -drivers/pci/quirks.c. Then please give it very good testing, to make sure -that the unhidden SMBus doesn't conflict with e.g. ACPI. - -If it works, proves useful (i.e. there are usable chips on the SMBus) -and seems safe, please submit a patch for inclusion into the kernel. - -Note: There's a useful script in lm_sensors 2.10.2 and later, named -unhide_ICH_SMBus (in prog/hotplug), which uses the fakephp driver to -temporarily unhide the SMBus without having to patch and recompile your -kernel. It's very convenient if you just want to check if there's -anything interesting on your hidden ICH SMBus. - - -********************** -The lm_sensors project gratefully acknowledges the support of Texas -Instruments in the initial development of this driver. - -The lm_sensors project gratefully acknowledges the support of Intel in the -development of SMBus 2.0 / ICH4 features of this driver. diff --git a/Documentation/i2c/busses/i2c-i801.rst b/Documentation/i2c/busses/i2c-i801.rst new file mode 100644 index 000000000000..2a570c214880 --- /dev/null +++ b/Documentation/i2c/busses/i2c-i801.rst @@ -0,0 +1,182 @@ +====================== +Kernel driver i2c-i801 +====================== + + +Supported adapters: + * Intel 82801AA and 82801AB (ICH and ICH0 - part of the + '810' and '810E' chipsets) + * Intel 82801BA (ICH2 - part of the '815E' chipset) + * Intel 82801CA/CAM (ICH3) + * Intel 82801DB (ICH4) (HW PEC supported) + * Intel 82801EB/ER (ICH5) (HW PEC supported) + * Intel 6300ESB + * Intel 82801FB/FR/FW/FRW (ICH6) + * Intel 82801G (ICH7) + * Intel 631xESB/632xESB (ESB2) + * Intel 82801H (ICH8) + * Intel 82801I (ICH9) + * Intel EP80579 (Tolapai) + * Intel 82801JI (ICH10) + * Intel 5/3400 Series (PCH) + * Intel 6 Series (PCH) + * Intel Patsburg (PCH) + * Intel DH89xxCC (PCH) + * Intel Panther Point (PCH) + * Intel Lynx Point (PCH) + * Intel Avoton (SOC) + * Intel Wellsburg (PCH) + * Intel Coleto Creek (PCH) + * Intel Wildcat Point (PCH) + * Intel BayTrail (SOC) + * Intel Braswell (SOC) + * Intel Sunrise Point (PCH) + * Intel Kaby Lake (PCH) + * Intel DNV (SOC) + * Intel Broxton (SOC) + * Intel Lewisburg (PCH) + * Intel Gemini Lake (SOC) + * Intel Cannon Lake (PCH) + * Intel Cedar Fork (PCH) + * Intel Ice Lake (PCH) + * Intel Comet Lake (PCH) + * Intel Elkhart Lake (PCH) + * Intel Tiger Lake (PCH) + + Datasheets: Publicly available at the Intel website + +On Intel Patsburg and later chipsets, both the normal host SMBus controller +and the additional 'Integrated Device Function' controllers are supported. + +Authors: + - Mark Studebaker + - Jean Delvare + + +Module Parameters +----------------- + +* disable_features (bit vector) + +Disable selected features normally supported by the device. This makes it +possible to work around possible driver or hardware bugs if the feature in +question doesn't work as intended for whatever reason. Bit values: + + ==== ========================================= + 0x01 disable SMBus PEC + 0x02 disable the block buffer + 0x08 disable the I2C block read functionality + 0x10 don't use interrupts + 0x20 disable SMBus Host Notify + ==== ========================================= + + +Description +----------- + +The ICH (properly known as the 82801AA), ICH0 (82801AB), ICH2 (82801BA), +ICH3 (82801CA/CAM) and later devices (PCH) are Intel chips that are a part of +Intel's '810' chipset for Celeron-based PCs, '810E' chipset for +Pentium-based PCs, '815E' chipset, and others. + +The ICH chips contain at least SEVEN separate PCI functions in TWO logical +PCI devices. An output of lspci will show something similar to the +following:: + + 00:1e.0 PCI bridge: Intel Corporation: Unknown device 2418 (rev 01) + 00:1f.0 ISA bridge: Intel Corporation: Unknown device 2410 (rev 01) + 00:1f.1 IDE interface: Intel Corporation: Unknown device 2411 (rev 01) + 00:1f.2 USB Controller: Intel Corporation: Unknown device 2412 (rev 01) + 00:1f.3 Unknown class [0c05]: Intel Corporation: Unknown device 2413 (rev 01) + +The SMBus controller is function 3 in device 1f. Class 0c05 is SMBus Serial +Controller. + +The ICH chips are quite similar to Intel's PIIX4 chip, at least in the +SMBus controller. + + +Process Call Support +-------------------- + +Block process call is supported on the 82801EB (ICH5) and later chips. + + +I2C Block Read Support +---------------------- + +I2C block read is supported on the 82801EB (ICH5) and later chips. + + +SMBus 2.0 Support +----------------- + +The 82801DB (ICH4) and later chips support several SMBus 2.0 features. + + +Interrupt Support +----------------- + +PCI interrupt support is supported on the 82801EB (ICH5) and later chips. + + +Hidden ICH SMBus +---------------- + +If your system has an Intel ICH south bridge, but you do NOT see the +SMBus device at 00:1f.3 in lspci, and you can't figure out any way in the +BIOS to enable it, it means it has been hidden by the BIOS code. Asus is +well known for first doing this on their P4B motherboard, and many other +boards after that. Some vendor machines are affected as well. + +The first thing to try is the "i2c-scmi" ACPI driver. It could be that the +SMBus was hidden on purpose because it'll be driven by ACPI. If the +i2c-scmi driver works for you, just forget about the i2c-i801 driver and +don't try to unhide the ICH SMBus. Even if i2c-scmi doesn't work, you +better make sure that the SMBus isn't used by the ACPI code. Try loading +the "fan" and "thermal" drivers, and check in /sys/class/thermal. If you +find a thermal zone with type "acpitz", it's likely that the ACPI is +accessing the SMBus and it's safer not to unhide it. Only once you are +certain that ACPI isn't using the SMBus, you can attempt to unhide it. + +In order to unhide the SMBus, we need to change the value of a PCI +register before the kernel enumerates the PCI devices. This is done in +drivers/pci/quirks.c, where all affected boards must be listed (see +function asus_hides_smbus_hostbridge.) If the SMBus device is missing, +and you think there's something interesting on the SMBus (e.g. a +hardware monitoring chip), you need to add your board to the list. + +The motherboard is identified using the subvendor and subdevice IDs of the +host bridge PCI device. Get yours with ``lspci -n -v -s 00:00.0``:: + + 00:00.0 Class 0600: 8086:2570 (rev 02) + Subsystem: 1043:80f2 + Flags: bus master, fast devsel, latency 0 + Memory at fc000000 (32-bit, prefetchable) [size=32M] + Capabilities: [e4] #09 [2106] + Capabilities: [a0] AGP version 3.0 + +Here the host bridge ID is 2570 (82865G/PE/P), the subvendor ID is 1043 +(Asus) and the subdevice ID is 80f2 (P4P800-X). You can find the symbolic +names for the bridge ID and the subvendor ID in include/linux/pci_ids.h, +and then add a case for your subdevice ID at the right place in +drivers/pci/quirks.c. Then please give it very good testing, to make sure +that the unhidden SMBus doesn't conflict with e.g. ACPI. + +If it works, proves useful (i.e. there are usable chips on the SMBus) +and seems safe, please submit a patch for inclusion into the kernel. + +Note: There's a useful script in lm_sensors 2.10.2 and later, named +unhide_ICH_SMBus (in prog/hotplug), which uses the fakephp driver to +temporarily unhide the SMBus without having to patch and recompile your +kernel. It's very convenient if you just want to check if there's +anything interesting on your hidden ICH SMBus. + + +---------------------------------------------------------------------------- + +The lm_sensors project gratefully acknowledges the support of Texas +Instruments in the initial development of this driver. + +The lm_sensors project gratefully acknowledges the support of Intel in the +development of SMBus 2.0 / ICH4 features of this driver. diff --git a/Documentation/i2c/busses/i2c-ismt b/Documentation/i2c/busses/i2c-ismt deleted file mode 100644 index 737355822c0b..000000000000 --- a/Documentation/i2c/busses/i2c-ismt +++ /dev/null @@ -1,36 +0,0 @@ -Kernel driver i2c-ismt - -Supported adapters: - * Intel S12xx series SOCs - -Authors: - Bill Brown - - -Module Parameters ------------------ - -* bus_speed (unsigned int) -Allows changing of the bus speed. Normally, the bus speed is set by the BIOS -and never needs to be changed. However, some SMBus analyzers are too slow for -monitoring the bus during debug, thus the need for this module parameter. -Specify the bus speed in kHz. -Available bus frequency settings: - 0 no change - 80 kHz - 100 kHz - 400 kHz - 1000 kHz - - -Description ------------ - -The S12xx series of SOCs have a pair of integrated SMBus 2.0 controllers -targeted primarily at the microserver and storage markets. - -The S12xx series contain a pair of PCI functions. An output of lspci will show -something similar to the following: - - 00:13.0 System peripheral: Intel Corporation Centerton SMBus 2.0 Controller 0 - 00:13.1 System peripheral: Intel Corporation Centerton SMBus 2.0 Controller 1 diff --git a/Documentation/i2c/busses/i2c-ismt.rst b/Documentation/i2c/busses/i2c-ismt.rst new file mode 100644 index 000000000000..8e74919a3fdf --- /dev/null +++ b/Documentation/i2c/busses/i2c-ismt.rst @@ -0,0 +1,44 @@ +====================== +Kernel driver i2c-ismt +====================== + + +Supported adapters: + * Intel S12xx series SOCs + +Authors: + Bill Brown + + +Module Parameters +----------------- + +* bus_speed (unsigned int) + +Allows changing of the bus speed. Normally, the bus speed is set by the BIOS +and never needs to be changed. However, some SMBus analyzers are too slow for +monitoring the bus during debug, thus the need for this module parameter. +Specify the bus speed in kHz. + +Available bus frequency settings: + + ==== ========= + 0 no change + 80 kHz + 100 kHz + 400 kHz + 1000 kHz + ==== ========= + + +Description +----------- + +The S12xx series of SOCs have a pair of integrated SMBus 2.0 controllers +targeted primarily at the microserver and storage markets. + +The S12xx series contain a pair of PCI functions. An output of lspci will show +something similar to the following:: + + 00:13.0 System peripheral: Intel Corporation Centerton SMBus 2.0 Controller 0 + 00:13.1 System peripheral: Intel Corporation Centerton SMBus 2.0 Controller 1 diff --git a/Documentation/i2c/busses/i2c-mlxcpld b/Documentation/i2c/busses/i2c-mlxcpld deleted file mode 100644 index 925904aa9b57..000000000000 --- a/Documentation/i2c/busses/i2c-mlxcpld +++ /dev/null @@ -1,51 +0,0 @@ -Driver i2c-mlxcpld - -Author: Michael Shych - -This is the Mellanox I2C controller logic, implemented in Lattice CPLD -device. -Device supports: - - Master mode. - - One physical bus. - - Polling mode. - -This controller is equipped within the next Mellanox systems: -"msx6710", "msx6720", "msb7700", "msn2700", "msx1410", "msn2410", "msb7800", -"msn2740", "msn2100". - -The next transaction types are supported: - - Receive Byte/Block. - - Send Byte/Block. - - Read Byte/Block. - - Write Byte/Block. - -Registers: -CPBLTY 0x0 - capability reg. - Bits [6:5] - transaction length. b01 - 72B is supported, - 36B in other case. - Bit 7 - SMBus block read support. -CTRL 0x1 - control reg. - Resets all the registers. -HALF_CYC 0x4 - cycle reg. - Configure the width of I2C SCL half clock cycle (in 4 LPC_CLK - units). -I2C_HOLD 0x5 - hold reg. - OE (output enable) is delayed by value set to this register - (in LPC_CLK units) -CMD 0x6 - command reg. - Bit 0, 0 = write, 1 = read. - Bits [7:1] - the 7bit Address of the I2C device. - It should be written last as it triggers an I2C transaction. -NUM_DATA 0x7 - data size reg. - Number of data bytes to write in read transaction -NUM_ADDR 0x8 - address reg. - Number of address bytes to write in read transaction. -STATUS 0x9 - status reg. - Bit 0 - transaction is completed. - Bit 4 - ACK/NACK. -DATAx 0xa - 0x54 - 68 bytes data buffer regs. - For write transaction address is specified in four first bytes - (DATA1 - DATA4), data starting from DATA4. - For read transactions address is sent in a separate transaction and - specified in the four first bytes (DATA0 - DATA3). Data is read - starting from DATA0. diff --git a/Documentation/i2c/busses/i2c-mlxcpld.rst b/Documentation/i2c/busses/i2c-mlxcpld.rst new file mode 100644 index 000000000000..9a0b2916aa71 --- /dev/null +++ b/Documentation/i2c/busses/i2c-mlxcpld.rst @@ -0,0 +1,57 @@ +================== +Driver i2c-mlxcpld +================== + +Author: Michael Shych + +This is the Mellanox I2C controller logic, implemented in Lattice CPLD +device. + +Device supports: + - Master mode. + - One physical bus. + - Polling mode. + +This controller is equipped within the next Mellanox systems: +"msx6710", "msx6720", "msb7700", "msn2700", "msx1410", "msn2410", "msb7800", +"msn2740", "msn2100". + +The next transaction types are supported: + - Receive Byte/Block. + - Send Byte/Block. + - Read Byte/Block. + - Write Byte/Block. + +Registers: + +=============== === ======================================================================= +CPBLTY 0x0 - capability reg. + Bits [6:5] - transaction length. b01 - 72B is supported, + 36B in other case. + Bit 7 - SMBus block read support. +CTRL 0x1 - control reg. + Resets all the registers. +HALF_CYC 0x4 - cycle reg. + Configure the width of I2C SCL half clock cycle (in 4 LPC_CLK + units). +I2C_HOLD 0x5 - hold reg. + OE (output enable) is delayed by value set to this register + (in LPC_CLK units) +CMD 0x6 - command reg. + Bit 0, 0 = write, 1 = read. + Bits [7:1] - the 7bit Address of the I2C device. + It should be written last as it triggers an I2C transaction. +NUM_DATA 0x7 - data size reg. + Number of data bytes to write in read transaction +NUM_ADDR 0x8 - address reg. + Number of address bytes to write in read transaction. +STATUS 0x9 - status reg. + Bit 0 - transaction is completed. + Bit 4 - ACK/NACK. +DATAx 0xa - 0x54 - 68 bytes data buffer regs. + For write transaction address is specified in four first bytes + (DATA1 - DATA4), data starting from DATA4. + For read transactions address is sent in a separate transaction and + specified in the four first bytes (DATA0 - DATA3). Data is read + starting from DATA0. +=============== === ======================================================================= diff --git a/Documentation/i2c/busses/i2c-nforce2 b/Documentation/i2c/busses/i2c-nforce2 deleted file mode 100644 index 9698c396b830..000000000000 --- a/Documentation/i2c/busses/i2c-nforce2 +++ /dev/null @@ -1,50 +0,0 @@ -Kernel driver i2c-nforce2 - -Supported adapters: - * nForce2 MCP 10de:0064 - * nForce2 Ultra 400 MCP 10de:0084 - * nForce3 Pro150 MCP 10de:00D4 - * nForce3 250Gb MCP 10de:00E4 - * nForce4 MCP 10de:0052 - * nForce4 MCP-04 10de:0034 - * nForce MCP51 10de:0264 - * nForce MCP55 10de:0368 - * nForce MCP61 10de:03EB - * nForce MCP65 10de:0446 - * nForce MCP67 10de:0542 - * nForce MCP73 10de:07D8 - * nForce MCP78S 10de:0752 - * nForce MCP79 10de:0AA2 - -Datasheet: not publicly available, but seems to be similar to the - AMD-8111 SMBus 2.0 adapter. - -Authors: - Hans-Frieder Vogt , - Thomas Leibold , - Patrick Dreker - -Description ------------ - -i2c-nforce2 is a driver for the SMBuses included in the nVidia nForce2 MCP. - -If your 'lspci -v' listing shows something like the following, - -00:01.1 SMBus: nVidia Corporation: Unknown device 0064 (rev a2) - Subsystem: Asustek Computer, Inc.: Unknown device 0c11 - Flags: 66Mhz, fast devsel, IRQ 5 - I/O ports at c000 [size=32] - Capabilities: - -then this driver should support the SMBuses of your motherboard. - - -Notes ------ - -The SMBus adapter in the nForce2 chipset seems to be very similar to the -SMBus 2.0 adapter in the AMD-8111 south bridge. However, I could only get -the driver to work with direct I/O access, which is different to the EC -interface of the AMD-8111. Tested on Asus A7N8X. The ACPI DSDT table of the -Asus A7N8X lists two SMBuses, both of which are supported by this driver. diff --git a/Documentation/i2c/busses/i2c-nforce2.rst b/Documentation/i2c/busses/i2c-nforce2.rst new file mode 100644 index 000000000000..83181445268f --- /dev/null +++ b/Documentation/i2c/busses/i2c-nforce2.rst @@ -0,0 +1,53 @@ +========================= +Kernel driver i2c-nforce2 +========================= + +Supported adapters: + * nForce2 MCP 10de:0064 + * nForce2 Ultra 400 MCP 10de:0084 + * nForce3 Pro150 MCP 10de:00D4 + * nForce3 250Gb MCP 10de:00E4 + * nForce4 MCP 10de:0052 + * nForce4 MCP-04 10de:0034 + * nForce MCP51 10de:0264 + * nForce MCP55 10de:0368 + * nForce MCP61 10de:03EB + * nForce MCP65 10de:0446 + * nForce MCP67 10de:0542 + * nForce MCP73 10de:07D8 + * nForce MCP78S 10de:0752 + * nForce MCP79 10de:0AA2 + +Datasheet: + not publicly available, but seems to be similar to the + AMD-8111 SMBus 2.0 adapter. + +Authors: + - Hans-Frieder Vogt , + - Thomas Leibold , + - Patrick Dreker + +Description +----------- + +i2c-nforce2 is a driver for the SMBuses included in the nVidia nForce2 MCP. + +If your ``lspci -v`` listing shows something like the following:: + + 00:01.1 SMBus: nVidia Corporation: Unknown device 0064 (rev a2) + Subsystem: Asustek Computer, Inc.: Unknown device 0c11 + Flags: 66Mhz, fast devsel, IRQ 5 + I/O ports at c000 [size=32] + Capabilities: + +then this driver should support the SMBuses of your motherboard. + + +Notes +----- + +The SMBus adapter in the nForce2 chipset seems to be very similar to the +SMBus 2.0 adapter in the AMD-8111 south bridge. However, I could only get +the driver to work with direct I/O access, which is different to the EC +interface of the AMD-8111. Tested on Asus A7N8X. The ACPI DSDT table of the +Asus A7N8X lists two SMBuses, both of which are supported by this driver. diff --git a/Documentation/i2c/busses/i2c-nvidia-gpu b/Documentation/i2c/busses/i2c-nvidia-gpu deleted file mode 100644 index 31884d2b2eb5..000000000000 --- a/Documentation/i2c/busses/i2c-nvidia-gpu +++ /dev/null @@ -1,18 +0,0 @@ -Kernel driver i2c-nvidia-gpu - -Datasheet: not publicly available. - -Authors: - Ajay Gupta - -Description ------------ - -i2c-nvidia-gpu is a driver for I2C controller included in NVIDIA Turing -and later GPUs and it is used to communicate with Type-C controller on GPUs. - -If your 'lspci -v' listing shows something like the following, - -01:00.3 Serial bus controller [0c80]: NVIDIA Corporation Device 1ad9 (rev a1) - -then this driver should support the I2C controller of your GPU. diff --git a/Documentation/i2c/busses/i2c-nvidia-gpu.rst b/Documentation/i2c/busses/i2c-nvidia-gpu.rst new file mode 100644 index 000000000000..38fb8a4c8756 --- /dev/null +++ b/Documentation/i2c/busses/i2c-nvidia-gpu.rst @@ -0,0 +1,20 @@ +============================ +Kernel driver i2c-nvidia-gpu +============================ + +Datasheet: not publicly available. + +Authors: + Ajay Gupta + +Description +----------- + +i2c-nvidia-gpu is a driver for I2C controller included in NVIDIA Turing +and later GPUs and it is used to communicate with Type-C controller on GPUs. + +If your ``lspci -v`` listing shows something like the following:: + + 01:00.3 Serial bus controller [0c80]: NVIDIA Corporation Device 1ad9 (rev a1) + +then this driver should support the I2C controller of your GPU. diff --git a/Documentation/i2c/busses/i2c-ocores b/Documentation/i2c/busses/i2c-ocores deleted file mode 100644 index 9caaf7df1b2f..000000000000 --- a/Documentation/i2c/busses/i2c-ocores +++ /dev/null @@ -1,68 +0,0 @@ -Kernel driver i2c-ocores - -Supported adapters: - * OpenCores.org I2C controller by Richard Herveille (see datasheet link) - https://opencores.org/project/i2c/overview - -Author: Peter Korsgaard - -Description ------------ - -i2c-ocores is an i2c bus driver for the OpenCores.org I2C controller -IP core by Richard Herveille. - -Usage ------ - -i2c-ocores uses the platform bus, so you need to provide a struct -platform_device with the base address and interrupt number. The -dev.platform_data of the device should also point to a struct -ocores_i2c_platform_data (see linux/platform_data/i2c-ocores.h) describing the -distance between registers and the input clock speed. -There is also a possibility to attach a list of i2c_board_info which -the i2c-ocores driver will add to the bus upon creation. - -E.G. something like: - -static struct resource ocores_resources[] = { - [0] = { - .start = MYI2C_BASEADDR, - .end = MYI2C_BASEADDR + 8, - .flags = IORESOURCE_MEM, - }, - [1] = { - .start = MYI2C_IRQ, - .end = MYI2C_IRQ, - .flags = IORESOURCE_IRQ, - }, -}; - -/* optional board info */ -struct i2c_board_info ocores_i2c_board_info[] = { - { - I2C_BOARD_INFO("tsc2003", 0x48), - .platform_data = &tsc2003_platform_data, - .irq = TSC_IRQ - }, - { - I2C_BOARD_INFO("adv7180", 0x42 >> 1), - .irq = ADV_IRQ - } -}; - -static struct ocores_i2c_platform_data myi2c_data = { - .regstep = 2, /* two bytes between registers */ - .clock_khz = 50000, /* input clock of 50MHz */ - .devices = ocores_i2c_board_info, /* optional table of devices */ - .num_devices = ARRAY_SIZE(ocores_i2c_board_info), /* table size */ -}; - -static struct platform_device myi2c = { - .name = "ocores-i2c", - .dev = { - .platform_data = &myi2c_data, - }, - .num_resources = ARRAY_SIZE(ocores_resources), - .resource = ocores_resources, -}; diff --git a/Documentation/i2c/busses/i2c-ocores.rst b/Documentation/i2c/busses/i2c-ocores.rst new file mode 100644 index 000000000000..f5e175f2a2a6 --- /dev/null +++ b/Documentation/i2c/busses/i2c-ocores.rst @@ -0,0 +1,70 @@ +======================== +Kernel driver i2c-ocores +======================== + +Supported adapters: + * OpenCores.org I2C controller by Richard Herveille (see datasheet link) + https://opencores.org/project/i2c/overview + +Author: Peter Korsgaard + +Description +----------- + +i2c-ocores is an i2c bus driver for the OpenCores.org I2C controller +IP core by Richard Herveille. + +Usage +----- + +i2c-ocores uses the platform bus, so you need to provide a struct +platform_device with the base address and interrupt number. The +dev.platform_data of the device should also point to a struct +ocores_i2c_platform_data (see linux/platform_data/i2c-ocores.h) describing the +distance between registers and the input clock speed. +There is also a possibility to attach a list of i2c_board_info which +the i2c-ocores driver will add to the bus upon creation. + +E.G. something like:: + + static struct resource ocores_resources[] = { + [0] = { + .start = MYI2C_BASEADDR, + .end = MYI2C_BASEADDR + 8, + .flags = IORESOURCE_MEM, + }, + [1] = { + .start = MYI2C_IRQ, + .end = MYI2C_IRQ, + .flags = IORESOURCE_IRQ, + }, + }; + + /* optional board info */ + struct i2c_board_info ocores_i2c_board_info[] = { + { + I2C_BOARD_INFO("tsc2003", 0x48), + .platform_data = &tsc2003_platform_data, + .irq = TSC_IRQ + }, + { + I2C_BOARD_INFO("adv7180", 0x42 >> 1), + .irq = ADV_IRQ + } + }; + + static struct ocores_i2c_platform_data myi2c_data = { + .regstep = 2, /* two bytes between registers */ + .clock_khz = 50000, /* input clock of 50MHz */ + .devices = ocores_i2c_board_info, /* optional table of devices */ + .num_devices = ARRAY_SIZE(ocores_i2c_board_info), /* table size */ + }; + + static struct platform_device myi2c = { + .name = "ocores-i2c", + .dev = { + .platform_data = &myi2c_data, + }, + .num_resources = ARRAY_SIZE(ocores_resources), + .resource = ocores_resources, + }; diff --git a/Documentation/i2c/busses/i2c-parport b/Documentation/i2c/busses/i2c-parport deleted file mode 100644 index c3dbb3bfd814..000000000000 --- a/Documentation/i2c/busses/i2c-parport +++ /dev/null @@ -1,178 +0,0 @@ -Kernel driver i2c-parport - -Author: Jean Delvare - -This is a unified driver for several i2c-over-parallel-port adapters, -such as the ones made by Philips, Velleman or ELV. This driver is -meant as a replacement for the older, individual drivers: - * i2c-philips-par - * i2c-elv - * i2c-velleman - * video/i2c-parport (NOT the same as this one, dedicated to home brew - teletext adapters) - -It currently supports the following devices: - * (type=0) Philips adapter - * (type=1) home brew teletext adapter - * (type=2) Velleman K8000 adapter - * (type=3) ELV adapter - * (type=4) Analog Devices ADM1032 evaluation board - * (type=5) Analog Devices evaluation boards: ADM1025, ADM1030, ADM1031 - * (type=6) Barco LPT->DVI (K5800236) adapter - * (type=7) One For All JP1 parallel port adapter - * (type=8) VCT-jig - -These devices use different pinout configurations, so you have to tell -the driver what you have, using the type module parameter. There is no -way to autodetect the devices. Support for different pinout configurations -can be easily added when needed. - -Earlier kernels defaulted to type=0 (Philips). But now, if the type -parameter is missing, the driver will simply fail to initialize. - -SMBus alert support is available on adapters which have this line properly -connected to the parallel port's interrupt pin. - - -Building your own adapter -------------------------- - -If you want to build you own i2c-over-parallel-port adapter, here is -a sample electronics schema (credits go to Sylvain Munaut): - -Device PC -Side ___________________Vdd (+) Side - | | | - --- --- --- - | | | | | | - |R| |R| |R| - | | | | | | - --- --- --- - | | | - | | /| | -SCL ----------x--------o |-----------x------------------- pin 2 - | \| | | - | | | - | |\ | | -SDA ----------x----x---| o---x--------------------------- pin 13 - | |/ | - | | - | /| | - ---------o |----------------x-------------- pin 3 - \| | | - | | - --- --- - | | | | - |R| |R| - | | | | - --- --- - | | - ### ### - GND GND - -Remarks: - - This is the exact pinout and electronics used on the Analog Devices - evaluation boards. - /| - - All inverters -o |- must be 74HC05, they must be open collector output. - \| - - All resitors are 10k. - - Pins 18-25 of the parallel port connected to GND. - - Pins 4-9 (D2-D7) could be used as VDD is the driver drives them high. - The ADM1032 evaluation board uses D4-D7. Beware that the amount of - current you can draw from the parallel port is limited. Also note that - all connected lines MUST BE driven at the same state, else you'll short - circuit the output buffers! So plugging the I2C adapter after loading - the i2c-parport module might be a good safety since data line state - prior to init may be unknown. - - This is 5V! - - Obviously you cannot read SCL (so it's not really standard-compliant). - Pretty easy to add, just copy the SDA part and use another input pin. - That would give (ELV compatible pinout): - - -Device PC -Side ______________________________Vdd (+) Side - | | | | - --- --- --- --- - | | | | | | | | - |R| |R| |R| |R| - | | | | | | | | - --- --- --- --- - | | | | - | | |\ | | -SCL ----------x--------x--| o---x------------------------ pin 15 - | | |/ | - | | | - | | /| | - | ---o |-------------x-------------- pin 2 - | \| | | - | | | - | | | - | |\ | | -SDA ---------------x---x--| o--------x------------------- pin 10 - | |/ | - | | - | /| | - ---o |------------------x--------- pin 3 - \| | | - | | - --- --- - | | | | - |R| |R| - | | | | - --- --- - | | - ### ### - GND GND - - -If possible, you should use the same pinout configuration as existing -adapters do, so you won't even have to change the code. - - -Similar (but different) drivers -------------------------------- - -This driver is NOT the same as the i2c-pport driver found in the i2c -package. The i2c-pport driver makes use of modern parallel port features so -that you don't need additional electronics. It has other restrictions -however, and was not ported to Linux 2.6 (yet). - -This driver is also NOT the same as the i2c-pcf-epp driver found in the -lm_sensors package. The i2c-pcf-epp driver doesn't use the parallel port as -an I2C bus directly. Instead, it uses it to control an external I2C bus -master. That driver was not ported to Linux 2.6 (yet) either. - - -Legacy documentation for Velleman adapter ------------------------------------------ - -Useful links: -Velleman http://www.velleman.be/ -Velleman K8000 Howto http://howto.htlw16.ac.at/k8000-howto.html - -The project has lead to new libs for the Velleman K8000 and K8005: - LIBK8000 v1.99.1 and LIBK8005 v0.21 -With these libs, you can control the K8000 interface card and the K8005 -stepper motor card with the simple commands which are in the original -Velleman software, like SetIOchannel, ReadADchannel, SendStepCCWFull and -many more, using /dev/velleman. - http://home.wanadoo.nl/hihihi/libk8000.htm - http://home.wanadoo.nl/hihihi/libk8005.htm - http://struyve.mine.nu:8080/index.php?block=k8000 - http://sourceforge.net/projects/libk8005/ - - -One For All JP1 parallel port adapter -------------------------------------- - -The JP1 project revolves around a set of remote controls which expose -the I2C bus their internal configuration EEPROM lives on via a 6 pin -jumper in the battery compartment. More details can be found at: - -http://www.hifi-remote.com/jp1/ - -Details of the simple parallel port hardware can be found at: - -http://www.hifi-remote.com/jp1/hardware.shtml diff --git a/Documentation/i2c/busses/i2c-parport-light b/Documentation/i2c/busses/i2c-parport-light deleted file mode 100644 index 7071b8ba0af4..000000000000 --- a/Documentation/i2c/busses/i2c-parport-light +++ /dev/null @@ -1,22 +0,0 @@ -Kernel driver i2c-parport-light - -Author: Jean Delvare - -This driver is a light version of i2c-parport. It doesn't depend -on the parport driver, and uses direct I/O access instead. This might be -preferred on embedded systems where wasting memory for the clean but heavy -parport handling is not an option. The drawback is a reduced portability -and the impossibility to daisy-chain other parallel port devices. - -Please see i2c-parport for documentation. - -Module parameters: - -* type: type of adapter (see i2c-parport or modinfo) - -* base: base I/O address - Default is 0x378 which is fairly common for parallel ports, at least on PC. - -* irq: optional IRQ - This must be passed if you want SMBus alert support, assuming your adapter - actually supports this. diff --git a/Documentation/i2c/busses/i2c-parport-light.rst b/Documentation/i2c/busses/i2c-parport-light.rst new file mode 100644 index 000000000000..e73af975d2c8 --- /dev/null +++ b/Documentation/i2c/busses/i2c-parport-light.rst @@ -0,0 +1,24 @@ +=============================== +Kernel driver i2c-parport-light +=============================== + +Author: Jean Delvare + +This driver is a light version of i2c-parport. It doesn't depend +on the parport driver, and uses direct I/O access instead. This might be +preferred on embedded systems where wasting memory for the clean but heavy +parport handling is not an option. The drawback is a reduced portability +and the impossibility to daisy-chain other parallel port devices. + +Please see i2c-parport for documentation. + +Module parameters: + +* type: type of adapter (see i2c-parport or modinfo) + +* base: base I/O address + Default is 0x378 which is fairly common for parallel ports, at least on PC. + +* irq: optional IRQ + This must be passed if you want SMBus alert support, assuming your adapter + actually supports this. diff --git a/Documentation/i2c/busses/i2c-parport.rst b/Documentation/i2c/busses/i2c-parport.rst new file mode 100644 index 000000000000..a9b4e8133700 --- /dev/null +++ b/Documentation/i2c/busses/i2c-parport.rst @@ -0,0 +1,190 @@ +========================= +Kernel driver i2c-parport +========================= + +Author: Jean Delvare + +This is a unified driver for several i2c-over-parallel-port adapters, +such as the ones made by Philips, Velleman or ELV. This driver is +meant as a replacement for the older, individual drivers: + + * i2c-philips-par + * i2c-elv + * i2c-velleman + * video/i2c-parport + (NOT the same as this one, dedicated to home brew teletext adapters) + +It currently supports the following devices: + + * (type=0) Philips adapter + * (type=1) home brew teletext adapter + * (type=2) Velleman K8000 adapter + * (type=3) ELV adapter + * (type=4) Analog Devices ADM1032 evaluation board + * (type=5) Analog Devices evaluation boards: ADM1025, ADM1030, ADM1031 + * (type=6) Barco LPT->DVI (K5800236) adapter + * (type=7) One For All JP1 parallel port adapter + * (type=8) VCT-jig + +These devices use different pinout configurations, so you have to tell +the driver what you have, using the type module parameter. There is no +way to autodetect the devices. Support for different pinout configurations +can be easily added when needed. + +Earlier kernels defaulted to type=0 (Philips). But now, if the type +parameter is missing, the driver will simply fail to initialize. + +SMBus alert support is available on adapters which have this line properly +connected to the parallel port's interrupt pin. + + +Building your own adapter +------------------------- + +If you want to build you own i2c-over-parallel-port adapter, here is +a sample electronics schema (credits go to Sylvain Munaut):: + + Device PC + Side ___________________Vdd (+) Side + | | | + --- --- --- + | | | | | | + |R| |R| |R| + | | | | | | + --- --- --- + | | | + | | /| | + SCL ----------x--------o |-----------x------------------- pin 2 + | \| | | + | | | + | |\ | | + SDA ----------x----x---| o---x--------------------------- pin 13 + | |/ | + | | + | /| | + ---------o |----------------x-------------- pin 3 + \| | | + | | + --- --- + | | | | + |R| |R| + | | | | + --- --- + | | + ### ### + GND GND + +Remarks: + - This is the exact pinout and electronics used on the Analog Devices + evaluation boards. + - All inverters:: + + /| + -o |- + \| + + must be 74HC05, they must be open collector output. + - All resitors are 10k. + - Pins 18-25 of the parallel port connected to GND. + - Pins 4-9 (D2-D7) could be used as VDD is the driver drives them high. + The ADM1032 evaluation board uses D4-D7. Beware that the amount of + current you can draw from the parallel port is limited. Also note that + all connected lines MUST BE driven at the same state, else you'll short + circuit the output buffers! So plugging the I2C adapter after loading + the i2c-parport module might be a good safety since data line state + prior to init may be unknown. + - This is 5V! + - Obviously you cannot read SCL (so it's not really standard-compliant). + Pretty easy to add, just copy the SDA part and use another input pin. + That would give (ELV compatible pinout):: + + + Device PC + Side ______________________________Vdd (+) Side + | | | | + --- --- --- --- + | | | | | | | | + |R| |R| |R| |R| + | | | | | | | | + --- --- --- --- + | | | | + | | |\ | | + SCL ----------x--------x--| o---x------------------------ pin 15 + | | |/ | + | | | + | | /| | + | ---o |-------------x-------------- pin 2 + | \| | | + | | | + | | | + | |\ | | + SDA ---------------x---x--| o--------x------------------- pin 10 + | |/ | + | | + | /| | + ---o |------------------x--------- pin 3 + \| | | + | | + --- --- + | | | | + |R| |R| + | | | | + --- --- + | | + ### ### + GND GND + + +If possible, you should use the same pinout configuration as existing +adapters do, so you won't even have to change the code. + + +Similar (but different) drivers +------------------------------- + +This driver is NOT the same as the i2c-pport driver found in the i2c +package. The i2c-pport driver makes use of modern parallel port features so +that you don't need additional electronics. It has other restrictions +however, and was not ported to Linux 2.6 (yet). + +This driver is also NOT the same as the i2c-pcf-epp driver found in the +lm_sensors package. The i2c-pcf-epp driver doesn't use the parallel port as +an I2C bus directly. Instead, it uses it to control an external I2C bus +master. That driver was not ported to Linux 2.6 (yet) either. + + +Legacy documentation for Velleman adapter +----------------------------------------- + +Useful links: + +- Velleman http://www.velleman.be/ +- Velleman K8000 Howto http://howto.htlw16.ac.at/k8000-howto.html + +The project has lead to new libs for the Velleman K8000 and K8005: + + LIBK8000 v1.99.1 and LIBK8005 v0.21 + +With these libs, you can control the K8000 interface card and the K8005 +stepper motor card with the simple commands which are in the original +Velleman software, like SetIOchannel, ReadADchannel, SendStepCCWFull and +many more, using /dev/velleman. + + - http://home.wanadoo.nl/hihihi/libk8000.htm + - http://home.wanadoo.nl/hihihi/libk8005.htm + - http://struyve.mine.nu:8080/index.php?block=k8000 + - http://sourceforge.net/projects/libk8005/ + + +One For All JP1 parallel port adapter +------------------------------------- + +The JP1 project revolves around a set of remote controls which expose +the I2C bus their internal configuration EEPROM lives on via a 6 pin +jumper in the battery compartment. More details can be found at: + +http://www.hifi-remote.com/jp1/ + +Details of the simple parallel port hardware can be found at: + +http://www.hifi-remote.com/jp1/hardware.shtml diff --git a/Documentation/i2c/busses/i2c-pca-isa b/Documentation/i2c/busses/i2c-pca-isa deleted file mode 100644 index b044e5265488..000000000000 --- a/Documentation/i2c/busses/i2c-pca-isa +++ /dev/null @@ -1,23 +0,0 @@ -Kernel driver i2c-pca-isa - -Supported adapters: -This driver supports ISA boards using the Philips PCA 9564 -Parallel bus to I2C bus controller - -Author: Ian Campbell , Arcom Control Systems - -Module Parameters ------------------ - -* base int - I/O base address -* irq int - IRQ interrupt -* clock int - Clock rate as described in table 1 of PCA9564 datasheet - -Description ------------ - -This driver supports ISA boards using the Philips PCA 9564 -Parallel bus to I2C bus controller diff --git a/Documentation/i2c/busses/i2c-pca-isa.rst b/Documentation/i2c/busses/i2c-pca-isa.rst new file mode 100644 index 000000000000..a254010c8055 --- /dev/null +++ b/Documentation/i2c/busses/i2c-pca-isa.rst @@ -0,0 +1,26 @@ +========================= +Kernel driver i2c-pca-isa +========================= + +Supported adapters: + +This driver supports ISA boards using the Philips PCA 9564 +Parallel bus to I2C bus controller + +Author: Ian Campbell , Arcom Control Systems + +Module Parameters +----------------- + +* base int + I/O base address +* irq int + IRQ interrupt +* clock int + Clock rate as described in table 1 of PCA9564 datasheet + +Description +----------- + +This driver supports ISA boards using the Philips PCA 9564 +Parallel bus to I2C bus controller diff --git a/Documentation/i2c/busses/i2c-piix4 b/Documentation/i2c/busses/i2c-piix4 deleted file mode 100644 index 2703bc3acad0..000000000000 --- a/Documentation/i2c/busses/i2c-piix4 +++ /dev/null @@ -1,112 +0,0 @@ -Kernel driver i2c-piix4 - -Supported adapters: - * Intel 82371AB PIIX4 and PIIX4E - * Intel 82443MX (440MX) - Datasheet: Publicly available at the Intel website - * ServerWorks OSB4, CSB5, CSB6, HT-1000 and HT-1100 southbridges - Datasheet: Only available via NDA from ServerWorks - * ATI IXP200, IXP300, IXP400, SB600, SB700 and SB800 southbridges - Datasheet: Not publicly available - SB700 register reference available at: - http://support.amd.com/us/Embedded_TechDocs/43009_sb7xx_rrg_pub_1.00.pdf - * AMD SP5100 (SB700 derivative found on some server mainboards) - Datasheet: Publicly available at the AMD website - http://support.amd.com/us/Embedded_TechDocs/44413.pdf - * AMD Hudson-2, ML, CZ - Datasheet: Not publicly available - * Hygon CZ - Datasheet: Not publicly available - * Standard Microsystems (SMSC) SLC90E66 (Victory66) southbridge - Datasheet: Publicly available at the SMSC website http://www.smsc.com - -Authors: - Frodo Looijaard - Philip Edelbrock - - -Module Parameters ------------------ - -* force: int - Forcibly enable the PIIX4. DANGEROUS! -* force_addr: int - Forcibly enable the PIIX4 at the given address. EXTREMELY DANGEROUS! - - -Description ------------ - -The PIIX4 (properly known as the 82371AB) is an Intel chip with a lot of -functionality. Among other things, it implements the PCI bus. One of its -minor functions is implementing a System Management Bus. This is a true -SMBus - you can not access it on I2C levels. The good news is that it -natively understands SMBus commands and you do not have to worry about -timing problems. The bad news is that non-SMBus devices connected to it can -confuse it mightily. Yes, this is known to happen... - -Do 'lspci -v' and see whether it contains an entry like this: - -0000:00:02.3 Bridge: Intel Corp. 82371AB/EB/MB PIIX4 ACPI (rev 02) - Flags: medium devsel, IRQ 9 - -Bus and device numbers may differ, but the function number must be -identical (like many PCI devices, the PIIX4 incorporates a number of -different 'functions', which can be considered as separate devices). If you -find such an entry, you have a PIIX4 SMBus controller. - -On some computers (most notably, some Dells), the SMBus is disabled by -default. If you use the insmod parameter 'force=1', the kernel module will -try to enable it. THIS IS VERY DANGEROUS! If the BIOS did not set up a -correct address for this module, you could get in big trouble (read: -crashes, data corruption, etc.). Try this only as a last resort (try BIOS -updates first, for example), and backup first! An even more dangerous -option is 'force_addr='. This will not only enable the PIIX4 like -'force' foes, but it will also set a new base I/O port address. The SMBus -parts of the PIIX4 needs a range of 8 of these addresses to function -correctly. If these addresses are already reserved by some other device, -you will get into big trouble! DON'T USE THIS IF YOU ARE NOT VERY SURE -ABOUT WHAT YOU ARE DOING! - -The PIIX4E is just an new version of the PIIX4; it is supported as well. -The PIIX/PIIX3 does not implement an SMBus or I2C bus, so you can't use -this driver on those mainboards. - -The ServerWorks Southbridges, the Intel 440MX, and the Victory66 are -identical to the PIIX4 in I2C/SMBus support. - -The AMD SB700, SB800, SP5100 and Hudson-2 chipsets implement two -PIIX4-compatible SMBus controllers. If your BIOS initializes the -secondary controller, it will be detected by this driver as -an "Auxiliary SMBus Host Controller". - -If you own Force CPCI735 motherboard or other OSB4 based systems you may need -to change the SMBus Interrupt Select register so the SMBus controller uses -the SMI mode. - -1) Use lspci command and locate the PCI device with the SMBus controller: - 00:0f.0 ISA bridge: ServerWorks OSB4 South Bridge (rev 4f) - The line may vary for different chipsets. Please consult the driver source - for all possible PCI ids (and lspci -n to match them). Lets assume the - device is located at 00:0f.0. -2) Now you just need to change the value in 0xD2 register. Get it first with - command: lspci -xxx -s 00:0f.0 - If the value is 0x3 then you need to change it to 0x1 - setpci -s 00:0f.0 d2.b=1 - -Please note that you don't need to do that in all cases, just when the SMBus is -not working properly. - - -Hardware-specific issues ------------------------- - -This driver will refuse to load on IBM systems with an Intel PIIX4 SMBus. -Some of these machines have an RFID EEPROM (24RF08) connected to the SMBus, -which can easily get corrupted due to a state machine bug. These are mostly -Thinkpad laptops, but desktop systems may also be affected. We have no list -of all affected systems, so the only safe solution was to prevent access to -the SMBus on all IBM systems (detected using DMI data.) - -For additional information, read: -http://www.lm-sensors.org/browser/lm-sensors/trunk/README diff --git a/Documentation/i2c/busses/i2c-piix4.rst b/Documentation/i2c/busses/i2c-piix4.rst new file mode 100644 index 000000000000..cc9000259223 --- /dev/null +++ b/Documentation/i2c/busses/i2c-piix4.rst @@ -0,0 +1,114 @@ +======================= +Kernel driver i2c-piix4 +======================= + +Supported adapters: + * Intel 82371AB PIIX4 and PIIX4E + * Intel 82443MX (440MX) + Datasheet: Publicly available at the Intel website + * ServerWorks OSB4, CSB5, CSB6, HT-1000 and HT-1100 southbridges + Datasheet: Only available via NDA from ServerWorks + * ATI IXP200, IXP300, IXP400, SB600, SB700 and SB800 southbridges + Datasheet: Not publicly available + SB700 register reference available at: + http://support.amd.com/us/Embedded_TechDocs/43009_sb7xx_rrg_pub_1.00.pdf + * AMD SP5100 (SB700 derivative found on some server mainboards) + Datasheet: Publicly available at the AMD website + http://support.amd.com/us/Embedded_TechDocs/44413.pdf + * AMD Hudson-2, ML, CZ + Datasheet: Not publicly available + * Hygon CZ + Datasheet: Not publicly available + * Standard Microsystems (SMSC) SLC90E66 (Victory66) southbridge + Datasheet: Publicly available at the SMSC website http://www.smsc.com + +Authors: + - Frodo Looijaard + - Philip Edelbrock + + +Module Parameters +----------------- + +* force: int + Forcibly enable the PIIX4. DANGEROUS! +* force_addr: int + Forcibly enable the PIIX4 at the given address. EXTREMELY DANGEROUS! + + +Description +----------- + +The PIIX4 (properly known as the 82371AB) is an Intel chip with a lot of +functionality. Among other things, it implements the PCI bus. One of its +minor functions is implementing a System Management Bus. This is a true +SMBus - you can not access it on I2C levels. The good news is that it +natively understands SMBus commands and you do not have to worry about +timing problems. The bad news is that non-SMBus devices connected to it can +confuse it mightily. Yes, this is known to happen... + +Do ``lspci -v`` and see whether it contains an entry like this:: + + 0000:00:02.3 Bridge: Intel Corp. 82371AB/EB/MB PIIX4 ACPI (rev 02) + Flags: medium devsel, IRQ 9 + +Bus and device numbers may differ, but the function number must be +identical (like many PCI devices, the PIIX4 incorporates a number of +different 'functions', which can be considered as separate devices). If you +find such an entry, you have a PIIX4 SMBus controller. + +On some computers (most notably, some Dells), the SMBus is disabled by +default. If you use the insmod parameter 'force=1', the kernel module will +try to enable it. THIS IS VERY DANGEROUS! If the BIOS did not set up a +correct address for this module, you could get in big trouble (read: +crashes, data corruption, etc.). Try this only as a last resort (try BIOS +updates first, for example), and backup first! An even more dangerous +option is 'force_addr='. This will not only enable the PIIX4 like +'force' foes, but it will also set a new base I/O port address. The SMBus +parts of the PIIX4 needs a range of 8 of these addresses to function +correctly. If these addresses are already reserved by some other device, +you will get into big trouble! DON'T USE THIS IF YOU ARE NOT VERY SURE +ABOUT WHAT YOU ARE DOING! + +The PIIX4E is just an new version of the PIIX4; it is supported as well. +The PIIX/PIIX3 does not implement an SMBus or I2C bus, so you can't use +this driver on those mainboards. + +The ServerWorks Southbridges, the Intel 440MX, and the Victory66 are +identical to the PIIX4 in I2C/SMBus support. + +The AMD SB700, SB800, SP5100 and Hudson-2 chipsets implement two +PIIX4-compatible SMBus controllers. If your BIOS initializes the +secondary controller, it will be detected by this driver as +an "Auxiliary SMBus Host Controller". + +If you own Force CPCI735 motherboard or other OSB4 based systems you may need +to change the SMBus Interrupt Select register so the SMBus controller uses +the SMI mode. + +1) Use lspci command and locate the PCI device with the SMBus controller: + 00:0f.0 ISA bridge: ServerWorks OSB4 South Bridge (rev 4f) + The line may vary for different chipsets. Please consult the driver source + for all possible PCI ids (and lspci -n to match them). Lets assume the + device is located at 00:0f.0. +2) Now you just need to change the value in 0xD2 register. Get it first with + command: lspci -xxx -s 00:0f.0 + If the value is 0x3 then you need to change it to 0x1: + setpci -s 00:0f.0 d2.b=1 + +Please note that you don't need to do that in all cases, just when the SMBus is +not working properly. + + +Hardware-specific issues +------------------------ + +This driver will refuse to load on IBM systems with an Intel PIIX4 SMBus. +Some of these machines have an RFID EEPROM (24RF08) connected to the SMBus, +which can easily get corrupted due to a state machine bug. These are mostly +Thinkpad laptops, but desktop systems may also be affected. We have no list +of all affected systems, so the only safe solution was to prevent access to +the SMBus on all IBM systems (detected using DMI data.) + +For additional information, read: +http://www.lm-sensors.org/browser/lm-sensors/trunk/README diff --git a/Documentation/i2c/busses/i2c-sis5595 b/Documentation/i2c/busses/i2c-sis5595 deleted file mode 100644 index ecd21fb49a8f..000000000000 --- a/Documentation/i2c/busses/i2c-sis5595 +++ /dev/null @@ -1,59 +0,0 @@ -Kernel driver i2c-sis5595 - -Authors: - Frodo Looijaard , - Mark D. Studebaker , - Philip Edelbrock - -Supported adapters: - * Silicon Integrated Systems Corp. SiS5595 Southbridge - Datasheet: Publicly available at the Silicon Integrated Systems Corp. site. - -Note: all have mfr. ID 0x1039. - - SUPPORTED PCI ID - 5595 0008 - - Note: these chips contain a 0008 device which is incompatible with the - 5595. We recognize these by the presence of the listed - "blacklist" PCI ID and refuse to load. - - NOT SUPPORTED PCI ID BLACKLIST PCI ID - 540 0008 0540 - 550 0008 0550 - 5513 0008 5511 - 5581 0008 5597 - 5582 0008 5597 - 5597 0008 5597 - 5598 0008 5597/5598 - 630 0008 0630 - 645 0008 0645 - 646 0008 0646 - 648 0008 0648 - 650 0008 0650 - 651 0008 0651 - 730 0008 0730 - 735 0008 0735 - 745 0008 0745 - 746 0008 0746 - -Module Parameters ------------------ - -* force_addr=0xaddr Set the I/O base address. Useful for boards - that don't set the address in the BIOS. Does not do a - PCI force; the device must still be present in lspci. - Don't use this unless the driver complains that the - base address is not set. - -Description ------------ - -i2c-sis5595 is a true SMBus host driver for motherboards with the SiS5595 -southbridges. - -WARNING: If you are trying to access the integrated sensors on the SiS5595 -chip, you want the sis5595 driver for those, not this driver. This driver -is a BUS driver, not a CHIP driver. A BUS driver is used by other CHIP -drivers to access chips on the bus. - diff --git a/Documentation/i2c/busses/i2c-sis5595.rst b/Documentation/i2c/busses/i2c-sis5595.rst new file mode 100644 index 000000000000..b85630c84a96 --- /dev/null +++ b/Documentation/i2c/busses/i2c-sis5595.rst @@ -0,0 +1,68 @@ +========================= +Kernel driver i2c-sis5595 +========================= + +Authors: + - Frodo Looijaard , + - Mark D. Studebaker , + - Philip Edelbrock + +Supported adapters: + * Silicon Integrated Systems Corp. SiS5595 Southbridge + Datasheet: Publicly available at the Silicon Integrated Systems Corp. site. + +Note: all have mfr. ID 0x1039. + + ========= ====== + SUPPORTED PCI ID + ========= ====== + 5595 0008 + ========= ====== + + Note: these chips contain a 0008 device which is incompatible with the + 5595. We recognize these by the presence of the listed + "blacklist" PCI ID and refuse to load. + + ============= ====== ================ + NOT SUPPORTED PCI ID BLACKLIST PCI ID + ============= ====== ================ + 540 0008 0540 + 550 0008 0550 + 5513 0008 5511 + 5581 0008 5597 + 5582 0008 5597 + 5597 0008 5597 + 5598 0008 5597/5598 + 630 0008 0630 + 645 0008 0645 + 646 0008 0646 + 648 0008 0648 + 650 0008 0650 + 651 0008 0651 + 730 0008 0730 + 735 0008 0735 + 745 0008 0745 + 746 0008 0746 + ============= ====== ================ + +Module Parameters +----------------- + +================== ===================================================== +force_addr=0xaddr Set the I/O base address. Useful for boards + that don't set the address in the BIOS. Does not do a + PCI force; the device must still be present in lspci. + Don't use this unless the driver complains that the + base address is not set. +================== ===================================================== + +Description +----------- + +i2c-sis5595 is a true SMBus host driver for motherboards with the SiS5595 +southbridges. + +WARNING: If you are trying to access the integrated sensors on the SiS5595 +chip, you want the sis5595 driver for those, not this driver. This driver +is a BUS driver, not a CHIP driver. A BUS driver is used by other CHIP +drivers to access chips on the bus. diff --git a/Documentation/i2c/busses/i2c-sis630 b/Documentation/i2c/busses/i2c-sis630 deleted file mode 100644 index ee7943631074..000000000000 --- a/Documentation/i2c/busses/i2c-sis630 +++ /dev/null @@ -1,58 +0,0 @@ -Kernel driver i2c-sis630 - -Supported adapters: - * Silicon Integrated Systems Corp (SiS) - 630 chipset (Datasheet: available at http://www.sfr-fresh.com/linux) - 730 chipset - 964 chipset - * Possible other SiS chipsets ? - -Author: Alexander Malysh - Amaury Decrême - SiS964 support - -Module Parameters ------------------ - -* force = [1|0] Forcibly enable the SIS630. DANGEROUS! - This can be interesting for chipsets not named - above to check if it works for you chipset, but DANGEROUS! - -* high_clock = [1|0] Forcibly set Host Master Clock to 56KHz (default, - what your BIOS use). DANGEROUS! This should be a bit - faster, but freeze some systems (i.e. my Laptop). - SIS630/730 chip only. - - -Description ------------ - -This SMBus only driver is known to work on motherboards with the above -named chipsets. - -If you see something like this: - -00:00.0 Host bridge: Silicon Integrated Systems [SiS] 630 Host (rev 31) -00:01.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513 - -or like this: - -00:00.0 Host bridge: Silicon Integrated Systems [SiS] 730 Host (rev 02) -00:01.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513 - -or like this: - -00:00.0 Host bridge: Silicon Integrated Systems [SiS] 760/M760 Host (rev 02) -00:02.0 ISA bridge: Silicon Integrated Systems [SiS] SiS964 [MuTIOL Media IO] - LPC Controller (rev 36) - -in your 'lspci' output , then this driver is for your chipset. - -Thank You ---------- -Philip Edelbrock -- testing SiS730 support -Mark M. Hoffman -- bug fixes - -To anyone else which I forgot here ;), thanks! - diff --git a/Documentation/i2c/busses/i2c-sis630.rst b/Documentation/i2c/busses/i2c-sis630.rst new file mode 100644 index 000000000000..9fcd74b18781 --- /dev/null +++ b/Documentation/i2c/busses/i2c-sis630.rst @@ -0,0 +1,63 @@ +======================== +Kernel driver i2c-sis630 +======================== + +Supported adapters: + * Silicon Integrated Systems Corp (SiS) + 630 chipset (Datasheet: available at http://www.sfr-fresh.com/linux) + 730 chipset + 964 chipset + * Possible other SiS chipsets ? + +Author: + - Alexander Malysh + - Amaury Decrême - SiS964 support + +Module Parameters +----------------- + +================== ===================================================== +force = [1|0] Forcibly enable the SIS630. DANGEROUS! + This can be interesting for chipsets not named + above to check if it works for you chipset, + but DANGEROUS! + +high_clock = [1|0] Forcibly set Host Master Clock to 56KHz (default, + what your BIOS use). DANGEROUS! This should be a bit + faster, but freeze some systems (i.e. my Laptop). + SIS630/730 chip only. +================== ===================================================== + + +Description +----------- + +This SMBus only driver is known to work on motherboards with the above +named chipsets. + +If you see something like this:: + + 00:00.0 Host bridge: Silicon Integrated Systems [SiS] 630 Host (rev 31) + 00:01.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513 + +or like this:: + + 00:00.0 Host bridge: Silicon Integrated Systems [SiS] 730 Host (rev 02) + 00:01.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513 + +or like this:: + + 00:00.0 Host bridge: Silicon Integrated Systems [SiS] 760/M760 Host (rev 02) + 00:02.0 ISA bridge: Silicon Integrated Systems [SiS] SiS964 [MuTIOL Media IO] + LPC Controller (rev 36) + +in your ``lspci`` output , then this driver is for your chipset. + +Thank You +--------- +Philip Edelbrock +- testing SiS730 support +Mark M. Hoffman +- bug fixes + +To anyone else which I forgot here ;), thanks! diff --git a/Documentation/i2c/busses/i2c-sis96x b/Documentation/i2c/busses/i2c-sis96x deleted file mode 100644 index 0b979f3252a4..000000000000 --- a/Documentation/i2c/busses/i2c-sis96x +++ /dev/null @@ -1,73 +0,0 @@ -Kernel driver i2c-sis96x - -Replaces 2.4.x i2c-sis645 - -Supported adapters: - * Silicon Integrated Systems Corp (SiS) - Any combination of these host bridges: - 645, 645DX (aka 646), 648, 650, 651, 655, 735, 745, 746 - and these south bridges: - 961, 962, 963(L) - -Author: Mark M. Hoffman - -Description ------------ - -This SMBus only driver is known to work on motherboards with the above -named chipset combinations. The driver was developed without benefit of a -proper datasheet from SiS. The SMBus registers are assumed compatible with -those of the SiS630, although they are located in a completely different -place. Thanks to Alexander Malysh for providing the -SiS630 datasheet (and driver). - -The command "lspci" as root should produce something like these lines: - -00:00.0 Host bridge: Silicon Integrated Systems [SiS]: Unknown device 0645 -00:02.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513 -00:02.1 SMBus: Silicon Integrated Systems [SiS]: Unknown device 0016 - -or perhaps this... - -00:00.0 Host bridge: Silicon Integrated Systems [SiS]: Unknown device 0645 -00:02.0 ISA bridge: Silicon Integrated Systems [SiS]: Unknown device 0961 -00:02.1 SMBus: Silicon Integrated Systems [SiS]: Unknown device 0016 - -(kernel versions later than 2.4.18 may fill in the "Unknown"s) - -If you can't see it please look on quirk_sis_96x_smbus -(drivers/pci/quirks.c) (also if southbridge detection fails) - -I suspect that this driver could be made to work for the following SiS -chipsets as well: 635, and 635T. If anyone owns a board with those chips -AND is willing to risk crashing & burning an otherwise well-behaved kernel -in the name of progress... please contact me at or -via the linux-i2c mailing list: . Please send bug -reports and/or success stories as well. - - -TO DOs ------- - -* The driver does not support SMBus block reads/writes; I may add them if a -scenario is found where they're needed. - - -Thank You ---------- - -Mark D. Studebaker - - design hints and bug fixes -Alexander Maylsh - - ditto, plus an important datasheet... almost the one I really wanted -Hans-Günter Lütke Uphues - - patch for SiS735 -Robert Zwerus - - testing for SiS645DX -Kianusch Sayah Karadji - - patch for SiS645DX/962 -Ken Healy - - patch for SiS655 - -To anyone else who has written w/ feedback, thanks! - diff --git a/Documentation/i2c/busses/i2c-sis96x.rst b/Documentation/i2c/busses/i2c-sis96x.rst new file mode 100644 index 000000000000..437cc1d89588 --- /dev/null +++ b/Documentation/i2c/busses/i2c-sis96x.rst @@ -0,0 +1,82 @@ +======================== +Kernel driver i2c-sis96x +======================== + +Replaces 2.4.x i2c-sis645 + +Supported adapters: + + * Silicon Integrated Systems Corp (SiS) + + Any combination of these host bridges: + 645, 645DX (aka 646), 648, 650, 651, 655, 735, 745, 746 + + and these south bridges: + 961, 962, 963(L) + +Author: Mark M. Hoffman + +Description +----------- + +This SMBus only driver is known to work on motherboards with the above +named chipset combinations. The driver was developed without benefit of a +proper datasheet from SiS. The SMBus registers are assumed compatible with +those of the SiS630, although they are located in a completely different +place. Thanks to Alexander Malysh for providing the +SiS630 datasheet (and driver). + +The command ``lspci`` as root should produce something like these lines:: + + 00:00.0 Host bridge: Silicon Integrated Systems [SiS]: Unknown device 0645 + 00:02.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513 + 00:02.1 SMBus: Silicon Integrated Systems [SiS]: Unknown device 0016 + +or perhaps this:: + + 00:00.0 Host bridge: Silicon Integrated Systems [SiS]: Unknown device 0645 + 00:02.0 ISA bridge: Silicon Integrated Systems [SiS]: Unknown device 0961 + 00:02.1 SMBus: Silicon Integrated Systems [SiS]: Unknown device 0016 + +(kernel versions later than 2.4.18 may fill in the "Unknown"s) + +If you can't see it please look on quirk_sis_96x_smbus +(drivers/pci/quirks.c) (also if southbridge detection fails) + +I suspect that this driver could be made to work for the following SiS +chipsets as well: 635, and 635T. If anyone owns a board with those chips +AND is willing to risk crashing & burning an otherwise well-behaved kernel +in the name of progress... please contact me at or +via the linux-i2c mailing list: . Please send bug +reports and/or success stories as well. + + +TO DOs +------ + +* The driver does not support SMBus block reads/writes; I may add them if a + scenario is found where they're needed. + + +Thank You +--------- + +Mark D. Studebaker + - design hints and bug fixes + +Alexander Maylsh + - ditto, plus an important datasheet... almost the one I really wanted + +Hans-Günter Lütke Uphues + - patch for SiS735 + +Robert Zwerus + - testing for SiS645DX + +Kianusch Sayah Karadji + - patch for SiS645DX/962 + +Ken Healy + - patch for SiS655 + +To anyone else who has written w/ feedback, thanks! diff --git a/Documentation/i2c/busses/i2c-taos-evm b/Documentation/i2c/busses/i2c-taos-evm deleted file mode 100644 index 60299555dcf0..000000000000 --- a/Documentation/i2c/busses/i2c-taos-evm +++ /dev/null @@ -1,46 +0,0 @@ -Kernel driver i2c-taos-evm - -Author: Jean Delvare - -This is a driver for the evaluation modules for TAOS I2C/SMBus chips. -The modules include an SMBus master with limited capabilities, which can -be controlled over the serial port. Virtually all evaluation modules -are supported, but a few lines of code need to be added for each new -module to instantiate the right I2C chip on the bus. Obviously, a driver -for the chip in question is also needed. - -Currently supported devices are: - -* TAOS TSL2550 EVM - -For additional information on TAOS products, please see - http://www.taosinc.com/ - - -Using this driver ------------------ - -In order to use this driver, you'll need the serport driver, and the -inputattach tool, which is part of the input-utils package. The following -commands will tell the kernel that you have a TAOS EVM on the first -serial port: - -# modprobe serport -# inputattach --taos-evm /dev/ttyS0 - - -Technical details ------------------ - -Only 4 SMBus transaction types are supported by the TAOS evaluation -modules: -* Receive Byte -* Send Byte -* Read Byte -* Write Byte - -The communication protocol is text-based and pretty simple. It is -described in a PDF document on the CD which comes with the evaluation -module. The communication is rather slow, because the serial port has -to operate at 1200 bps. However, I don't think this is a big concern in -practice, as these modules are meant for evaluation and testing only. diff --git a/Documentation/i2c/busses/i2c-taos-evm.rst b/Documentation/i2c/busses/i2c-taos-evm.rst new file mode 100644 index 000000000000..f342e313ee3d --- /dev/null +++ b/Documentation/i2c/busses/i2c-taos-evm.rst @@ -0,0 +1,48 @@ +========================== +Kernel driver i2c-taos-evm +========================== + +Author: Jean Delvare + +This is a driver for the evaluation modules for TAOS I2C/SMBus chips. +The modules include an SMBus master with limited capabilities, which can +be controlled over the serial port. Virtually all evaluation modules +are supported, but a few lines of code need to be added for each new +module to instantiate the right I2C chip on the bus. Obviously, a driver +for the chip in question is also needed. + +Currently supported devices are: + +* TAOS TSL2550 EVM + +For additional information on TAOS products, please see + http://www.taosinc.com/ + + +Using this driver +----------------- + +In order to use this driver, you'll need the serport driver, and the +inputattach tool, which is part of the input-utils package. The following +commands will tell the kernel that you have a TAOS EVM on the first +serial port:: + + # modprobe serport + # inputattach --taos-evm /dev/ttyS0 + + +Technical details +----------------- + +Only 4 SMBus transaction types are supported by the TAOS evaluation +modules: +* Receive Byte +* Send Byte +* Read Byte +* Write Byte + +The communication protocol is text-based and pretty simple. It is +described in a PDF document on the CD which comes with the evaluation +module. The communication is rather slow, because the serial port has +to operate at 1200 bps. However, I don't think this is a big concern in +practice, as these modules are meant for evaluation and testing only. diff --git a/Documentation/i2c/busses/i2c-via b/Documentation/i2c/busses/i2c-via deleted file mode 100644 index 343870661ac3..000000000000 --- a/Documentation/i2c/busses/i2c-via +++ /dev/null @@ -1,34 +0,0 @@ -Kernel driver i2c-via - -Supported adapters: - * VIA Technologies, InC. VT82C586B - Datasheet: Publicly available at the VIA website - -Author: Kyösti Mälkki - -Description ------------ - -i2c-via is an i2c bus driver for motherboards with VIA chipset. - -The following VIA pci chipsets are supported: - - MVP3, VP3, VP2/97, VPX/97 - - others with South bridge VT82C586B - -Your lspci listing must show this : - - Bridge: VIA Technologies, Inc. VT82C586B ACPI (rev 10) - - Problems? - - Q: You have VT82C586B on the motherboard, but not in the listing. - - A: Go to your BIOS setup, section PCI devices or similar. - Turn USB support on, and try again. - - Q: No error messages, but still i2c doesn't seem to work. - - A: This can happen. This driver uses the pins VIA recommends in their - datasheets, but there are several ways the motherboard manufacturer - can actually wire the lines. - diff --git a/Documentation/i2c/busses/i2c-via.rst b/Documentation/i2c/busses/i2c-via.rst new file mode 100644 index 000000000000..846aa17d80a2 --- /dev/null +++ b/Documentation/i2c/busses/i2c-via.rst @@ -0,0 +1,40 @@ +===================== +Kernel driver i2c-via +===================== + +Supported adapters: + * VIA Technologies, InC. VT82C586B + Datasheet: Publicly available at the VIA website + +Author: Kyösti Mälkki + +Description +----------- + +i2c-via is an i2c bus driver for motherboards with VIA chipset. + +The following VIA pci chipsets are supported: + - MVP3, VP3, VP2/97, VPX/97 + - others with South bridge VT82C586B + +Your ``lspci`` listing must show this :: + + Bridge: VIA Technologies, Inc. VT82C586B ACPI (rev 10) + +Problems? +--------- + + Q: + You have VT82C586B on the motherboard, but not in the listing. + + A: + Go to your BIOS setup, section PCI devices or similar. + Turn USB support on, and try again. + + Q: + No error messages, but still i2c doesn't seem to work. + + A: + This can happen. This driver uses the pins VIA recommends in their + datasheets, but there are several ways the motherboard manufacturer + can actually wire the lines. diff --git a/Documentation/i2c/busses/i2c-viapro b/Documentation/i2c/busses/i2c-viapro deleted file mode 100644 index ab64ce21c254..000000000000 --- a/Documentation/i2c/busses/i2c-viapro +++ /dev/null @@ -1,73 +0,0 @@ -Kernel driver i2c-viapro - -Supported adapters: - * VIA Technologies, Inc. VT82C596A/B - Datasheet: Sometimes available at the VIA website - - * VIA Technologies, Inc. VT82C686A/B - Datasheet: Sometimes available at the VIA website - - * VIA Technologies, Inc. VT8231, VT8233, VT8233A - Datasheet: available on request from VIA - - * VIA Technologies, Inc. VT8235, VT8237R, VT8237A, VT8237S, VT8251 - Datasheet: available on request and under NDA from VIA - - * VIA Technologies, Inc. CX700 - Datasheet: available on request and under NDA from VIA - - * VIA Technologies, Inc. VX800/VX820 - Datasheet: available on http://linux.via.com.tw - - * VIA Technologies, Inc. VX855/VX875 - Datasheet: available on http://linux.via.com.tw - - * VIA Technologies, Inc. VX900 - Datasheet: available on http://linux.via.com.tw - -Authors: - Kyösti Mälkki , - Mark D. Studebaker , - Jean Delvare - -Module Parameters ------------------ - -* force: int - Forcibly enable the SMBus controller. DANGEROUS! -* force_addr: int - Forcibly enable the SMBus at the given address. EXTREMELY DANGEROUS! - -Description ------------ - -i2c-viapro is a true SMBus host driver for motherboards with one of the -supported VIA south bridges. - -Your lspci -n listing must show one of these : - - device 1106:3050 (VT82C596A function 3) - device 1106:3051 (VT82C596B function 3) - device 1106:3057 (VT82C686 function 4) - device 1106:3074 (VT8233) - device 1106:3147 (VT8233A) - device 1106:8235 (VT8231 function 4) - device 1106:3177 (VT8235) - device 1106:3227 (VT8237R) - device 1106:3337 (VT8237A) - device 1106:3372 (VT8237S) - device 1106:3287 (VT8251) - device 1106:8324 (CX700) - device 1106:8353 (VX800/VX820) - device 1106:8409 (VX855/VX875) - device 1106:8410 (VX900) - -If none of these show up, you should look in the BIOS for settings like -enable ACPI / SMBus or even USB. - -Except for the oldest chips (VT82C596A/B, VT82C686A and most probably -VT8231), this driver supports I2C block transactions. Such transactions -are mainly useful to read from and write to EEPROMs. - -The CX700/VX800/VX820 additionally appears to support SMBus PEC, although -this driver doesn't implement it yet. diff --git a/Documentation/i2c/busses/i2c-viapro.rst b/Documentation/i2c/busses/i2c-viapro.rst new file mode 100644 index 000000000000..1762f0cf93d0 --- /dev/null +++ b/Documentation/i2c/busses/i2c-viapro.rst @@ -0,0 +1,77 @@ +======================== +Kernel driver i2c-viapro +======================== + +Supported adapters: + * VIA Technologies, Inc. VT82C596A/B + Datasheet: Sometimes available at the VIA website + + * VIA Technologies, Inc. VT82C686A/B + Datasheet: Sometimes available at the VIA website + + * VIA Technologies, Inc. VT8231, VT8233, VT8233A + Datasheet: available on request from VIA + + * VIA Technologies, Inc. VT8235, VT8237R, VT8237A, VT8237S, VT8251 + Datasheet: available on request and under NDA from VIA + + * VIA Technologies, Inc. CX700 + Datasheet: available on request and under NDA from VIA + + * VIA Technologies, Inc. VX800/VX820 + Datasheet: available on http://linux.via.com.tw + + * VIA Technologies, Inc. VX855/VX875 + Datasheet: available on http://linux.via.com.tw + + * VIA Technologies, Inc. VX900 + Datasheet: available on http://linux.via.com.tw + +Authors: + - Kyösti Mälkki , + - Mark D. Studebaker , + - Jean Delvare + +Module Parameters +----------------- + +* force: int + Forcibly enable the SMBus controller. DANGEROUS! +* force_addr: int + Forcibly enable the SMBus at the given address. EXTREMELY DANGEROUS! + +Description +----------- + +i2c-viapro is a true SMBus host driver for motherboards with one of the +supported VIA south bridges. + +Your ``lspci -n`` listing must show one of these : + + ================ ====================== + device 1106:3050 (VT82C596A function 3) + device 1106:3051 (VT82C596B function 3) + device 1106:3057 (VT82C686 function 4) + device 1106:3074 (VT8233) + device 1106:3147 (VT8233A) + device 1106:8235 (VT8231 function 4) + device 1106:3177 (VT8235) + device 1106:3227 (VT8237R) + device 1106:3337 (VT8237A) + device 1106:3372 (VT8237S) + device 1106:3287 (VT8251) + device 1106:8324 (CX700) + device 1106:8353 (VX800/VX820) + device 1106:8409 (VX855/VX875) + device 1106:8410 (VX900) + ================ ====================== + +If none of these show up, you should look in the BIOS for settings like +enable ACPI / SMBus or even USB. + +Except for the oldest chips (VT82C596A/B, VT82C686A and most probably +VT8231), this driver supports I2C block transactions. Such transactions +are mainly useful to read from and write to EEPROMs. + +The CX700/VX800/VX820 additionally appears to support SMBus PEC, although +this driver doesn't implement it yet. diff --git a/Documentation/i2c/busses/index.rst b/Documentation/i2c/busses/index.rst new file mode 100644 index 000000000000..97ca4d510816 --- /dev/null +++ b/Documentation/i2c/busses/index.rst @@ -0,0 +1,33 @@ +. SPDX-License-Identifier: GPL-2.0 + +=============== +I2C Bus Drivers +=============== + +.. toctree:: + :maxdepth: 1 + + i2c-ali1535 + i2c-ali1563 + i2c-ali15x3 + i2c-amd756 + i2c-amd8111 + i2c-amd-mp2 + i2c-diolan-u2c + i2c-i801 + i2c-ismt + i2c-mlxcpld + i2c-nforce2 + i2c-nvidia-gpu + i2c-ocores + i2c-parport-light + i2c-parport + i2c-pca-isa + i2c-piix4 + i2c-sis5595 + i2c-sis630 + i2c-sis96x + i2c-taos-evm + i2c-viapro + i2c-via + scx200_acb diff --git a/Documentation/i2c/busses/scx200_acb b/Documentation/i2c/busses/scx200_acb deleted file mode 100644 index ce83c871fe95..000000000000 --- a/Documentation/i2c/busses/scx200_acb +++ /dev/null @@ -1,32 +0,0 @@ -Kernel driver scx200_acb - -Author: Christer Weinigel - -The driver supersedes the older, never merged driver named i2c-nscacb. - -Module Parameters ------------------ - -* base: up to 4 ints - Base addresses for the ACCESS.bus controllers on SCx200 and SC1100 devices - - By default the driver uses two base addresses 0x820 and 0x840. - If you want only one base address, specify the second as 0 so as to - override this default. - -Description ------------ - -Enable the use of the ACCESS.bus controller on the Geode SCx200 and -SC1100 processors and the CS5535 and CS5536 Geode companion devices. - -Device-specific notes ---------------------- - -The SC1100 WRAP boards are known to use base addresses 0x810 and 0x820. -If the scx200_acb driver is built into the kernel, add the following -parameter to your boot command line: - scx200_acb.base=0x810,0x820 -If the scx200_acb driver is built as a module, add the following line to -a configuration file in /etc/modprobe.d/ instead: - options scx200_acb base=0x810,0x820 diff --git a/Documentation/i2c/busses/scx200_acb.rst b/Documentation/i2c/busses/scx200_acb.rst new file mode 100644 index 000000000000..8dc7c352508c --- /dev/null +++ b/Documentation/i2c/busses/scx200_acb.rst @@ -0,0 +1,37 @@ +======================== +Kernel driver scx200_acb +======================== + +Author: Christer Weinigel + +The driver supersedes the older, never merged driver named i2c-nscacb. + +Module Parameters +----------------- + +* base: up to 4 ints + Base addresses for the ACCESS.bus controllers on SCx200 and SC1100 devices + + By default the driver uses two base addresses 0x820 and 0x840. + If you want only one base address, specify the second as 0 so as to + override this default. + +Description +----------- + +Enable the use of the ACCESS.bus controller on the Geode SCx200 and +SC1100 processors and the CS5535 and CS5536 Geode companion devices. + +Device-specific notes +--------------------- + +The SC1100 WRAP boards are known to use base addresses 0x810 and 0x820. +If the scx200_acb driver is built into the kernel, add the following +parameter to your boot command line:: + + scx200_acb.base=0x810,0x820 + +If the scx200_acb driver is built as a module, add the following line to +a configuration file in /etc/modprobe.d/ instead:: + + options scx200_acb base=0x810,0x820 diff --git a/Documentation/i2c/dev-interface b/Documentation/i2c/dev-interface deleted file mode 100644 index fbed645ccd75..000000000000 --- a/Documentation/i2c/dev-interface +++ /dev/null @@ -1,213 +0,0 @@ -Usually, i2c devices are controlled by a kernel driver. But it is also -possible to access all devices on an adapter from userspace, through -the /dev interface. You need to load module i2c-dev for this. - -Each registered i2c adapter gets a number, counting from 0. You can -examine /sys/class/i2c-dev/ to see what number corresponds to which adapter. -Alternatively, you can run "i2cdetect -l" to obtain a formatted list of all -i2c adapters present on your system at a given time. i2cdetect is part of -the i2c-tools package. - -I2C device files are character device files with major device number 89 -and a minor device number corresponding to the number assigned as -explained above. They should be called "i2c-%d" (i2c-0, i2c-1, ..., -i2c-10, ...). All 256 minor device numbers are reserved for i2c. - - -C example -========= - -So let's say you want to access an i2c adapter from a C program. -First, you need to include these two headers: - - #include - #include - -Now, you have to decide which adapter you want to access. You should -inspect /sys/class/i2c-dev/ or run "i2cdetect -l" to decide this. -Adapter numbers are assigned somewhat dynamically, so you can not -assume much about them. They can even change from one boot to the next. - -Next thing, open the device file, as follows: - - int file; - int adapter_nr = 2; /* probably dynamically determined */ - char filename[20]; - - snprintf(filename, 19, "/dev/i2c-%d", adapter_nr); - file = open(filename, O_RDWR); - if (file < 0) { - /* ERROR HANDLING; you can check errno to see what went wrong */ - exit(1); - } - -When you have opened the device, you must specify with what device -address you want to communicate: - - int addr = 0x40; /* The I2C address */ - - if (ioctl(file, I2C_SLAVE, addr) < 0) { - /* ERROR HANDLING; you can check errno to see what went wrong */ - exit(1); - } - -Well, you are all set up now. You can now use SMBus commands or plain -I2C to communicate with your device. SMBus commands are preferred if -the device supports them. Both are illustrated below. - - __u8 reg = 0x10; /* Device register to access */ - __s32 res; - char buf[10]; - - /* Using SMBus commands */ - res = i2c_smbus_read_word_data(file, reg); - if (res < 0) { - /* ERROR HANDLING: i2c transaction failed */ - } else { - /* res contains the read word */ - } - - /* - * Using I2C Write, equivalent of - * i2c_smbus_write_word_data(file, reg, 0x6543) - */ - buf[0] = reg; - buf[1] = 0x43; - buf[2] = 0x65; - if (write(file, buf, 3) != 3) { - /* ERROR HANDLING: i2c transaction failed */ - } - - /* Using I2C Read, equivalent of i2c_smbus_read_byte(file) */ - if (read(file, buf, 1) != 1) { - /* ERROR HANDLING: i2c transaction failed */ - } else { - /* buf[0] contains the read byte */ - } - -Note that only a subset of the I2C and SMBus protocols can be achieved by -the means of read() and write() calls. In particular, so-called combined -transactions (mixing read and write messages in the same transaction) -aren't supported. For this reason, this interface is almost never used by -user-space programs. - -IMPORTANT: because of the use of inline functions, you *have* to use -'-O' or some variation when you compile your program! - - -Full interface description -========================== - -The following IOCTLs are defined: - -ioctl(file, I2C_SLAVE, long addr) - Change slave address. The address is passed in the 7 lower bits of the - argument (except for 10 bit addresses, passed in the 10 lower bits in this - case). - -ioctl(file, I2C_TENBIT, long select) - Selects ten bit addresses if select not equals 0, selects normal 7 bit - addresses if select equals 0. Default 0. This request is only valid - if the adapter has I2C_FUNC_10BIT_ADDR. - -ioctl(file, I2C_PEC, long select) - Selects SMBus PEC (packet error checking) generation and verification - if select not equals 0, disables if select equals 0. Default 0. - Used only for SMBus transactions. This request only has an effect if the - the adapter has I2C_FUNC_SMBUS_PEC; it is still safe if not, it just - doesn't have any effect. - -ioctl(file, I2C_FUNCS, unsigned long *funcs) - Gets the adapter functionality and puts it in *funcs. - -ioctl(file, I2C_RDWR, struct i2c_rdwr_ioctl_data *msgset) - Do combined read/write transaction without stop in between. - Only valid if the adapter has I2C_FUNC_I2C. The argument is - a pointer to a - - struct i2c_rdwr_ioctl_data { - struct i2c_msg *msgs; /* ptr to array of simple messages */ - int nmsgs; /* number of messages to exchange */ - } - - The msgs[] themselves contain further pointers into data buffers. - The function will write or read data to or from that buffers depending - on whether the I2C_M_RD flag is set in a particular message or not. - The slave address and whether to use ten bit address mode has to be - set in each message, overriding the values set with the above ioctl's. - -ioctl(file, I2C_SMBUS, struct i2c_smbus_ioctl_data *args) - If possible, use the provided i2c_smbus_* methods described below instead - of issuing direct ioctls. - -You can do plain i2c transactions by using read(2) and write(2) calls. -You do not need to pass the address byte; instead, set it through -ioctl I2C_SLAVE before you try to access the device. - -You can do SMBus level transactions (see documentation file smbus-protocol -for details) through the following functions: - __s32 i2c_smbus_write_quick(int file, __u8 value); - __s32 i2c_smbus_read_byte(int file); - __s32 i2c_smbus_write_byte(int file, __u8 value); - __s32 i2c_smbus_read_byte_data(int file, __u8 command); - __s32 i2c_smbus_write_byte_data(int file, __u8 command, __u8 value); - __s32 i2c_smbus_read_word_data(int file, __u8 command); - __s32 i2c_smbus_write_word_data(int file, __u8 command, __u16 value); - __s32 i2c_smbus_process_call(int file, __u8 command, __u16 value); - __s32 i2c_smbus_read_block_data(int file, __u8 command, __u8 *values); - __s32 i2c_smbus_write_block_data(int file, __u8 command, __u8 length, - __u8 *values); -All these transactions return -1 on failure; you can read errno to see -what happened. The 'write' transactions return 0 on success; the -'read' transactions return the read value, except for read_block, which -returns the number of values read. The block buffers need not be longer -than 32 bytes. - -The above functions are made available by linking against the libi2c library, -which is provided by the i2c-tools project. See: -https://git.kernel.org/pub/scm/utils/i2c-tools/i2c-tools.git/. - - -Implementation details -====================== - -For the interested, here's the code flow which happens inside the kernel -when you use the /dev interface to I2C: - -1* Your program opens /dev/i2c-N and calls ioctl() on it, as described in -section "C example" above. - -2* These open() and ioctl() calls are handled by the i2c-dev kernel -driver: see i2c-dev.c:i2cdev_open() and i2c-dev.c:i2cdev_ioctl(), -respectively. You can think of i2c-dev as a generic I2C chip driver -that can be programmed from user-space. - -3* Some ioctl() calls are for administrative tasks and are handled by -i2c-dev directly. Examples include I2C_SLAVE (set the address of the -device you want to access) and I2C_PEC (enable or disable SMBus error -checking on future transactions.) - -4* Other ioctl() calls are converted to in-kernel function calls by -i2c-dev. Examples include I2C_FUNCS, which queries the I2C adapter -functionality using i2c.h:i2c_get_functionality(), and I2C_SMBUS, which -performs an SMBus transaction using i2c-core-smbus.c:i2c_smbus_xfer(). - -The i2c-dev driver is responsible for checking all the parameters that -come from user-space for validity. After this point, there is no -difference between these calls that came from user-space through i2c-dev -and calls that would have been performed by kernel I2C chip drivers -directly. This means that I2C bus drivers don't need to implement -anything special to support access from user-space. - -5* These i2c.h functions are wrappers to the actual implementation of -your I2C bus driver. Each adapter must declare callback functions -implementing these standard calls. i2c.h:i2c_get_functionality() calls -i2c_adapter.algo->functionality(), while -i2c-core-smbus.c:i2c_smbus_xfer() calls either -adapter.algo->smbus_xfer() if it is implemented, or if not, -i2c-core-smbus.c:i2c_smbus_xfer_emulated() which in turn calls -i2c_adapter.algo->master_xfer(). - -After your I2C bus driver has processed these requests, execution runs -up the call chain, with almost no processing done, except by i2c-dev to -package the returned data, if any, in suitable format for the ioctl. diff --git a/Documentation/i2c/dev-interface.rst b/Documentation/i2c/dev-interface.rst new file mode 100644 index 000000000000..69c23a3c2b1b --- /dev/null +++ b/Documentation/i2c/dev-interface.rst @@ -0,0 +1,219 @@ +==================== +I2C Device Interface +==================== + +Usually, i2c devices are controlled by a kernel driver. But it is also +possible to access all devices on an adapter from userspace, through +the /dev interface. You need to load module i2c-dev for this. + +Each registered i2c adapter gets a number, counting from 0. You can +examine /sys/class/i2c-dev/ to see what number corresponds to which adapter. +Alternatively, you can run "i2cdetect -l" to obtain a formatted list of all +i2c adapters present on your system at a given time. i2cdetect is part of +the i2c-tools package. + +I2C device files are character device files with major device number 89 +and a minor device number corresponding to the number assigned as +explained above. They should be called "i2c-%d" (i2c-0, i2c-1, ..., +i2c-10, ...). All 256 minor device numbers are reserved for i2c. + + +C example +========= + +So let's say you want to access an i2c adapter from a C program. +First, you need to include these two headers:: + + #include + #include + +Now, you have to decide which adapter you want to access. You should +inspect /sys/class/i2c-dev/ or run "i2cdetect -l" to decide this. +Adapter numbers are assigned somewhat dynamically, so you can not +assume much about them. They can even change from one boot to the next. + +Next thing, open the device file, as follows:: + + int file; + int adapter_nr = 2; /* probably dynamically determined */ + char filename[20]; + + snprintf(filename, 19, "/dev/i2c-%d", adapter_nr); + file = open(filename, O_RDWR); + if (file < 0) { + /* ERROR HANDLING; you can check errno to see what went wrong */ + exit(1); + } + +When you have opened the device, you must specify with what device +address you want to communicate:: + + int addr = 0x40; /* The I2C address */ + + if (ioctl(file, I2C_SLAVE, addr) < 0) { + /* ERROR HANDLING; you can check errno to see what went wrong */ + exit(1); + } + +Well, you are all set up now. You can now use SMBus commands or plain +I2C to communicate with your device. SMBus commands are preferred if +the device supports them. Both are illustrated below:: + + __u8 reg = 0x10; /* Device register to access */ + __s32 res; + char buf[10]; + + /* Using SMBus commands */ + res = i2c_smbus_read_word_data(file, reg); + if (res < 0) { + /* ERROR HANDLING: i2c transaction failed */ + } else { + /* res contains the read word */ + } + + /* + * Using I2C Write, equivalent of + * i2c_smbus_write_word_data(file, reg, 0x6543) + */ + buf[0] = reg; + buf[1] = 0x43; + buf[2] = 0x65; + if (write(file, buf, 3) != 3) { + /* ERROR HANDLING: i2c transaction failed */ + } + + /* Using I2C Read, equivalent of i2c_smbus_read_byte(file) */ + if (read(file, buf, 1) != 1) { + /* ERROR HANDLING: i2c transaction failed */ + } else { + /* buf[0] contains the read byte */ + } + +Note that only a subset of the I2C and SMBus protocols can be achieved by +the means of read() and write() calls. In particular, so-called combined +transactions (mixing read and write messages in the same transaction) +aren't supported. For this reason, this interface is almost never used by +user-space programs. + +IMPORTANT: because of the use of inline functions, you *have* to use +'-O' or some variation when you compile your program! + + +Full interface description +========================== + +The following IOCTLs are defined: + +``ioctl(file, I2C_SLAVE, long addr)`` + Change slave address. The address is passed in the 7 lower bits of the + argument (except for 10 bit addresses, passed in the 10 lower bits in this + case). + +``ioctl(file, I2C_TENBIT, long select)`` + Selects ten bit addresses if select not equals 0, selects normal 7 bit + addresses if select equals 0. Default 0. This request is only valid + if the adapter has I2C_FUNC_10BIT_ADDR. + +``ioctl(file, I2C_PEC, long select)`` + Selects SMBus PEC (packet error checking) generation and verification + if select not equals 0, disables if select equals 0. Default 0. + Used only for SMBus transactions. This request only has an effect if the + the adapter has I2C_FUNC_SMBUS_PEC; it is still safe if not, it just + doesn't have any effect. + +``ioctl(file, I2C_FUNCS, unsigned long *funcs)`` + Gets the adapter functionality and puts it in ``*funcs``. + +``ioctl(file, I2C_RDWR, struct i2c_rdwr_ioctl_data *msgset)`` + Do combined read/write transaction without stop in between. + Only valid if the adapter has I2C_FUNC_I2C. The argument is + a pointer to a:: + + struct i2c_rdwr_ioctl_data { + struct i2c_msg *msgs; /* ptr to array of simple messages */ + int nmsgs; /* number of messages to exchange */ + } + + The msgs[] themselves contain further pointers into data buffers. + The function will write or read data to or from that buffers depending + on whether the I2C_M_RD flag is set in a particular message or not. + The slave address and whether to use ten bit address mode has to be + set in each message, overriding the values set with the above ioctl's. + +``ioctl(file, I2C_SMBUS, struct i2c_smbus_ioctl_data *args)`` + If possible, use the provided ``i2c_smbus_*`` methods described below instead + of issuing direct ioctls. + +You can do plain i2c transactions by using read(2) and write(2) calls. +You do not need to pass the address byte; instead, set it through +ioctl I2C_SLAVE before you try to access the device. + +You can do SMBus level transactions (see documentation file smbus-protocol +for details) through the following functions:: + + __s32 i2c_smbus_write_quick(int file, __u8 value); + __s32 i2c_smbus_read_byte(int file); + __s32 i2c_smbus_write_byte(int file, __u8 value); + __s32 i2c_smbus_read_byte_data(int file, __u8 command); + __s32 i2c_smbus_write_byte_data(int file, __u8 command, __u8 value); + __s32 i2c_smbus_read_word_data(int file, __u8 command); + __s32 i2c_smbus_write_word_data(int file, __u8 command, __u16 value); + __s32 i2c_smbus_process_call(int file, __u8 command, __u16 value); + __s32 i2c_smbus_read_block_data(int file, __u8 command, __u8 *values); + __s32 i2c_smbus_write_block_data(int file, __u8 command, __u8 length, + __u8 *values); + +All these transactions return -1 on failure; you can read errno to see +what happened. The 'write' transactions return 0 on success; the +'read' transactions return the read value, except for read_block, which +returns the number of values read. The block buffers need not be longer +than 32 bytes. + +The above functions are made available by linking against the libi2c library, +which is provided by the i2c-tools project. See: +https://git.kernel.org/pub/scm/utils/i2c-tools/i2c-tools.git/. + + +Implementation details +====================== + +For the interested, here's the code flow which happens inside the kernel +when you use the /dev interface to I2C: + +1) Your program opens /dev/i2c-N and calls ioctl() on it, as described in + section "C example" above. + +2) These open() and ioctl() calls are handled by the i2c-dev kernel + driver: see i2c-dev.c:i2cdev_open() and i2c-dev.c:i2cdev_ioctl(), + respectively. You can think of i2c-dev as a generic I2C chip driver + that can be programmed from user-space. + +3) Some ioctl() calls are for administrative tasks and are handled by + i2c-dev directly. Examples include I2C_SLAVE (set the address of the + device you want to access) and I2C_PEC (enable or disable SMBus error + checking on future transactions.) + +4) Other ioctl() calls are converted to in-kernel function calls by + i2c-dev. Examples include I2C_FUNCS, which queries the I2C adapter + functionality using i2c.h:i2c_get_functionality(), and I2C_SMBUS, which + performs an SMBus transaction using i2c-core-smbus.c:i2c_smbus_xfer(). + + The i2c-dev driver is responsible for checking all the parameters that + come from user-space for validity. After this point, there is no + difference between these calls that came from user-space through i2c-dev + and calls that would have been performed by kernel I2C chip drivers + directly. This means that I2C bus drivers don't need to implement + anything special to support access from user-space. + +5) These i2c.h functions are wrappers to the actual implementation of + your I2C bus driver. Each adapter must declare callback functions + implementing these standard calls. i2c.h:i2c_get_functionality() calls + i2c_adapter.algo->functionality(), while + i2c-core-smbus.c:i2c_smbus_xfer() calls either + adapter.algo->smbus_xfer() if it is implemented, or if not, + i2c-core-smbus.c:i2c_smbus_xfer_emulated() which in turn calls + i2c_adapter.algo->master_xfer(). + +After your I2C bus driver has processed these requests, execution runs +up the call chain, with almost no processing done, except by i2c-dev to +package the returned data, if any, in suitable format for the ioctl. diff --git a/Documentation/i2c/dma-considerations.rst b/Documentation/i2c/dma-considerations.rst new file mode 100644 index 000000000000..203002054120 --- /dev/null +++ b/Documentation/i2c/dma-considerations.rst @@ -0,0 +1,71 @@ +================= +Linux I2C and DMA +================= + +Given that i2c is a low-speed bus, over which the majority of messages +transferred are small, it is not considered a prime user of DMA access. At this +time of writing, only 10% of I2C bus master drivers have DMA support +implemented. And the vast majority of transactions are so small that setting up +DMA for it will likely add more overhead than a plain PIO transfer. + +Therefore, it is *not* mandatory that the buffer of an I2C message is DMA safe. +It does not seem reasonable to apply additional burdens when the feature is so +rarely used. However, it is recommended to use a DMA-safe buffer if your +message size is likely applicable for DMA. Most drivers have this threshold +around 8 bytes (as of today, this is mostly an educated guess, however). For +any message of 16 byte or larger, it is probably a really good idea. Please +note that other subsystems you use might add requirements. E.g., if your +I2C bus master driver is using USB as a bridge, then you need to have DMA +safe buffers always, because USB requires it. + +Clients +------- + +For clients, if you use a DMA safe buffer in i2c_msg, set the I2C_M_DMA_SAFE +flag with it. Then, the I2C core and drivers know they can safely operate DMA +on it. Note that using this flag is optional. I2C host drivers which are not +updated to use this flag will work like before. And like before, they risk +using an unsafe DMA buffer. To improve this situation, using I2C_M_DMA_SAFE in +more and more clients and host drivers is the planned way forward. Note also +that setting this flag makes only sense in kernel space. User space data is +copied into kernel space anyhow. The I2C core makes sure the destination +buffers in kernel space are always DMA capable. Also, when the core emulates +SMBus transactions via I2C, the buffers for block transfers are DMA safe. Users +of i2c_master_send() and i2c_master_recv() functions can now use DMA safe +variants (i2c_master_send_dmasafe() and i2c_master_recv_dmasafe()) once they +know their buffers are DMA safe. Users of i2c_transfer() must set the +I2C_M_DMA_SAFE flag manually. + +Masters +------- + +Bus master drivers wishing to implement safe DMA can use helper functions from +the I2C core. One gives you a DMA-safe buffer for a given i2c_msg as long as a +certain threshold is met:: + + dma_buf = i2c_get_dma_safe_msg_buf(msg, threshold_in_byte); + +If a buffer is returned, it is either msg->buf for the I2C_M_DMA_SAFE case or a +bounce buffer. But you don't need to care about that detail, just use the +returned buffer. If NULL is returned, the threshold was not met or a bounce +buffer could not be allocated. Fall back to PIO in that case. + +In any case, a buffer obtained from above needs to be released. Another helper +function ensures a potentially used bounce buffer is freed:: + + i2c_put_dma_safe_msg_buf(dma_buf, msg, xferred); + +The last argument 'xferred' controls if the buffer is synced back to the +message or not. No syncing is needed in cases setting up DMA had an error and +there was no data transferred. + +The bounce buffer handling from the core is generic and simple. It will always +allocate a new bounce buffer. If you want a more sophisticated handling (e.g. +reusing pre-allocated buffers), you are free to implement your own. + +Please also check the in-kernel documentation for details. The i2c-sh_mobile +driver can be used as a reference example how to use the above helpers. + +Final note: If you plan to use DMA with I2C (or with anything else, actually) +make sure you have CONFIG_DMA_API_DEBUG enabled during development. It can help +you find various issues which can be complex to debug otherwise. diff --git a/Documentation/i2c/fault-codes b/Documentation/i2c/fault-codes deleted file mode 100644 index 0cee0fc545b4..000000000000 --- a/Documentation/i2c/fault-codes +++ /dev/null @@ -1,128 +0,0 @@ -This is a summary of the most important conventions for use of fault -codes in the I2C/SMBus stack. - - -A "Fault" is not always an "Error" ----------------------------------- -Not all fault reports imply errors; "page faults" should be a familiar -example. Software often retries idempotent operations after transient -faults. There may be fancier recovery schemes that are appropriate in -some cases, such as re-initializing (and maybe resetting). After such -recovery, triggered by a fault report, there is no error. - -In a similar way, sometimes a "fault" code just reports one defined -result for an operation ... it doesn't indicate that anything is wrong -at all, just that the outcome wasn't on the "golden path". - -In short, your I2C driver code may need to know these codes in order -to respond correctly. Other code may need to rely on YOUR code reporting -the right fault code, so that it can (in turn) behave correctly. - - -I2C and SMBus fault codes -------------------------- -These are returned as negative numbers from most calls, with zero or -some positive number indicating a non-fault return. The specific -numbers associated with these symbols differ between architectures, -though most Linux systems use numbering. - -Note that the descriptions here are not exhaustive. There are other -codes that may be returned, and other cases where these codes should -be returned. However, drivers should not return other codes for these -cases (unless the hardware doesn't provide unique fault reports). - -Also, codes returned by adapter probe methods follow rules which are -specific to their host bus (such as PCI, or the platform bus). - - -EAGAIN - Returned by I2C adapters when they lose arbitration in master - transmit mode: some other master was transmitting different - data at the same time. - - Also returned when trying to invoke an I2C operation in an - atomic context, when some task is already using that I2C bus - to execute some other operation. - -EBADMSG - Returned by SMBus logic when an invalid Packet Error Code byte - is received. This code is a CRC covering all bytes in the - transaction, and is sent before the terminating STOP. This - fault is only reported on read transactions; the SMBus slave - may have a way to report PEC mismatches on writes from the - host. Note that even if PECs are in use, you should not rely - on these as the only way to detect incorrect data transfers. - -EBUSY - Returned by SMBus adapters when the bus was busy for longer - than allowed. This usually indicates some device (maybe the - SMBus adapter) needs some fault recovery (such as resetting), - or that the reset was attempted but failed. - -EINVAL - This rather vague error means an invalid parameter has been - detected before any I/O operation was started. Use a more - specific fault code when you can. - -EIO - This rather vague error means something went wrong when - performing an I/O operation. Use a more specific fault - code when you can. - -ENODEV - Returned by driver probe() methods. This is a bit more - specific than ENXIO, implying the problem isn't with the - address, but with the device found there. Driver probes - may verify the device returns *correct* responses, and - return this as appropriate. (The driver core will warn - about probe faults other than ENXIO and ENODEV.) - -ENOMEM - Returned by any component that can't allocate memory when - it needs to do so. - -ENXIO - Returned by I2C adapters to indicate that the address phase - of a transfer didn't get an ACK. While it might just mean - an I2C device was temporarily not responding, usually it - means there's nothing listening at that address. - - Returned by driver probe() methods to indicate that they - found no device to bind to. (ENODEV may also be used.) - -EOPNOTSUPP - Returned by an adapter when asked to perform an operation - that it doesn't, or can't, support. - - For example, this would be returned when an adapter that - doesn't support SMBus block transfers is asked to execute - one. In that case, the driver making that request should - have verified that functionality was supported before it - made that block transfer request. - - Similarly, if an I2C adapter can't execute all legal I2C - messages, it should return this when asked to perform a - transaction it can't. (These limitations can't be seen in - the adapter's functionality mask, since the assumption is - that if an adapter supports I2C it supports all of I2C.) - -EPROTO - Returned when slave does not conform to the relevant I2C - or SMBus (or chip-specific) protocol specifications. One - case is when the length of an SMBus block data response - (from the SMBus slave) is outside the range 1-32 bytes. - -ESHUTDOWN - Returned when a transfer was requested using an adapter - which is already suspended. - -ETIMEDOUT - This is returned by drivers when an operation took too much - time, and was aborted before it completed. - - SMBus adapters may return it when an operation took more - time than allowed by the SMBus specification; for example, - when a slave stretches clocks too far. I2C has no such - timeouts, but it's normal for I2C adapters to impose some - arbitrary limits (much longer than SMBus!) too. - diff --git a/Documentation/i2c/fault-codes.rst b/Documentation/i2c/fault-codes.rst new file mode 100644 index 000000000000..80b14e718b52 --- /dev/null +++ b/Documentation/i2c/fault-codes.rst @@ -0,0 +1,131 @@ +===================== +I2C/SMBUS Fault Codes +===================== + +This is a summary of the most important conventions for use of fault +codes in the I2C/SMBus stack. + + +A "Fault" is not always an "Error" +---------------------------------- +Not all fault reports imply errors; "page faults" should be a familiar +example. Software often retries idempotent operations after transient +faults. There may be fancier recovery schemes that are appropriate in +some cases, such as re-initializing (and maybe resetting). After such +recovery, triggered by a fault report, there is no error. + +In a similar way, sometimes a "fault" code just reports one defined +result for an operation ... it doesn't indicate that anything is wrong +at all, just that the outcome wasn't on the "golden path". + +In short, your I2C driver code may need to know these codes in order +to respond correctly. Other code may need to rely on YOUR code reporting +the right fault code, so that it can (in turn) behave correctly. + + +I2C and SMBus fault codes +------------------------- +These are returned as negative numbers from most calls, with zero or +some positive number indicating a non-fault return. The specific +numbers associated with these symbols differ between architectures, +though most Linux systems use numbering. + +Note that the descriptions here are not exhaustive. There are other +codes that may be returned, and other cases where these codes should +be returned. However, drivers should not return other codes for these +cases (unless the hardware doesn't provide unique fault reports). + +Also, codes returned by adapter probe methods follow rules which are +specific to their host bus (such as PCI, or the platform bus). + + +EAGAIN + Returned by I2C adapters when they lose arbitration in master + transmit mode: some other master was transmitting different + data at the same time. + + Also returned when trying to invoke an I2C operation in an + atomic context, when some task is already using that I2C bus + to execute some other operation. + +EBADMSG + Returned by SMBus logic when an invalid Packet Error Code byte + is received. This code is a CRC covering all bytes in the + transaction, and is sent before the terminating STOP. This + fault is only reported on read transactions; the SMBus slave + may have a way to report PEC mismatches on writes from the + host. Note that even if PECs are in use, you should not rely + on these as the only way to detect incorrect data transfers. + +EBUSY + Returned by SMBus adapters when the bus was busy for longer + than allowed. This usually indicates some device (maybe the + SMBus adapter) needs some fault recovery (such as resetting), + or that the reset was attempted but failed. + +EINVAL + This rather vague error means an invalid parameter has been + detected before any I/O operation was started. Use a more + specific fault code when you can. + +EIO + This rather vague error means something went wrong when + performing an I/O operation. Use a more specific fault + code when you can. + +ENODEV + Returned by driver probe() methods. This is a bit more + specific than ENXIO, implying the problem isn't with the + address, but with the device found there. Driver probes + may verify the device returns *correct* responses, and + return this as appropriate. (The driver core will warn + about probe faults other than ENXIO and ENODEV.) + +ENOMEM + Returned by any component that can't allocate memory when + it needs to do so. + +ENXIO + Returned by I2C adapters to indicate that the address phase + of a transfer didn't get an ACK. While it might just mean + an I2C device was temporarily not responding, usually it + means there's nothing listening at that address. + + Returned by driver probe() methods to indicate that they + found no device to bind to. (ENODEV may also be used.) + +EOPNOTSUPP + Returned by an adapter when asked to perform an operation + that it doesn't, or can't, support. + + For example, this would be returned when an adapter that + doesn't support SMBus block transfers is asked to execute + one. In that case, the driver making that request should + have verified that functionality was supported before it + made that block transfer request. + + Similarly, if an I2C adapter can't execute all legal I2C + messages, it should return this when asked to perform a + transaction it can't. (These limitations can't be seen in + the adapter's functionality mask, since the assumption is + that if an adapter supports I2C it supports all of I2C.) + +EPROTO + Returned when slave does not conform to the relevant I2C + or SMBus (or chip-specific) protocol specifications. One + case is when the length of an SMBus block data response + (from the SMBus slave) is outside the range 1-32 bytes. + +ESHUTDOWN + Returned when a transfer was requested using an adapter + which is already suspended. + +ETIMEDOUT + This is returned by drivers when an operation took too much + time, and was aborted before it completed. + + SMBus adapters may return it when an operation took more + time than allowed by the SMBus specification; for example, + when a slave stretches clocks too far. I2C has no such + timeouts, but it's normal for I2C adapters to impose some + arbitrary limits (much longer than SMBus!) too. diff --git a/Documentation/i2c/functionality b/Documentation/i2c/functionality deleted file mode 100644 index 4aae8ed15873..000000000000 --- a/Documentation/i2c/functionality +++ /dev/null @@ -1,148 +0,0 @@ -INTRODUCTION ------------- - -Because not every I2C or SMBus adapter implements everything in the -I2C specifications, a client can not trust that everything it needs -is implemented when it is given the option to attach to an adapter: -the client needs some way to check whether an adapter has the needed -functionality. - - -FUNCTIONALITY CONSTANTS ------------------------ - -For the most up-to-date list of functionality constants, please check -! - - I2C_FUNC_I2C Plain i2c-level commands (Pure SMBus - adapters typically can not do these) - I2C_FUNC_10BIT_ADDR Handles the 10-bit address extensions - I2C_FUNC_PROTOCOL_MANGLING Knows about the I2C_M_IGNORE_NAK, - I2C_M_REV_DIR_ADDR and I2C_M_NO_RD_ACK - flags (which modify the I2C protocol!) - I2C_FUNC_NOSTART Can skip repeated start sequence - I2C_FUNC_SMBUS_QUICK Handles the SMBus write_quick command - I2C_FUNC_SMBUS_READ_BYTE Handles the SMBus read_byte command - I2C_FUNC_SMBUS_WRITE_BYTE Handles the SMBus write_byte command - I2C_FUNC_SMBUS_READ_BYTE_DATA Handles the SMBus read_byte_data command - I2C_FUNC_SMBUS_WRITE_BYTE_DATA Handles the SMBus write_byte_data command - I2C_FUNC_SMBUS_READ_WORD_DATA Handles the SMBus read_word_data command - I2C_FUNC_SMBUS_WRITE_WORD_DATA Handles the SMBus write_byte_data command - I2C_FUNC_SMBUS_PROC_CALL Handles the SMBus process_call command - I2C_FUNC_SMBUS_READ_BLOCK_DATA Handles the SMBus read_block_data command - I2C_FUNC_SMBUS_WRITE_BLOCK_DATA Handles the SMBus write_block_data command - I2C_FUNC_SMBUS_READ_I2C_BLOCK Handles the SMBus read_i2c_block_data command - I2C_FUNC_SMBUS_WRITE_I2C_BLOCK Handles the SMBus write_i2c_block_data command - -A few combinations of the above flags are also defined for your convenience: - - I2C_FUNC_SMBUS_BYTE Handles the SMBus read_byte - and write_byte commands - I2C_FUNC_SMBUS_BYTE_DATA Handles the SMBus read_byte_data - and write_byte_data commands - I2C_FUNC_SMBUS_WORD_DATA Handles the SMBus read_word_data - and write_word_data commands - I2C_FUNC_SMBUS_BLOCK_DATA Handles the SMBus read_block_data - and write_block_data commands - I2C_FUNC_SMBUS_I2C_BLOCK Handles the SMBus read_i2c_block_data - and write_i2c_block_data commands - I2C_FUNC_SMBUS_EMUL Handles all SMBus commands that can be - emulated by a real I2C adapter (using - the transparent emulation layer) - -In kernel versions prior to 3.5 I2C_FUNC_NOSTART was implemented as -part of I2C_FUNC_PROTOCOL_MANGLING. - - -ADAPTER IMPLEMENTATION ----------------------- - -When you write a new adapter driver, you will have to implement a -function callback `functionality'. Typical implementations are given -below. - -A typical SMBus-only adapter would list all the SMBus transactions it -supports. This example comes from the i2c-piix4 driver: - - static u32 piix4_func(struct i2c_adapter *adapter) - { - return I2C_FUNC_SMBUS_QUICK | I2C_FUNC_SMBUS_BYTE | - I2C_FUNC_SMBUS_BYTE_DATA | I2C_FUNC_SMBUS_WORD_DATA | - I2C_FUNC_SMBUS_BLOCK_DATA; - } - -A typical full-I2C adapter would use the following (from the i2c-pxa -driver): - - static u32 i2c_pxa_functionality(struct i2c_adapter *adap) - { - return I2C_FUNC_I2C | I2C_FUNC_SMBUS_EMUL; - } - -I2C_FUNC_SMBUS_EMUL includes all the SMBus transactions (with the -addition of I2C block transactions) which i2c-core can emulate using -I2C_FUNC_I2C without any help from the adapter driver. The idea is -to let the client drivers check for the support of SMBus functions -without having to care whether the said functions are implemented in -hardware by the adapter, or emulated in software by i2c-core on top -of an I2C adapter. - - -CLIENT CHECKING ---------------- - -Before a client tries to attach to an adapter, or even do tests to check -whether one of the devices it supports is present on an adapter, it should -check whether the needed functionality is present. The typical way to do -this is (from the lm75 driver): - - static int lm75_detect(...) - { - (...) - if (!i2c_check_functionality(adapter, I2C_FUNC_SMBUS_BYTE_DATA | - I2C_FUNC_SMBUS_WORD_DATA)) - goto exit; - (...) - } - -Here, the lm75 driver checks if the adapter can do both SMBus byte data -and SMBus word data transactions. If not, then the driver won't work on -this adapter and there's no point in going on. If the check above is -successful, then the driver knows that it can call the following -functions: i2c_smbus_read_byte_data(), i2c_smbus_write_byte_data(), -i2c_smbus_read_word_data() and i2c_smbus_write_word_data(). As a rule of -thumb, the functionality constants you test for with -i2c_check_functionality() should match exactly the i2c_smbus_* functions -which you driver is calling. - -Note that the check above doesn't tell whether the functionalities are -implemented in hardware by the underlying adapter or emulated in -software by i2c-core. Client drivers don't have to care about this, as -i2c-core will transparently implement SMBus transactions on top of I2C -adapters. - - -CHECKING THROUGH /DEV ---------------------- - -If you try to access an adapter from a userspace program, you will have -to use the /dev interface. You will still have to check whether the -functionality you need is supported, of course. This is done using -the I2C_FUNCS ioctl. An example, adapted from the i2cdetect program, is -below: - - int file; - if (file = open("/dev/i2c-0", O_RDWR) < 0) { - /* Some kind of error handling */ - exit(1); - } - if (ioctl(file, I2C_FUNCS, &funcs) < 0) { - /* Some kind of error handling */ - exit(1); - } - if (!(funcs & I2C_FUNC_SMBUS_QUICK)) { - /* Oops, the needed functionality (SMBus write_quick function) is - not available! */ - exit(1); - } - /* Now it is safe to use the SMBus write_quick command */ diff --git a/Documentation/i2c/functionality.rst b/Documentation/i2c/functionality.rst new file mode 100644 index 000000000000..377507c56162 --- /dev/null +++ b/Documentation/i2c/functionality.rst @@ -0,0 +1,156 @@ +======================= +I2C/SMBus Functionality +======================= + +INTRODUCTION +------------ + +Because not every I2C or SMBus adapter implements everything in the +I2C specifications, a client can not trust that everything it needs +is implemented when it is given the option to attach to an adapter: +the client needs some way to check whether an adapter has the needed +functionality. + + +FUNCTIONALITY CONSTANTS +----------------------- + +For the most up-to-date list of functionality constants, please check +! + + =============================== ============================================== + I2C_FUNC_I2C Plain i2c-level commands (Pure SMBus + adapters typically can not do these) + I2C_FUNC_10BIT_ADDR Handles the 10-bit address extensions + I2C_FUNC_PROTOCOL_MANGLING Knows about the I2C_M_IGNORE_NAK, + I2C_M_REV_DIR_ADDR and I2C_M_NO_RD_ACK + flags (which modify the I2C protocol!) + I2C_FUNC_NOSTART Can skip repeated start sequence + I2C_FUNC_SMBUS_QUICK Handles the SMBus write_quick command + I2C_FUNC_SMBUS_READ_BYTE Handles the SMBus read_byte command + I2C_FUNC_SMBUS_WRITE_BYTE Handles the SMBus write_byte command + I2C_FUNC_SMBUS_READ_BYTE_DATA Handles the SMBus read_byte_data command + I2C_FUNC_SMBUS_WRITE_BYTE_DATA Handles the SMBus write_byte_data command + I2C_FUNC_SMBUS_READ_WORD_DATA Handles the SMBus read_word_data command + I2C_FUNC_SMBUS_WRITE_WORD_DATA Handles the SMBus write_byte_data command + I2C_FUNC_SMBUS_PROC_CALL Handles the SMBus process_call command + I2C_FUNC_SMBUS_READ_BLOCK_DATA Handles the SMBus read_block_data command + I2C_FUNC_SMBUS_WRITE_BLOCK_DATA Handles the SMBus write_block_data command + I2C_FUNC_SMBUS_READ_I2C_BLOCK Handles the SMBus read_i2c_block_data command + I2C_FUNC_SMBUS_WRITE_I2C_BLOCK Handles the SMBus write_i2c_block_data command + =============================== ============================================== + +A few combinations of the above flags are also defined for your convenience: + + ========================= ====================================== + I2C_FUNC_SMBUS_BYTE Handles the SMBus read_byte + and write_byte commands + I2C_FUNC_SMBUS_BYTE_DATA Handles the SMBus read_byte_data + and write_byte_data commands + I2C_FUNC_SMBUS_WORD_DATA Handles the SMBus read_word_data + and write_word_data commands + I2C_FUNC_SMBUS_BLOCK_DATA Handles the SMBus read_block_data + and write_block_data commands + I2C_FUNC_SMBUS_I2C_BLOCK Handles the SMBus read_i2c_block_data + and write_i2c_block_data commands + I2C_FUNC_SMBUS_EMUL Handles all SMBus commands that can be + emulated by a real I2C adapter (using + the transparent emulation layer) + ========================= ====================================== + +In kernel versions prior to 3.5 I2C_FUNC_NOSTART was implemented as +part of I2C_FUNC_PROTOCOL_MANGLING. + + +ADAPTER IMPLEMENTATION +---------------------- + +When you write a new adapter driver, you will have to implement a +function callback ``functionality``. Typical implementations are given +below. + +A typical SMBus-only adapter would list all the SMBus transactions it +supports. This example comes from the i2c-piix4 driver:: + + static u32 piix4_func(struct i2c_adapter *adapter) + { + return I2C_FUNC_SMBUS_QUICK | I2C_FUNC_SMBUS_BYTE | + I2C_FUNC_SMBUS_BYTE_DATA | I2C_FUNC_SMBUS_WORD_DATA | + I2C_FUNC_SMBUS_BLOCK_DATA; + } + +A typical full-I2C adapter would use the following (from the i2c-pxa +driver):: + + static u32 i2c_pxa_functionality(struct i2c_adapter *adap) + { + return I2C_FUNC_I2C | I2C_FUNC_SMBUS_EMUL; + } + +I2C_FUNC_SMBUS_EMUL includes all the SMBus transactions (with the +addition of I2C block transactions) which i2c-core can emulate using +I2C_FUNC_I2C without any help from the adapter driver. The idea is +to let the client drivers check for the support of SMBus functions +without having to care whether the said functions are implemented in +hardware by the adapter, or emulated in software by i2c-core on top +of an I2C adapter. + + +CLIENT CHECKING +--------------- + +Before a client tries to attach to an adapter, or even do tests to check +whether one of the devices it supports is present on an adapter, it should +check whether the needed functionality is present. The typical way to do +this is (from the lm75 driver):: + + static int lm75_detect(...) + { + (...) + if (!i2c_check_functionality(adapter, I2C_FUNC_SMBUS_BYTE_DATA | + I2C_FUNC_SMBUS_WORD_DATA)) + goto exit; + (...) + } + +Here, the lm75 driver checks if the adapter can do both SMBus byte data +and SMBus word data transactions. If not, then the driver won't work on +this adapter and there's no point in going on. If the check above is +successful, then the driver knows that it can call the following +functions: i2c_smbus_read_byte_data(), i2c_smbus_write_byte_data(), +i2c_smbus_read_word_data() and i2c_smbus_write_word_data(). As a rule of +thumb, the functionality constants you test for with +i2c_check_functionality() should match exactly the i2c_smbus_* functions +which you driver is calling. + +Note that the check above doesn't tell whether the functionalities are +implemented in hardware by the underlying adapter or emulated in +software by i2c-core. Client drivers don't have to care about this, as +i2c-core will transparently implement SMBus transactions on top of I2C +adapters. + + +CHECKING THROUGH /DEV +--------------------- + +If you try to access an adapter from a userspace program, you will have +to use the /dev interface. You will still have to check whether the +functionality you need is supported, of course. This is done using +the I2C_FUNCS ioctl. An example, adapted from the i2cdetect program, is +below:: + + int file; + if (file = open("/dev/i2c-0", O_RDWR) < 0) { + /* Some kind of error handling */ + exit(1); + } + if (ioctl(file, I2C_FUNCS, &funcs) < 0) { + /* Some kind of error handling */ + exit(1); + } + if (!(funcs & I2C_FUNC_SMBUS_QUICK)) { + /* Oops, the needed functionality (SMBus write_quick function) is + not available! */ + exit(1); + } + /* Now it is safe to use the SMBus write_quick command */ diff --git a/Documentation/i2c/gpio-fault-injection b/Documentation/i2c/gpio-fault-injection deleted file mode 100644 index c87f416d53dd..000000000000 --- a/Documentation/i2c/gpio-fault-injection +++ /dev/null @@ -1,136 +0,0 @@ -========================= -Linux I2C fault injection -========================= - -The GPIO based I2C bus master driver can be configured to provide fault -injection capabilities. It is then meant to be connected to another I2C bus -which is driven by the I2C bus master driver under test. The GPIO fault -injection driver can create special states on the bus which the other I2C bus -master driver should handle gracefully. - -Once the Kconfig option I2C_GPIO_FAULT_INJECTOR is enabled, there will be an -'i2c-fault-injector' subdirectory in the Kernel debugfs filesystem, usually -mounted at /sys/kernel/debug. There will be a separate subdirectory per GPIO -driven I2C bus. Each subdirectory will contain files to trigger the fault -injection. They will be described now along with their intended use-cases. - -Wire states -=========== - -"scl" ------ - -By reading this file, you get the current state of SCL. By writing, you can -change its state to either force it low or to release it again. So, by using -"echo 0 > scl" you force SCL low and thus, no communication will be possible -because the bus master under test will not be able to clock. It should detect -the condition of SCL being unresponsive and report an error to the upper -layers. - -"sda" ------ - -By reading this file, you get the current state of SDA. By writing, you can -change its state to either force it low or to release it again. So, by using -"echo 0 > sda" you force SDA low and thus, data cannot be transmitted. The bus -master under test should detect this condition and trigger a bus recovery (see -I2C specification version 4, section 3.1.16) using the helpers of the Linux I2C -core (see 'struct bus_recovery_info'). However, the bus recovery will not -succeed because SDA is still pinned low until you manually release it again -with "echo 1 > sda". A test with an automatic release can be done with the -"incomplete transfers" class of fault injectors. - -Incomplete transfers -==================== - -The following fault injectors create situations where SDA will be held low by a -device. Bus recovery should be able to fix these situations. But please note: -there are I2C client devices which detect a stuck SDA on their side and release -it on their own after a few milliseconds. Also, there might be an external -device deglitching and monitoring the I2C bus. It could also detect a stuck SDA -and will init a bus recovery on its own. If you want to implement bus recovery -in a bus master driver, make sure you checked your hardware setup for such -devices before. And always verify with a scope or logic analyzer! - -"incomplete_address_phase" --------------------------- - -This file is write only and you need to write the address of an existing I2C -client device to it. Then, a read transfer to this device will be started, but -it will stop at the ACK phase after the address of the client has been -transmitted. Because the device will ACK its presence, this results in SDA -being pulled low by the device while SCL is high. So, similar to the "sda" file -above, the bus master under test should detect this condition and try a bus -recovery. This time, however, it should succeed and the device should release -SDA after toggling SCL. - -"incomplete_write_byte" ------------------------ - -Similar to above, this file is write only and you need to write the address of -an existing I2C client device to it. - -The injector will again stop at one ACK phase, so the device will keep SDA low -because it acknowledges data. However, there are two differences compared to -'incomplete_address_phase': - -a) the message sent out will be a write message -b) after the address byte, a 0x00 byte will be transferred. Then, stop at ACK. - -This is a highly delicate state, the device is set up to write any data to -register 0x00 (if it has registers) when further clock pulses happen on SCL. -This is why bus recovery (up to 9 clock pulses) must either check SDA or send -additional STOP conditions to ensure the bus has been released. Otherwise -random data will be written to a device! - -Lost arbitration -================ - -Here, we want to simulate the condition where the master under test loses the -bus arbitration against another master in a multi-master setup. - -"lose_arbitration" ------------------- - -This file is write only and you need to write the duration of the arbitration -intereference (in µs, maximum is 100ms). The calling process will then sleep -and wait for the next bus clock. The process is interruptible, though. - -Arbitration lost is achieved by waiting for SCL going down by the master under -test and then pulling SDA low for some time. So, the I2C address sent out -should be corrupted and that should be detected properly. That means that the -address sent out should have a lot of '1' bits to be able to detect corruption. -There doesn't need to be a device at this address because arbitration lost -should be detected beforehand. Also note, that SCL going down is monitored -using interrupts, so the interrupt latency might cause the first bits to be not -corrupted. A good starting point for using this fault injector on an otherwise -idle bus is: - -# echo 200 > lose_arbitration & -# i2cget -y 0x3f - -Panic during transfer -===================== - -This fault injector will create a Kernel panic once the master under test -started a transfer. This usually means that the state machine of the bus master -driver will be ungracefully interrupted and the bus may end up in an unusual -state. Use this to check if your shutdown/reboot/boot code can handle this -scenario. - -"inject_panic" --------------- - -This file is write only and you need to write the delay between the detected -start of a transmission and the induced Kernel panic (in µs, maximum is 100ms). -The calling process will then sleep and wait for the next bus clock. The -process is interruptible, though. - -Start of a transfer is detected by waiting for SCL going down by the master -under test. A good starting point for using this fault injector is: - -# echo 0 > inject_panic & -# i2cget -y - -Note that there doesn't need to be a device listening to the address you are -using. Results may vary depending on that, though. diff --git a/Documentation/i2c/gpio-fault-injection.rst b/Documentation/i2c/gpio-fault-injection.rst new file mode 100644 index 000000000000..9dca6ec7d266 --- /dev/null +++ b/Documentation/i2c/gpio-fault-injection.rst @@ -0,0 +1,136 @@ +========================= +Linux I2C fault injection +========================= + +The GPIO based I2C bus master driver can be configured to provide fault +injection capabilities. It is then meant to be connected to another I2C bus +which is driven by the I2C bus master driver under test. The GPIO fault +injection driver can create special states on the bus which the other I2C bus +master driver should handle gracefully. + +Once the Kconfig option I2C_GPIO_FAULT_INJECTOR is enabled, there will be an +'i2c-fault-injector' subdirectory in the Kernel debugfs filesystem, usually +mounted at /sys/kernel/debug. There will be a separate subdirectory per GPIO +driven I2C bus. Each subdirectory will contain files to trigger the fault +injection. They will be described now along with their intended use-cases. + +Wire states +=========== + +"scl" +----- + +By reading this file, you get the current state of SCL. By writing, you can +change its state to either force it low or to release it again. So, by using +"echo 0 > scl" you force SCL low and thus, no communication will be possible +because the bus master under test will not be able to clock. It should detect +the condition of SCL being unresponsive and report an error to the upper +layers. + +"sda" +----- + +By reading this file, you get the current state of SDA. By writing, you can +change its state to either force it low or to release it again. So, by using +"echo 0 > sda" you force SDA low and thus, data cannot be transmitted. The bus +master under test should detect this condition and trigger a bus recovery (see +I2C specification version 4, section 3.1.16) using the helpers of the Linux I2C +core (see 'struct bus_recovery_info'). However, the bus recovery will not +succeed because SDA is still pinned low until you manually release it again +with "echo 1 > sda". A test with an automatic release can be done with the +"incomplete transfers" class of fault injectors. + +Incomplete transfers +==================== + +The following fault injectors create situations where SDA will be held low by a +device. Bus recovery should be able to fix these situations. But please note: +there are I2C client devices which detect a stuck SDA on their side and release +it on their own after a few milliseconds. Also, there might be an external +device deglitching and monitoring the I2C bus. It could also detect a stuck SDA +and will init a bus recovery on its own. If you want to implement bus recovery +in a bus master driver, make sure you checked your hardware setup for such +devices before. And always verify with a scope or logic analyzer! + +"incomplete_address_phase" +-------------------------- + +This file is write only and you need to write the address of an existing I2C +client device to it. Then, a read transfer to this device will be started, but +it will stop at the ACK phase after the address of the client has been +transmitted. Because the device will ACK its presence, this results in SDA +being pulled low by the device while SCL is high. So, similar to the "sda" file +above, the bus master under test should detect this condition and try a bus +recovery. This time, however, it should succeed and the device should release +SDA after toggling SCL. + +"incomplete_write_byte" +----------------------- + +Similar to above, this file is write only and you need to write the address of +an existing I2C client device to it. + +The injector will again stop at one ACK phase, so the device will keep SDA low +because it acknowledges data. However, there are two differences compared to +'incomplete_address_phase': + +a) the message sent out will be a write message +b) after the address byte, a 0x00 byte will be transferred. Then, stop at ACK. + +This is a highly delicate state, the device is set up to write any data to +register 0x00 (if it has registers) when further clock pulses happen on SCL. +This is why bus recovery (up to 9 clock pulses) must either check SDA or send +additional STOP conditions to ensure the bus has been released. Otherwise +random data will be written to a device! + +Lost arbitration +================ + +Here, we want to simulate the condition where the master under test loses the +bus arbitration against another master in a multi-master setup. + +"lose_arbitration" +------------------ + +This file is write only and you need to write the duration of the arbitration +intereference (in µs, maximum is 100ms). The calling process will then sleep +and wait for the next bus clock. The process is interruptible, though. + +Arbitration lost is achieved by waiting for SCL going down by the master under +test and then pulling SDA low for some time. So, the I2C address sent out +should be corrupted and that should be detected properly. That means that the +address sent out should have a lot of '1' bits to be able to detect corruption. +There doesn't need to be a device at this address because arbitration lost +should be detected beforehand. Also note, that SCL going down is monitored +using interrupts, so the interrupt latency might cause the first bits to be not +corrupted. A good starting point for using this fault injector on an otherwise +idle bus is:: + + # echo 200 > lose_arbitration & + # i2cget -y 0x3f + +Panic during transfer +===================== + +This fault injector will create a Kernel panic once the master under test +started a transfer. This usually means that the state machine of the bus master +driver will be ungracefully interrupted and the bus may end up in an unusual +state. Use this to check if your shutdown/reboot/boot code can handle this +scenario. + +"inject_panic" +-------------- + +This file is write only and you need to write the delay between the detected +start of a transmission and the induced Kernel panic (in µs, maximum is 100ms). +The calling process will then sleep and wait for the next bus clock. The +process is interruptible, though. + +Start of a transfer is detected by waiting for SCL going down by the master +under test. A good starting point for using this fault injector is:: + + # echo 0 > inject_panic & + # i2cget -y + +Note that there doesn't need to be a device listening to the address you are +using. Results may vary depending on that, though. diff --git a/Documentation/i2c/i2c-protocol b/Documentation/i2c/i2c-protocol deleted file mode 100644 index ff6d6cee6c7e..000000000000 --- a/Documentation/i2c/i2c-protocol +++ /dev/null @@ -1,88 +0,0 @@ -This document describes the i2c protocol. Or will, when it is finished :-) - -Key to symbols -============== - -S (1 bit) : Start bit -P (1 bit) : Stop bit -Rd/Wr (1 bit) : Read/Write bit. Rd equals 1, Wr equals 0. -A, NA (1 bit) : Accept and reverse accept bit. -Addr (7 bits): I2C 7 bit address. Note that this can be expanded as usual to - get a 10 bit I2C address. -Comm (8 bits): Command byte, a data byte which often selects a register on - the device. -Data (8 bits): A plain data byte. Sometimes, I write DataLow, DataHigh - for 16 bit data. -Count (8 bits): A data byte containing the length of a block operation. - -[..]: Data sent by I2C device, as opposed to data sent by the host adapter. - - -Simple send transaction -====================== - -This corresponds to i2c_master_send. - - S Addr Wr [A] Data [A] Data [A] ... [A] Data [A] P - - -Simple receive transaction -=========================== - -This corresponds to i2c_master_recv - - S Addr Rd [A] [Data] A [Data] A ... A [Data] NA P - - -Combined transactions -==================== - -This corresponds to i2c_transfer - -They are just like the above transactions, but instead of a stop bit P -a start bit S is sent and the transaction continues. An example of -a byte read, followed by a byte write: - - S Addr Rd [A] [Data] NA S Addr Wr [A] Data [A] P - - -Modified transactions -===================== - -The following modifications to the I2C protocol can also be generated by -setting these flags for i2c messages. With the exception of I2C_M_NOSTART, they -are usually only needed to work around device issues: - -I2C_M_IGNORE_NAK: - Normally message is interrupted immediately if there is [NA] from the - client. Setting this flag treats any [NA] as [A], and all of - message is sent. - These messages may still fail to SCL lo->hi timeout. - -I2C_M_NO_RD_ACK: - In a read message, master A/NA bit is skipped. - -I2C_M_NOSTART: - In a combined transaction, no 'S Addr Wr/Rd [A]' is generated at some - point. For example, setting I2C_M_NOSTART on the second partial message - generates something like: - S Addr Rd [A] [Data] NA Data [A] P - If you set the I2C_M_NOSTART variable for the first partial message, - we do not generate Addr, but we do generate the startbit S. This will - probably confuse all other clients on your bus, so don't try this. - - This is often used to gather transmits from multiple data buffers in - system memory into something that appears as a single transfer to the - I2C device but may also be used between direction changes by some - rare devices. - -I2C_M_REV_DIR_ADDR: - This toggles the Rd/Wr flag. That is, if you want to do a write, but - need to emit an Rd instead of a Wr, or vice versa, you set this - flag. For example: - S Addr Rd [A] Data [A] Data [A] ... [A] Data [A] P - -I2C_M_STOP: - Force a stop condition (P) after the message. Some I2C related protocols - like SCCB require that. Normally, you really don't want to get interrupted - between the messages of one transfer. diff --git a/Documentation/i2c/i2c-protocol.rst b/Documentation/i2c/i2c-protocol.rst new file mode 100644 index 000000000000..2f8fcf671b2e --- /dev/null +++ b/Documentation/i2c/i2c-protocol.rst @@ -0,0 +1,98 @@ +============ +I2C Protocol +============ + +This document describes the i2c protocol. Or will, when it is finished :-) + +Key to symbols +============== + +=============== ============================================================= +S (1 bit) : Start bit +P (1 bit) : Stop bit +Rd/Wr (1 bit) : Read/Write bit. Rd equals 1, Wr equals 0. +A, NA (1 bit) : Accept and reverse accept bit. +Addr (7 bits): I2C 7 bit address. Note that this can be expanded as usual to + get a 10 bit I2C address. +Comm (8 bits): Command byte, a data byte which often selects a register on + the device. +Data (8 bits): A plain data byte. Sometimes, I write DataLow, DataHigh + for 16 bit data. +Count (8 bits): A data byte containing the length of a block operation. + +[..]: Data sent by I2C device, as opposed to data sent by the + host adapter. +=============== ============================================================= + + +Simple send transaction +======================= + +This corresponds to i2c_master_send:: + + S Addr Wr [A] Data [A] Data [A] ... [A] Data [A] P + + +Simple receive transaction +========================== + +This corresponds to i2c_master_recv:: + + S Addr Rd [A] [Data] A [Data] A ... A [Data] NA P + + +Combined transactions +===================== + +This corresponds to i2c_transfer + +They are just like the above transactions, but instead of a stop bit P +a start bit S is sent and the transaction continues. An example of +a byte read, followed by a byte write:: + + S Addr Rd [A] [Data] NA S Addr Wr [A] Data [A] P + + +Modified transactions +===================== + +The following modifications to the I2C protocol can also be generated by +setting these flags for i2c messages. With the exception of I2C_M_NOSTART, they +are usually only needed to work around device issues: + +I2C_M_IGNORE_NAK: + Normally message is interrupted immediately if there is [NA] from the + client. Setting this flag treats any [NA] as [A], and all of + message is sent. + These messages may still fail to SCL lo->hi timeout. + +I2C_M_NO_RD_ACK: + In a read message, master A/NA bit is skipped. + +I2C_M_NOSTART: + In a combined transaction, no 'S Addr Wr/Rd [A]' is generated at some + point. For example, setting I2C_M_NOSTART on the second partial message + generates something like:: + + S Addr Rd [A] [Data] NA Data [A] P + + If you set the I2C_M_NOSTART variable for the first partial message, + we do not generate Addr, but we do generate the startbit S. This will + probably confuse all other clients on your bus, so don't try this. + + This is often used to gather transmits from multiple data buffers in + system memory into something that appears as a single transfer to the + I2C device but may also be used between direction changes by some + rare devices. + +I2C_M_REV_DIR_ADDR: + This toggles the Rd/Wr flag. That is, if you want to do a write, but + need to emit an Rd instead of a Wr, or vice versa, you set this + flag. For example:: + + S Addr Rd [A] Data [A] Data [A] ... [A] Data [A] P + +I2C_M_STOP: + Force a stop condition (P) after the message. Some I2C related protocols + like SCCB require that. Normally, you really don't want to get interrupted + between the messages of one transfer. diff --git a/Documentation/i2c/i2c-stub b/Documentation/i2c/i2c-stub deleted file mode 100644 index a16924fbd289..000000000000 --- a/Documentation/i2c/i2c-stub +++ /dev/null @@ -1,64 +0,0 @@ -MODULE: i2c-stub - -DESCRIPTION: - -This module is a very simple fake I2C/SMBus driver. It implements six -types of SMBus commands: write quick, (r/w) byte, (r/w) byte data, (r/w) -word data, (r/w) I2C block data, and (r/w) SMBus block data. - -You need to provide chip addresses as a module parameter when loading this -driver, which will then only react to SMBus commands to these addresses. - -No hardware is needed nor associated with this module. It will accept write -quick commands to the specified addresses; it will respond to the other -commands (also to the specified addresses) by reading from or writing to -arrays in memory. It will also spam the kernel logs for every command it -handles. - -A pointer register with auto-increment is implemented for all byte -operations. This allows for continuous byte reads like those supported by -EEPROMs, among others. - -SMBus block command support is disabled by default, and must be enabled -explicitly by setting the respective bits (0x03000000) in the functionality -module parameter. - -SMBus block commands must be written to configure an SMBus command for -SMBus block operations. Writes can be partial. Block read commands always -return the number of bytes selected with the largest write so far. - -The typical use-case is like this: - 1. load this module - 2. use i2cset (from the i2c-tools project) to pre-load some data - 3. load the target chip driver module - 4. observe its behavior in the kernel log - -There's a script named i2c-stub-from-dump in the i2c-tools package which -can load register values automatically from a chip dump. - -PARAMETERS: - -int chip_addr[10]: - The SMBus addresses to emulate chips at. - -unsigned long functionality: - Functionality override, to disable some commands. See I2C_FUNC_* - constants in for the suitable values. For example, - value 0x1f0000 would only enable the quick, byte and byte data - commands. - -u8 bank_reg[10] -u8 bank_mask[10] -u8 bank_start[10] -u8 bank_end[10]: - Optional bank settings. They tell which bits in which register - select the active bank, as well as the range of banked registers. - -CAVEATS: - -If your target driver polls some byte or word waiting for it to change, the -stub could lock it up. Use i2cset to unlock it. - -If you spam it hard enough, printk can be lossy. This module really wants -something like relayfs. - diff --git a/Documentation/i2c/i2c-stub.rst b/Documentation/i2c/i2c-stub.rst new file mode 100644 index 000000000000..a6fc6916d6bc --- /dev/null +++ b/Documentation/i2c/i2c-stub.rst @@ -0,0 +1,66 @@ +======== +i2c-stub +======== + +Description +=========== + +This module is a very simple fake I2C/SMBus driver. It implements six +types of SMBus commands: write quick, (r/w) byte, (r/w) byte data, (r/w) +word data, (r/w) I2C block data, and (r/w) SMBus block data. + +You need to provide chip addresses as a module parameter when loading this +driver, which will then only react to SMBus commands to these addresses. + +No hardware is needed nor associated with this module. It will accept write +quick commands to the specified addresses; it will respond to the other +commands (also to the specified addresses) by reading from or writing to +arrays in memory. It will also spam the kernel logs for every command it +handles. + +A pointer register with auto-increment is implemented for all byte +operations. This allows for continuous byte reads like those supported by +EEPROMs, among others. + +SMBus block command support is disabled by default, and must be enabled +explicitly by setting the respective bits (0x03000000) in the functionality +module parameter. + +SMBus block commands must be written to configure an SMBus command for +SMBus block operations. Writes can be partial. Block read commands always +return the number of bytes selected with the largest write so far. + +The typical use-case is like this: + + 1. load this module + 2. use i2cset (from the i2c-tools project) to pre-load some data + 3. load the target chip driver module + 4. observe its behavior in the kernel log + +There's a script named i2c-stub-from-dump in the i2c-tools package which +can load register values automatically from a chip dump. + +Parameters +========== + +int chip_addr[10]: + The SMBus addresses to emulate chips at. + +unsigned long functionality: + Functionality override, to disable some commands. See I2C_FUNC_* + constants in for the suitable values. For example, + value 0x1f0000 would only enable the quick, byte and byte data + commands. + +u8 bank_reg[10], u8 bank_mask[10], u8 bank_start[10], u8 bank_end[10]: + Optional bank settings. They tell which bits in which register + select the active bank, as well as the range of banked registers. + +Caveats +======= + +If your target driver polls some byte or word waiting for it to change, the +stub could lock it up. Use i2cset to unlock it. + +If you spam it hard enough, printk can be lossy. This module really wants +something like relayfs. diff --git a/Documentation/i2c/i2c-topology b/Documentation/i2c/i2c-topology deleted file mode 100644 index f74d78b53d4d..000000000000 --- a/Documentation/i2c/i2c-topology +++ /dev/null @@ -1,376 +0,0 @@ -I2C topology -============ - -There are a couple of reasons for building more complex i2c topologies -than a straight-forward i2c bus with one adapter and one or more devices. - -1. A mux may be needed on the bus to prevent address collisions. - -2. The bus may be accessible from some external bus master, and arbitration - may be needed to determine if it is ok to access the bus. - -3. A device (particularly RF tuners) may want to avoid the digital noise - from the i2c bus, at least most of the time, and sits behind a gate - that has to be operated before the device can be accessed. - -Etc - -These constructs are represented as i2c adapter trees by Linux, where -each adapter has a parent adapter (except the root adapter) and zero or -more child adapters. The root adapter is the actual adapter that issues -i2c transfers, and all adapters with a parent are part of an "i2c-mux" -object (quoted, since it can also be an arbitrator or a gate). - -Depending of the particular mux driver, something happens when there is -an i2c transfer on one of its child adapters. The mux driver can -obviously operate a mux, but it can also do arbitration with an external -bus master or open a gate. The mux driver has two operations for this, -select and deselect. select is called before the transfer and (the -optional) deselect is called after the transfer. - - -Locking -======= - -There are two variants of locking available to i2c muxes, they can be -mux-locked or parent-locked muxes. As is evident from below, it can be -useful to know if a mux is mux-locked or if it is parent-locked. The -following list was correct at the time of writing: - -In drivers/i2c/muxes/ -i2c-arb-gpio-challenge Parent-locked -i2c-mux-gpio Normally parent-locked, mux-locked iff - all involved gpio pins are controlled by the - same i2c root adapter that they mux. -i2c-mux-gpmux Normally parent-locked, mux-locked iff - specified in device-tree. -i2c-mux-ltc4306 Mux-locked -i2c-mux-mlxcpld Parent-locked -i2c-mux-pca9541 Parent-locked -i2c-mux-pca954x Parent-locked -i2c-mux-pinctrl Normally parent-locked, mux-locked iff - all involved pinctrl devices are controlled - by the same i2c root adapter that they mux. -i2c-mux-reg Parent-locked - -In drivers/iio/ -gyro/mpu3050 Mux-locked -imu/inv_mpu6050/ Mux-locked - -In drivers/media/ -dvb-frontends/lgdt3306a Mux-locked -dvb-frontends/m88ds3103 Parent-locked -dvb-frontends/rtl2830 Parent-locked -dvb-frontends/rtl2832 Mux-locked -dvb-frontends/si2168 Mux-locked -usb/cx231xx/ Parent-locked - - -Mux-locked muxes ----------------- - -Mux-locked muxes does not lock the entire parent adapter during the -full select-transfer-deselect transaction, only the muxes on the parent -adapter are locked. Mux-locked muxes are mostly interesting if the -select and/or deselect operations must use i2c transfers to complete -their tasks. Since the parent adapter is not fully locked during the -full transaction, unrelated i2c transfers may interleave the different -stages of the transaction. This has the benefit that the mux driver -may be easier and cleaner to implement, but it has some caveats. - -ML1. If you build a topology with a mux-locked mux being the parent - of a parent-locked mux, this might break the expectation from the - parent-locked mux that the root adapter is locked during the - transaction. - -ML2. It is not safe to build arbitrary topologies with two (or more) - mux-locked muxes that are not siblings, when there are address - collisions between the devices on the child adapters of these - non-sibling muxes. - - I.e. the select-transfer-deselect transaction targeting e.g. device - address 0x42 behind mux-one may be interleaved with a similar - operation targeting device address 0x42 behind mux-two. The - intension with such a topology would in this hypothetical example - be that mux-one and mux-two should not be selected simultaneously, - but mux-locked muxes do not guarantee that in all topologies. - -ML3. A mux-locked mux cannot be used by a driver for auto-closing - gates/muxes, i.e. something that closes automatically after a given - number (one, in most cases) of i2c transfers. Unrelated i2c transfers - may creep in and close prematurely. - -ML4. If any non-i2c operation in the mux driver changes the i2c mux state, - the driver has to lock the root adapter during that operation. - Otherwise garbage may appear on the bus as seen from devices - behind the mux, when an unrelated i2c transfer is in flight during - the non-i2c mux-changing operation. - - -Mux-locked Example ------------------- - - .----------. .--------. - .--------. | mux- |-----| dev D1 | - | root |--+--| locked | '--------' - '--------' | | mux M1 |--. .--------. - | '----------' '--| dev D2 | - | .--------. '--------' - '--| dev D3 | - '--------' - -When there is an access to D1, this happens: - - 1. Someone issues an i2c-transfer to D1. - 2. M1 locks muxes on its parent (the root adapter in this case). - 3. M1 calls ->select to ready the mux. - 4. M1 (presumably) does some i2c-transfers as part of its select. - These transfers are normal i2c-transfers that locks the parent - adapter. - 5. M1 feeds the i2c-transfer from step 1 to its parent adapter as a - normal i2c-transfer that locks the parent adapter. - 6. M1 calls ->deselect, if it has one. - 7. Same rules as in step 4, but for ->deselect. - 8. M1 unlocks muxes on its parent. - -This means that accesses to D2 are lockout out for the full duration -of the entire operation. But accesses to D3 are possibly interleaved -at any point. - - -Parent-locked muxes -------------------- - -Parent-locked muxes lock the parent adapter during the full select- -transfer-deselect transaction. The implication is that the mux driver -has to ensure that any and all i2c transfers through that parent -adapter during the transaction are unlocked i2c transfers (using e.g. -__i2c_transfer), or a deadlock will follow. There are a couple of -caveats. - -PL1. If you build a topology with a parent-locked mux being the child - of another mux, this might break a possible assumption from the - child mux that the root adapter is unused between its select op - and the actual transfer (e.g. if the child mux is auto-closing - and the parent mux issus i2c-transfers as part of its select). - This is especially the case if the parent mux is mux-locked, but - it may also happen if the parent mux is parent-locked. - -PL2. If select/deselect calls out to other subsystems such as gpio, - pinctrl, regmap or iio, it is essential that any i2c transfers - caused by these subsystems are unlocked. This can be convoluted to - accomplish, maybe even impossible if an acceptably clean solution - is sought. - - -Parent-locked Example ---------------------- - - .----------. .--------. - .--------. | parent- |-----| dev D1 | - | root |--+--| locked | '--------' - '--------' | | mux M1 |--. .--------. - | '----------' '--| dev D2 | - | .--------. '--------' - '--| dev D3 | - '--------' - -When there is an access to D1, this happens: - - 1. Someone issues an i2c-transfer to D1. - 2. M1 locks muxes on its parent (the root adapter in this case). - 3. M1 locks its parent adapter. - 4. M1 calls ->select to ready the mux. - 5. If M1 does any i2c-transfers (on this root adapter) as part of - its select, those transfers must be unlocked i2c-transfers so - that they do not deadlock the root adapter. - 6. M1 feeds the i2c-transfer from step 1 to the root adapter as an - unlocked i2c-transfer, so that it does not deadlock the parent - adapter. - 7. M1 calls ->deselect, if it has one. - 8. Same rules as in step 5, but for ->deselect. - 9. M1 unlocks its parent adapter. -10. M1 unlocks muxes on its parent. - - -This means that accesses to both D2 and D3 are locked out for the full -duration of the entire operation. - - -Complex Examples -================ - -Parent-locked mux as parent of parent-locked mux ------------------------------------------------- - -This is a useful topology, but it can be bad. - - .----------. .----------. .--------. - .--------. | parent- |-----| parent- |-----| dev D1 | - | root |--+--| locked | | locked | '--------' - '--------' | | mux M1 |--. | mux M2 |--. .--------. - | '----------' | '----------' '--| dev D2 | - | .--------. | .--------. '--------' - '--| dev D4 | '--| dev D3 | - '--------' '--------' - -When any device is accessed, all other devices are locked out for -the full duration of the operation (both muxes lock their parent, -and specifically when M2 requests its parent to lock, M1 passes -the buck to the root adapter). - -This topology is bad if M2 is an auto-closing mux and M1->select -issues any unlocked i2c transfers on the root adapter that may leak -through and be seen by the M2 adapter, thus closing M2 prematurely. - - -Mux-locked mux as parent of mux-locked mux ------------------------------------------- - -This is a good topology. - - .----------. .----------. .--------. - .--------. | mux- |-----| mux- |-----| dev D1 | - | root |--+--| locked | | locked | '--------' - '--------' | | mux M1 |--. | mux M2 |--. .--------. - | '----------' | '----------' '--| dev D2 | - | .--------. | .--------. '--------' - '--| dev D4 | '--| dev D3 | - '--------' '--------' - -When device D1 is accessed, accesses to D2 are locked out for the -full duration of the operation (muxes on the top child adapter of M1 -are locked). But accesses to D3 and D4 are possibly interleaved at -any point. Accesses to D3 locks out D1 and D2, but accesses to D4 -are still possibly interleaved. - - -Mux-locked mux as parent of parent-locked mux ---------------------------------------------- - -This is probably a bad topology. - - .----------. .----------. .--------. - .--------. | mux- |-----| parent- |-----| dev D1 | - | root |--+--| locked | | locked | '--------' - '--------' | | mux M1 |--. | mux M2 |--. .--------. - | '----------' | '----------' '--| dev D2 | - | .--------. | .--------. '--------' - '--| dev D4 | '--| dev D3 | - '--------' '--------' - -When device D1 is accessed, accesses to D2 and D3 are locked out -for the full duration of the operation (M1 locks child muxes on the -root adapter). But accesses to D4 are possibly interleaved at any -point. - -This kind of topology is generally not suitable and should probably -be avoided. The reason is that M2 probably assumes that there will -be no i2c transfers during its calls to ->select and ->deselect, and -if there are, any such transfers might appear on the slave side of M2 -as partial i2c transfers, i.e. garbage or worse. This might cause -device lockups and/or other problems. - -The topology is especially troublesome if M2 is an auto-closing -mux. In that case, any interleaved accesses to D4 might close M2 -prematurely, as might any i2c-transfers part of M1->select. - -But if M2 is not making the above stated assumption, and if M2 is not -auto-closing, the topology is fine. - - -Parent-locked mux as parent of mux-locked mux ---------------------------------------------- - -This is a good topology. - - .----------. .----------. .--------. - .--------. | parent- |-----| mux- |-----| dev D1 | - | root |--+--| locked | | locked | '--------' - '--------' | | mux M1 |--. | mux M2 |--. .--------. - | '----------' | '----------' '--| dev D2 | - | .--------. | .--------. '--------' - '--| dev D4 | '--| dev D3 | - '--------' '--------' - -When D1 is accessed, accesses to D2 are locked out for the full -duration of the operation (muxes on the top child adapter of M1 -are locked). Accesses to D3 and D4 are possibly interleaved at -any point, just as is expected for mux-locked muxes. - -When D3 or D4 are accessed, everything else is locked out. For D3 -accesses, M1 locks the root adapter. For D4 accesses, the root -adapter is locked directly. - - -Two mux-locked sibling muxes ----------------------------- - -This is a good topology. - - .--------. - .----------. .--| dev D1 | - | mux- |--' '--------' - .--| locked | .--------. - | | mux M1 |-----| dev D2 | - | '----------' '--------' - | .----------. .--------. - .--------. | | mux- |-----| dev D3 | - | root |--+--| locked | '--------' - '--------' | | mux M2 |--. .--------. - | '----------' '--| dev D4 | - | .--------. '--------' - '--| dev D5 | - '--------' - -When D1 is accessed, accesses to D2, D3 and D4 are locked out. But -accesses to D5 may be interleaved at any time. - - -Two parent-locked sibling muxes -------------------------------- - -This is a good topology. - - .--------. - .----------. .--| dev D1 | - | parent- |--' '--------' - .--| locked | .--------. - | | mux M1 |-----| dev D2 | - | '----------' '--------' - | .----------. .--------. - .--------. | | parent- |-----| dev D3 | - | root |--+--| locked | '--------' - '--------' | | mux M2 |--. .--------. - | '----------' '--| dev D4 | - | .--------. '--------' - '--| dev D5 | - '--------' - -When any device is accessed, accesses to all other devices are locked -out. - - -Mux-locked and parent-locked sibling muxes ------------------------------------------- - -This is a good topology. - - .--------. - .----------. .--| dev D1 | - | mux- |--' '--------' - .--| locked | .--------. - | | mux M1 |-----| dev D2 | - | '----------' '--------' - | .----------. .--------. - .--------. | | parent- |-----| dev D3 | - | root |--+--| locked | '--------' - '--------' | | mux M2 |--. .--------. - | '----------' '--| dev D4 | - | .--------. '--------' - '--| dev D5 | - '--------' - -When D1 or D2 are accessed, accesses to D3 and D4 are locked out while -accesses to D5 may interleave. When D3 or D4 are accessed, accesses to -all other devices are locked out. diff --git a/Documentation/i2c/i2c-topology.rst b/Documentation/i2c/i2c-topology.rst new file mode 100644 index 000000000000..0c1ae95f6a97 --- /dev/null +++ b/Documentation/i2c/i2c-topology.rst @@ -0,0 +1,396 @@ +============ +I2C topology +============ + +There are a couple of reasons for building more complex i2c topologies +than a straight-forward i2c bus with one adapter and one or more devices. + +1. A mux may be needed on the bus to prevent address collisions. + +2. The bus may be accessible from some external bus master, and arbitration + may be needed to determine if it is ok to access the bus. + +3. A device (particularly RF tuners) may want to avoid the digital noise + from the i2c bus, at least most of the time, and sits behind a gate + that has to be operated before the device can be accessed. + +Etc +=== + +These constructs are represented as i2c adapter trees by Linux, where +each adapter has a parent adapter (except the root adapter) and zero or +more child adapters. The root adapter is the actual adapter that issues +i2c transfers, and all adapters with a parent are part of an "i2c-mux" +object (quoted, since it can also be an arbitrator or a gate). + +Depending of the particular mux driver, something happens when there is +an i2c transfer on one of its child adapters. The mux driver can +obviously operate a mux, but it can also do arbitration with an external +bus master or open a gate. The mux driver has two operations for this, +select and deselect. select is called before the transfer and (the +optional) deselect is called after the transfer. + + +Locking +======= + +There are two variants of locking available to i2c muxes, they can be +mux-locked or parent-locked muxes. As is evident from below, it can be +useful to know if a mux is mux-locked or if it is parent-locked. The +following list was correct at the time of writing: + +In drivers/i2c/muxes/: + +====================== ============================================= +i2c-arb-gpio-challenge Parent-locked +i2c-mux-gpio Normally parent-locked, mux-locked iff + all involved gpio pins are controlled by the + same i2c root adapter that they mux. +i2c-mux-gpmux Normally parent-locked, mux-locked iff + specified in device-tree. +i2c-mux-ltc4306 Mux-locked +i2c-mux-mlxcpld Parent-locked +i2c-mux-pca9541 Parent-locked +i2c-mux-pca954x Parent-locked +i2c-mux-pinctrl Normally parent-locked, mux-locked iff + all involved pinctrl devices are controlled + by the same i2c root adapter that they mux. +i2c-mux-reg Parent-locked +====================== ============================================= + +In drivers/iio/: + +====================== ============================================= +gyro/mpu3050 Mux-locked +imu/inv_mpu6050/ Mux-locked +====================== ============================================= + +In drivers/media/: + +======================= ============================================= +dvb-frontends/lgdt3306a Mux-locked +dvb-frontends/m88ds3103 Parent-locked +dvb-frontends/rtl2830 Parent-locked +dvb-frontends/rtl2832 Mux-locked +dvb-frontends/si2168 Mux-locked +usb/cx231xx/ Parent-locked +======================= ============================================= + + +Mux-locked muxes +---------------- + +Mux-locked muxes does not lock the entire parent adapter during the +full select-transfer-deselect transaction, only the muxes on the parent +adapter are locked. Mux-locked muxes are mostly interesting if the +select and/or deselect operations must use i2c transfers to complete +their tasks. Since the parent adapter is not fully locked during the +full transaction, unrelated i2c transfers may interleave the different +stages of the transaction. This has the benefit that the mux driver +may be easier and cleaner to implement, but it has some caveats. + +==== ===================================================================== +ML1. If you build a topology with a mux-locked mux being the parent + of a parent-locked mux, this might break the expectation from the + parent-locked mux that the root adapter is locked during the + transaction. + +ML2. It is not safe to build arbitrary topologies with two (or more) + mux-locked muxes that are not siblings, when there are address + collisions between the devices on the child adapters of these + non-sibling muxes. + + I.e. the select-transfer-deselect transaction targeting e.g. device + address 0x42 behind mux-one may be interleaved with a similar + operation targeting device address 0x42 behind mux-two. The + intension with such a topology would in this hypothetical example + be that mux-one and mux-two should not be selected simultaneously, + but mux-locked muxes do not guarantee that in all topologies. + +ML3. A mux-locked mux cannot be used by a driver for auto-closing + gates/muxes, i.e. something that closes automatically after a given + number (one, in most cases) of i2c transfers. Unrelated i2c transfers + may creep in and close prematurely. + +ML4. If any non-i2c operation in the mux driver changes the i2c mux state, + the driver has to lock the root adapter during that operation. + Otherwise garbage may appear on the bus as seen from devices + behind the mux, when an unrelated i2c transfer is in flight during + the non-i2c mux-changing operation. +==== ===================================================================== + + +Mux-locked Example +------------------ + + +:: + + .----------. .--------. + .--------. | mux- |-----| dev D1 | + | root |--+--| locked | '--------' + '--------' | | mux M1 |--. .--------. + | '----------' '--| dev D2 | + | .--------. '--------' + '--| dev D3 | + '--------' + +When there is an access to D1, this happens: + + 1. Someone issues an i2c-transfer to D1. + 2. M1 locks muxes on its parent (the root adapter in this case). + 3. M1 calls ->select to ready the mux. + 4. M1 (presumably) does some i2c-transfers as part of its select. + These transfers are normal i2c-transfers that locks the parent + adapter. + 5. M1 feeds the i2c-transfer from step 1 to its parent adapter as a + normal i2c-transfer that locks the parent adapter. + 6. M1 calls ->deselect, if it has one. + 7. Same rules as in step 4, but for ->deselect. + 8. M1 unlocks muxes on its parent. + +This means that accesses to D2 are lockout out for the full duration +of the entire operation. But accesses to D3 are possibly interleaved +at any point. + + +Parent-locked muxes +------------------- + +Parent-locked muxes lock the parent adapter during the full select- +transfer-deselect transaction. The implication is that the mux driver +has to ensure that any and all i2c transfers through that parent +adapter during the transaction are unlocked i2c transfers (using e.g. +__i2c_transfer), or a deadlock will follow. There are a couple of +caveats. + +==== ==================================================================== +PL1. If you build a topology with a parent-locked mux being the child + of another mux, this might break a possible assumption from the + child mux that the root adapter is unused between its select op + and the actual transfer (e.g. if the child mux is auto-closing + and the parent mux issus i2c-transfers as part of its select). + This is especially the case if the parent mux is mux-locked, but + it may also happen if the parent mux is parent-locked. + +PL2. If select/deselect calls out to other subsystems such as gpio, + pinctrl, regmap or iio, it is essential that any i2c transfers + caused by these subsystems are unlocked. This can be convoluted to + accomplish, maybe even impossible if an acceptably clean solution + is sought. +==== ==================================================================== + + +Parent-locked Example +--------------------- + +:: + + .----------. .--------. + .--------. | parent- |-----| dev D1 | + | root |--+--| locked | '--------' + '--------' | | mux M1 |--. .--------. + | '----------' '--| dev D2 | + | .--------. '--------' + '--| dev D3 | + '--------' + +When there is an access to D1, this happens: + + 1. Someone issues an i2c-transfer to D1. + 2. M1 locks muxes on its parent (the root adapter in this case). + 3. M1 locks its parent adapter. + 4. M1 calls ->select to ready the mux. + 5. If M1 does any i2c-transfers (on this root adapter) as part of + its select, those transfers must be unlocked i2c-transfers so + that they do not deadlock the root adapter. + 6. M1 feeds the i2c-transfer from step 1 to the root adapter as an + unlocked i2c-transfer, so that it does not deadlock the parent + adapter. + 7. M1 calls ->deselect, if it has one. + 8. Same rules as in step 5, but for ->deselect. + 9. M1 unlocks its parent adapter. + 10. M1 unlocks muxes on its parent. + + +This means that accesses to both D2 and D3 are locked out for the full +duration of the entire operation. + + +Complex Examples +================ + +Parent-locked mux as parent of parent-locked mux +------------------------------------------------ + +This is a useful topology, but it can be bad:: + + .----------. .----------. .--------. + .--------. | parent- |-----| parent- |-----| dev D1 | + | root |--+--| locked | | locked | '--------' + '--------' | | mux M1 |--. | mux M2 |--. .--------. + | '----------' | '----------' '--| dev D2 | + | .--------. | .--------. '--------' + '--| dev D4 | '--| dev D3 | + '--------' '--------' + +When any device is accessed, all other devices are locked out for +the full duration of the operation (both muxes lock their parent, +and specifically when M2 requests its parent to lock, M1 passes +the buck to the root adapter). + +This topology is bad if M2 is an auto-closing mux and M1->select +issues any unlocked i2c transfers on the root adapter that may leak +through and be seen by the M2 adapter, thus closing M2 prematurely. + + +Mux-locked mux as parent of mux-locked mux +------------------------------------------ + +This is a good topology:: + + .----------. .----------. .--------. + .--------. | mux- |-----| mux- |-----| dev D1 | + | root |--+--| locked | | locked | '--------' + '--------' | | mux M1 |--. | mux M2 |--. .--------. + | '----------' | '----------' '--| dev D2 | + | .--------. | .--------. '--------' + '--| dev D4 | '--| dev D3 | + '--------' '--------' + +When device D1 is accessed, accesses to D2 are locked out for the +full duration of the operation (muxes on the top child adapter of M1 +are locked). But accesses to D3 and D4 are possibly interleaved at +any point. Accesses to D3 locks out D1 and D2, but accesses to D4 +are still possibly interleaved. + + +Mux-locked mux as parent of parent-locked mux +--------------------------------------------- + +This is probably a bad topology:: + + .----------. .----------. .--------. + .--------. | mux- |-----| parent- |-----| dev D1 | + | root |--+--| locked | | locked | '--------' + '--------' | | mux M1 |--. | mux M2 |--. .--------. + | '----------' | '----------' '--| dev D2 | + | .--------. | .--------. '--------' + '--| dev D4 | '--| dev D3 | + '--------' '--------' + +When device D1 is accessed, accesses to D2 and D3 are locked out +for the full duration of the operation (M1 locks child muxes on the +root adapter). But accesses to D4 are possibly interleaved at any +point. + +This kind of topology is generally not suitable and should probably +be avoided. The reason is that M2 probably assumes that there will +be no i2c transfers during its calls to ->select and ->deselect, and +if there are, any such transfers might appear on the slave side of M2 +as partial i2c transfers, i.e. garbage or worse. This might cause +device lockups and/or other problems. + +The topology is especially troublesome if M2 is an auto-closing +mux. In that case, any interleaved accesses to D4 might close M2 +prematurely, as might any i2c-transfers part of M1->select. + +But if M2 is not making the above stated assumption, and if M2 is not +auto-closing, the topology is fine. + + +Parent-locked mux as parent of mux-locked mux +--------------------------------------------- + +This is a good topology:: + + .----------. .----------. .--------. + .--------. | parent- |-----| mux- |-----| dev D1 | + | root |--+--| locked | | locked | '--------' + '--------' | | mux M1 |--. | mux M2 |--. .--------. + | '----------' | '----------' '--| dev D2 | + | .--------. | .--------. '--------' + '--| dev D4 | '--| dev D3 | + '--------' '--------' + +When D1 is accessed, accesses to D2 are locked out for the full +duration of the operation (muxes on the top child adapter of M1 +are locked). Accesses to D3 and D4 are possibly interleaved at +any point, just as is expected for mux-locked muxes. + +When D3 or D4 are accessed, everything else is locked out. For D3 +accesses, M1 locks the root adapter. For D4 accesses, the root +adapter is locked directly. + + +Two mux-locked sibling muxes +---------------------------- + +This is a good topology:: + + .--------. + .----------. .--| dev D1 | + | mux- |--' '--------' + .--| locked | .--------. + | | mux M1 |-----| dev D2 | + | '----------' '--------' + | .----------. .--------. + .--------. | | mux- |-----| dev D3 | + | root |--+--| locked | '--------' + '--------' | | mux M2 |--. .--------. + | '----------' '--| dev D4 | + | .--------. '--------' + '--| dev D5 | + '--------' + +When D1 is accessed, accesses to D2, D3 and D4 are locked out. But +accesses to D5 may be interleaved at any time. + + +Two parent-locked sibling muxes +------------------------------- + +This is a good topology:: + + .--------. + .----------. .--| dev D1 | + | parent- |--' '--------' + .--| locked | .--------. + | | mux M1 |-----| dev D2 | + | '----------' '--------' + | .----------. .--------. + .--------. | | parent- |-----| dev D3 | + | root |--+--| locked | '--------' + '--------' | | mux M2 |--. .--------. + | '----------' '--| dev D4 | + | .--------. '--------' + '--| dev D5 | + '--------' + +When any device is accessed, accesses to all other devices are locked +out. + + +Mux-locked and parent-locked sibling muxes +------------------------------------------ + +This is a good topology:: + + .--------. + .----------. .--| dev D1 | + | mux- |--' '--------' + .--| locked | .--------. + | | mux M1 |-----| dev D2 | + | '----------' '--------' + | .----------. .--------. + .--------. | | parent- |-----| dev D3 | + | root |--+--| locked | '--------' + '--------' | | mux M2 |--. .--------. + | '----------' '--| dev D4 | + | .--------. '--------' + '--| dev D5 | + '--------' + +When D1 or D2 are accessed, accesses to D3 and D4 are locked out while +accesses to D5 may interleave. When D3 or D4 are accessed, accesses to +all other devices are locked out. diff --git a/Documentation/i2c/index.rst b/Documentation/i2c/index.rst new file mode 100644 index 000000000000..cd8d020f7ac5 --- /dev/null +++ b/Documentation/i2c/index.rst @@ -0,0 +1,37 @@ +. SPDX-License-Identifier: GPL-2.0 + +=================== +I2C/SMBus Subsystem +=================== + +.. toctree:: + :maxdepth: 1 + + dev-interface + dma-considerations + fault-codes + functionality + gpio-fault-injection + i2c-protocol + i2c-stub + i2c-topology + instantiating-devices + old-module-parameters + slave-eeprom-backend + slave-interface + smbus-protocol + summary + ten-bit-addresses + upgrading-clients + writing-clients + + muxes/i2c-mux-gpio + + busses/index + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/i2c/instantiating-devices b/Documentation/i2c/instantiating-devices deleted file mode 100644 index 345e9ea8281a..000000000000 --- a/Documentation/i2c/instantiating-devices +++ /dev/null @@ -1,248 +0,0 @@ -How to instantiate I2C devices -============================== - -Unlike PCI or USB devices, I2C devices are not enumerated at the hardware -level. Instead, the software must know which devices are connected on each -I2C bus segment, and what address these devices are using. For this -reason, the kernel code must instantiate I2C devices explicitly. There are -several ways to achieve this, depending on the context and requirements. - - -Method 1a: Declare the I2C devices by bus number ------------------------------------------------- - -This method is appropriate when the I2C bus is a system bus as is the case -for many embedded systems. On such systems, each I2C bus has a number -which is known in advance. It is thus possible to pre-declare the I2C -devices which live on this bus. This is done with an array of struct -i2c_board_info which is registered by calling i2c_register_board_info(). - -Example (from omap2 h4): - -static struct i2c_board_info h4_i2c_board_info[] __initdata = { - { - I2C_BOARD_INFO("isp1301_omap", 0x2d), - .irq = OMAP_GPIO_IRQ(125), - }, - { /* EEPROM on mainboard */ - I2C_BOARD_INFO("24c01", 0x52), - .platform_data = &m24c01, - }, - { /* EEPROM on cpu card */ - I2C_BOARD_INFO("24c01", 0x57), - .platform_data = &m24c01, - }, -}; - -static void __init omap_h4_init(void) -{ - (...) - i2c_register_board_info(1, h4_i2c_board_info, - ARRAY_SIZE(h4_i2c_board_info)); - (...) -} - -The above code declares 3 devices on I2C bus 1, including their respective -addresses and custom data needed by their drivers. When the I2C bus in -question is registered, the I2C devices will be instantiated automatically -by i2c-core. - -The devices will be automatically unbound and destroyed when the I2C bus -they sit on goes away (if ever.) - - -Method 1b: Declare the I2C devices via devicetree -------------------------------------------------- - -This method has the same implications as method 1a. The declaration of I2C -devices is here done via devicetree as subnodes of the master controller. - -Example: - - i2c1: i2c@400a0000 { - /* ... master properties skipped ... */ - clock-frequency = <100000>; - - flash@50 { - compatible = "atmel,24c256"; - reg = <0x50>; - }; - - pca9532: gpio@60 { - compatible = "nxp,pca9532"; - gpio-controller; - #gpio-cells = <2>; - reg = <0x60>; - }; - }; - -Here, two devices are attached to the bus using a speed of 100kHz. For -additional properties which might be needed to set up the device, please refer -to its devicetree documentation in Documentation/devicetree/bindings/. - - -Method 1c: Declare the I2C devices via ACPI -------------------------------------------- - -ACPI can also describe I2C devices. There is special documentation for this -which is currently located at Documentation/firmware-guide/acpi/enumeration.rst. - - -Method 2: Instantiate the devices explicitly --------------------------------------------- - -This method is appropriate when a larger device uses an I2C bus for -internal communication. A typical case is TV adapters. These can have a -tuner, a video decoder, an audio decoder, etc. usually connected to the -main chip by the means of an I2C bus. You won't know the number of the I2C -bus in advance, so the method 1 described above can't be used. Instead, -you can instantiate your I2C devices explicitly. This is done by filling -a struct i2c_board_info and calling i2c_new_device(). - -Example (from the sfe4001 network driver): - -static struct i2c_board_info sfe4001_hwmon_info = { - I2C_BOARD_INFO("max6647", 0x4e), -}; - -int sfe4001_init(struct efx_nic *efx) -{ - (...) - efx->board_info.hwmon_client = - i2c_new_device(&efx->i2c_adap, &sfe4001_hwmon_info); - - (...) -} - -The above code instantiates 1 I2C device on the I2C bus which is on the -network adapter in question. - -A variant of this is when you don't know for sure if an I2C device is -present or not (for example for an optional feature which is not present -on cheap variants of a board but you have no way to tell them apart), or -it may have different addresses from one board to the next (manufacturer -changing its design without notice). In this case, you can call -i2c_new_probed_device() instead of i2c_new_device(). - -Example (from the nxp OHCI driver): - -static const unsigned short normal_i2c[] = { 0x2c, 0x2d, I2C_CLIENT_END }; - -static int usb_hcd_nxp_probe(struct platform_device *pdev) -{ - (...) - struct i2c_adapter *i2c_adap; - struct i2c_board_info i2c_info; - - (...) - i2c_adap = i2c_get_adapter(2); - memset(&i2c_info, 0, sizeof(struct i2c_board_info)); - strscpy(i2c_info.type, "isp1301_nxp", sizeof(i2c_info.type)); - isp1301_i2c_client = i2c_new_probed_device(i2c_adap, &i2c_info, - normal_i2c, NULL); - i2c_put_adapter(i2c_adap); - (...) -} - -The above code instantiates up to 1 I2C device on the I2C bus which is on -the OHCI adapter in question. It first tries at address 0x2c, if nothing -is found there it tries address 0x2d, and if still nothing is found, it -simply gives up. - -The driver which instantiated the I2C device is responsible for destroying -it on cleanup. This is done by calling i2c_unregister_device() on the -pointer that was earlier returned by i2c_new_device() or -i2c_new_probed_device(). - - -Method 3: Probe an I2C bus for certain devices ----------------------------------------------- - -Sometimes you do not have enough information about an I2C device, not even -to call i2c_new_probed_device(). The typical case is hardware monitoring -chips on PC mainboards. There are several dozen models, which can live -at 25 different addresses. Given the huge number of mainboards out there, -it is next to impossible to build an exhaustive list of the hardware -monitoring chips being used. Fortunately, most of these chips have -manufacturer and device ID registers, so they can be identified by -probing. - -In that case, I2C devices are neither declared nor instantiated -explicitly. Instead, i2c-core will probe for such devices as soon as their -drivers are loaded, and if any is found, an I2C device will be -instantiated automatically. In order to prevent any misbehavior of this -mechanism, the following restrictions apply: -* The I2C device driver must implement the detect() method, which - identifies a supported device by reading from arbitrary registers. -* Only buses which are likely to have a supported device and agree to be - probed, will be probed. For example this avoids probing for hardware - monitoring chips on a TV adapter. - -Example: -See lm90_driver and lm90_detect() in drivers/hwmon/lm90.c - -I2C devices instantiated as a result of such a successful probe will be -destroyed automatically when the driver which detected them is removed, -or when the underlying I2C bus is itself destroyed, whichever happens -first. - -Those of you familiar with the i2c subsystem of 2.4 kernels and early 2.6 -kernels will find out that this method 3 is essentially similar to what -was done there. Two significant differences are: -* Probing is only one way to instantiate I2C devices now, while it was the - only way back then. Where possible, methods 1 and 2 should be preferred. - Method 3 should only be used when there is no other way, as it can have - undesirable side effects. -* I2C buses must now explicitly say which I2C driver classes can probe - them (by the means of the class bitfield), while all I2C buses were - probed by default back then. The default is an empty class which means - that no probing happens. The purpose of the class bitfield is to limit - the aforementioned undesirable side effects. - -Once again, method 3 should be avoided wherever possible. Explicit device -instantiation (methods 1 and 2) is much preferred for it is safer and -faster. - - -Method 4: Instantiate from user-space -------------------------------------- - -In general, the kernel should know which I2C devices are connected and -what addresses they live at. However, in certain cases, it does not, so a -sysfs interface was added to let the user provide the information. This -interface is made of 2 attribute files which are created in every I2C bus -directory: new_device and delete_device. Both files are write only and you -must write the right parameters to them in order to properly instantiate, -respectively delete, an I2C device. - -File new_device takes 2 parameters: the name of the I2C device (a string) -and the address of the I2C device (a number, typically expressed in -hexadecimal starting with 0x, but can also be expressed in decimal.) - -File delete_device takes a single parameter: the address of the I2C -device. As no two devices can live at the same address on a given I2C -segment, the address is sufficient to uniquely identify the device to be -deleted. - -Example: -# echo eeprom 0x50 > /sys/bus/i2c/devices/i2c-3/new_device - -While this interface should only be used when in-kernel device declaration -can't be done, there is a variety of cases where it can be helpful: -* The I2C driver usually detects devices (method 3 above) but the bus - segment your device lives on doesn't have the proper class bit set and - thus detection doesn't trigger. -* The I2C driver usually detects devices, but your device lives at an - unexpected address. -* The I2C driver usually detects devices, but your device is not detected, - either because the detection routine is too strict, or because your - device is not officially supported yet but you know it is compatible. -* You are developing a driver on a test board, where you soldered the I2C - device yourself. - -This interface is a replacement for the force_* module parameters some I2C -drivers implement. Being implemented in i2c-core rather than in each -device driver individually, it is much more efficient, and also has the -advantage that you do not have to reload the driver to change a setting. -You can also instantiate the device before the driver is loaded or even -available, and you don't need to know what driver the device needs. diff --git a/Documentation/i2c/instantiating-devices.rst b/Documentation/i2c/instantiating-devices.rst new file mode 100644 index 000000000000..1238f1fa3382 --- /dev/null +++ b/Documentation/i2c/instantiating-devices.rst @@ -0,0 +1,253 @@ +============================== +How to instantiate I2C devices +============================== + +Unlike PCI or USB devices, I2C devices are not enumerated at the hardware +level. Instead, the software must know which devices are connected on each +I2C bus segment, and what address these devices are using. For this +reason, the kernel code must instantiate I2C devices explicitly. There are +several ways to achieve this, depending on the context and requirements. + + +Method 1a: Declare the I2C devices by bus number +------------------------------------------------ + +This method is appropriate when the I2C bus is a system bus as is the case +for many embedded systems. On such systems, each I2C bus has a number +which is known in advance. It is thus possible to pre-declare the I2C +devices which live on this bus. This is done with an array of struct +i2c_board_info which is registered by calling i2c_register_board_info(). + +Example (from omap2 h4):: + + static struct i2c_board_info h4_i2c_board_info[] __initdata = { + { + I2C_BOARD_INFO("isp1301_omap", 0x2d), + .irq = OMAP_GPIO_IRQ(125), + }, + { /* EEPROM on mainboard */ + I2C_BOARD_INFO("24c01", 0x52), + .platform_data = &m24c01, + }, + { /* EEPROM on cpu card */ + I2C_BOARD_INFO("24c01", 0x57), + .platform_data = &m24c01, + }, + }; + + static void __init omap_h4_init(void) + { + (...) + i2c_register_board_info(1, h4_i2c_board_info, + ARRAY_SIZE(h4_i2c_board_info)); + (...) + } + +The above code declares 3 devices on I2C bus 1, including their respective +addresses and custom data needed by their drivers. When the I2C bus in +question is registered, the I2C devices will be instantiated automatically +by i2c-core. + +The devices will be automatically unbound and destroyed when the I2C bus +they sit on goes away (if ever.) + + +Method 1b: Declare the I2C devices via devicetree +------------------------------------------------- + +This method has the same implications as method 1a. The declaration of I2C +devices is here done via devicetree as subnodes of the master controller. + +Example:: + + i2c1: i2c@400a0000 { + /* ... master properties skipped ... */ + clock-frequency = <100000>; + + flash@50 { + compatible = "atmel,24c256"; + reg = <0x50>; + }; + + pca9532: gpio@60 { + compatible = "nxp,pca9532"; + gpio-controller; + #gpio-cells = <2>; + reg = <0x60>; + }; + }; + +Here, two devices are attached to the bus using a speed of 100kHz. For +additional properties which might be needed to set up the device, please refer +to its devicetree documentation in Documentation/devicetree/bindings/. + + +Method 1c: Declare the I2C devices via ACPI +------------------------------------------- + +ACPI can also describe I2C devices. There is special documentation for this +which is currently located at Documentation/firmware-guide/acpi/enumeration.rst. + + +Method 2: Instantiate the devices explicitly +-------------------------------------------- + +This method is appropriate when a larger device uses an I2C bus for +internal communication. A typical case is TV adapters. These can have a +tuner, a video decoder, an audio decoder, etc. usually connected to the +main chip by the means of an I2C bus. You won't know the number of the I2C +bus in advance, so the method 1 described above can't be used. Instead, +you can instantiate your I2C devices explicitly. This is done by filling +a struct i2c_board_info and calling i2c_new_device(). + +Example (from the sfe4001 network driver):: + + static struct i2c_board_info sfe4001_hwmon_info = { + I2C_BOARD_INFO("max6647", 0x4e), + }; + + int sfe4001_init(struct efx_nic *efx) + { + (...) + efx->board_info.hwmon_client = + i2c_new_device(&efx->i2c_adap, &sfe4001_hwmon_info); + + (...) + } + +The above code instantiates 1 I2C device on the I2C bus which is on the +network adapter in question. + +A variant of this is when you don't know for sure if an I2C device is +present or not (for example for an optional feature which is not present +on cheap variants of a board but you have no way to tell them apart), or +it may have different addresses from one board to the next (manufacturer +changing its design without notice). In this case, you can call +i2c_new_probed_device() instead of i2c_new_device(). + +Example (from the nxp OHCI driver):: + + static const unsigned short normal_i2c[] = { 0x2c, 0x2d, I2C_CLIENT_END }; + + static int usb_hcd_nxp_probe(struct platform_device *pdev) + { + (...) + struct i2c_adapter *i2c_adap; + struct i2c_board_info i2c_info; + + (...) + i2c_adap = i2c_get_adapter(2); + memset(&i2c_info, 0, sizeof(struct i2c_board_info)); + strscpy(i2c_info.type, "isp1301_nxp", sizeof(i2c_info.type)); + isp1301_i2c_client = i2c_new_probed_device(i2c_adap, &i2c_info, + normal_i2c, NULL); + i2c_put_adapter(i2c_adap); + (...) + } + +The above code instantiates up to 1 I2C device on the I2C bus which is on +the OHCI adapter in question. It first tries at address 0x2c, if nothing +is found there it tries address 0x2d, and if still nothing is found, it +simply gives up. + +The driver which instantiated the I2C device is responsible for destroying +it on cleanup. This is done by calling i2c_unregister_device() on the +pointer that was earlier returned by i2c_new_device() or +i2c_new_probed_device(). + + +Method 3: Probe an I2C bus for certain devices +---------------------------------------------- + +Sometimes you do not have enough information about an I2C device, not even +to call i2c_new_probed_device(). The typical case is hardware monitoring +chips on PC mainboards. There are several dozen models, which can live +at 25 different addresses. Given the huge number of mainboards out there, +it is next to impossible to build an exhaustive list of the hardware +monitoring chips being used. Fortunately, most of these chips have +manufacturer and device ID registers, so they can be identified by +probing. + +In that case, I2C devices are neither declared nor instantiated +explicitly. Instead, i2c-core will probe for such devices as soon as their +drivers are loaded, and if any is found, an I2C device will be +instantiated automatically. In order to prevent any misbehavior of this +mechanism, the following restrictions apply: + +* The I2C device driver must implement the detect() method, which + identifies a supported device by reading from arbitrary registers. +* Only buses which are likely to have a supported device and agree to be + probed, will be probed. For example this avoids probing for hardware + monitoring chips on a TV adapter. + +Example: +See lm90_driver and lm90_detect() in drivers/hwmon/lm90.c + +I2C devices instantiated as a result of such a successful probe will be +destroyed automatically when the driver which detected them is removed, +or when the underlying I2C bus is itself destroyed, whichever happens +first. + +Those of you familiar with the i2c subsystem of 2.4 kernels and early 2.6 +kernels will find out that this method 3 is essentially similar to what +was done there. Two significant differences are: + +* Probing is only one way to instantiate I2C devices now, while it was the + only way back then. Where possible, methods 1 and 2 should be preferred. + Method 3 should only be used when there is no other way, as it can have + undesirable side effects. +* I2C buses must now explicitly say which I2C driver classes can probe + them (by the means of the class bitfield), while all I2C buses were + probed by default back then. The default is an empty class which means + that no probing happens. The purpose of the class bitfield is to limit + the aforementioned undesirable side effects. + +Once again, method 3 should be avoided wherever possible. Explicit device +instantiation (methods 1 and 2) is much preferred for it is safer and +faster. + + +Method 4: Instantiate from user-space +------------------------------------- + +In general, the kernel should know which I2C devices are connected and +what addresses they live at. However, in certain cases, it does not, so a +sysfs interface was added to let the user provide the information. This +interface is made of 2 attribute files which are created in every I2C bus +directory: new_device and delete_device. Both files are write only and you +must write the right parameters to them in order to properly instantiate, +respectively delete, an I2C device. + +File new_device takes 2 parameters: the name of the I2C device (a string) +and the address of the I2C device (a number, typically expressed in +hexadecimal starting with 0x, but can also be expressed in decimal.) + +File delete_device takes a single parameter: the address of the I2C +device. As no two devices can live at the same address on a given I2C +segment, the address is sufficient to uniquely identify the device to be +deleted. + +Example:: + + # echo eeprom 0x50 > /sys/bus/i2c/devices/i2c-3/new_device + +While this interface should only be used when in-kernel device declaration +can't be done, there is a variety of cases where it can be helpful: + +* The I2C driver usually detects devices (method 3 above) but the bus + segment your device lives on doesn't have the proper class bit set and + thus detection doesn't trigger. +* The I2C driver usually detects devices, but your device lives at an + unexpected address. +* The I2C driver usually detects devices, but your device is not detected, + either because the detection routine is too strict, or because your + device is not officially supported yet but you know it is compatible. +* You are developing a driver on a test board, where you soldered the I2C + device yourself. + +This interface is a replacement for the force_* module parameters some I2C +drivers implement. Being implemented in i2c-core rather than in each +device driver individually, it is much more efficient, and also has the +advantage that you do not have to reload the driver to change a setting. +You can also instantiate the device before the driver is loaded or even +available, and you don't need to know what driver the device needs. diff --git a/Documentation/i2c/muxes/i2c-mux-gpio b/Documentation/i2c/muxes/i2c-mux-gpio deleted file mode 100644 index 893ecdfe6e43..000000000000 --- a/Documentation/i2c/muxes/i2c-mux-gpio +++ /dev/null @@ -1,83 +0,0 @@ -Kernel driver i2c-mux-gpio - -Author: Peter Korsgaard - -Description ------------ - -i2c-mux-gpio is an i2c mux driver providing access to I2C bus segments -from a master I2C bus and a hardware MUX controlled through GPIO pins. - -E.G.: - - ---------- ---------- Bus segment 1 - - - - - - | | SCL/SDA | |-------------- | | - | |------------| | - | | | | Bus segment 2 | | - | Linux | GPIO 1..N | MUX |--------------- Devices - | |------------| | | | - | | | | Bus segment M - | | | |---------------| | - ---------- ---------- - - - - - - -SCL/SDA of the master I2C bus is multiplexed to bus segment 1..M -according to the settings of the GPIO pins 1..N. - -Usage ------ - -i2c-mux-gpio uses the platform bus, so you need to provide a struct -platform_device with the platform_data pointing to a struct -i2c_mux_gpio_platform_data with the I2C adapter number of the master -bus, the number of bus segments to create and the GPIO pins used -to control it. See include/linux/platform_data/i2c-mux-gpio.h for details. - -E.G. something like this for a MUX providing 4 bus segments -controlled through 3 GPIO pins: - -#include -#include - -static const unsigned myboard_gpiomux_gpios[] = { - AT91_PIN_PC26, AT91_PIN_PC25, AT91_PIN_PC24 -}; - -static const unsigned myboard_gpiomux_values[] = { - 0, 1, 2, 3 -}; - -static struct i2c_mux_gpio_platform_data myboard_i2cmux_data = { - .parent = 1, - .base_nr = 2, /* optional */ - .values = myboard_gpiomux_values, - .n_values = ARRAY_SIZE(myboard_gpiomux_values), - .gpios = myboard_gpiomux_gpios, - .n_gpios = ARRAY_SIZE(myboard_gpiomux_gpios), - .idle = 4, /* optional */ -}; - -static struct platform_device myboard_i2cmux = { - .name = "i2c-mux-gpio", - .id = 0, - .dev = { - .platform_data = &myboard_i2cmux_data, - }, -}; - -If you don't know the absolute GPIO pin numbers at registration time, -you can instead provide a chip name (.chip_name) and relative GPIO pin -numbers, and the i2c-mux-gpio driver will do the work for you, -including deferred probing if the GPIO chip isn't immediately -available. - -Device Registration -------------------- - -When registering your i2c-mux-gpio device, you should pass the number -of any GPIO pin it uses as the device ID. This guarantees that every -instance has a different ID. - -Alternatively, if you don't need a stable device name, you can simply -pass PLATFORM_DEVID_AUTO as the device ID, and the platform core will -assign a dynamic ID to your device. If you do not know the absolute -GPIO pin numbers at registration time, this is even the only option. diff --git a/Documentation/i2c/muxes/i2c-mux-gpio.rst b/Documentation/i2c/muxes/i2c-mux-gpio.rst new file mode 100644 index 000000000000..7d27444035c3 --- /dev/null +++ b/Documentation/i2c/muxes/i2c-mux-gpio.rst @@ -0,0 +1,85 @@ +========================== +Kernel driver i2c-mux-gpio +========================== + +Author: Peter Korsgaard + +Description +----------- + +i2c-mux-gpio is an i2c mux driver providing access to I2C bus segments +from a master I2C bus and a hardware MUX controlled through GPIO pins. + +E.G.:: + + ---------- ---------- Bus segment 1 - - - - - + | | SCL/SDA | |-------------- | | + | |------------| | + | | | | Bus segment 2 | | + | Linux | GPIO 1..N | MUX |--------------- Devices + | |------------| | | | + | | | | Bus segment M + | | | |---------------| | + ---------- ---------- - - - - - + +SCL/SDA of the master I2C bus is multiplexed to bus segment 1..M +according to the settings of the GPIO pins 1..N. + +Usage +----- + +i2c-mux-gpio uses the platform bus, so you need to provide a struct +platform_device with the platform_data pointing to a struct +i2c_mux_gpio_platform_data with the I2C adapter number of the master +bus, the number of bus segments to create and the GPIO pins used +to control it. See include/linux/platform_data/i2c-mux-gpio.h for details. + +E.G. something like this for a MUX providing 4 bus segments +controlled through 3 GPIO pins:: + + #include + #include + + static const unsigned myboard_gpiomux_gpios[] = { + AT91_PIN_PC26, AT91_PIN_PC25, AT91_PIN_PC24 + }; + + static const unsigned myboard_gpiomux_values[] = { + 0, 1, 2, 3 + }; + + static struct i2c_mux_gpio_platform_data myboard_i2cmux_data = { + .parent = 1, + .base_nr = 2, /* optional */ + .values = myboard_gpiomux_values, + .n_values = ARRAY_SIZE(myboard_gpiomux_values), + .gpios = myboard_gpiomux_gpios, + .n_gpios = ARRAY_SIZE(myboard_gpiomux_gpios), + .idle = 4, /* optional */ + }; + + static struct platform_device myboard_i2cmux = { + .name = "i2c-mux-gpio", + .id = 0, + .dev = { + .platform_data = &myboard_i2cmux_data, + }, + }; + +If you don't know the absolute GPIO pin numbers at registration time, +you can instead provide a chip name (.chip_name) and relative GPIO pin +numbers, and the i2c-mux-gpio driver will do the work for you, +including deferred probing if the GPIO chip isn't immediately +available. + +Device Registration +------------------- + +When registering your i2c-mux-gpio device, you should pass the number +of any GPIO pin it uses as the device ID. This guarantees that every +instance has a different ID. + +Alternatively, if you don't need a stable device name, you can simply +pass PLATFORM_DEVID_AUTO as the device ID, and the platform core will +assign a dynamic ID to your device. If you do not know the absolute +GPIO pin numbers at registration time, this is even the only option. diff --git a/Documentation/i2c/old-module-parameters b/Documentation/i2c/old-module-parameters deleted file mode 100644 index 8e2b629d533c..000000000000 --- a/Documentation/i2c/old-module-parameters +++ /dev/null @@ -1,44 +0,0 @@ -I2C device driver binding control from user-space -================================================= - -Up to kernel 2.6.32, many i2c drivers used helper macros provided by - which created standard module parameters to let the user -control how the driver would probe i2c buses and attach to devices. These -parameters were known as "probe" (to let the driver probe for an extra -address), "force" (to forcibly attach the driver to a given device) and -"ignore" (to prevent a driver from probing a given address). - -With the conversion of the i2c subsystem to the standard device driver -binding model, it became clear that these per-module parameters were no -longer needed, and that a centralized implementation was possible. The new, -sysfs-based interface is described in the documentation file -"instantiating-devices", section "Method 4: Instantiate from user-space". - -Below is a mapping from the old module parameters to the new interface. - -Attaching a driver to an I2C device ------------------------------------ - -Old method (module parameters): -# modprobe probe=1,0x2d -# modprobe force=1,0x2d -# modprobe force_=1,0x2d - -New method (sysfs interface): -# echo 0x2d > /sys/bus/i2c/devices/i2c-1/new_device - -Preventing a driver from attaching to an I2C device ---------------------------------------------------- - -Old method (module parameters): -# modprobe ignore=1,0x2f - -New method (sysfs interface): -# echo dummy 0x2f > /sys/bus/i2c/devices/i2c-1/new_device -# modprobe - -Of course, it is important to instantiate the "dummy" device before loading -the driver. The dummy device will be handled by i2c-core itself, preventing -other drivers from binding to it later on. If there is a real device at the -problematic address, and you want another driver to bind to it, then simply -pass the name of the device in question instead of "dummy". diff --git a/Documentation/i2c/old-module-parameters.rst b/Documentation/i2c/old-module-parameters.rst new file mode 100644 index 000000000000..a1939512ad66 --- /dev/null +++ b/Documentation/i2c/old-module-parameters.rst @@ -0,0 +1,49 @@ +================================================= +I2C device driver binding control from user-space +================================================= + +Up to kernel 2.6.32, many i2c drivers used helper macros provided by + which created standard module parameters to let the user +control how the driver would probe i2c buses and attach to devices. These +parameters were known as "probe" (to let the driver probe for an extra +address), "force" (to forcibly attach the driver to a given device) and +"ignore" (to prevent a driver from probing a given address). + +With the conversion of the i2c subsystem to the standard device driver +binding model, it became clear that these per-module parameters were no +longer needed, and that a centralized implementation was possible. The new, +sysfs-based interface is described in the documentation file +"instantiating-devices", section "Method 4: Instantiate from user-space". + +Below is a mapping from the old module parameters to the new interface. + +Attaching a driver to an I2C device +----------------------------------- + +Old method (module parameters):: + + # modprobe probe=1,0x2d + # modprobe force=1,0x2d + # modprobe force_=1,0x2d + +New method (sysfs interface):: + + # echo 0x2d > /sys/bus/i2c/devices/i2c-1/new_device + +Preventing a driver from attaching to an I2C device +--------------------------------------------------- + +Old method (module parameters):: + + # modprobe ignore=1,0x2f + +New method (sysfs interface):: + + # echo dummy 0x2f > /sys/bus/i2c/devices/i2c-1/new_device + # modprobe + +Of course, it is important to instantiate the "dummy" device before loading +the driver. The dummy device will be handled by i2c-core itself, preventing +other drivers from binding to it later on. If there is a real device at the +problematic address, and you want another driver to bind to it, then simply +pass the name of the device in question instead of "dummy". diff --git a/Documentation/i2c/slave-eeprom-backend b/Documentation/i2c/slave-eeprom-backend deleted file mode 100644 index 04f8d8a9b817..000000000000 --- a/Documentation/i2c/slave-eeprom-backend +++ /dev/null @@ -1,14 +0,0 @@ -Linux I2C slave eeprom backend -============================== - -by Wolfram Sang in 2014-15 - -This is a proof-of-concept backend which acts like an EEPROM on the connected -I2C bus. The memory contents can be modified from userspace via this file -located in sysfs: - - /sys/bus/i2c/devices//slave-eeprom - -As of 2015, Linux doesn't support poll on binary sysfs files, so there is no -notification when another master changed the content. - diff --git a/Documentation/i2c/slave-eeprom-backend.rst b/Documentation/i2c/slave-eeprom-backend.rst new file mode 100644 index 000000000000..0b8cd83698e0 --- /dev/null +++ b/Documentation/i2c/slave-eeprom-backend.rst @@ -0,0 +1,14 @@ +============================== +Linux I2C slave eeprom backend +============================== + +by Wolfram Sang in 2014-15 + +This is a proof-of-concept backend which acts like an EEPROM on the connected +I2C bus. The memory contents can be modified from userspace via this file +located in sysfs:: + + /sys/bus/i2c/devices//slave-eeprom + +As of 2015, Linux doesn't support poll on binary sysfs files, so there is no +notification when another master changed the content. diff --git a/Documentation/i2c/slave-interface b/Documentation/i2c/slave-interface deleted file mode 100644 index 7e2a228f21bc..000000000000 --- a/Documentation/i2c/slave-interface +++ /dev/null @@ -1,193 +0,0 @@ -Linux I2C slave interface description -===================================== - -by Wolfram Sang in 2014-15 - -Linux can also be an I2C slave if the I2C controller in use has slave -functionality. For that to work, one needs slave support in the bus driver plus -a hardware independent software backend providing the actual functionality. An -example for the latter is the slave-eeprom driver, which acts as a dual memory -driver. While another I2C master on the bus can access it like a regular -EEPROM, the Linux I2C slave can access the content via sysfs and handle data as -needed. The backend driver and the I2C bus driver communicate via events. Here -is a small graph visualizing the data flow and the means by which data is -transported. The dotted line marks only one example. The backend could also -use a character device, be in-kernel only, or something completely different: - - - e.g. sysfs I2C slave events I/O registers - +-----------+ v +---------+ v +--------+ v +------------+ - | Userspace +........+ Backend +-----------+ Driver +-----+ Controller | - +-----------+ +---------+ +--------+ +------------+ - | | - ----------------------------------------------------------------+-- I2C - --------------------------------------------------------------+---- Bus - -Note: Technically, there is also the I2C core between the backend and the -driver. However, at this time of writing, the layer is transparent. - - -User manual -=========== - -I2C slave backends behave like standard I2C clients. So, you can instantiate -them as described in the document 'instantiating-devices'. The only difference -is that i2c slave backends have their own address space. So, you have to add -0x1000 to the address you would originally request. An example for -instantiating the slave-eeprom driver from userspace at the 7 bit address 0x64 -on bus 1: - - # echo slave-24c02 0x1064 > /sys/bus/i2c/devices/i2c-1/new_device - -Each backend should come with separate documentation to describe its specific -behaviour and setup. - - -Developer manual -================ - -First, the events which are used by the bus driver and the backend will be -described in detail. After that, some implementation hints for extending bus -drivers and writing backends will be given. - - -I2C slave events ----------------- - -The bus driver sends an event to the backend using the following function: - - ret = i2c_slave_event(client, event, &val) - -'client' describes the i2c slave device. 'event' is one of the special event -types described hereafter. 'val' holds an u8 value for the data byte to be -read/written and is thus bidirectional. The pointer to val must always be -provided even if val is not used for an event, i.e. don't use NULL here. 'ret' -is the return value from the backend. Mandatory events must be provided by the -bus drivers and must be checked for by backend drivers. - -Event types: - -* I2C_SLAVE_WRITE_REQUESTED (mandatory) - -'val': unused -'ret': always 0 - -Another I2C master wants to write data to us. This event should be sent once -our own address and the write bit was detected. The data did not arrive yet, so -there is nothing to process or return. Wakeup or initialization probably needs -to be done, though. - -* I2C_SLAVE_READ_REQUESTED (mandatory) - -'val': backend returns first byte to be sent -'ret': always 0 - -Another I2C master wants to read data from us. This event should be sent once -our own address and the read bit was detected. After returning, the bus driver -should transmit the first byte. - -* I2C_SLAVE_WRITE_RECEIVED (mandatory) - -'val': bus driver delivers received byte -'ret': 0 if the byte should be acked, some errno if the byte should be nacked - -Another I2C master has sent a byte to us which needs to be set in 'val'. If 'ret' -is zero, the bus driver should ack this byte. If 'ret' is an errno, then the byte -should be nacked. - -* I2C_SLAVE_READ_PROCESSED (mandatory) - -'val': backend returns next byte to be sent -'ret': always 0 - -The bus driver requests the next byte to be sent to another I2C master in -'val'. Important: This does not mean that the previous byte has been acked, it -only means that the previous byte is shifted out to the bus! To ensure seamless -transmission, most hardware requests the next byte when the previous one is -still shifted out. If the master sends NACK and stops reading after the byte -currently shifted out, this byte requested here is never used. It very likely -needs to be sent again on the next I2C_SLAVE_READ_REQUEST, depending a bit on -your backend, though. - -* I2C_SLAVE_STOP (mandatory) - -'val': unused -'ret': always 0 - -A stop condition was received. This can happen anytime and the backend should -reset its state machine for I2C transfers to be able to receive new requests. - - -Software backends ------------------ - -If you want to write a software backend: - -* use a standard i2c_driver and its matching mechanisms -* write the slave_callback which handles the above slave events - (best using a state machine) -* register this callback via i2c_slave_register() - -Check the i2c-slave-eeprom driver as an example. - - -Bus driver support ------------------- - -If you want to add slave support to the bus driver: - -* implement calls to register/unregister the slave and add those to the - struct i2c_algorithm. When registering, you probably need to set the i2c - slave address and enable slave specific interrupts. If you use runtime pm, you - should use pm_runtime_get_sync() because your device usually needs to be - powered on always to be able to detect its slave address. When unregistering, - do the inverse of the above. - -* Catch the slave interrupts and send appropriate i2c_slave_events to the backend. - -Note that most hardware supports being master _and_ slave on the same bus. So, -if you extend a bus driver, please make sure that the driver supports that as -well. In almost all cases, slave support does not need to disable the master -functionality. - -Check the i2c-rcar driver as an example. - - -About ACK/NACK --------------- - -It is good behaviour to always ACK the address phase, so the master knows if a -device is basically present or if it mysteriously disappeared. Using NACK to -state being busy is troublesome. SMBus demands to always ACK the address phase, -while the I2C specification is more loose on that. Most I2C controllers also -automatically ACK when detecting their slave addresses, so there is no option -to NACK them. For those reasons, this API does not support NACK in the address -phase. - -Currently, there is no slave event to report if the master did ACK or NACK a -byte when it reads from us. We could make this an optional event if the need -arises. However, cases should be extremely rare because the master is expected -to send STOP after that and we have an event for that. Also, keep in mind not -all I2C controllers have the possibility to report that event. - - -About buffers -------------- - -During development of this API, the question of using buffers instead of just -bytes came up. Such an extension might be possible, usefulness is unclear at -this time of writing. Some points to keep in mind when using buffers: - -* Buffers should be opt-in and backend drivers will always have to support - byte-based transactions as the ultimate fallback anyhow because this is how - the majority of HW works. - -* For backends simulating hardware registers, buffers are largely not helpful - because after each byte written an action should be immediately triggered. - For reads, the data kept in the buffer might get stale if the backend just - updated a register because of internal processing. - -* A master can send STOP at any time. For partially transferred buffers, this - means additional code to handle this exception. Such code tends to be - error-prone. - diff --git a/Documentation/i2c/slave-interface.rst b/Documentation/i2c/slave-interface.rst new file mode 100644 index 000000000000..c769bd6a15bf --- /dev/null +++ b/Documentation/i2c/slave-interface.rst @@ -0,0 +1,198 @@ +===================================== +Linux I2C slave interface description +===================================== + +by Wolfram Sang in 2014-15 + +Linux can also be an I2C slave if the I2C controller in use has slave +functionality. For that to work, one needs slave support in the bus driver plus +a hardware independent software backend providing the actual functionality. An +example for the latter is the slave-eeprom driver, which acts as a dual memory +driver. While another I2C master on the bus can access it like a regular +EEPROM, the Linux I2C slave can access the content via sysfs and handle data as +needed. The backend driver and the I2C bus driver communicate via events. Here +is a small graph visualizing the data flow and the means by which data is +transported. The dotted line marks only one example. The backend could also +use a character device, be in-kernel only, or something completely different:: + + + e.g. sysfs I2C slave events I/O registers + +-----------+ v +---------+ v +--------+ v +------------+ + | Userspace +........+ Backend +-----------+ Driver +-----+ Controller | + +-----------+ +---------+ +--------+ +------------+ + | | + ----------------------------------------------------------------+-- I2C + --------------------------------------------------------------+---- Bus + +Note: Technically, there is also the I2C core between the backend and the +driver. However, at this time of writing, the layer is transparent. + + +User manual +=========== + +I2C slave backends behave like standard I2C clients. So, you can instantiate +them as described in the document 'instantiating-devices'. The only difference +is that i2c slave backends have their own address space. So, you have to add +0x1000 to the address you would originally request. An example for +instantiating the slave-eeprom driver from userspace at the 7 bit address 0x64 +on bus 1:: + + # echo slave-24c02 0x1064 > /sys/bus/i2c/devices/i2c-1/new_device + +Each backend should come with separate documentation to describe its specific +behaviour and setup. + + +Developer manual +================ + +First, the events which are used by the bus driver and the backend will be +described in detail. After that, some implementation hints for extending bus +drivers and writing backends will be given. + + +I2C slave events +---------------- + +The bus driver sends an event to the backend using the following function:: + + ret = i2c_slave_event(client, event, &val) + +'client' describes the i2c slave device. 'event' is one of the special event +types described hereafter. 'val' holds an u8 value for the data byte to be +read/written and is thus bidirectional. The pointer to val must always be +provided even if val is not used for an event, i.e. don't use NULL here. 'ret' +is the return value from the backend. Mandatory events must be provided by the +bus drivers and must be checked for by backend drivers. + +Event types: + +* I2C_SLAVE_WRITE_REQUESTED (mandatory) + + 'val': unused + + 'ret': always 0 + +Another I2C master wants to write data to us. This event should be sent once +our own address and the write bit was detected. The data did not arrive yet, so +there is nothing to process or return. Wakeup or initialization probably needs +to be done, though. + +* I2C_SLAVE_READ_REQUESTED (mandatory) + + 'val': backend returns first byte to be sent + + 'ret': always 0 + +Another I2C master wants to read data from us. This event should be sent once +our own address and the read bit was detected. After returning, the bus driver +should transmit the first byte. + +* I2C_SLAVE_WRITE_RECEIVED (mandatory) + + 'val': bus driver delivers received byte + + 'ret': 0 if the byte should be acked, some errno if the byte should be nacked + +Another I2C master has sent a byte to us which needs to be set in 'val'. If 'ret' +is zero, the bus driver should ack this byte. If 'ret' is an errno, then the byte +should be nacked. + +* I2C_SLAVE_READ_PROCESSED (mandatory) + + 'val': backend returns next byte to be sent + + 'ret': always 0 + +The bus driver requests the next byte to be sent to another I2C master in +'val'. Important: This does not mean that the previous byte has been acked, it +only means that the previous byte is shifted out to the bus! To ensure seamless +transmission, most hardware requests the next byte when the previous one is +still shifted out. If the master sends NACK and stops reading after the byte +currently shifted out, this byte requested here is never used. It very likely +needs to be sent again on the next I2C_SLAVE_READ_REQUEST, depending a bit on +your backend, though. + +* I2C_SLAVE_STOP (mandatory) + + 'val': unused + + 'ret': always 0 + +A stop condition was received. This can happen anytime and the backend should +reset its state machine for I2C transfers to be able to receive new requests. + + +Software backends +----------------- + +If you want to write a software backend: + +* use a standard i2c_driver and its matching mechanisms +* write the slave_callback which handles the above slave events + (best using a state machine) +* register this callback via i2c_slave_register() + +Check the i2c-slave-eeprom driver as an example. + + +Bus driver support +------------------ + +If you want to add slave support to the bus driver: + +* implement calls to register/unregister the slave and add those to the + struct i2c_algorithm. When registering, you probably need to set the i2c + slave address and enable slave specific interrupts. If you use runtime pm, you + should use pm_runtime_get_sync() because your device usually needs to be + powered on always to be able to detect its slave address. When unregistering, + do the inverse of the above. + +* Catch the slave interrupts and send appropriate i2c_slave_events to the backend. + +Note that most hardware supports being master _and_ slave on the same bus. So, +if you extend a bus driver, please make sure that the driver supports that as +well. In almost all cases, slave support does not need to disable the master +functionality. + +Check the i2c-rcar driver as an example. + + +About ACK/NACK +-------------- + +It is good behaviour to always ACK the address phase, so the master knows if a +device is basically present or if it mysteriously disappeared. Using NACK to +state being busy is troublesome. SMBus demands to always ACK the address phase, +while the I2C specification is more loose on that. Most I2C controllers also +automatically ACK when detecting their slave addresses, so there is no option +to NACK them. For those reasons, this API does not support NACK in the address +phase. + +Currently, there is no slave event to report if the master did ACK or NACK a +byte when it reads from us. We could make this an optional event if the need +arises. However, cases should be extremely rare because the master is expected +to send STOP after that and we have an event for that. Also, keep in mind not +all I2C controllers have the possibility to report that event. + + +About buffers +------------- + +During development of this API, the question of using buffers instead of just +bytes came up. Such an extension might be possible, usefulness is unclear at +this time of writing. Some points to keep in mind when using buffers: + +* Buffers should be opt-in and backend drivers will always have to support + byte-based transactions as the ultimate fallback anyhow because this is how + the majority of HW works. + +* For backends simulating hardware registers, buffers are largely not helpful + because after each byte written an action should be immediately triggered. + For reads, the data kept in the buffer might get stale if the backend just + updated a register because of internal processing. + +* A master can send STOP at any time. For partially transferred buffers, this + means additional code to handle this exception. Such code tends to be + error-prone. diff --git a/Documentation/i2c/smbus-protocol b/Documentation/i2c/smbus-protocol deleted file mode 100644 index 092d474f5843..000000000000 --- a/Documentation/i2c/smbus-protocol +++ /dev/null @@ -1,283 +0,0 @@ -SMBus Protocol Summary -====================== - -The following is a summary of the SMBus protocol. It applies to -all revisions of the protocol (1.0, 1.1, and 2.0). -Certain protocol features which are not supported by -this package are briefly described at the end of this document. - -Some adapters understand only the SMBus (System Management Bus) protocol, -which is a subset from the I2C protocol. Fortunately, many devices use -only the same subset, which makes it possible to put them on an SMBus. - -If you write a driver for some I2C device, please try to use the SMBus -commands if at all possible (if the device uses only that subset of the -I2C protocol). This makes it possible to use the device driver on both -SMBus adapters and I2C adapters (the SMBus command set is automatically -translated to I2C on I2C adapters, but plain I2C commands can not be -handled at all on most pure SMBus adapters). - -Below is a list of SMBus protocol operations, and the functions executing -them. Note that the names used in the SMBus protocol specifications usually -don't match these function names. For some of the operations which pass a -single data byte, the functions using SMBus protocol operation names execute -a different protocol operation entirely. - -Each transaction type corresponds to a functionality flag. Before calling a -transaction function, a device driver should always check (just once) for -the corresponding functionality flag to ensure that the underlying I2C -adapter supports the transaction in question. See - for the details. - - -Key to symbols -============== - -S (1 bit) : Start bit -P (1 bit) : Stop bit -Rd/Wr (1 bit) : Read/Write bit. Rd equals 1, Wr equals 0. -A, NA (1 bit) : Accept and reverse accept bit. -Addr (7 bits): I2C 7 bit address. Note that this can be expanded as usual to - get a 10 bit I2C address. -Comm (8 bits): Command byte, a data byte which often selects a register on - the device. -Data (8 bits): A plain data byte. Sometimes, I write DataLow, DataHigh - for 16 bit data. -Count (8 bits): A data byte containing the length of a block operation. - -[..]: Data sent by I2C device, as opposed to data sent by the host adapter. - - -SMBus Quick Command -=================== - -This sends a single bit to the device, at the place of the Rd/Wr bit. - -A Addr Rd/Wr [A] P - -Functionality flag: I2C_FUNC_SMBUS_QUICK - - -SMBus Receive Byte: i2c_smbus_read_byte() -========================================== - -This reads a single byte from a device, without specifying a device -register. Some devices are so simple that this interface is enough; for -others, it is a shorthand if you want to read the same register as in -the previous SMBus command. - -S Addr Rd [A] [Data] NA P - -Functionality flag: I2C_FUNC_SMBUS_READ_BYTE - - -SMBus Send Byte: i2c_smbus_write_byte() -======================================== - -This operation is the reverse of Receive Byte: it sends a single byte -to a device. See Receive Byte for more information. - -S Addr Wr [A] Data [A] P - -Functionality flag: I2C_FUNC_SMBUS_WRITE_BYTE - - -SMBus Read Byte: i2c_smbus_read_byte_data() -============================================ - -This reads a single byte from a device, from a designated register. -The register is specified through the Comm byte. - -S Addr Wr [A] Comm [A] S Addr Rd [A] [Data] NA P - -Functionality flag: I2C_FUNC_SMBUS_READ_BYTE_DATA - - -SMBus Read Word: i2c_smbus_read_word_data() -============================================ - -This operation is very like Read Byte; again, data is read from a -device, from a designated register that is specified through the Comm -byte. But this time, the data is a complete word (16 bits). - -S Addr Wr [A] Comm [A] S Addr Rd [A] [DataLow] A [DataHigh] NA P - -Functionality flag: I2C_FUNC_SMBUS_READ_WORD_DATA - -Note the convenience function i2c_smbus_read_word_swapped is -available for reads where the two data bytes are the other way -around (not SMBus compliant, but very popular.) - - -SMBus Write Byte: i2c_smbus_write_byte_data() -============================================== - -This writes a single byte to a device, to a designated register. The -register is specified through the Comm byte. This is the opposite of -the Read Byte operation. - -S Addr Wr [A] Comm [A] Data [A] P - -Functionality flag: I2C_FUNC_SMBUS_WRITE_BYTE_DATA - - -SMBus Write Word: i2c_smbus_write_word_data() -============================================== - -This is the opposite of the Read Word operation. 16 bits -of data is written to a device, to the designated register that is -specified through the Comm byte. - -S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] P - -Functionality flag: I2C_FUNC_SMBUS_WRITE_WORD_DATA - -Note the convenience function i2c_smbus_write_word_swapped is -available for writes where the two data bytes are the other way -around (not SMBus compliant, but very popular.) - - -SMBus Process Call: -=================== - -This command selects a device register (through the Comm byte), sends -16 bits of data to it, and reads 16 bits of data in return. - -S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] - S Addr Rd [A] [DataLow] A [DataHigh] NA P - -Functionality flag: I2C_FUNC_SMBUS_PROC_CALL - - -SMBus Block Read: i2c_smbus_read_block_data() -============================================== - -This command reads a block of up to 32 bytes from a device, from a -designated register that is specified through the Comm byte. The amount -of data is specified by the device in the Count byte. - -S Addr Wr [A] Comm [A] - S Addr Rd [A] [Count] A [Data] A [Data] A ... A [Data] NA P - -Functionality flag: I2C_FUNC_SMBUS_READ_BLOCK_DATA - - -SMBus Block Write: i2c_smbus_write_block_data() -================================================ - -The opposite of the Block Read command, this writes up to 32 bytes to -a device, to a designated register that is specified through the -Comm byte. The amount of data is specified in the Count byte. - -S Addr Wr [A] Comm [A] Count [A] Data [A] Data [A] ... [A] Data [A] P - -Functionality flag: I2C_FUNC_SMBUS_WRITE_BLOCK_DATA - - -SMBus Block Write - Block Read Process Call -=========================================== - -SMBus Block Write - Block Read Process Call was introduced in -Revision 2.0 of the specification. - -This command selects a device register (through the Comm byte), sends -1 to 31 bytes of data to it, and reads 1 to 31 bytes of data in return. - -S Addr Wr [A] Comm [A] Count [A] Data [A] ... - S Addr Rd [A] [Count] A [Data] ... A P - -Functionality flag: I2C_FUNC_SMBUS_BLOCK_PROC_CALL - - -SMBus Host Notify -================= - -This command is sent from a SMBus device acting as a master to the -SMBus host acting as a slave. -It is the same form as Write Word, with the command code replaced by the -alerting device's address. - -[S] [HostAddr] [Wr] A [DevAddr] A [DataLow] A [DataHigh] A [P] - -This is implemented in the following way in the Linux kernel: -* I2C bus drivers which support SMBus Host Notify should report - I2C_FUNC_SMBUS_HOST_NOTIFY. -* I2C bus drivers trigger SMBus Host Notify by a call to - i2c_handle_smbus_host_notify(). -* I2C drivers for devices which can trigger SMBus Host Notify will have - client->irq assigned to a Host Notify IRQ if noone else specified an other. - -There is currently no way to retrieve the data parameter from the client. - - -Packet Error Checking (PEC) -=========================== - -Packet Error Checking was introduced in Revision 1.1 of the specification. - -PEC adds a CRC-8 error-checking byte to transfers using it, immediately -before the terminating STOP. - - -Address Resolution Protocol (ARP) -================================= - -The Address Resolution Protocol was introduced in Revision 2.0 of -the specification. It is a higher-layer protocol which uses the -messages above. - -ARP adds device enumeration and dynamic address assignment to -the protocol. All ARP communications use slave address 0x61 and -require PEC checksums. - - -SMBus Alert -=========== - -SMBus Alert was introduced in Revision 1.0 of the specification. - -The SMBus alert protocol allows several SMBus slave devices to share a -single interrupt pin on the SMBus master, while still allowing the master -to know which slave triggered the interrupt. - -This is implemented the following way in the Linux kernel: -* I2C bus drivers which support SMBus alert should call - i2c_setup_smbus_alert() to setup SMBus alert support. -* I2C drivers for devices which can trigger SMBus alerts should implement - the optional alert() callback. - - -I2C Block Transactions -====================== - -The following I2C block transactions are supported by the -SMBus layer and are described here for completeness. -They are *NOT* defined by the SMBus specification. - -I2C block transactions do not limit the number of bytes transferred -but the SMBus layer places a limit of 32 bytes. - - -I2C Block Read: i2c_smbus_read_i2c_block_data() -================================================ - -This command reads a block of bytes from a device, from a -designated register that is specified through the Comm byte. - -S Addr Wr [A] Comm [A] - S Addr Rd [A] [Data] A [Data] A ... A [Data] NA P - -Functionality flag: I2C_FUNC_SMBUS_READ_I2C_BLOCK - - -I2C Block Write: i2c_smbus_write_i2c_block_data() -================================================== - -The opposite of the Block Read command, this writes bytes to -a device, to a designated register that is specified through the -Comm byte. Note that command lengths of 0, 2, or more bytes are -supported as they are indistinguishable from data. - -S Addr Wr [A] Comm [A] Data [A] Data [A] ... [A] Data [A] P - -Functionality flag: I2C_FUNC_SMBUS_WRITE_I2C_BLOCK diff --git a/Documentation/i2c/smbus-protocol.rst b/Documentation/i2c/smbus-protocol.rst new file mode 100644 index 000000000000..e30eb1d274c6 --- /dev/null +++ b/Documentation/i2c/smbus-protocol.rst @@ -0,0 +1,301 @@ +====================== +SMBus Protocol Summary +====================== + +The following is a summary of the SMBus protocol. It applies to +all revisions of the protocol (1.0, 1.1, and 2.0). +Certain protocol features which are not supported by +this package are briefly described at the end of this document. + +Some adapters understand only the SMBus (System Management Bus) protocol, +which is a subset from the I2C protocol. Fortunately, many devices use +only the same subset, which makes it possible to put them on an SMBus. + +If you write a driver for some I2C device, please try to use the SMBus +commands if at all possible (if the device uses only that subset of the +I2C protocol). This makes it possible to use the device driver on both +SMBus adapters and I2C adapters (the SMBus command set is automatically +translated to I2C on I2C adapters, but plain I2C commands can not be +handled at all on most pure SMBus adapters). + +Below is a list of SMBus protocol operations, and the functions executing +them. Note that the names used in the SMBus protocol specifications usually +don't match these function names. For some of the operations which pass a +single data byte, the functions using SMBus protocol operation names execute +a different protocol operation entirely. + +Each transaction type corresponds to a functionality flag. Before calling a +transaction function, a device driver should always check (just once) for +the corresponding functionality flag to ensure that the underlying I2C +adapter supports the transaction in question. See + for the details. + + +Key to symbols +============== + +=============== ============================================================= +S (1 bit) : Start bit +P (1 bit) : Stop bit +Rd/Wr (1 bit) : Read/Write bit. Rd equals 1, Wr equals 0. +A, NA (1 bit) : Accept and reverse accept bit. +Addr (7 bits): I2C 7 bit address. Note that this can be expanded as usual to + get a 10 bit I2C address. +Comm (8 bits): Command byte, a data byte which often selects a register on + the device. +Data (8 bits): A plain data byte. Sometimes, I write DataLow, DataHigh + for 16 bit data. +Count (8 bits): A data byte containing the length of a block operation. + +[..]: Data sent by I2C device, as opposed to data sent by the host + adapter. +=============== ============================================================= + + +SMBus Quick Command +=================== + +This sends a single bit to the device, at the place of the Rd/Wr bit:: + + A Addr Rd/Wr [A] P + +Functionality flag: I2C_FUNC_SMBUS_QUICK + + +SMBus Receive Byte: i2c_smbus_read_byte() +========================================== + +This reads a single byte from a device, without specifying a device +register. Some devices are so simple that this interface is enough; for +others, it is a shorthand if you want to read the same register as in +the previous SMBus command:: + + S Addr Rd [A] [Data] NA P + +Functionality flag: I2C_FUNC_SMBUS_READ_BYTE + + +SMBus Send Byte: i2c_smbus_write_byte() +======================================== + +This operation is the reverse of Receive Byte: it sends a single byte +to a device. See Receive Byte for more information. + +:: + + S Addr Wr [A] Data [A] P + +Functionality flag: I2C_FUNC_SMBUS_WRITE_BYTE + + +SMBus Read Byte: i2c_smbus_read_byte_data() +============================================ + +This reads a single byte from a device, from a designated register. +The register is specified through the Comm byte:: + + S Addr Wr [A] Comm [A] S Addr Rd [A] [Data] NA P + +Functionality flag: I2C_FUNC_SMBUS_READ_BYTE_DATA + + +SMBus Read Word: i2c_smbus_read_word_data() +============================================ + +This operation is very like Read Byte; again, data is read from a +device, from a designated register that is specified through the Comm +byte. But this time, the data is a complete word (16 bits):: + + S Addr Wr [A] Comm [A] S Addr Rd [A] [DataLow] A [DataHigh] NA P + +Functionality flag: I2C_FUNC_SMBUS_READ_WORD_DATA + +Note the convenience function i2c_smbus_read_word_swapped is +available for reads where the two data bytes are the other way +around (not SMBus compliant, but very popular.) + + +SMBus Write Byte: i2c_smbus_write_byte_data() +============================================== + +This writes a single byte to a device, to a designated register. The +register is specified through the Comm byte. This is the opposite of +the Read Byte operation. + +:: + + S Addr Wr [A] Comm [A] Data [A] P + +Functionality flag: I2C_FUNC_SMBUS_WRITE_BYTE_DATA + + +SMBus Write Word: i2c_smbus_write_word_data() +============================================== + +This is the opposite of the Read Word operation. 16 bits +of data is written to a device, to the designated register that is +specified through the Comm byte.:: + + S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] P + +Functionality flag: I2C_FUNC_SMBUS_WRITE_WORD_DATA + +Note the convenience function i2c_smbus_write_word_swapped is +available for writes where the two data bytes are the other way +around (not SMBus compliant, but very popular.) + + +SMBus Process Call: +=================== + +This command selects a device register (through the Comm byte), sends +16 bits of data to it, and reads 16 bits of data in return:: + + S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] + S Addr Rd [A] [DataLow] A [DataHigh] NA P + +Functionality flag: I2C_FUNC_SMBUS_PROC_CALL + + +SMBus Block Read: i2c_smbus_read_block_data() +============================================== + +This command reads a block of up to 32 bytes from a device, from a +designated register that is specified through the Comm byte. The amount +of data is specified by the device in the Count byte. + +:: + + S Addr Wr [A] Comm [A] + S Addr Rd [A] [Count] A [Data] A [Data] A ... A [Data] NA P + +Functionality flag: I2C_FUNC_SMBUS_READ_BLOCK_DATA + + +SMBus Block Write: i2c_smbus_write_block_data() +================================================ + +The opposite of the Block Read command, this writes up to 32 bytes to +a device, to a designated register that is specified through the +Comm byte. The amount of data is specified in the Count byte. + +:: + + S Addr Wr [A] Comm [A] Count [A] Data [A] Data [A] ... [A] Data [A] P + +Functionality flag: I2C_FUNC_SMBUS_WRITE_BLOCK_DATA + + +SMBus Block Write - Block Read Process Call +=========================================== + +SMBus Block Write - Block Read Process Call was introduced in +Revision 2.0 of the specification. + +This command selects a device register (through the Comm byte), sends +1 to 31 bytes of data to it, and reads 1 to 31 bytes of data in return:: + + S Addr Wr [A] Comm [A] Count [A] Data [A] ... + S Addr Rd [A] [Count] A [Data] ... A P + +Functionality flag: I2C_FUNC_SMBUS_BLOCK_PROC_CALL + + +SMBus Host Notify +================= + +This command is sent from a SMBus device acting as a master to the +SMBus host acting as a slave. +It is the same form as Write Word, with the command code replaced by the +alerting device's address. + +:: + + [S] [HostAddr] [Wr] A [DevAddr] A [DataLow] A [DataHigh] A [P] + +This is implemented in the following way in the Linux kernel: + +* I2C bus drivers which support SMBus Host Notify should report + I2C_FUNC_SMBUS_HOST_NOTIFY. +* I2C bus drivers trigger SMBus Host Notify by a call to + i2c_handle_smbus_host_notify(). +* I2C drivers for devices which can trigger SMBus Host Notify will have + client->irq assigned to a Host Notify IRQ if noone else specified an other. + +There is currently no way to retrieve the data parameter from the client. + + +Packet Error Checking (PEC) +=========================== + +Packet Error Checking was introduced in Revision 1.1 of the specification. + +PEC adds a CRC-8 error-checking byte to transfers using it, immediately +before the terminating STOP. + + +Address Resolution Protocol (ARP) +================================= + +The Address Resolution Protocol was introduced in Revision 2.0 of +the specification. It is a higher-layer protocol which uses the +messages above. + +ARP adds device enumeration and dynamic address assignment to +the protocol. All ARP communications use slave address 0x61 and +require PEC checksums. + + +SMBus Alert +=========== + +SMBus Alert was introduced in Revision 1.0 of the specification. + +The SMBus alert protocol allows several SMBus slave devices to share a +single interrupt pin on the SMBus master, while still allowing the master +to know which slave triggered the interrupt. + +This is implemented the following way in the Linux kernel: + +* I2C bus drivers which support SMBus alert should call + i2c_setup_smbus_alert() to setup SMBus alert support. +* I2C drivers for devices which can trigger SMBus alerts should implement + the optional alert() callback. + + +I2C Block Transactions +====================== + +The following I2C block transactions are supported by the +SMBus layer and are described here for completeness. +They are *NOT* defined by the SMBus specification. + +I2C block transactions do not limit the number of bytes transferred +but the SMBus layer places a limit of 32 bytes. + + +I2C Block Read: i2c_smbus_read_i2c_block_data() +================================================ + +This command reads a block of bytes from a device, from a +designated register that is specified through the Comm byte:: + + S Addr Wr [A] Comm [A] + S Addr Rd [A] [Data] A [Data] A ... A [Data] NA P + +Functionality flag: I2C_FUNC_SMBUS_READ_I2C_BLOCK + + +I2C Block Write: i2c_smbus_write_i2c_block_data() +================================================== + +The opposite of the Block Read command, this writes bytes to +a device, to a designated register that is specified through the +Comm byte. Note that command lengths of 0, 2, or more bytes are +supported as they are indistinguishable from data. + +:: + + S Addr Wr [A] Comm [A] Data [A] Data [A] ... [A] Data [A] P + +Functionality flag: I2C_FUNC_SMBUS_WRITE_I2C_BLOCK diff --git a/Documentation/i2c/summary b/Documentation/i2c/summary deleted file mode 100644 index 809541ab352f..000000000000 --- a/Documentation/i2c/summary +++ /dev/null @@ -1,43 +0,0 @@ -I2C and SMBus -============= - -I2C (pronounce: I squared C) is a protocol developed by Philips. It is a -slow two-wire protocol (variable speed, up to 400 kHz), with a high speed -extension (3.4 MHz). It provides an inexpensive bus for connecting many -types of devices with infrequent or low bandwidth communications needs. -I2C is widely used with embedded systems. Some systems use variants that -don't meet branding requirements, and so are not advertised as being I2C. - -SMBus (System Management Bus) is based on the I2C protocol, and is mostly -a subset of I2C protocols and signaling. Many I2C devices will work on an -SMBus, but some SMBus protocols add semantics beyond what is required to -achieve I2C branding. Modern PC mainboards rely on SMBus. The most common -devices connected through SMBus are RAM modules configured using I2C EEPROMs, -and hardware monitoring chips. - -Because the SMBus is mostly a subset of the generalized I2C bus, we can -use its protocols on many I2C systems. However, there are systems that don't -meet both SMBus and I2C electrical constraints; and others which can't -implement all the common SMBus protocol semantics or messages. - - -Terminology -=========== - -When we talk about I2C, we use the following terms: - Bus -> Algorithm - Adapter - Device -> Driver - Client - -An Algorithm driver contains general code that can be used for a whole class -of I2C adapters. Each specific adapter driver either depends on one algorithm -driver, or includes its own implementation. - -A Driver driver (yes, this sounds ridiculous, sorry) contains the general -code to access some type of device. Each detected device gets its own -data in the Client structure. Usually, Driver and Client are more closely -integrated than Algorithm and Adapter. - -For a given configuration, you will need a driver for your I2C bus, and -drivers for your I2C devices (usually one driver for each device). diff --git a/Documentation/i2c/summary.rst b/Documentation/i2c/summary.rst new file mode 100644 index 000000000000..3a24eac17375 --- /dev/null +++ b/Documentation/i2c/summary.rst @@ -0,0 +1,45 @@ +============= +I2C and SMBus +============= + +I2C (pronounce: I squared C) is a protocol developed by Philips. It is a +slow two-wire protocol (variable speed, up to 400 kHz), with a high speed +extension (3.4 MHz). It provides an inexpensive bus for connecting many +types of devices with infrequent or low bandwidth communications needs. +I2C is widely used with embedded systems. Some systems use variants that +don't meet branding requirements, and so are not advertised as being I2C. + +SMBus (System Management Bus) is based on the I2C protocol, and is mostly +a subset of I2C protocols and signaling. Many I2C devices will work on an +SMBus, but some SMBus protocols add semantics beyond what is required to +achieve I2C branding. Modern PC mainboards rely on SMBus. The most common +devices connected through SMBus are RAM modules configured using I2C EEPROMs, +and hardware monitoring chips. + +Because the SMBus is mostly a subset of the generalized I2C bus, we can +use its protocols on many I2C systems. However, there are systems that don't +meet both SMBus and I2C electrical constraints; and others which can't +implement all the common SMBus protocol semantics or messages. + + +Terminology +=========== + +When we talk about I2C, we use the following terms:: + + Bus -> Algorithm + Adapter + Device -> Driver + Client + +An Algorithm driver contains general code that can be used for a whole class +of I2C adapters. Each specific adapter driver either depends on one algorithm +driver, or includes its own implementation. + +A Driver driver (yes, this sounds ridiculous, sorry) contains the general +code to access some type of device. Each detected device gets its own +data in the Client structure. Usually, Driver and Client are more closely +integrated than Algorithm and Adapter. + +For a given configuration, you will need a driver for your I2C bus, and +drivers for your I2C devices (usually one driver for each device). diff --git a/Documentation/i2c/ten-bit-addresses b/Documentation/i2c/ten-bit-addresses deleted file mode 100644 index 7b2d11e53a49..000000000000 --- a/Documentation/i2c/ten-bit-addresses +++ /dev/null @@ -1,28 +0,0 @@ -The I2C protocol knows about two kinds of device addresses: normal 7 bit -addresses, and an extended set of 10 bit addresses. The sets of addresses -do not intersect: the 7 bit address 0x10 is not the same as the 10 bit -address 0x10 (though a single device could respond to both of them). -To avoid ambiguity, the user sees 10 bit addresses mapped to a different -address space, namely 0xa000-0xa3ff. The leading 0xa (= 10) represents the -10 bit mode. This is used for creating device names in sysfs. It is also -needed when instantiating 10 bit devices via the new_device file in sysfs. - -I2C messages to and from 10-bit address devices have a different format. -See the I2C specification for the details. - -The current 10 bit address support is minimal. It should work, however -you can expect some problems along the way: -* Not all bus drivers support 10-bit addresses. Some don't because the - hardware doesn't support them (SMBus doesn't require 10-bit address - support for example), some don't because nobody bothered adding the - code (or it's there but not working properly.) Software implementation - (i2c-algo-bit) is known to work. -* Some optional features do not support 10-bit addresses. This is the - case of automatic detection and instantiation of devices by their, - drivers, for example. -* Many user-space packages (for example i2c-tools) lack support for - 10-bit addresses. - -Note that 10-bit address devices are still pretty rare, so the limitations -listed above could stay for a long time, maybe even forever if nobody -needs them to be fixed. diff --git a/Documentation/i2c/ten-bit-addresses.rst b/Documentation/i2c/ten-bit-addresses.rst new file mode 100644 index 000000000000..5c765aff16d5 --- /dev/null +++ b/Documentation/i2c/ten-bit-addresses.rst @@ -0,0 +1,33 @@ +===================== +I2C Ten-bit Addresses +===================== + +The I2C protocol knows about two kinds of device addresses: normal 7 bit +addresses, and an extended set of 10 bit addresses. The sets of addresses +do not intersect: the 7 bit address 0x10 is not the same as the 10 bit +address 0x10 (though a single device could respond to both of them). +To avoid ambiguity, the user sees 10 bit addresses mapped to a different +address space, namely 0xa000-0xa3ff. The leading 0xa (= 10) represents the +10 bit mode. This is used for creating device names in sysfs. It is also +needed when instantiating 10 bit devices via the new_device file in sysfs. + +I2C messages to and from 10-bit address devices have a different format. +See the I2C specification for the details. + +The current 10 bit address support is minimal. It should work, however +you can expect some problems along the way: + +* Not all bus drivers support 10-bit addresses. Some don't because the + hardware doesn't support them (SMBus doesn't require 10-bit address + support for example), some don't because nobody bothered adding the + code (or it's there but not working properly.) Software implementation + (i2c-algo-bit) is known to work. +* Some optional features do not support 10-bit addresses. This is the + case of automatic detection and instantiation of devices by their, + drivers, for example. +* Many user-space packages (for example i2c-tools) lack support for + 10-bit addresses. + +Note that 10-bit address devices are still pretty rare, so the limitations +listed above could stay for a long time, maybe even forever if nobody +needs them to be fixed. diff --git a/Documentation/i2c/upgrading-clients b/Documentation/i2c/upgrading-clients deleted file mode 100644 index 96392cc5b5c7..000000000000 --- a/Documentation/i2c/upgrading-clients +++ /dev/null @@ -1,279 +0,0 @@ -Upgrading I2C Drivers to the new 2.6 Driver Model -================================================= - -Ben Dooks - -Introduction ------------- - -This guide outlines how to alter existing Linux 2.6 client drivers from -the old to the new new binding methods. - - -Example old-style driver ------------------------- - - -struct example_state { - struct i2c_client client; - .... -}; - -static struct i2c_driver example_driver; - -static unsigned short ignore[] = { I2C_CLIENT_END }; -static unsigned short normal_addr[] = { OUR_ADDR, I2C_CLIENT_END }; - -I2C_CLIENT_INSMOD; - -static int example_attach(struct i2c_adapter *adap, int addr, int kind) -{ - struct example_state *state; - struct device *dev = &adap->dev; /* to use for dev_ reports */ - int ret; - - state = kzalloc(sizeof(struct example_state), GFP_KERNEL); - if (state == NULL) { - dev_err(dev, "failed to create our state\n"); - return -ENOMEM; - } - - example->client.addr = addr; - example->client.flags = 0; - example->client.adapter = adap; - - i2c_set_clientdata(&state->i2c_client, state); - strscpy(client->i2c_client.name, "example", sizeof(client->i2c_client.name)); - - ret = i2c_attach_client(&state->i2c_client); - if (ret < 0) { - dev_err(dev, "failed to attach client\n"); - kfree(state); - return ret; - } - - dev = &state->i2c_client.dev; - - /* rest of the initialisation goes here. */ - - dev_info(dev, "example client created\n"); - - return 0; -} - -static int example_detach(struct i2c_client *client) -{ - struct example_state *state = i2c_get_clientdata(client); - - i2c_detach_client(client); - kfree(state); - return 0; -} - -static int example_attach_adapter(struct i2c_adapter *adap) -{ - return i2c_probe(adap, &addr_data, example_attach); -} - -static struct i2c_driver example_driver = { - .driver = { - .owner = THIS_MODULE, - .name = "example", - .pm = &example_pm_ops, - }, - .attach_adapter = example_attach_adapter, - .detach_client = example_detach, -}; - - -Updating the client -------------------- - -The new style binding model will check against a list of supported -devices and their associated address supplied by the code registering -the busses. This means that the driver .attach_adapter and -.detach_client methods can be removed, along with the addr_data, -as follows: - -- static struct i2c_driver example_driver; - -- static unsigned short ignore[] = { I2C_CLIENT_END }; -- static unsigned short normal_addr[] = { OUR_ADDR, I2C_CLIENT_END }; - -- I2C_CLIENT_INSMOD; - -- static int example_attach_adapter(struct i2c_adapter *adap) -- { -- return i2c_probe(adap, &addr_data, example_attach); -- } - - static struct i2c_driver example_driver = { -- .attach_adapter = example_attach_adapter, -- .detach_client = example_detach, - } - -Add the probe and remove methods to the i2c_driver, as so: - - static struct i2c_driver example_driver = { -+ .probe = example_probe, -+ .remove = example_remove, - } - -Change the example_attach method to accept the new parameters -which include the i2c_client that it will be working with: - -- static int example_attach(struct i2c_adapter *adap, int addr, int kind) -+ static int example_probe(struct i2c_client *client, -+ const struct i2c_device_id *id) - -Change the name of example_attach to example_probe to align it with the -i2c_driver entry names. The rest of the probe routine will now need to be -changed as the i2c_client has already been setup for use. - -The necessary client fields have already been setup before -the probe function is called, so the following client setup -can be removed: - -- example->client.addr = addr; -- example->client.flags = 0; -- example->client.adapter = adap; -- -- strscpy(client->i2c_client.name, "example", sizeof(client->i2c_client.name)); - -The i2c_set_clientdata is now: - -- i2c_set_clientdata(&state->client, state); -+ i2c_set_clientdata(client, state); - -The call to i2c_attach_client is no longer needed, if the probe -routine exits successfully, then the driver will be automatically -attached by the core. Change the probe routine as so: - -- ret = i2c_attach_client(&state->i2c_client); -- if (ret < 0) { -- dev_err(dev, "failed to attach client\n"); -- kfree(state); -- return ret; -- } - - -Remove the storage of 'struct i2c_client' from the 'struct example_state' -as we are provided with the i2c_client in our example_probe. Instead we -store a pointer to it for when it is needed. - -struct example_state { -- struct i2c_client client; -+ struct i2c_client *client; - -the new i2c client as so: - -- struct device *dev = &adap->dev; /* to use for dev_ reports */ -+ struct device *dev = &i2c_client->dev; /* to use for dev_ reports */ - -And remove the change after our client is attached, as the driver no -longer needs to register a new client structure with the core: - -- dev = &state->i2c_client.dev; - -In the probe routine, ensure that the new state has the client stored -in it: - -static int example_probe(struct i2c_client *i2c_client, - const struct i2c_device_id *id) -{ - struct example_state *state; - struct device *dev = &i2c_client->dev; - int ret; - - state = kzalloc(sizeof(struct example_state), GFP_KERNEL); - if (state == NULL) { - dev_err(dev, "failed to create our state\n"); - return -ENOMEM; - } - -+ state->client = i2c_client; - -Update the detach method, by changing the name to _remove and -to delete the i2c_detach_client call. It is possible that you -can also remove the ret variable as it is not needed for any -of the core functions. - -- static int example_detach(struct i2c_client *client) -+ static int example_remove(struct i2c_client *client) -{ - struct example_state *state = i2c_get_clientdata(client); - -- i2c_detach_client(client); - -And finally ensure that we have the correct ID table for the i2c-core -and other utilities: - -+ struct i2c_device_id example_idtable[] = { -+ { "example", 0 }, -+ { } -+}; -+ -+MODULE_DEVICE_TABLE(i2c, example_idtable); - -static struct i2c_driver example_driver = { - .driver = { - .owner = THIS_MODULE, - .name = "example", - }, -+ .id_table = example_ids, - - -Our driver should now look like this: - -struct example_state { - struct i2c_client *client; - .... -}; - -static int example_probe(struct i2c_client *client, - const struct i2c_device_id *id) -{ - struct example_state *state; - struct device *dev = &client->dev; - - state = kzalloc(sizeof(struct example_state), GFP_KERNEL); - if (state == NULL) { - dev_err(dev, "failed to create our state\n"); - return -ENOMEM; - } - - state->client = client; - i2c_set_clientdata(client, state); - - /* rest of the initialisation goes here. */ - - dev_info(dev, "example client created\n"); - - return 0; -} - -static int example_remove(struct i2c_client *client) -{ - struct example_state *state = i2c_get_clientdata(client); - - kfree(state); - return 0; -} - -static struct i2c_device_id example_idtable[] = { - { "example", 0 }, - { } -}; - -MODULE_DEVICE_TABLE(i2c, example_idtable); - -static struct i2c_driver example_driver = { - .driver = { - .owner = THIS_MODULE, - .name = "example", - .pm = &example_pm_ops, - }, - .id_table = example_idtable, - .probe = example_probe, - .remove = example_remove, -}; diff --git a/Documentation/i2c/upgrading-clients.rst b/Documentation/i2c/upgrading-clients.rst new file mode 100644 index 000000000000..27d29032c138 --- /dev/null +++ b/Documentation/i2c/upgrading-clients.rst @@ -0,0 +1,285 @@ +================================================= +Upgrading I2C Drivers to the new 2.6 Driver Model +================================================= + +Ben Dooks + +Introduction +------------ + +This guide outlines how to alter existing Linux 2.6 client drivers from +the old to the new new binding methods. + + +Example old-style driver +------------------------ + +:: + + struct example_state { + struct i2c_client client; + .... + }; + + static struct i2c_driver example_driver; + + static unsigned short ignore[] = { I2C_CLIENT_END }; + static unsigned short normal_addr[] = { OUR_ADDR, I2C_CLIENT_END }; + + I2C_CLIENT_INSMOD; + + static int example_attach(struct i2c_adapter *adap, int addr, int kind) + { + struct example_state *state; + struct device *dev = &adap->dev; /* to use for dev_ reports */ + int ret; + + state = kzalloc(sizeof(struct example_state), GFP_KERNEL); + if (state == NULL) { + dev_err(dev, "failed to create our state\n"); + return -ENOMEM; + } + + example->client.addr = addr; + example->client.flags = 0; + example->client.adapter = adap; + + i2c_set_clientdata(&state->i2c_client, state); + strscpy(client->i2c_client.name, "example", sizeof(client->i2c_client.name)); + + ret = i2c_attach_client(&state->i2c_client); + if (ret < 0) { + dev_err(dev, "failed to attach client\n"); + kfree(state); + return ret; + } + + dev = &state->i2c_client.dev; + + /* rest of the initialisation goes here. */ + + dev_info(dev, "example client created\n"); + + return 0; + } + + static int example_detach(struct i2c_client *client) + { + struct example_state *state = i2c_get_clientdata(client); + + i2c_detach_client(client); + kfree(state); + return 0; + } + + static int example_attach_adapter(struct i2c_adapter *adap) + { + return i2c_probe(adap, &addr_data, example_attach); + } + + static struct i2c_driver example_driver = { + .driver = { + .owner = THIS_MODULE, + .name = "example", + .pm = &example_pm_ops, + }, + .attach_adapter = example_attach_adapter, + .detach_client = example_detach, + }; + + +Updating the client +------------------- + +The new style binding model will check against a list of supported +devices and their associated address supplied by the code registering +the busses. This means that the driver .attach_adapter and +.detach_client methods can be removed, along with the addr_data, +as follows:: + + - static struct i2c_driver example_driver; + + - static unsigned short ignore[] = { I2C_CLIENT_END }; + - static unsigned short normal_addr[] = { OUR_ADDR, I2C_CLIENT_END }; + + - I2C_CLIENT_INSMOD; + + - static int example_attach_adapter(struct i2c_adapter *adap) + - { + - return i2c_probe(adap, &addr_data, example_attach); + - } + + static struct i2c_driver example_driver = { + - .attach_adapter = example_attach_adapter, + - .detach_client = example_detach, + } + +Add the probe and remove methods to the i2c_driver, as so:: + + static struct i2c_driver example_driver = { + + .probe = example_probe, + + .remove = example_remove, + } + +Change the example_attach method to accept the new parameters +which include the i2c_client that it will be working with:: + + - static int example_attach(struct i2c_adapter *adap, int addr, int kind) + + static int example_probe(struct i2c_client *client, + + const struct i2c_device_id *id) + +Change the name of example_attach to example_probe to align it with the +i2c_driver entry names. The rest of the probe routine will now need to be +changed as the i2c_client has already been setup for use. + +The necessary client fields have already been setup before +the probe function is called, so the following client setup +can be removed:: + + - example->client.addr = addr; + - example->client.flags = 0; + - example->client.adapter = adap; + - + - strscpy(client->i2c_client.name, "example", sizeof(client->i2c_client.name)); + +The i2c_set_clientdata is now:: + + - i2c_set_clientdata(&state->client, state); + + i2c_set_clientdata(client, state); + +The call to i2c_attach_client is no longer needed, if the probe +routine exits successfully, then the driver will be automatically +attached by the core. Change the probe routine as so:: + + - ret = i2c_attach_client(&state->i2c_client); + - if (ret < 0) { + - dev_err(dev, "failed to attach client\n"); + - kfree(state); + - return ret; + - } + + +Remove the storage of 'struct i2c_client' from the 'struct example_state' +as we are provided with the i2c_client in our example_probe. Instead we +store a pointer to it for when it is needed. + +:: + + struct example_state { + - struct i2c_client client; + + struct i2c_client *client; + +the new i2c client as so:: + + - struct device *dev = &adap->dev; /* to use for dev_ reports */ + + struct device *dev = &i2c_client->dev; /* to use for dev_ reports */ + +And remove the change after our client is attached, as the driver no +longer needs to register a new client structure with the core:: + + - dev = &state->i2c_client.dev; + +In the probe routine, ensure that the new state has the client stored +in it:: + + static int example_probe(struct i2c_client *i2c_client, + const struct i2c_device_id *id) + { + struct example_state *state; + struct device *dev = &i2c_client->dev; + int ret; + + state = kzalloc(sizeof(struct example_state), GFP_KERNEL); + if (state == NULL) { + dev_err(dev, "failed to create our state\n"); + return -ENOMEM; + } + + + state->client = i2c_client; + +Update the detach method, by changing the name to _remove and +to delete the i2c_detach_client call. It is possible that you +can also remove the ret variable as it is not needed for any +of the core functions. + +:: + + - static int example_detach(struct i2c_client *client) + + static int example_remove(struct i2c_client *client) + { + struct example_state *state = i2c_get_clientdata(client); + + - i2c_detach_client(client); + +And finally ensure that we have the correct ID table for the i2c-core +and other utilities:: + + + struct i2c_device_id example_idtable[] = { + + { "example", 0 }, + + { } + +}; + + + +MODULE_DEVICE_TABLE(i2c, example_idtable); + + static struct i2c_driver example_driver = { + .driver = { + .owner = THIS_MODULE, + .name = "example", + }, + + .id_table = example_ids, + + +Our driver should now look like this:: + + struct example_state { + struct i2c_client *client; + .... + }; + + static int example_probe(struct i2c_client *client, + const struct i2c_device_id *id) + { + struct example_state *state; + struct device *dev = &client->dev; + + state = kzalloc(sizeof(struct example_state), GFP_KERNEL); + if (state == NULL) { + dev_err(dev, "failed to create our state\n"); + return -ENOMEM; + } + + state->client = client; + i2c_set_clientdata(client, state); + + /* rest of the initialisation goes here. */ + + dev_info(dev, "example client created\n"); + + return 0; + } + + static int example_remove(struct i2c_client *client) + { + struct example_state *state = i2c_get_clientdata(client); + + kfree(state); + return 0; + } + + static struct i2c_device_id example_idtable[] = { + { "example", 0 }, + { } + }; + + MODULE_DEVICE_TABLE(i2c, example_idtable); + + static struct i2c_driver example_driver = { + .driver = { + .owner = THIS_MODULE, + .name = "example", + .pm = &example_pm_ops, + }, + .id_table = example_idtable, + .probe = example_probe, + .remove = example_remove, + }; diff --git a/Documentation/i2c/writing-clients b/Documentation/i2c/writing-clients deleted file mode 100644 index a755b141fa4a..000000000000 --- a/Documentation/i2c/writing-clients +++ /dev/null @@ -1,403 +0,0 @@ -This is a small guide for those who want to write kernel drivers for I2C -or SMBus devices, using Linux as the protocol host/master (not slave). - -To set up a driver, you need to do several things. Some are optional, and -some things can be done slightly or completely different. Use this as a -guide, not as a rule book! - - -General remarks -=============== - -Try to keep the kernel namespace as clean as possible. The best way to -do this is to use a unique prefix for all global symbols. This is -especially important for exported symbols, but it is a good idea to do -it for non-exported symbols too. We will use the prefix `foo_' in this -tutorial. - - -The driver structure -==================== - -Usually, you will implement a single driver structure, and instantiate -all clients from it. Remember, a driver structure contains general access -routines, and should be zero-initialized except for fields with data you -provide. A client structure holds device-specific information like the -driver model device node, and its I2C address. - -static struct i2c_device_id foo_idtable[] = { - { "foo", my_id_for_foo }, - { "bar", my_id_for_bar }, - { } -}; - -MODULE_DEVICE_TABLE(i2c, foo_idtable); - -static struct i2c_driver foo_driver = { - .driver = { - .name = "foo", - .pm = &foo_pm_ops, /* optional */ - }, - - .id_table = foo_idtable, - .probe = foo_probe, - .remove = foo_remove, - /* if device autodetection is needed: */ - .class = I2C_CLASS_SOMETHING, - .detect = foo_detect, - .address_list = normal_i2c, - - .shutdown = foo_shutdown, /* optional */ - .command = foo_command, /* optional, deprecated */ -} - -The name field is the driver name, and must not contain spaces. It -should match the module name (if the driver can be compiled as a module), -although you can use MODULE_ALIAS (passing "foo" in this example) to add -another name for the module. If the driver name doesn't match the module -name, the module won't be automatically loaded (hotplug/coldplug). - -All other fields are for call-back functions which will be explained -below. - - -Extra client data -================= - -Each client structure has a special `data' field that can point to any -structure at all. You should use this to keep device-specific data. - - /* store the value */ - void i2c_set_clientdata(struct i2c_client *client, void *data); - - /* retrieve the value */ - void *i2c_get_clientdata(const struct i2c_client *client); - -Note that starting with kernel 2.6.34, you don't have to set the `data' field -to NULL in remove() or if probe() failed anymore. The i2c-core does this -automatically on these occasions. Those are also the only times the core will -touch this field. - - -Accessing the client -==================== - -Let's say we have a valid client structure. At some time, we will need -to gather information from the client, or write new information to the -client. - -I have found it useful to define foo_read and foo_write functions for this. -For some cases, it will be easier to call the i2c functions directly, -but many chips have some kind of register-value idea that can easily -be encapsulated. - -The below functions are simple examples, and should not be copied -literally. - -int foo_read_value(struct i2c_client *client, u8 reg) -{ - if (reg < 0x10) /* byte-sized register */ - return i2c_smbus_read_byte_data(client, reg); - else /* word-sized register */ - return i2c_smbus_read_word_data(client, reg); -} - -int foo_write_value(struct i2c_client *client, u8 reg, u16 value) -{ - if (reg == 0x10) /* Impossible to write - driver error! */ - return -EINVAL; - else if (reg < 0x10) /* byte-sized register */ - return i2c_smbus_write_byte_data(client, reg, value); - else /* word-sized register */ - return i2c_smbus_write_word_data(client, reg, value); -} - - -Probing and attaching -===================== - -The Linux I2C stack was originally written to support access to hardware -monitoring chips on PC motherboards, and thus used to embed some assumptions -that were more appropriate to SMBus (and PCs) than to I2C. One of these -assumptions was that most adapters and devices drivers support the SMBUS_QUICK -protocol to probe device presence. Another was that devices and their drivers -can be sufficiently configured using only such probe primitives. - -As Linux and its I2C stack became more widely used in embedded systems -and complex components such as DVB adapters, those assumptions became more -problematic. Drivers for I2C devices that issue interrupts need more (and -different) configuration information, as do drivers handling chip variants -that can't be distinguished by protocol probing, or which need some board -specific information to operate correctly. - - -Device/Driver Binding ---------------------- - -System infrastructure, typically board-specific initialization code or -boot firmware, reports what I2C devices exist. For example, there may be -a table, in the kernel or from the boot loader, identifying I2C devices -and linking them to board-specific configuration information about IRQs -and other wiring artifacts, chip type, and so on. That could be used to -create i2c_client objects for each I2C device. - -I2C device drivers using this binding model work just like any other -kind of driver in Linux: they provide a probe() method to bind to -those devices, and a remove() method to unbind. - - static int foo_probe(struct i2c_client *client, - const struct i2c_device_id *id); - static int foo_remove(struct i2c_client *client); - -Remember that the i2c_driver does not create those client handles. The -handle may be used during foo_probe(). If foo_probe() reports success -(zero not a negative status code) it may save the handle and use it until -foo_remove() returns. That binding model is used by most Linux drivers. - -The probe function is called when an entry in the id_table name field -matches the device's name. It is passed the entry that was matched so -the driver knows which one in the table matched. - - -Device Creation ---------------- - -If you know for a fact that an I2C device is connected to a given I2C bus, -you can instantiate that device by simply filling an i2c_board_info -structure with the device address and driver name, and calling -i2c_new_device(). This will create the device, then the driver core will -take care of finding the right driver and will call its probe() method. -If a driver supports different device types, you can specify the type you -want using the type field. You can also specify an IRQ and platform data -if needed. - -Sometimes you know that a device is connected to a given I2C bus, but you -don't know the exact address it uses. This happens on TV adapters for -example, where the same driver supports dozens of slightly different -models, and I2C device addresses change from one model to the next. In -that case, you can use the i2c_new_probed_device() variant, which is -similar to i2c_new_device(), except that it takes an additional list of -possible I2C addresses to probe. A device is created for the first -responsive address in the list. If you expect more than one device to be -present in the address range, simply call i2c_new_probed_device() that -many times. - -The call to i2c_new_device() or i2c_new_probed_device() typically happens -in the I2C bus driver. You may want to save the returned i2c_client -reference for later use. - - -Device Detection ----------------- - -Sometimes you do not know in advance which I2C devices are connected to -a given I2C bus. This is for example the case of hardware monitoring -devices on a PC's SMBus. In that case, you may want to let your driver -detect supported devices automatically. This is how the legacy model -was working, and is now available as an extension to the standard -driver model. - -You simply have to define a detect callback which will attempt to -identify supported devices (returning 0 for supported ones and -ENODEV -for unsupported ones), a list of addresses to probe, and a device type -(or class) so that only I2C buses which may have that type of device -connected (and not otherwise enumerated) will be probed. For example, -a driver for a hardware monitoring chip for which auto-detection is -needed would set its class to I2C_CLASS_HWMON, and only I2C adapters -with a class including I2C_CLASS_HWMON would be probed by this driver. -Note that the absence of matching classes does not prevent the use of -a device of that type on the given I2C adapter. All it prevents is -auto-detection; explicit instantiation of devices is still possible. - -Note that this mechanism is purely optional and not suitable for all -devices. You need some reliable way to identify the supported devices -(typically using device-specific, dedicated identification registers), -otherwise misdetections are likely to occur and things can get wrong -quickly. Keep in mind that the I2C protocol doesn't include any -standard way to detect the presence of a chip at a given address, let -alone a standard way to identify devices. Even worse is the lack of -semantics associated to bus transfers, which means that the same -transfer can be seen as a read operation by a chip and as a write -operation by another chip. For these reasons, explicit device -instantiation should always be preferred to auto-detection where -possible. - - -Device Deletion ---------------- - -Each I2C device which has been created using i2c_new_device() or -i2c_new_probed_device() can be unregistered by calling -i2c_unregister_device(). If you don't call it explicitly, it will be -called automatically before the underlying I2C bus itself is removed, as a -device can't survive its parent in the device driver model. - - -Initializing the driver -======================= - -When the kernel is booted, or when your foo driver module is inserted, -you have to do some initializing. Fortunately, just registering the -driver module is usually enough. - -static int __init foo_init(void) -{ - return i2c_add_driver(&foo_driver); -} -module_init(foo_init); - -static void __exit foo_cleanup(void) -{ - i2c_del_driver(&foo_driver); -} -module_exit(foo_cleanup); - -The module_i2c_driver() macro can be used to reduce above code. - -module_i2c_driver(foo_driver); - -Note that some functions are marked by `__init'. These functions can -be removed after kernel booting (or module loading) is completed. -Likewise, functions marked by `__exit' are dropped by the compiler when -the code is built into the kernel, as they would never be called. - - -Driver Information -================== - -/* Substitute your own name and email address */ -MODULE_AUTHOR("Frodo Looijaard " -MODULE_DESCRIPTION("Driver for Barf Inc. Foo I2C devices"); - -/* a few non-GPL license types are also allowed */ -MODULE_LICENSE("GPL"); - - -Power Management -================ - -If your I2C device needs special handling when entering a system low -power state -- like putting a transceiver into a low power mode, or -activating a system wakeup mechanism -- do that by implementing the -appropriate callbacks for the dev_pm_ops of the driver (like suspend -and resume). - -These are standard driver model calls, and they work just like they -would for any other driver stack. The calls can sleep, and can use -I2C messaging to the device being suspended or resumed (since their -parent I2C adapter is active when these calls are issued, and IRQs -are still enabled). - - -System Shutdown -=============== - -If your I2C device needs special handling when the system shuts down -or reboots (including kexec) -- like turning something off -- use a -shutdown() method. - -Again, this is a standard driver model call, working just like it -would for any other driver stack: the calls can sleep, and can use -I2C messaging. - - -Command function -================ - -A generic ioctl-like function call back is supported. You will seldom -need this, and its use is deprecated anyway, so newer design should not -use it. - - -Sending and receiving -===================== - -If you want to communicate with your device, there are several functions -to do this. You can find all of them in . - -If you can choose between plain I2C communication and SMBus level -communication, please use the latter. All adapters understand SMBus level -commands, but only some of them understand plain I2C! - - -Plain I2C communication ------------------------ - - int i2c_master_send(struct i2c_client *client, const char *buf, - int count); - int i2c_master_recv(struct i2c_client *client, char *buf, int count); - -These routines read and write some bytes from/to a client. The client -contains the i2c address, so you do not have to include it. The second -parameter contains the bytes to read/write, the third the number of bytes -to read/write (must be less than the length of the buffer, also should be -less than 64k since msg.len is u16.) Returned is the actual number of bytes -read/written. - - int i2c_transfer(struct i2c_adapter *adap, struct i2c_msg *msg, - int num); - -This sends a series of messages. Each message can be a read or write, -and they can be mixed in any way. The transactions are combined: no -stop bit is sent between transaction. The i2c_msg structure contains -for each message the client address, the number of bytes of the message -and the message data itself. - -You can read the file `i2c-protocol' for more information about the -actual I2C protocol. - - -SMBus communication -------------------- - - s32 i2c_smbus_xfer(struct i2c_adapter *adapter, u16 addr, - unsigned short flags, char read_write, u8 command, - int size, union i2c_smbus_data *data); - -This is the generic SMBus function. All functions below are implemented -in terms of it. Never use this function directly! - - s32 i2c_smbus_read_byte(struct i2c_client *client); - s32 i2c_smbus_write_byte(struct i2c_client *client, u8 value); - s32 i2c_smbus_read_byte_data(struct i2c_client *client, u8 command); - s32 i2c_smbus_write_byte_data(struct i2c_client *client, - u8 command, u8 value); - s32 i2c_smbus_read_word_data(struct i2c_client *client, u8 command); - s32 i2c_smbus_write_word_data(struct i2c_client *client, - u8 command, u16 value); - s32 i2c_smbus_read_block_data(struct i2c_client *client, - u8 command, u8 *values); - s32 i2c_smbus_write_block_data(struct i2c_client *client, - u8 command, u8 length, const u8 *values); - s32 i2c_smbus_read_i2c_block_data(struct i2c_client *client, - u8 command, u8 length, u8 *values); - s32 i2c_smbus_write_i2c_block_data(struct i2c_client *client, - u8 command, u8 length, - const u8 *values); - -These ones were removed from i2c-core because they had no users, but could -be added back later if needed: - - s32 i2c_smbus_write_quick(struct i2c_client *client, u8 value); - s32 i2c_smbus_process_call(struct i2c_client *client, - u8 command, u16 value); - s32 i2c_smbus_block_process_call(struct i2c_client *client, - u8 command, u8 length, u8 *values); - -All these transactions return a negative errno value on failure. The 'write' -transactions return 0 on success; the 'read' transactions return the read -value, except for block transactions, which return the number of values -read. The block buffers need not be longer than 32 bytes. - -You can read the file `smbus-protocol' for more information about the -actual SMBus protocol. - - -General purpose routines -======================== - -Below all general purpose routines are listed, that were not mentioned -before. - - /* Return the adapter number for a specific adapter */ - int i2c_adapter_id(struct i2c_adapter *adap); diff --git a/Documentation/i2c/writing-clients.rst b/Documentation/i2c/writing-clients.rst new file mode 100644 index 000000000000..dddf0a14ab7c --- /dev/null +++ b/Documentation/i2c/writing-clients.rst @@ -0,0 +1,425 @@ +=================== +Writing I2C Clients +=================== + +This is a small guide for those who want to write kernel drivers for I2C +or SMBus devices, using Linux as the protocol host/master (not slave). + +To set up a driver, you need to do several things. Some are optional, and +some things can be done slightly or completely different. Use this as a +guide, not as a rule book! + + +General remarks +=============== + +Try to keep the kernel namespace as clean as possible. The best way to +do this is to use a unique prefix for all global symbols. This is +especially important for exported symbols, but it is a good idea to do +it for non-exported symbols too. We will use the prefix ``foo_`` in this +tutorial. + + +The driver structure +==================== + +Usually, you will implement a single driver structure, and instantiate +all clients from it. Remember, a driver structure contains general access +routines, and should be zero-initialized except for fields with data you +provide. A client structure holds device-specific information like the +driver model device node, and its I2C address. + +:: + + static struct i2c_device_id foo_idtable[] = { + { "foo", my_id_for_foo }, + { "bar", my_id_for_bar }, + { } + }; + + MODULE_DEVICE_TABLE(i2c, foo_idtable); + + static struct i2c_driver foo_driver = { + .driver = { + .name = "foo", + .pm = &foo_pm_ops, /* optional */ + }, + + .id_table = foo_idtable, + .probe = foo_probe, + .remove = foo_remove, + /* if device autodetection is needed: */ + .class = I2C_CLASS_SOMETHING, + .detect = foo_detect, + .address_list = normal_i2c, + + .shutdown = foo_shutdown, /* optional */ + .command = foo_command, /* optional, deprecated */ + } + +The name field is the driver name, and must not contain spaces. It +should match the module name (if the driver can be compiled as a module), +although you can use MODULE_ALIAS (passing "foo" in this example) to add +another name for the module. If the driver name doesn't match the module +name, the module won't be automatically loaded (hotplug/coldplug). + +All other fields are for call-back functions which will be explained +below. + + +Extra client data +================= + +Each client structure has a special ``data`` field that can point to any +structure at all. You should use this to keep device-specific data. + +:: + + /* store the value */ + void i2c_set_clientdata(struct i2c_client *client, void *data); + + /* retrieve the value */ + void *i2c_get_clientdata(const struct i2c_client *client); + +Note that starting with kernel 2.6.34, you don't have to set the ``data`` field +to NULL in remove() or if probe() failed anymore. The i2c-core does this +automatically on these occasions. Those are also the only times the core will +touch this field. + + +Accessing the client +==================== + +Let's say we have a valid client structure. At some time, we will need +to gather information from the client, or write new information to the +client. + +I have found it useful to define foo_read and foo_write functions for this. +For some cases, it will be easier to call the i2c functions directly, +but many chips have some kind of register-value idea that can easily +be encapsulated. + +The below functions are simple examples, and should not be copied +literally:: + + int foo_read_value(struct i2c_client *client, u8 reg) + { + if (reg < 0x10) /* byte-sized register */ + return i2c_smbus_read_byte_data(client, reg); + else /* word-sized register */ + return i2c_smbus_read_word_data(client, reg); + } + + int foo_write_value(struct i2c_client *client, u8 reg, u16 value) + { + if (reg == 0x10) /* Impossible to write - driver error! */ + return -EINVAL; + else if (reg < 0x10) /* byte-sized register */ + return i2c_smbus_write_byte_data(client, reg, value); + else /* word-sized register */ + return i2c_smbus_write_word_data(client, reg, value); + } + + +Probing and attaching +===================== + +The Linux I2C stack was originally written to support access to hardware +monitoring chips on PC motherboards, and thus used to embed some assumptions +that were more appropriate to SMBus (and PCs) than to I2C. One of these +assumptions was that most adapters and devices drivers support the SMBUS_QUICK +protocol to probe device presence. Another was that devices and their drivers +can be sufficiently configured using only such probe primitives. + +As Linux and its I2C stack became more widely used in embedded systems +and complex components such as DVB adapters, those assumptions became more +problematic. Drivers for I2C devices that issue interrupts need more (and +different) configuration information, as do drivers handling chip variants +that can't be distinguished by protocol probing, or which need some board +specific information to operate correctly. + + +Device/Driver Binding +--------------------- + +System infrastructure, typically board-specific initialization code or +boot firmware, reports what I2C devices exist. For example, there may be +a table, in the kernel or from the boot loader, identifying I2C devices +and linking them to board-specific configuration information about IRQs +and other wiring artifacts, chip type, and so on. That could be used to +create i2c_client objects for each I2C device. + +I2C device drivers using this binding model work just like any other +kind of driver in Linux: they provide a probe() method to bind to +those devices, and a remove() method to unbind. + +:: + + static int foo_probe(struct i2c_client *client, + const struct i2c_device_id *id); + static int foo_remove(struct i2c_client *client); + +Remember that the i2c_driver does not create those client handles. The +handle may be used during foo_probe(). If foo_probe() reports success +(zero not a negative status code) it may save the handle and use it until +foo_remove() returns. That binding model is used by most Linux drivers. + +The probe function is called when an entry in the id_table name field +matches the device's name. It is passed the entry that was matched so +the driver knows which one in the table matched. + + +Device Creation +--------------- + +If you know for a fact that an I2C device is connected to a given I2C bus, +you can instantiate that device by simply filling an i2c_board_info +structure with the device address and driver name, and calling +i2c_new_device(). This will create the device, then the driver core will +take care of finding the right driver and will call its probe() method. +If a driver supports different device types, you can specify the type you +want using the type field. You can also specify an IRQ and platform data +if needed. + +Sometimes you know that a device is connected to a given I2C bus, but you +don't know the exact address it uses. This happens on TV adapters for +example, where the same driver supports dozens of slightly different +models, and I2C device addresses change from one model to the next. In +that case, you can use the i2c_new_probed_device() variant, which is +similar to i2c_new_device(), except that it takes an additional list of +possible I2C addresses to probe. A device is created for the first +responsive address in the list. If you expect more than one device to be +present in the address range, simply call i2c_new_probed_device() that +many times. + +The call to i2c_new_device() or i2c_new_probed_device() typically happens +in the I2C bus driver. You may want to save the returned i2c_client +reference for later use. + + +Device Detection +---------------- + +Sometimes you do not know in advance which I2C devices are connected to +a given I2C bus. This is for example the case of hardware monitoring +devices on a PC's SMBus. In that case, you may want to let your driver +detect supported devices automatically. This is how the legacy model +was working, and is now available as an extension to the standard +driver model. + +You simply have to define a detect callback which will attempt to +identify supported devices (returning 0 for supported ones and -ENODEV +for unsupported ones), a list of addresses to probe, and a device type +(or class) so that only I2C buses which may have that type of device +connected (and not otherwise enumerated) will be probed. For example, +a driver for a hardware monitoring chip for which auto-detection is +needed would set its class to I2C_CLASS_HWMON, and only I2C adapters +with a class including I2C_CLASS_HWMON would be probed by this driver. +Note that the absence of matching classes does not prevent the use of +a device of that type on the given I2C adapter. All it prevents is +auto-detection; explicit instantiation of devices is still possible. + +Note that this mechanism is purely optional and not suitable for all +devices. You need some reliable way to identify the supported devices +(typically using device-specific, dedicated identification registers), +otherwise misdetections are likely to occur and things can get wrong +quickly. Keep in mind that the I2C protocol doesn't include any +standard way to detect the presence of a chip at a given address, let +alone a standard way to identify devices. Even worse is the lack of +semantics associated to bus transfers, which means that the same +transfer can be seen as a read operation by a chip and as a write +operation by another chip. For these reasons, explicit device +instantiation should always be preferred to auto-detection where +possible. + + +Device Deletion +--------------- + +Each I2C device which has been created using i2c_new_device() or +i2c_new_probed_device() can be unregistered by calling +i2c_unregister_device(). If you don't call it explicitly, it will be +called automatically before the underlying I2C bus itself is removed, as a +device can't survive its parent in the device driver model. + + +Initializing the driver +======================= + +When the kernel is booted, or when your foo driver module is inserted, +you have to do some initializing. Fortunately, just registering the +driver module is usually enough. + +:: + + static int __init foo_init(void) + { + return i2c_add_driver(&foo_driver); + } + module_init(foo_init); + + static void __exit foo_cleanup(void) + { + i2c_del_driver(&foo_driver); + } + module_exit(foo_cleanup); + + The module_i2c_driver() macro can be used to reduce above code. + + module_i2c_driver(foo_driver); + +Note that some functions are marked by ``__init``. These functions can +be removed after kernel booting (or module loading) is completed. +Likewise, functions marked by ``__exit`` are dropped by the compiler when +the code is built into the kernel, as they would never be called. + + +Driver Information +================== + +:: + + /* Substitute your own name and email address */ + MODULE_AUTHOR("Frodo Looijaard " + MODULE_DESCRIPTION("Driver for Barf Inc. Foo I2C devices"); + + /* a few non-GPL license types are also allowed */ + MODULE_LICENSE("GPL"); + + +Power Management +================ + +If your I2C device needs special handling when entering a system low +power state -- like putting a transceiver into a low power mode, or +activating a system wakeup mechanism -- do that by implementing the +appropriate callbacks for the dev_pm_ops of the driver (like suspend +and resume). + +These are standard driver model calls, and they work just like they +would for any other driver stack. The calls can sleep, and can use +I2C messaging to the device being suspended or resumed (since their +parent I2C adapter is active when these calls are issued, and IRQs +are still enabled). + + +System Shutdown +=============== + +If your I2C device needs special handling when the system shuts down +or reboots (including kexec) -- like turning something off -- use a +shutdown() method. + +Again, this is a standard driver model call, working just like it +would for any other driver stack: the calls can sleep, and can use +I2C messaging. + + +Command function +================ + +A generic ioctl-like function call back is supported. You will seldom +need this, and its use is deprecated anyway, so newer design should not +use it. + + +Sending and receiving +===================== + +If you want to communicate with your device, there are several functions +to do this. You can find all of them in . + +If you can choose between plain I2C communication and SMBus level +communication, please use the latter. All adapters understand SMBus level +commands, but only some of them understand plain I2C! + + +Plain I2C communication +----------------------- + +:: + + int i2c_master_send(struct i2c_client *client, const char *buf, + int count); + int i2c_master_recv(struct i2c_client *client, char *buf, int count); + +These routines read and write some bytes from/to a client. The client +contains the i2c address, so you do not have to include it. The second +parameter contains the bytes to read/write, the third the number of bytes +to read/write (must be less than the length of the buffer, also should be +less than 64k since msg.len is u16.) Returned is the actual number of bytes +read/written. + +:: + + int i2c_transfer(struct i2c_adapter *adap, struct i2c_msg *msg, + int num); + +This sends a series of messages. Each message can be a read or write, +and they can be mixed in any way. The transactions are combined: no +stop bit is sent between transaction. The i2c_msg structure contains +for each message the client address, the number of bytes of the message +and the message data itself. + +You can read the file ``i2c-protocol`` for more information about the +actual I2C protocol. + + +SMBus communication +------------------- + +:: + + s32 i2c_smbus_xfer(struct i2c_adapter *adapter, u16 addr, + unsigned short flags, char read_write, u8 command, + int size, union i2c_smbus_data *data); + +This is the generic SMBus function. All functions below are implemented +in terms of it. Never use this function directly! + +:: + + s32 i2c_smbus_read_byte(struct i2c_client *client); + s32 i2c_smbus_write_byte(struct i2c_client *client, u8 value); + s32 i2c_smbus_read_byte_data(struct i2c_client *client, u8 command); + s32 i2c_smbus_write_byte_data(struct i2c_client *client, + u8 command, u8 value); + s32 i2c_smbus_read_word_data(struct i2c_client *client, u8 command); + s32 i2c_smbus_write_word_data(struct i2c_client *client, + u8 command, u16 value); + s32 i2c_smbus_read_block_data(struct i2c_client *client, + u8 command, u8 *values); + s32 i2c_smbus_write_block_data(struct i2c_client *client, + u8 command, u8 length, const u8 *values); + s32 i2c_smbus_read_i2c_block_data(struct i2c_client *client, + u8 command, u8 length, u8 *values); + s32 i2c_smbus_write_i2c_block_data(struct i2c_client *client, + u8 command, u8 length, + const u8 *values); + +These ones were removed from i2c-core because they had no users, but could +be added back later if needed:: + + s32 i2c_smbus_write_quick(struct i2c_client *client, u8 value); + s32 i2c_smbus_process_call(struct i2c_client *client, + u8 command, u16 value); + s32 i2c_smbus_block_process_call(struct i2c_client *client, + u8 command, u8 length, u8 *values); + +All these transactions return a negative errno value on failure. The 'write' +transactions return 0 on success; the 'read' transactions return the read +value, except for block transactions, which return the number of values +read. The block buffers need not be longer than 32 bytes. + +You can read the file ``smbus-protocol`` for more information about the +actual SMBus protocol. + + +General purpose routines +======================== + +Below all general purpose routines are listed, that were not mentioned +before:: + + /* Return the adapter number for a specific adapter */ + int i2c_adapter_id(struct i2c_adapter *adap); diff --git a/Documentation/index.rst b/Documentation/index.rst index 2df5a3da563c..9b45af84fd29 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -104,6 +104,7 @@ needed). fb/index fpga/index hid/index + i2c/index iio/index infiniband/index leds/index diff --git a/Documentation/spi/spi-sc18is602 b/Documentation/spi/spi-sc18is602 index a45702865a38..0feffd5af411 100644 --- a/Documentation/spi/spi-sc18is602 +++ b/Documentation/spi/spi-sc18is602 @@ -17,7 +17,7 @@ kernel's SPI core subsystem. The driver does not probe for supported chips, since the SI18IS602/603 does not support Chip ID registers. You will have to instantiate the devices explicitly. -Please see Documentation/i2c/instantiating-devices for details. +Please see Documentation/i2c/instantiating-devices.rst for details. Usage Notes diff --git a/MAINTAINERS b/MAINTAINERS index 6326445952f6..a3d5dd341088 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -666,7 +666,7 @@ ALI1563 I2C DRIVER M: Rudolf Marek L: linux-i2c@vger.kernel.org S: Maintained -F: Documentation/i2c/busses/i2c-ali1563 +F: Documentation/i2c/busses/i2c-ali1563.rst F: drivers/i2c/busses/i2c-ali1563.c ALLEGRO DVT VIDEO IP CORE DRIVER @@ -6741,7 +6741,7 @@ L: linux-i2c@vger.kernel.org S: Supported F: drivers/i2c/muxes/i2c-mux-gpio.c F: include/linux/platform_data/i2c-mux-gpio.h -F: Documentation/i2c/muxes/i2c-mux-gpio +F: Documentation/i2c/muxes/i2c-mux-gpio.rst GENERIC HDLC (WAN) DRIVERS M: Krzysztof Halasa @@ -7497,14 +7497,14 @@ I2C CONTROLLER DRIVER FOR NVIDIA GPU M: Ajay Gupta L: linux-i2c@vger.kernel.org S: Maintained -F: Documentation/i2c/busses/i2c-nvidia-gpu +F: Documentation/i2c/busses/i2c-nvidia-gpu.rst F: drivers/i2c/busses/i2c-nvidia-gpu.c I2C MUXES M: Peter Rosin L: linux-i2c@vger.kernel.org S: Maintained -F: Documentation/i2c/i2c-topology +F: Documentation/i2c/i2c-topology.rst F: Documentation/i2c/muxes/ F: Documentation/devicetree/bindings/i2c/i2c-mux* F: Documentation/devicetree/bindings/i2c/i2c-arb* @@ -7524,8 +7524,8 @@ I2C OVER PARALLEL PORT M: Jean Delvare L: linux-i2c@vger.kernel.org S: Maintained -F: Documentation/i2c/busses/i2c-parport -F: Documentation/i2c/busses/i2c-parport-light +F: Documentation/i2c/busses/i2c-parport.rst +F: Documentation/i2c/busses/i2c-parport-light.rst F: drivers/i2c/busses/i2c-parport.c F: drivers/i2c/busses/i2c-parport-light.c @@ -7559,7 +7559,7 @@ I2C-TAOS-EVM DRIVER M: Jean Delvare L: linux-i2c@vger.kernel.org S: Maintained -F: Documentation/i2c/busses/i2c-taos-evm +F: Documentation/i2c/busses/i2c-taos-evm.rst F: drivers/i2c/busses/i2c-taos-evm.c I2C-TINY-USB DRIVER @@ -7573,19 +7573,19 @@ I2C/SMBUS CONTROLLER DRIVERS FOR PC M: Jean Delvare L: linux-i2c@vger.kernel.org S: Maintained -F: Documentation/i2c/busses/i2c-ali1535 -F: Documentation/i2c/busses/i2c-ali1563 -F: Documentation/i2c/busses/i2c-ali15x3 -F: Documentation/i2c/busses/i2c-amd756 -F: Documentation/i2c/busses/i2c-amd8111 -F: Documentation/i2c/busses/i2c-i801 -F: Documentation/i2c/busses/i2c-nforce2 -F: Documentation/i2c/busses/i2c-piix4 -F: Documentation/i2c/busses/i2c-sis5595 -F: Documentation/i2c/busses/i2c-sis630 -F: Documentation/i2c/busses/i2c-sis96x -F: Documentation/i2c/busses/i2c-via -F: Documentation/i2c/busses/i2c-viapro +F: Documentation/i2c/busses/i2c-ali1535.rst +F: Documentation/i2c/busses/i2c-ali1563.rst +F: Documentation/i2c/busses/i2c-ali15x3.rst +F: Documentation/i2c/busses/i2c-amd756.rst +F: Documentation/i2c/busses/i2c-amd8111.rst +F: Documentation/i2c/busses/i2c-i801.rst +F: Documentation/i2c/busses/i2c-nforce2.rst +F: Documentation/i2c/busses/i2c-piix4.rst +F: Documentation/i2c/busses/i2c-sis5595.rst +F: Documentation/i2c/busses/i2c-sis630.rst +F: Documentation/i2c/busses/i2c-sis96x.rst +F: Documentation/i2c/busses/i2c-via.rst +F: Documentation/i2c/busses/i2c-viapro.rst F: drivers/i2c/busses/i2c-ali1535.c F: drivers/i2c/busses/i2c-ali1563.c F: drivers/i2c/busses/i2c-ali15x3.c @@ -7614,7 +7614,7 @@ M: Seth Heasley M: Neil Horman L: linux-i2c@vger.kernel.org F: drivers/i2c/busses/i2c-ismt.c -F: Documentation/i2c/busses/i2c-ismt +F: Documentation/i2c/busses/i2c-ismt.rst I2C/SMBUS STUB DRIVER M: Jean Delvare @@ -10355,7 +10355,7 @@ L: linux-i2c@vger.kernel.org S: Supported F: drivers/i2c/busses/i2c-mlxcpld.c F: drivers/i2c/muxes/i2c-mux-mlxcpld.c -F: Documentation/i2c/busses/i2c-mlxcpld +F: Documentation/i2c/busses/i2c-mlxcpld.rst MELLANOX MLXCPLD LED DRIVER M: Vadim Pasternak @@ -11976,7 +11976,7 @@ M: Andrew Lunn L: linux-i2c@vger.kernel.org S: Maintained F: Documentation/devicetree/bindings/i2c/i2c-ocores.txt -F: Documentation/i2c/busses/i2c-ocores +F: Documentation/i2c/busses/i2c-ocores.rst F: drivers/i2c/busses/i2c-ocores.c F: include/linux/platform_data/i2c-ocores.h @@ -14280,7 +14280,7 @@ F: net/sctp/ SCx200 CPU SUPPORT M: Jim Cromie S: Odd Fixes -F: Documentation/i2c/busses/scx200_acb +F: Documentation/i2c/busses/scx200_acb.rst F: arch/x86/platform/scx200/ F: drivers/watchdog/scx200_wdt.c F: drivers/i2c/busses/scx200* diff --git a/drivers/hwmon/atxp1.c b/drivers/hwmon/atxp1.c index e232fa948833..79b8df258371 100644 --- a/drivers/hwmon/atxp1.c +++ b/drivers/hwmon/atxp1.c @@ -5,7 +5,7 @@ * * The ATXP1 can reside on I2C addresses 0x37 or 0x4e. The chip is * not auto-detected by the driver and must be instantiated explicitly. - * See Documentation/i2c/instantiating-devices for more information. + * See Documentation/i2c/instantiating-devices.rst for more information. */ #include diff --git a/drivers/hwmon/smm665.c b/drivers/hwmon/smm665.c index d8c91c2cb8cf..9ae0dc28b9cf 100644 --- a/drivers/hwmon/smm665.c +++ b/drivers/hwmon/smm665.c @@ -197,7 +197,7 @@ static int smm665_read_adc(struct smm665_data *data, int adc) if (rv != -ENXIO) { /* * We expect ENXIO to reflect NACK - * (per Documentation/i2c/fault-codes). + * (per Documentation/i2c/fault-codes.rst). * Everything else is an error. */ dev_dbg(&client->dev, diff --git a/drivers/i2c/Kconfig b/drivers/i2c/Kconfig index abedd55a1264..1474e57ecafc 100644 --- a/drivers/i2c/Kconfig +++ b/drivers/i2c/Kconfig @@ -54,7 +54,7 @@ config I2C_CHARDEV Say Y here to use i2c-* device files, usually found in the /dev directory on your system. They make it possible to have user-space programs use the I2C bus. Information on how to do this is - contained in the file . + contained in the file . This support is also available as a module. If so, the module will be called i2c-dev. @@ -107,7 +107,7 @@ config I2C_STUB especially for certain kinds of sensor chips. If you do build this module, be sure to read the notes and warnings - in . + in . If you don't know what to do here, definitely say N. diff --git a/drivers/i2c/busses/Kconfig b/drivers/i2c/busses/Kconfig index 09367fc014c3..22fcf554257b 100644 --- a/drivers/i2c/busses/Kconfig +++ b/drivers/i2c/busses/Kconfig @@ -1206,7 +1206,7 @@ config I2C_PARPORT and makes it easier to add support for new devices. An adapter type parameter is now mandatory. Please read the file - Documentation/i2c/busses/i2c-parport for details. + Documentation/i2c/busses/i2c-parport.rst for details. Another driver exists, named i2c-parport-light, which doesn't depend on the parport driver. This is meant for embedded systems. Don't say diff --git a/drivers/i2c/busses/i2c-i801.c b/drivers/i2c/busses/i2c-i801.c index f2956936c3f2..c2f087d20420 100644 --- a/drivers/i2c/busses/i2c-i801.c +++ b/drivers/i2c/busses/i2c-i801.c @@ -77,7 +77,7 @@ * SMBus Host Notify yes * Interrupt processing yes * - * See the file Documentation/i2c/busses/i2c-i801 for details. + * See the file Documentation/i2c/busses/i2c-i801.rst for details. */ #include diff --git a/drivers/i2c/busses/i2c-taos-evm.c b/drivers/i2c/busses/i2c-taos-evm.c index c82e78f57386..37347c93e8e0 100644 --- a/drivers/i2c/busses/i2c-taos-evm.c +++ b/drivers/i2c/busses/i2c-taos-evm.c @@ -125,7 +125,7 @@ static int taos_smbus_xfer(struct i2c_adapter *adapter, u16 addr, /* * Voluntarily dropping error code of kstrtou8 since all * error code that it could return are invalid according - * to Documentation/i2c/fault-codes. + * to Documentation/i2c/fault-codes.rst. */ if (kstrtou8(p + 1, 16, &data->byte)) return -EPROTO; diff --git a/drivers/i2c/i2c-core-base.c b/drivers/i2c/i2c-core-base.c index f26ed495d384..2e6dcf8ecbc9 100644 --- a/drivers/i2c/i2c-core-base.c +++ b/drivers/i2c/i2c-core-base.c @@ -2206,7 +2206,7 @@ static int i2c_detect_address(struct i2c_client *temp_client, dev_warn(&adapter->dev, "This adapter will soon drop class based instantiation of devices. " "Please make sure client 0x%02x gets instantiated by other means. " - "Check 'Documentation/i2c/instantiating-devices' for details.\n", + "Check 'Documentation/i2c/instantiating-devices.rst' for details.\n", info.addr); dev_dbg(&adapter->dev, "Creating %s at 0x%02x\n", @@ -2236,7 +2236,7 @@ static int i2c_detect(struct i2c_adapter *adapter, struct i2c_driver *driver) if (adapter->class == I2C_CLASS_DEPRECATED) { dev_dbg(&adapter->dev, "This adapter dropped support for I2C classes and won't auto-detect %s devices anymore. " - "If you need it, check 'Documentation/i2c/instantiating-devices' for alternatives.\n", + "If you need it, check 'Documentation/i2c/instantiating-devices.rst' for alternatives.\n", driver->driver.name); return 0; } diff --git a/drivers/iio/dummy/iio_simple_dummy.c b/drivers/iio/dummy/iio_simple_dummy.c index 8f99c005458a..d28974ad9e0e 100644 --- a/drivers/iio/dummy/iio_simple_dummy.c +++ b/drivers/iio/dummy/iio_simple_dummy.c @@ -693,7 +693,7 @@ static int iio_dummy_remove(struct iio_sw_device *swd) * Varies depending on bus type of the device. As there is no device * here, call probe directly. For information on device registration * i2c: - * Documentation/i2c/writing-clients + * Documentation/i2c/writing-clients.rst * spi: * Documentation/spi/spi-summary */ diff --git a/drivers/rtc/rtc-ds1374.c b/drivers/rtc/rtc-ds1374.c index 225a8df1d4e9..367497914c10 100644 --- a/drivers/rtc/rtc-ds1374.c +++ b/drivers/rtc/rtc-ds1374.c @@ -14,7 +14,7 @@ */ /* * It would be more efficient to use i2c msgs/i2c_transfer directly but, as - * recommened in .../Documentation/i2c/writing-clients section + * recommended in .../Documentation/i2c/writing-clients.rst section * "Sending and receiving", using SMBus level communication is preferred. */ diff --git a/include/linux/i2c.h b/include/linux/i2c.h index fa5552c2307b..c0a78c069117 100644 --- a/include/linux/i2c.h +++ b/include/linux/i2c.h @@ -521,7 +521,7 @@ i2c_register_board_info(int busnum, struct i2c_board_info const *info, * * The return codes from the @master_xfer{_atomic} fields should indicate the * type of error code that occurred during the transfer, as documented in the - * Kernel Documentation file Documentation/i2c/fault-codes. + * Kernel Documentation file Documentation/i2c/fault-codes.rst. */ struct i2c_algorithm { /* -- cgit v1.2.3 From ec23eb54fbc7a07405d416d77e8115e575ce3adc Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 26 Jul 2019 09:51:27 -0300 Subject: docs: fs: convert docs without extension to ReST There are 3 remaining files without an extension inside the fs docs dir. Manually convert them to ReST. In the case of the nfs/exporting.rst file, as the nfs docs aren't ported yet, I opted to convert and add a :orphan: there, with should be removed when it gets added into a nfs-specific part of the fs documentation. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/filesystems/Locking | 576 -------------------- Documentation/filesystems/directory-locking | 135 ----- Documentation/filesystems/directory-locking.rst | 145 ++++++ Documentation/filesystems/index.rst | 2 + Documentation/filesystems/locking.rst | 665 ++++++++++++++++++++++++ Documentation/filesystems/nfs/Exporting | 160 ------ Documentation/filesystems/nfs/exporting.rst | 165 ++++++ Documentation/filesystems/vfs.rst | 2 +- fs/cifs/export.c | 2 +- fs/exportfs/expfs.c | 2 +- fs/isofs/export.c | 2 +- fs/orangefs/file.c | 2 +- include/linux/dcache.h | 2 +- include/linux/exportfs.h | 2 +- 14 files changed, 984 insertions(+), 878 deletions(-) delete mode 100644 Documentation/filesystems/Locking delete mode 100644 Documentation/filesystems/directory-locking create mode 100644 Documentation/filesystems/directory-locking.rst create mode 100644 Documentation/filesystems/locking.rst delete mode 100644 Documentation/filesystems/nfs/Exporting create mode 100644 Documentation/filesystems/nfs/exporting.rst (limited to 'include') diff --git a/Documentation/filesystems/Locking b/Documentation/filesystems/Locking deleted file mode 100644 index 204dd3ea36bb..000000000000 --- a/Documentation/filesystems/Locking +++ /dev/null @@ -1,576 +0,0 @@ - The text below describes the locking rules for VFS-related methods. -It is (believed to be) up-to-date. *Please*, if you change anything in -prototypes or locking protocols - update this file. And update the relevant -instances in the tree, don't leave that to maintainers of filesystems/devices/ -etc. At the very least, put the list of dubious cases in the end of this file. -Don't turn it into log - maintainers of out-of-the-tree code are supposed to -be able to use diff(1). - Thing currently missing here: socket operations. Alexey? - ---------------------------- dentry_operations -------------------------- -prototypes: - int (*d_revalidate)(struct dentry *, unsigned int); - int (*d_weak_revalidate)(struct dentry *, unsigned int); - int (*d_hash)(const struct dentry *, struct qstr *); - int (*d_compare)(const struct dentry *, - unsigned int, const char *, const struct qstr *); - int (*d_delete)(struct dentry *); - int (*d_init)(struct dentry *); - void (*d_release)(struct dentry *); - void (*d_iput)(struct dentry *, struct inode *); - char *(*d_dname)((struct dentry *dentry, char *buffer, int buflen); - struct vfsmount *(*d_automount)(struct path *path); - int (*d_manage)(const struct path *, bool); - struct dentry *(*d_real)(struct dentry *, const struct inode *); - -locking rules: - rename_lock ->d_lock may block rcu-walk -d_revalidate: no no yes (ref-walk) maybe -d_weak_revalidate:no no yes no -d_hash no no no maybe -d_compare: yes no no maybe -d_delete: no yes no no -d_init: no no yes no -d_release: no no yes no -d_prune: no yes no no -d_iput: no no yes no -d_dname: no no no no -d_automount: no no yes no -d_manage: no no yes (ref-walk) maybe -d_real no no yes no - ---------------------------- inode_operations --------------------------- -prototypes: - int (*create) (struct inode *,struct dentry *,umode_t, bool); - struct dentry * (*lookup) (struct inode *,struct dentry *, unsigned int); - int (*link) (struct dentry *,struct inode *,struct dentry *); - int (*unlink) (struct inode *,struct dentry *); - int (*symlink) (struct inode *,struct dentry *,const char *); - int (*mkdir) (struct inode *,struct dentry *,umode_t); - int (*rmdir) (struct inode *,struct dentry *); - int (*mknod) (struct inode *,struct dentry *,umode_t,dev_t); - int (*rename) (struct inode *, struct dentry *, - struct inode *, struct dentry *, unsigned int); - int (*readlink) (struct dentry *, char __user *,int); - const char *(*get_link) (struct dentry *, struct inode *, struct delayed_call *); - void (*truncate) (struct inode *); - int (*permission) (struct inode *, int, unsigned int); - int (*get_acl)(struct inode *, int); - int (*setattr) (struct dentry *, struct iattr *); - int (*getattr) (const struct path *, struct kstat *, u32, unsigned int); - ssize_t (*listxattr) (struct dentry *, char *, size_t); - int (*fiemap)(struct inode *, struct fiemap_extent_info *, u64 start, u64 len); - void (*update_time)(struct inode *, struct timespec *, int); - int (*atomic_open)(struct inode *, struct dentry *, - struct file *, unsigned open_flag, - umode_t create_mode); - int (*tmpfile) (struct inode *, struct dentry *, umode_t); - -locking rules: - all may block - i_rwsem(inode) -lookup: shared -create: exclusive -link: exclusive (both) -mknod: exclusive -symlink: exclusive -mkdir: exclusive -unlink: exclusive (both) -rmdir: exclusive (both)(see below) -rename: exclusive (all) (see below) -readlink: no -get_link: no -setattr: exclusive -permission: no (may not block if called in rcu-walk mode) -get_acl: no -getattr: no -listxattr: no -fiemap: no -update_time: no -atomic_open: exclusive -tmpfile: no - - - Additionally, ->rmdir(), ->unlink() and ->rename() have ->i_rwsem - exclusive on victim. - cross-directory ->rename() has (per-superblock) ->s_vfs_rename_sem. - -See Documentation/filesystems/directory-locking for more detailed discussion -of the locking scheme for directory operations. - ------------------------ xattr_handler operations ----------------------- -prototypes: - bool (*list)(struct dentry *dentry); - int (*get)(const struct xattr_handler *handler, struct dentry *dentry, - struct inode *inode, const char *name, void *buffer, - size_t size); - int (*set)(const struct xattr_handler *handler, struct dentry *dentry, - struct inode *inode, const char *name, const void *buffer, - size_t size, int flags); - -locking rules: - all may block - i_rwsem(inode) -list: no -get: no -set: exclusive - ---------------------------- super_operations --------------------------- -prototypes: - struct inode *(*alloc_inode)(struct super_block *sb); - void (*free_inode)(struct inode *); - void (*destroy_inode)(struct inode *); - void (*dirty_inode) (struct inode *, int flags); - int (*write_inode) (struct inode *, struct writeback_control *wbc); - int (*drop_inode) (struct inode *); - void (*evict_inode) (struct inode *); - void (*put_super) (struct super_block *); - int (*sync_fs)(struct super_block *sb, int wait); - int (*freeze_fs) (struct super_block *); - int (*unfreeze_fs) (struct super_block *); - int (*statfs) (struct dentry *, struct kstatfs *); - int (*remount_fs) (struct super_block *, int *, char *); - void (*umount_begin) (struct super_block *); - int (*show_options)(struct seq_file *, struct dentry *); - ssize_t (*quota_read)(struct super_block *, int, char *, size_t, loff_t); - ssize_t (*quota_write)(struct super_block *, int, const char *, size_t, loff_t); - int (*bdev_try_to_free_page)(struct super_block*, struct page*, gfp_t); - -locking rules: - All may block [not true, see below] - s_umount -alloc_inode: -free_inode: called from RCU callback -destroy_inode: -dirty_inode: -write_inode: -drop_inode: !!!inode->i_lock!!! -evict_inode: -put_super: write -sync_fs: read -freeze_fs: write -unfreeze_fs: write -statfs: maybe(read) (see below) -remount_fs: write -umount_begin: no -show_options: no (namespace_sem) -quota_read: no (see below) -quota_write: no (see below) -bdev_try_to_free_page: no (see below) - -->statfs() has s_umount (shared) when called by ustat(2) (native or -compat), but that's an accident of bad API; s_umount is used to pin -the superblock down when we only have dev_t given us by userland to -identify the superblock. Everything else (statfs(), fstatfs(), etc.) -doesn't hold it when calling ->statfs() - superblock is pinned down -by resolving the pathname passed to syscall. -->quota_read() and ->quota_write() functions are both guaranteed to -be the only ones operating on the quota file by the quota code (via -dqio_sem) (unless an admin really wants to screw up something and -writes to quota files with quotas on). For other details about locking -see also dquot_operations section. -->bdev_try_to_free_page is called from the ->releasepage handler of -the block device inode. See there for more details. - ---------------------------- file_system_type --------------------------- -prototypes: - struct dentry *(*mount) (struct file_system_type *, int, - const char *, void *); - void (*kill_sb) (struct super_block *); -locking rules: - may block -mount yes -kill_sb yes - -->mount() returns ERR_PTR or the root dentry; its superblock should be locked -on return. -->kill_sb() takes a write-locked superblock, does all shutdown work on it, -unlocks and drops the reference. - ---------------------------- address_space_operations -------------------------- -prototypes: - int (*writepage)(struct page *page, struct writeback_control *wbc); - int (*readpage)(struct file *, struct page *); - int (*writepages)(struct address_space *, struct writeback_control *); - int (*set_page_dirty)(struct page *page); - int (*readpages)(struct file *filp, struct address_space *mapping, - struct list_head *pages, unsigned nr_pages); - int (*write_begin)(struct file *, struct address_space *mapping, - loff_t pos, unsigned len, unsigned flags, - struct page **pagep, void **fsdata); - int (*write_end)(struct file *, struct address_space *mapping, - loff_t pos, unsigned len, unsigned copied, - struct page *page, void *fsdata); - sector_t (*bmap)(struct address_space *, sector_t); - void (*invalidatepage) (struct page *, unsigned int, unsigned int); - int (*releasepage) (struct page *, int); - void (*freepage)(struct page *); - int (*direct_IO)(struct kiocb *, struct iov_iter *iter); - bool (*isolate_page) (struct page *, isolate_mode_t); - int (*migratepage)(struct address_space *, struct page *, struct page *); - void (*putback_page) (struct page *); - int (*launder_page)(struct page *); - int (*is_partially_uptodate)(struct page *, unsigned long, unsigned long); - int (*error_remove_page)(struct address_space *, struct page *); - int (*swap_activate)(struct file *); - int (*swap_deactivate)(struct file *); - -locking rules: - All except set_page_dirty and freepage may block - - PageLocked(page) i_rwsem -writepage: yes, unlocks (see below) -readpage: yes, unlocks -writepages: -set_page_dirty no -readpages: -write_begin: locks the page exclusive -write_end: yes, unlocks exclusive -bmap: -invalidatepage: yes -releasepage: yes -freepage: yes -direct_IO: -isolate_page: yes -migratepage: yes (both) -putback_page: yes -launder_page: yes -is_partially_uptodate: yes -error_remove_page: yes -swap_activate: no -swap_deactivate: no - - ->write_begin(), ->write_end() and ->readpage() may be called from -the request handler (/dev/loop). - - ->readpage() unlocks the page, either synchronously or via I/O -completion. - - ->readpages() populates the pagecache with the passed pages and starts -I/O against them. They come unlocked upon I/O completion. - - ->writepage() is used for two purposes: for "memory cleansing" and for -"sync". These are quite different operations and the behaviour may differ -depending upon the mode. - -If writepage is called for sync (wbc->sync_mode != WBC_SYNC_NONE) then -it *must* start I/O against the page, even if that would involve -blocking on in-progress I/O. - -If writepage is called for memory cleansing (sync_mode == -WBC_SYNC_NONE) then its role is to get as much writeout underway as -possible. So writepage should try to avoid blocking against -currently-in-progress I/O. - -If the filesystem is not called for "sync" and it determines that it -would need to block against in-progress I/O to be able to start new I/O -against the page the filesystem should redirty the page with -redirty_page_for_writepage(), then unlock the page and return zero. -This may also be done to avoid internal deadlocks, but rarely. - -If the filesystem is called for sync then it must wait on any -in-progress I/O and then start new I/O. - -The filesystem should unlock the page synchronously, before returning to the -caller, unless ->writepage() returns special WRITEPAGE_ACTIVATE -value. WRITEPAGE_ACTIVATE means that page cannot really be written out -currently, and VM should stop calling ->writepage() on this page for some -time. VM does this by moving page to the head of the active list, hence the -name. - -Unless the filesystem is going to redirty_page_for_writepage(), unlock the page -and return zero, writepage *must* run set_page_writeback() against the page, -followed by unlocking it. Once set_page_writeback() has been run against the -page, write I/O can be submitted and the write I/O completion handler must run -end_page_writeback() once the I/O is complete. If no I/O is submitted, the -filesystem must run end_page_writeback() against the page before returning from -writepage. - -That is: after 2.5.12, pages which are under writeout are *not* locked. Note, -if the filesystem needs the page to be locked during writeout, that is ok, too, -the page is allowed to be unlocked at any point in time between the calls to -set_page_writeback() and end_page_writeback(). - -Note, failure to run either redirty_page_for_writepage() or the combination of -set_page_writeback()/end_page_writeback() on a page submitted to writepage -will leave the page itself marked clean but it will be tagged as dirty in the -radix tree. This incoherency can lead to all sorts of hard-to-debug problems -in the filesystem like having dirty inodes at umount and losing written data. - - ->writepages() is used for periodic writeback and for syscall-initiated -sync operations. The address_space should start I/O against at least -*nr_to_write pages. *nr_to_write must be decremented for each page which is -written. The address_space implementation may write more (or less) pages -than *nr_to_write asks for, but it should try to be reasonably close. If -nr_to_write is NULL, all dirty pages must be written. - -writepages should _only_ write pages which are present on -mapping->io_pages. - - ->set_page_dirty() is called from various places in the kernel -when the target page is marked as needing writeback. It may be called -under spinlock (it cannot block) and is sometimes called with the page -not locked. - - ->bmap() is currently used by legacy ioctl() (FIBMAP) provided by some -filesystems and by the swapper. The latter will eventually go away. Please, -keep it that way and don't breed new callers. - - ->invalidatepage() is called when the filesystem must attempt to drop -some or all of the buffers from the page when it is being truncated. It -returns zero on success. If ->invalidatepage is zero, the kernel uses -block_invalidatepage() instead. - - ->releasepage() is called when the kernel is about to try to drop the -buffers from the page in preparation for freeing it. It returns zero to -indicate that the buffers are (or may be) freeable. If ->releasepage is zero, -the kernel assumes that the fs has no private interest in the buffers. - - ->freepage() is called when the kernel is done dropping the page -from the page cache. - - ->launder_page() may be called prior to releasing a page if -it is still found to be dirty. It returns zero if the page was successfully -cleaned, or an error value if not. Note that in order to prevent the page -getting mapped back in and redirtied, it needs to be kept locked -across the entire operation. - - ->swap_activate will be called with a non-zero argument on -files backing (non block device backed) swapfiles. A return value -of zero indicates success, in which case this file can be used for -backing swapspace. The swapspace operations will be proxied to the -address space operations. - - ->swap_deactivate() will be called in the sys_swapoff() -path after ->swap_activate() returned success. - ------------------------ file_lock_operations ------------------------------ -prototypes: - void (*fl_copy_lock)(struct file_lock *, struct file_lock *); - void (*fl_release_private)(struct file_lock *); - - -locking rules: - inode->i_lock may block -fl_copy_lock: yes no -fl_release_private: maybe maybe[1] - -[1]: ->fl_release_private for flock or POSIX locks is currently allowed -to block. Leases however can still be freed while the i_lock is held and -so fl_release_private called on a lease should not block. - ------------------------ lock_manager_operations --------------------------- -prototypes: - void (*lm_notify)(struct file_lock *); /* unblock callback */ - int (*lm_grant)(struct file_lock *, struct file_lock *, int); - void (*lm_break)(struct file_lock *); /* break_lease callback */ - int (*lm_change)(struct file_lock **, int); - -locking rules: - - inode->i_lock blocked_lock_lock may block -lm_notify: yes yes no -lm_grant: no no no -lm_break: yes no no -lm_change yes no no - ---------------------------- buffer_head ----------------------------------- -prototypes: - void (*b_end_io)(struct buffer_head *bh, int uptodate); - -locking rules: - called from interrupts. In other words, extreme care is needed here. -bh is locked, but that's all warranties we have here. Currently only RAID1, -highmem, fs/buffer.c, and fs/ntfs/aops.c are providing these. Block devices -call this method upon the IO completion. - ---------------------------- block_device_operations ----------------------- -prototypes: - int (*open) (struct block_device *, fmode_t); - int (*release) (struct gendisk *, fmode_t); - int (*ioctl) (struct block_device *, fmode_t, unsigned, unsigned long); - int (*compat_ioctl) (struct block_device *, fmode_t, unsigned, unsigned long); - int (*direct_access) (struct block_device *, sector_t, void **, - unsigned long *); - int (*media_changed) (struct gendisk *); - void (*unlock_native_capacity) (struct gendisk *); - int (*revalidate_disk) (struct gendisk *); - int (*getgeo)(struct block_device *, struct hd_geometry *); - void (*swap_slot_free_notify) (struct block_device *, unsigned long); - -locking rules: - bd_mutex -open: yes -release: yes -ioctl: no -compat_ioctl: no -direct_access: no -media_changed: no -unlock_native_capacity: no -revalidate_disk: no -getgeo: no -swap_slot_free_notify: no (see below) - -media_changed, unlock_native_capacity and revalidate_disk are called only from -check_disk_change(). - -swap_slot_free_notify is called with swap_lock and sometimes the page lock -held. - - ---------------------------- file_operations ------------------------------- -prototypes: - loff_t (*llseek) (struct file *, loff_t, int); - ssize_t (*read) (struct file *, char __user *, size_t, loff_t *); - ssize_t (*write) (struct file *, const char __user *, size_t, loff_t *); - ssize_t (*read_iter) (struct kiocb *, struct iov_iter *); - ssize_t (*write_iter) (struct kiocb *, struct iov_iter *); - int (*iterate) (struct file *, struct dir_context *); - int (*iterate_shared) (struct file *, struct dir_context *); - __poll_t (*poll) (struct file *, struct poll_table_struct *); - long (*unlocked_ioctl) (struct file *, unsigned int, unsigned long); - long (*compat_ioctl) (struct file *, unsigned int, unsigned long); - int (*mmap) (struct file *, struct vm_area_struct *); - int (*open) (struct inode *, struct file *); - int (*flush) (struct file *); - int (*release) (struct inode *, struct file *); - int (*fsync) (struct file *, loff_t start, loff_t end, int datasync); - int (*fasync) (int, struct file *, int); - int (*lock) (struct file *, int, struct file_lock *); - ssize_t (*readv) (struct file *, const struct iovec *, unsigned long, - loff_t *); - ssize_t (*writev) (struct file *, const struct iovec *, unsigned long, - loff_t *); - ssize_t (*sendfile) (struct file *, loff_t *, size_t, read_actor_t, - void __user *); - ssize_t (*sendpage) (struct file *, struct page *, int, size_t, - loff_t *, int); - unsigned long (*get_unmapped_area)(struct file *, unsigned long, - unsigned long, unsigned long, unsigned long); - int (*check_flags)(int); - int (*flock) (struct file *, int, struct file_lock *); - ssize_t (*splice_write)(struct pipe_inode_info *, struct file *, loff_t *, - size_t, unsigned int); - ssize_t (*splice_read)(struct file *, loff_t *, struct pipe_inode_info *, - size_t, unsigned int); - int (*setlease)(struct file *, long, struct file_lock **, void **); - long (*fallocate)(struct file *, int, loff_t, loff_t); -}; - -locking rules: - All may block. - -->llseek() locking has moved from llseek to the individual llseek -implementations. If your fs is not using generic_file_llseek, you -need to acquire and release the appropriate locks in your ->llseek(). -For many filesystems, it is probably safe to acquire the inode -mutex or just to use i_size_read() instead. -Note: this does not protect the file->f_pos against concurrent modifications -since this is something the userspace has to take care about. - -->iterate() is called with i_rwsem exclusive. - -->iterate_shared() is called with i_rwsem at least shared. - -->fasync() is responsible for maintaining the FASYNC bit in filp->f_flags. -Most instances call fasync_helper(), which does that maintenance, so it's -not normally something one needs to worry about. Return values > 0 will be -mapped to zero in the VFS layer. - -->readdir() and ->ioctl() on directories must be changed. Ideally we would -move ->readdir() to inode_operations and use a separate method for directory -->ioctl() or kill the latter completely. One of the problems is that for -anything that resembles union-mount we won't have a struct file for all -components. And there are other reasons why the current interface is a mess... - -->read on directories probably must go away - we should just enforce -EISDIR -in sys_read() and friends. - -->setlease operations should call generic_setlease() before or after setting -the lease within the individual filesystem to record the result of the -operation - ---------------------------- dquot_operations ------------------------------- -prototypes: - int (*write_dquot) (struct dquot *); - int (*acquire_dquot) (struct dquot *); - int (*release_dquot) (struct dquot *); - int (*mark_dirty) (struct dquot *); - int (*write_info) (struct super_block *, int); - -These operations are intended to be more or less wrapping functions that ensure -a proper locking wrt the filesystem and call the generic quota operations. - -What filesystem should expect from the generic quota functions: - - FS recursion Held locks when called -write_dquot: yes dqonoff_sem or dqptr_sem -acquire_dquot: yes dqonoff_sem or dqptr_sem -release_dquot: yes dqonoff_sem or dqptr_sem -mark_dirty: no - -write_info: yes dqonoff_sem - -FS recursion means calling ->quota_read() and ->quota_write() from superblock -operations. - -More details about quota locking can be found in fs/dquot.c. - ---------------------------- vm_operations_struct ----------------------------- -prototypes: - void (*open)(struct vm_area_struct*); - void (*close)(struct vm_area_struct*); - vm_fault_t (*fault)(struct vm_area_struct*, struct vm_fault *); - vm_fault_t (*page_mkwrite)(struct vm_area_struct *, struct vm_fault *); - vm_fault_t (*pfn_mkwrite)(struct vm_area_struct *, struct vm_fault *); - int (*access)(struct vm_area_struct *, unsigned long, void*, int, int); - -locking rules: - mmap_sem PageLocked(page) -open: yes -close: yes -fault: yes can return with page locked -map_pages: yes -page_mkwrite: yes can return with page locked -pfn_mkwrite: yes -access: yes - - ->fault() is called when a previously not present pte is about -to be faulted in. The filesystem must find and return the page associated -with the passed in "pgoff" in the vm_fault structure. If it is possible that -the page may be truncated and/or invalidated, then the filesystem must lock -the page, then ensure it is not already truncated (the page lock will block -subsequent truncate), and then return with VM_FAULT_LOCKED, and the page -locked. The VM will unlock the page. - - ->map_pages() is called when VM asks to map easy accessible pages. -Filesystem should find and map pages associated with offsets from "start_pgoff" -till "end_pgoff". ->map_pages() is called with page table locked and must -not block. If it's not possible to reach a page without blocking, -filesystem should skip it. Filesystem should use do_set_pte() to setup -page table entry. Pointer to entry associated with the page is passed in -"pte" field in vm_fault structure. Pointers to entries for other offsets -should be calculated relative to "pte". - - ->page_mkwrite() is called when a previously read-only pte is -about to become writeable. The filesystem again must ensure that there are -no truncate/invalidate races, and then return with the page locked. If -the page has been truncated, the filesystem should not look up a new page -like the ->fault() handler, but simply return with VM_FAULT_NOPAGE, which -will cause the VM to retry the fault. - - ->pfn_mkwrite() is the same as page_mkwrite but when the pte is -VM_PFNMAP or VM_MIXEDMAP with a page-less entry. Expected return is -VM_FAULT_NOPAGE. Or one of the VM_FAULT_ERROR types. The default behavior -after this call is to make the pte read-write, unless pfn_mkwrite returns -an error. - - ->access() is called when get_user_pages() fails in -access_process_vm(), typically used to debug a process through -/proc/pid/mem or ptrace. This function is needed only for -VM_IO | VM_PFNMAP VMAs. - -================================================================================ - Dubious stuff - -(if you break something or notice that it is broken and do not fix it yourself -- at least put it here) diff --git a/Documentation/filesystems/directory-locking b/Documentation/filesystems/directory-locking deleted file mode 100644 index 4e32cb961e5b..000000000000 --- a/Documentation/filesystems/directory-locking +++ /dev/null @@ -1,135 +0,0 @@ - Locking scheme used for directory operations is based on two -kinds of locks - per-inode (->i_rwsem) and per-filesystem -(->s_vfs_rename_mutex). - - When taking the i_rwsem on multiple non-directory objects, we -always acquire the locks in order by increasing address. We'll call -that "inode pointer" order in the following. - - For our purposes all operations fall in 5 classes: - -1) read access. Locking rules: caller locks directory we are accessing. -The lock is taken shared. - -2) object creation. Locking rules: same as above, but the lock is taken -exclusive. - -3) object removal. Locking rules: caller locks parent, finds victim, -locks victim and calls the method. Locks are exclusive. - -4) rename() that is _not_ cross-directory. Locking rules: caller locks -the parent and finds source and target. In case of exchange (with -RENAME_EXCHANGE in flags argument) lock both. In any case, -if the target already exists, lock it. If the source is a non-directory, -lock it. If we need to lock both, lock them in inode pointer order. -Then call the method. All locks are exclusive. -NB: we might get away with locking the the source (and target in exchange -case) shared. - -5) link creation. Locking rules: - * lock parent - * check that source is not a directory - * lock source - * call the method. -All locks are exclusive. - -6) cross-directory rename. The trickiest in the whole bunch. Locking -rules: - * lock the filesystem - * lock parents in "ancestors first" order. - * find source and target. - * if old parent is equal to or is a descendent of target - fail with -ENOTEMPTY - * if new parent is equal to or is a descendent of source - fail with -ELOOP - * If it's an exchange, lock both the source and the target. - * If the target exists, lock it. If the source is a non-directory, - lock it. If we need to lock both, do so in inode pointer order. - * call the method. -All ->i_rwsem are taken exclusive. Again, we might get away with locking -the the source (and target in exchange case) shared. - -The rules above obviously guarantee that all directories that are going to be -read, modified or removed by method will be locked by caller. - - -If no directory is its own ancestor, the scheme above is deadlock-free. -Proof: - - First of all, at any moment we have a partial ordering of the -objects - A < B iff A is an ancestor of B. - - That ordering can change. However, the following is true: - -(1) if object removal or non-cross-directory rename holds lock on A and - attempts to acquire lock on B, A will remain the parent of B until we - acquire the lock on B. (Proof: only cross-directory rename can change - the parent of object and it would have to lock the parent). - -(2) if cross-directory rename holds the lock on filesystem, order will not - change until rename acquires all locks. (Proof: other cross-directory - renames will be blocked on filesystem lock and we don't start changing - the order until we had acquired all locks). - -(3) locks on non-directory objects are acquired only after locks on - directory objects, and are acquired in inode pointer order. - (Proof: all operations but renames take lock on at most one - non-directory object, except renames, which take locks on source and - target in inode pointer order in the case they are not directories.) - - Now consider the minimal deadlock. Each process is blocked on -attempt to acquire some lock and already holds at least one lock. Let's -consider the set of contended locks. First of all, filesystem lock is -not contended, since any process blocked on it is not holding any locks. -Thus all processes are blocked on ->i_rwsem. - - By (3), any process holding a non-directory lock can only be -waiting on another non-directory lock with a larger address. Therefore -the process holding the "largest" such lock can always make progress, and -non-directory objects are not included in the set of contended locks. - - Thus link creation can't be a part of deadlock - it can't be -blocked on source and it means that it doesn't hold any locks. - - Any contended object is either held by cross-directory rename or -has a child that is also contended. Indeed, suppose that it is held by -operation other than cross-directory rename. Then the lock this operation -is blocked on belongs to child of that object due to (1). - - It means that one of the operations is cross-directory rename. -Otherwise the set of contended objects would be infinite - each of them -would have a contended child and we had assumed that no object is its -own descendent. Moreover, there is exactly one cross-directory rename -(see above). - - Consider the object blocking the cross-directory rename. One -of its descendents is locked by cross-directory rename (otherwise we -would again have an infinite set of contended objects). But that -means that cross-directory rename is taking locks out of order. Due -to (2) the order hadn't changed since we had acquired filesystem lock. -But locking rules for cross-directory rename guarantee that we do not -try to acquire lock on descendent before the lock on ancestor. -Contradiction. I.e. deadlock is impossible. Q.E.D. - - - These operations are guaranteed to avoid loop creation. Indeed, -the only operation that could introduce loops is cross-directory rename. -Since the only new (parent, child) pair added by rename() is (new parent, -source), such loop would have to contain these objects and the rest of it -would have to exist before rename(). I.e. at the moment of loop creation -rename() responsible for that would be holding filesystem lock and new parent -would have to be equal to or a descendent of source. But that means that -new parent had been equal to or a descendent of source since the moment when -we had acquired filesystem lock and rename() would fail with -ELOOP in that -case. - - While this locking scheme works for arbitrary DAGs, it relies on -ability to check that directory is a descendent of another object. Current -implementation assumes that directory graph is a tree. This assumption is -also preserved by all operations (cross-directory rename on a tree that would -not introduce a cycle will leave it a tree and link() fails for directories). - - Notice that "directory" in the above == "anything that might have -children", so if we are going to introduce hybrid objects we will need -either to make sure that link(2) doesn't work for them or to make changes -in is_subdir() that would make it work even in presence of such beasts. diff --git a/Documentation/filesystems/directory-locking.rst b/Documentation/filesystems/directory-locking.rst new file mode 100644 index 000000000000..de12016ee419 --- /dev/null +++ b/Documentation/filesystems/directory-locking.rst @@ -0,0 +1,145 @@ +================= +Directory Locking +================= + + +Locking scheme used for directory operations is based on two +kinds of locks - per-inode (->i_rwsem) and per-filesystem +(->s_vfs_rename_mutex). + +When taking the i_rwsem on multiple non-directory objects, we +always acquire the locks in order by increasing address. We'll call +that "inode pointer" order in the following. + +For our purposes all operations fall in 5 classes: + +1) read access. Locking rules: caller locks directory we are accessing. +The lock is taken shared. + +2) object creation. Locking rules: same as above, but the lock is taken +exclusive. + +3) object removal. Locking rules: caller locks parent, finds victim, +locks victim and calls the method. Locks are exclusive. + +4) rename() that is _not_ cross-directory. Locking rules: caller locks +the parent and finds source and target. In case of exchange (with +RENAME_EXCHANGE in flags argument) lock both. In any case, +if the target already exists, lock it. If the source is a non-directory, +lock it. If we need to lock both, lock them in inode pointer order. +Then call the method. All locks are exclusive. +NB: we might get away with locking the the source (and target in exchange +case) shared. + +5) link creation. Locking rules: + + * lock parent + * check that source is not a directory + * lock source + * call the method. + +All locks are exclusive. + +6) cross-directory rename. The trickiest in the whole bunch. Locking +rules: + + * lock the filesystem + * lock parents in "ancestors first" order. + * find source and target. + * if old parent is equal to or is a descendent of target + fail with -ENOTEMPTY + * if new parent is equal to or is a descendent of source + fail with -ELOOP + * If it's an exchange, lock both the source and the target. + * If the target exists, lock it. If the source is a non-directory, + lock it. If we need to lock both, do so in inode pointer order. + * call the method. + +All ->i_rwsem are taken exclusive. Again, we might get away with locking +the the source (and target in exchange case) shared. + +The rules above obviously guarantee that all directories that are going to be +read, modified or removed by method will be locked by caller. + + +If no directory is its own ancestor, the scheme above is deadlock-free. + +Proof: + + First of all, at any moment we have a partial ordering of the + objects - A < B iff A is an ancestor of B. + + That ordering can change. However, the following is true: + +(1) if object removal or non-cross-directory rename holds lock on A and + attempts to acquire lock on B, A will remain the parent of B until we + acquire the lock on B. (Proof: only cross-directory rename can change + the parent of object and it would have to lock the parent). + +(2) if cross-directory rename holds the lock on filesystem, order will not + change until rename acquires all locks. (Proof: other cross-directory + renames will be blocked on filesystem lock and we don't start changing + the order until we had acquired all locks). + +(3) locks on non-directory objects are acquired only after locks on + directory objects, and are acquired in inode pointer order. + (Proof: all operations but renames take lock on at most one + non-directory object, except renames, which take locks on source and + target in inode pointer order in the case they are not directories.) + +Now consider the minimal deadlock. Each process is blocked on +attempt to acquire some lock and already holds at least one lock. Let's +consider the set of contended locks. First of all, filesystem lock is +not contended, since any process blocked on it is not holding any locks. +Thus all processes are blocked on ->i_rwsem. + +By (3), any process holding a non-directory lock can only be +waiting on another non-directory lock with a larger address. Therefore +the process holding the "largest" such lock can always make progress, and +non-directory objects are not included in the set of contended locks. + +Thus link creation can't be a part of deadlock - it can't be +blocked on source and it means that it doesn't hold any locks. + +Any contended object is either held by cross-directory rename or +has a child that is also contended. Indeed, suppose that it is held by +operation other than cross-directory rename. Then the lock this operation +is blocked on belongs to child of that object due to (1). + +It means that one of the operations is cross-directory rename. +Otherwise the set of contended objects would be infinite - each of them +would have a contended child and we had assumed that no object is its +own descendent. Moreover, there is exactly one cross-directory rename +(see above). + +Consider the object blocking the cross-directory rename. One +of its descendents is locked by cross-directory rename (otherwise we +would again have an infinite set of contended objects). But that +means that cross-directory rename is taking locks out of order. Due +to (2) the order hadn't changed since we had acquired filesystem lock. +But locking rules for cross-directory rename guarantee that we do not +try to acquire lock on descendent before the lock on ancestor. +Contradiction. I.e. deadlock is impossible. Q.E.D. + + +These operations are guaranteed to avoid loop creation. Indeed, +the only operation that could introduce loops is cross-directory rename. +Since the only new (parent, child) pair added by rename() is (new parent, +source), such loop would have to contain these objects and the rest of it +would have to exist before rename(). I.e. at the moment of loop creation +rename() responsible for that would be holding filesystem lock and new parent +would have to be equal to or a descendent of source. But that means that +new parent had been equal to or a descendent of source since the moment when +we had acquired filesystem lock and rename() would fail with -ELOOP in that +case. + +While this locking scheme works for arbitrary DAGs, it relies on +ability to check that directory is a descendent of another object. Current +implementation assumes that directory graph is a tree. This assumption is +also preserved by all operations (cross-directory rename on a tree that would +not introduce a cycle will leave it a tree and link() fails for directories). + +Notice that "directory" in the above == "anything that might have +children", so if we are going to introduce hybrid objects we will need +either to make sure that link(2) doesn't work for them or to make changes +in is_subdir() that would make it work even in presence of such beasts. diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst index 2de2fe2ab078..08320c35d03b 100644 --- a/Documentation/filesystems/index.rst +++ b/Documentation/filesystems/index.rst @@ -20,6 +20,8 @@ algorithms work. path-lookup api-summary splice + locking + directory-locking Filesystem support layers ========================= diff --git a/Documentation/filesystems/locking.rst b/Documentation/filesystems/locking.rst new file mode 100644 index 000000000000..fc3a0704553c --- /dev/null +++ b/Documentation/filesystems/locking.rst @@ -0,0 +1,665 @@ +======= +Locking +======= + +The text below describes the locking rules for VFS-related methods. +It is (believed to be) up-to-date. *Please*, if you change anything in +prototypes or locking protocols - update this file. And update the relevant +instances in the tree, don't leave that to maintainers of filesystems/devices/ +etc. At the very least, put the list of dubious cases in the end of this file. +Don't turn it into log - maintainers of out-of-the-tree code are supposed to +be able to use diff(1). + +Thing currently missing here: socket operations. Alexey? + +dentry_operations +================= + +prototypes:: + + int (*d_revalidate)(struct dentry *, unsigned int); + int (*d_weak_revalidate)(struct dentry *, unsigned int); + int (*d_hash)(const struct dentry *, struct qstr *); + int (*d_compare)(const struct dentry *, + unsigned int, const char *, const struct qstr *); + int (*d_delete)(struct dentry *); + int (*d_init)(struct dentry *); + void (*d_release)(struct dentry *); + void (*d_iput)(struct dentry *, struct inode *); + char *(*d_dname)((struct dentry *dentry, char *buffer, int buflen); + struct vfsmount *(*d_automount)(struct path *path); + int (*d_manage)(const struct path *, bool); + struct dentry *(*d_real)(struct dentry *, const struct inode *); + +locking rules: + +================== =========== ======== ============== ======== +ops rename_lock ->d_lock may block rcu-walk +================== =========== ======== ============== ======== +d_revalidate: no no yes (ref-walk) maybe +d_weak_revalidate: no no yes no +d_hash no no no maybe +d_compare: yes no no maybe +d_delete: no yes no no +d_init: no no yes no +d_release: no no yes no +d_prune: no yes no no +d_iput: no no yes no +d_dname: no no no no +d_automount: no no yes no +d_manage: no no yes (ref-walk) maybe +d_real no no yes no +================== =========== ======== ============== ======== + +inode_operations +================ + +prototypes:: + + int (*create) (struct inode *,struct dentry *,umode_t, bool); + struct dentry * (*lookup) (struct inode *,struct dentry *, unsigned int); + int (*link) (struct dentry *,struct inode *,struct dentry *); + int (*unlink) (struct inode *,struct dentry *); + int (*symlink) (struct inode *,struct dentry *,const char *); + int (*mkdir) (struct inode *,struct dentry *,umode_t); + int (*rmdir) (struct inode *,struct dentry *); + int (*mknod) (struct inode *,struct dentry *,umode_t,dev_t); + int (*rename) (struct inode *, struct dentry *, + struct inode *, struct dentry *, unsigned int); + int (*readlink) (struct dentry *, char __user *,int); + const char *(*get_link) (struct dentry *, struct inode *, struct delayed_call *); + void (*truncate) (struct inode *); + int (*permission) (struct inode *, int, unsigned int); + int (*get_acl)(struct inode *, int); + int (*setattr) (struct dentry *, struct iattr *); + int (*getattr) (const struct path *, struct kstat *, u32, unsigned int); + ssize_t (*listxattr) (struct dentry *, char *, size_t); + int (*fiemap)(struct inode *, struct fiemap_extent_info *, u64 start, u64 len); + void (*update_time)(struct inode *, struct timespec *, int); + int (*atomic_open)(struct inode *, struct dentry *, + struct file *, unsigned open_flag, + umode_t create_mode); + int (*tmpfile) (struct inode *, struct dentry *, umode_t); + +locking rules: + all may block + +============ ============================================= +ops i_rwsem(inode) +============ ============================================= +lookup: shared +create: exclusive +link: exclusive (both) +mknod: exclusive +symlink: exclusive +mkdir: exclusive +unlink: exclusive (both) +rmdir: exclusive (both)(see below) +rename: exclusive (all) (see below) +readlink: no +get_link: no +setattr: exclusive +permission: no (may not block if called in rcu-walk mode) +get_acl: no +getattr: no +listxattr: no +fiemap: no +update_time: no +atomic_open: exclusive +tmpfile: no +============ ============================================= + + + Additionally, ->rmdir(), ->unlink() and ->rename() have ->i_rwsem + exclusive on victim. + cross-directory ->rename() has (per-superblock) ->s_vfs_rename_sem. + +See Documentation/filesystems/directory-locking.rst for more detailed discussion +of the locking scheme for directory operations. + +xattr_handler operations +======================== + +prototypes:: + + bool (*list)(struct dentry *dentry); + int (*get)(const struct xattr_handler *handler, struct dentry *dentry, + struct inode *inode, const char *name, void *buffer, + size_t size); + int (*set)(const struct xattr_handler *handler, struct dentry *dentry, + struct inode *inode, const char *name, const void *buffer, + size_t size, int flags); + +locking rules: + all may block + +===== ============== +ops i_rwsem(inode) +===== ============== +list: no +get: no +set: exclusive +===== ============== + +super_operations +================ + +prototypes:: + + struct inode *(*alloc_inode)(struct super_block *sb); + void (*free_inode)(struct inode *); + void (*destroy_inode)(struct inode *); + void (*dirty_inode) (struct inode *, int flags); + int (*write_inode) (struct inode *, struct writeback_control *wbc); + int (*drop_inode) (struct inode *); + void (*evict_inode) (struct inode *); + void (*put_super) (struct super_block *); + int (*sync_fs)(struct super_block *sb, int wait); + int (*freeze_fs) (struct super_block *); + int (*unfreeze_fs) (struct super_block *); + int (*statfs) (struct dentry *, struct kstatfs *); + int (*remount_fs) (struct super_block *, int *, char *); + void (*umount_begin) (struct super_block *); + int (*show_options)(struct seq_file *, struct dentry *); + ssize_t (*quota_read)(struct super_block *, int, char *, size_t, loff_t); + ssize_t (*quota_write)(struct super_block *, int, const char *, size_t, loff_t); + int (*bdev_try_to_free_page)(struct super_block*, struct page*, gfp_t); + +locking rules: + All may block [not true, see below] + +====================== ============ ======================== +ops s_umount note +====================== ============ ======================== +alloc_inode: +free_inode: called from RCU callback +destroy_inode: +dirty_inode: +write_inode: +drop_inode: !!!inode->i_lock!!! +evict_inode: +put_super: write +sync_fs: read +freeze_fs: write +unfreeze_fs: write +statfs: maybe(read) (see below) +remount_fs: write +umount_begin: no +show_options: no (namespace_sem) +quota_read: no (see below) +quota_write: no (see below) +bdev_try_to_free_page: no (see below) +====================== ============ ======================== + +->statfs() has s_umount (shared) when called by ustat(2) (native or +compat), but that's an accident of bad API; s_umount is used to pin +the superblock down when we only have dev_t given us by userland to +identify the superblock. Everything else (statfs(), fstatfs(), etc.) +doesn't hold it when calling ->statfs() - superblock is pinned down +by resolving the pathname passed to syscall. + +->quota_read() and ->quota_write() functions are both guaranteed to +be the only ones operating on the quota file by the quota code (via +dqio_sem) (unless an admin really wants to screw up something and +writes to quota files with quotas on). For other details about locking +see also dquot_operations section. + +->bdev_try_to_free_page is called from the ->releasepage handler of +the block device inode. See there for more details. + +file_system_type +================ + +prototypes:: + + struct dentry *(*mount) (struct file_system_type *, int, + const char *, void *); + void (*kill_sb) (struct super_block *); + +locking rules: + +======= ========= +ops may block +======= ========= +mount yes +kill_sb yes +======= ========= + +->mount() returns ERR_PTR or the root dentry; its superblock should be locked +on return. + +->kill_sb() takes a write-locked superblock, does all shutdown work on it, +unlocks and drops the reference. + +address_space_operations +======================== +prototypes:: + + int (*writepage)(struct page *page, struct writeback_control *wbc); + int (*readpage)(struct file *, struct page *); + int (*writepages)(struct address_space *, struct writeback_control *); + int (*set_page_dirty)(struct page *page); + int (*readpages)(struct file *filp, struct address_space *mapping, + struct list_head *pages, unsigned nr_pages); + int (*write_begin)(struct file *, struct address_space *mapping, + loff_t pos, unsigned len, unsigned flags, + struct page **pagep, void **fsdata); + int (*write_end)(struct file *, struct address_space *mapping, + loff_t pos, unsigned len, unsigned copied, + struct page *page, void *fsdata); + sector_t (*bmap)(struct address_space *, sector_t); + void (*invalidatepage) (struct page *, unsigned int, unsigned int); + int (*releasepage) (struct page *, int); + void (*freepage)(struct page *); + int (*direct_IO)(struct kiocb *, struct iov_iter *iter); + bool (*isolate_page) (struct page *, isolate_mode_t); + int (*migratepage)(struct address_space *, struct page *, struct page *); + void (*putback_page) (struct page *); + int (*launder_page)(struct page *); + int (*is_partially_uptodate)(struct page *, unsigned long, unsigned long); + int (*error_remove_page)(struct address_space *, struct page *); + int (*swap_activate)(struct file *); + int (*swap_deactivate)(struct file *); + +locking rules: + All except set_page_dirty and freepage may block + +====================== ======================== ========= +ops PageLocked(page) i_rwsem +====================== ======================== ========= +writepage: yes, unlocks (see below) +readpage: yes, unlocks +writepages: +set_page_dirty no +readpages: +write_begin: locks the page exclusive +write_end: yes, unlocks exclusive +bmap: +invalidatepage: yes +releasepage: yes +freepage: yes +direct_IO: +isolate_page: yes +migratepage: yes (both) +putback_page: yes +launder_page: yes +is_partially_uptodate: yes +error_remove_page: yes +swap_activate: no +swap_deactivate: no +====================== ======================== ========= + +->write_begin(), ->write_end() and ->readpage() may be called from +the request handler (/dev/loop). + +->readpage() unlocks the page, either synchronously or via I/O +completion. + +->readpages() populates the pagecache with the passed pages and starts +I/O against them. They come unlocked upon I/O completion. + +->writepage() is used for two purposes: for "memory cleansing" and for +"sync". These are quite different operations and the behaviour may differ +depending upon the mode. + +If writepage is called for sync (wbc->sync_mode != WBC_SYNC_NONE) then +it *must* start I/O against the page, even if that would involve +blocking on in-progress I/O. + +If writepage is called for memory cleansing (sync_mode == +WBC_SYNC_NONE) then its role is to get as much writeout underway as +possible. So writepage should try to avoid blocking against +currently-in-progress I/O. + +If the filesystem is not called for "sync" and it determines that it +would need to block against in-progress I/O to be able to start new I/O +against the page the filesystem should redirty the page with +redirty_page_for_writepage(), then unlock the page and return zero. +This may also be done to avoid internal deadlocks, but rarely. + +If the filesystem is called for sync then it must wait on any +in-progress I/O and then start new I/O. + +The filesystem should unlock the page synchronously, before returning to the +caller, unless ->writepage() returns special WRITEPAGE_ACTIVATE +value. WRITEPAGE_ACTIVATE means that page cannot really be written out +currently, and VM should stop calling ->writepage() on this page for some +time. VM does this by moving page to the head of the active list, hence the +name. + +Unless the filesystem is going to redirty_page_for_writepage(), unlock the page +and return zero, writepage *must* run set_page_writeback() against the page, +followed by unlocking it. Once set_page_writeback() has been run against the +page, write I/O can be submitted and the write I/O completion handler must run +end_page_writeback() once the I/O is complete. If no I/O is submitted, the +filesystem must run end_page_writeback() against the page before returning from +writepage. + +That is: after 2.5.12, pages which are under writeout are *not* locked. Note, +if the filesystem needs the page to be locked during writeout, that is ok, too, +the page is allowed to be unlocked at any point in time between the calls to +set_page_writeback() and end_page_writeback(). + +Note, failure to run either redirty_page_for_writepage() or the combination of +set_page_writeback()/end_page_writeback() on a page submitted to writepage +will leave the page itself marked clean but it will be tagged as dirty in the +radix tree. This incoherency can lead to all sorts of hard-to-debug problems +in the filesystem like having dirty inodes at umount and losing written data. + +->writepages() is used for periodic writeback and for syscall-initiated +sync operations. The address_space should start I/O against at least +``*nr_to_write`` pages. ``*nr_to_write`` must be decremented for each page +which is written. The address_space implementation may write more (or less) +pages than ``*nr_to_write`` asks for, but it should try to be reasonably close. +If nr_to_write is NULL, all dirty pages must be written. + +writepages should _only_ write pages which are present on +mapping->io_pages. + +->set_page_dirty() is called from various places in the kernel +when the target page is marked as needing writeback. It may be called +under spinlock (it cannot block) and is sometimes called with the page +not locked. + +->bmap() is currently used by legacy ioctl() (FIBMAP) provided by some +filesystems and by the swapper. The latter will eventually go away. Please, +keep it that way and don't breed new callers. + +->invalidatepage() is called when the filesystem must attempt to drop +some or all of the buffers from the page when it is being truncated. It +returns zero on success. If ->invalidatepage is zero, the kernel uses +block_invalidatepage() instead. + +->releasepage() is called when the kernel is about to try to drop the +buffers from the page in preparation for freeing it. It returns zero to +indicate that the buffers are (or may be) freeable. If ->releasepage is zero, +the kernel assumes that the fs has no private interest in the buffers. + +->freepage() is called when the kernel is done dropping the page +from the page cache. + +->launder_page() may be called prior to releasing a page if +it is still found to be dirty. It returns zero if the page was successfully +cleaned, or an error value if not. Note that in order to prevent the page +getting mapped back in and redirtied, it needs to be kept locked +across the entire operation. + +->swap_activate will be called with a non-zero argument on +files backing (non block device backed) swapfiles. A return value +of zero indicates success, in which case this file can be used for +backing swapspace. The swapspace operations will be proxied to the +address space operations. + +->swap_deactivate() will be called in the sys_swapoff() +path after ->swap_activate() returned success. + +file_lock_operations +==================== + +prototypes:: + + void (*fl_copy_lock)(struct file_lock *, struct file_lock *); + void (*fl_release_private)(struct file_lock *); + + +locking rules: + +=================== ============= ========= +ops inode->i_lock may block +=================== ============= ========= +fl_copy_lock: yes no +fl_release_private: maybe maybe[1]_ +=================== ============= ========= + +.. [1]: + ->fl_release_private for flock or POSIX locks is currently allowed + to block. Leases however can still be freed while the i_lock is held and + so fl_release_private called on a lease should not block. + +lock_manager_operations +======================= + +prototypes:: + + void (*lm_notify)(struct file_lock *); /* unblock callback */ + int (*lm_grant)(struct file_lock *, struct file_lock *, int); + void (*lm_break)(struct file_lock *); /* break_lease callback */ + int (*lm_change)(struct file_lock **, int); + +locking rules: + +========== ============= ================= ========= +ops inode->i_lock blocked_lock_lock may block +========== ============= ================= ========= +lm_notify: yes yes no +lm_grant: no no no +lm_break: yes no no +lm_change yes no no +========== ============= ================= ========= + +buffer_head +=========== + +prototypes:: + + void (*b_end_io)(struct buffer_head *bh, int uptodate); + +locking rules: + +called from interrupts. In other words, extreme care is needed here. +bh is locked, but that's all warranties we have here. Currently only RAID1, +highmem, fs/buffer.c, and fs/ntfs/aops.c are providing these. Block devices +call this method upon the IO completion. + +block_device_operations +======================= +prototypes:: + + int (*open) (struct block_device *, fmode_t); + int (*release) (struct gendisk *, fmode_t); + int (*ioctl) (struct block_device *, fmode_t, unsigned, unsigned long); + int (*compat_ioctl) (struct block_device *, fmode_t, unsigned, unsigned long); + int (*direct_access) (struct block_device *, sector_t, void **, + unsigned long *); + int (*media_changed) (struct gendisk *); + void (*unlock_native_capacity) (struct gendisk *); + int (*revalidate_disk) (struct gendisk *); + int (*getgeo)(struct block_device *, struct hd_geometry *); + void (*swap_slot_free_notify) (struct block_device *, unsigned long); + +locking rules: + +======================= =================== +ops bd_mutex +======================= =================== +open: yes +release: yes +ioctl: no +compat_ioctl: no +direct_access: no +media_changed: no +unlock_native_capacity: no +revalidate_disk: no +getgeo: no +swap_slot_free_notify: no (see below) +======================= =================== + +media_changed, unlock_native_capacity and revalidate_disk are called only from +check_disk_change(). + +swap_slot_free_notify is called with swap_lock and sometimes the page lock +held. + + +file_operations +=============== + +prototypes:: + + loff_t (*llseek) (struct file *, loff_t, int); + ssize_t (*read) (struct file *, char __user *, size_t, loff_t *); + ssize_t (*write) (struct file *, const char __user *, size_t, loff_t *); + ssize_t (*read_iter) (struct kiocb *, struct iov_iter *); + ssize_t (*write_iter) (struct kiocb *, struct iov_iter *); + int (*iterate) (struct file *, struct dir_context *); + int (*iterate_shared) (struct file *, struct dir_context *); + __poll_t (*poll) (struct file *, struct poll_table_struct *); + long (*unlocked_ioctl) (struct file *, unsigned int, unsigned long); + long (*compat_ioctl) (struct file *, unsigned int, unsigned long); + int (*mmap) (struct file *, struct vm_area_struct *); + int (*open) (struct inode *, struct file *); + int (*flush) (struct file *); + int (*release) (struct inode *, struct file *); + int (*fsync) (struct file *, loff_t start, loff_t end, int datasync); + int (*fasync) (int, struct file *, int); + int (*lock) (struct file *, int, struct file_lock *); + ssize_t (*readv) (struct file *, const struct iovec *, unsigned long, + loff_t *); + ssize_t (*writev) (struct file *, const struct iovec *, unsigned long, + loff_t *); + ssize_t (*sendfile) (struct file *, loff_t *, size_t, read_actor_t, + void __user *); + ssize_t (*sendpage) (struct file *, struct page *, int, size_t, + loff_t *, int); + unsigned long (*get_unmapped_area)(struct file *, unsigned long, + unsigned long, unsigned long, unsigned long); + int (*check_flags)(int); + int (*flock) (struct file *, int, struct file_lock *); + ssize_t (*splice_write)(struct pipe_inode_info *, struct file *, loff_t *, + size_t, unsigned int); + ssize_t (*splice_read)(struct file *, loff_t *, struct pipe_inode_info *, + size_t, unsigned int); + int (*setlease)(struct file *, long, struct file_lock **, void **); + long (*fallocate)(struct file *, int, loff_t, loff_t); + +locking rules: + All may block. + +->llseek() locking has moved from llseek to the individual llseek +implementations. If your fs is not using generic_file_llseek, you +need to acquire and release the appropriate locks in your ->llseek(). +For many filesystems, it is probably safe to acquire the inode +mutex or just to use i_size_read() instead. +Note: this does not protect the file->f_pos against concurrent modifications +since this is something the userspace has to take care about. + +->iterate() is called with i_rwsem exclusive. + +->iterate_shared() is called with i_rwsem at least shared. + +->fasync() is responsible for maintaining the FASYNC bit in filp->f_flags. +Most instances call fasync_helper(), which does that maintenance, so it's +not normally something one needs to worry about. Return values > 0 will be +mapped to zero in the VFS layer. + +->readdir() and ->ioctl() on directories must be changed. Ideally we would +move ->readdir() to inode_operations and use a separate method for directory +->ioctl() or kill the latter completely. One of the problems is that for +anything that resembles union-mount we won't have a struct file for all +components. And there are other reasons why the current interface is a mess... + +->read on directories probably must go away - we should just enforce -EISDIR +in sys_read() and friends. + +->setlease operations should call generic_setlease() before or after setting +the lease within the individual filesystem to record the result of the +operation + +dquot_operations +================ + +prototypes:: + + int (*write_dquot) (struct dquot *); + int (*acquire_dquot) (struct dquot *); + int (*release_dquot) (struct dquot *); + int (*mark_dirty) (struct dquot *); + int (*write_info) (struct super_block *, int); + +These operations are intended to be more or less wrapping functions that ensure +a proper locking wrt the filesystem and call the generic quota operations. + +What filesystem should expect from the generic quota functions: + +============== ============ ========================= +ops FS recursion Held locks when called +============== ============ ========================= +write_dquot: yes dqonoff_sem or dqptr_sem +acquire_dquot: yes dqonoff_sem or dqptr_sem +release_dquot: yes dqonoff_sem or dqptr_sem +mark_dirty: no - +write_info: yes dqonoff_sem +============== ============ ========================= + +FS recursion means calling ->quota_read() and ->quota_write() from superblock +operations. + +More details about quota locking can be found in fs/dquot.c. + +vm_operations_struct +==================== + +prototypes:: + + void (*open)(struct vm_area_struct*); + void (*close)(struct vm_area_struct*); + vm_fault_t (*fault)(struct vm_area_struct*, struct vm_fault *); + vm_fault_t (*page_mkwrite)(struct vm_area_struct *, struct vm_fault *); + vm_fault_t (*pfn_mkwrite)(struct vm_area_struct *, struct vm_fault *); + int (*access)(struct vm_area_struct *, unsigned long, void*, int, int); + +locking rules: + +============= ======== =========================== +ops mmap_sem PageLocked(page) +============= ======== =========================== +open: yes +close: yes +fault: yes can return with page locked +map_pages: yes +page_mkwrite: yes can return with page locked +pfn_mkwrite: yes +access: yes +============= ======== =========================== + +->fault() is called when a previously not present pte is about +to be faulted in. The filesystem must find and return the page associated +with the passed in "pgoff" in the vm_fault structure. If it is possible that +the page may be truncated and/or invalidated, then the filesystem must lock +the page, then ensure it is not already truncated (the page lock will block +subsequent truncate), and then return with VM_FAULT_LOCKED, and the page +locked. The VM will unlock the page. + +->map_pages() is called when VM asks to map easy accessible pages. +Filesystem should find and map pages associated with offsets from "start_pgoff" +till "end_pgoff". ->map_pages() is called with page table locked and must +not block. If it's not possible to reach a page without blocking, +filesystem should skip it. Filesystem should use do_set_pte() to setup +page table entry. Pointer to entry associated with the page is passed in +"pte" field in vm_fault structure. Pointers to entries for other offsets +should be calculated relative to "pte". + +->page_mkwrite() is called when a previously read-only pte is +about to become writeable. The filesystem again must ensure that there are +no truncate/invalidate races, and then return with the page locked. If +the page has been truncated, the filesystem should not look up a new page +like the ->fault() handler, but simply return with VM_FAULT_NOPAGE, which +will cause the VM to retry the fault. + +->pfn_mkwrite() is the same as page_mkwrite but when the pte is +VM_PFNMAP or VM_MIXEDMAP with a page-less entry. Expected return is +VM_FAULT_NOPAGE. Or one of the VM_FAULT_ERROR types. The default behavior +after this call is to make the pte read-write, unless pfn_mkwrite returns +an error. + +->access() is called when get_user_pages() fails in +access_process_vm(), typically used to debug a process through +/proc/pid/mem or ptrace. This function is needed only for +VM_IO | VM_PFNMAP VMAs. + +-------------------------------------------------------------------------------- + + Dubious stuff + +(if you break something or notice that it is broken and do not fix it yourself +- at least put it here) diff --git a/Documentation/filesystems/nfs/Exporting b/Documentation/filesystems/nfs/Exporting deleted file mode 100644 index 63889149f532..000000000000 --- a/Documentation/filesystems/nfs/Exporting +++ /dev/null @@ -1,160 +0,0 @@ - -Making Filesystems Exportable -============================= - -Overview --------- - -All filesystem operations require a dentry (or two) as a starting -point. Local applications have a reference-counted hold on suitable -dentries via open file descriptors or cwd/root. However remote -applications that access a filesystem via a remote filesystem protocol -such as NFS may not be able to hold such a reference, and so need a -different way to refer to a particular dentry. As the alternative -form of reference needs to be stable across renames, truncates, and -server-reboot (among other things, though these tend to be the most -problematic), there is no simple answer like 'filename'. - -The mechanism discussed here allows each filesystem implementation to -specify how to generate an opaque (outside of the filesystem) byte -string for any dentry, and how to find an appropriate dentry for any -given opaque byte string. -This byte string will be called a "filehandle fragment" as it -corresponds to part of an NFS filehandle. - -A filesystem which supports the mapping between filehandle fragments -and dentries will be termed "exportable". - - - -Dcache Issues -------------- - -The dcache normally contains a proper prefix of any given filesystem -tree. This means that if any filesystem object is in the dcache, then -all of the ancestors of that filesystem object are also in the dcache. -As normal access is by filename this prefix is created naturally and -maintained easily (by each object maintaining a reference count on -its parent). - -However when objects are included into the dcache by interpreting a -filehandle fragment, there is no automatic creation of a path prefix -for the object. This leads to two related but distinct features of -the dcache that are not needed for normal filesystem access. - -1/ The dcache must sometimes contain objects that are not part of the - proper prefix. i.e that are not connected to the root. -2/ The dcache must be prepared for a newly found (via ->lookup) directory - to already have a (non-connected) dentry, and must be able to move - that dentry into place (based on the parent and name in the - ->lookup). This is particularly needed for directories as - it is a dcache invariant that directories only have one dentry. - -To implement these features, the dcache has: - -a/ A dentry flag DCACHE_DISCONNECTED which is set on - any dentry that might not be part of the proper prefix. - This is set when anonymous dentries are created, and cleared when a - dentry is noticed to be a child of a dentry which is in the proper - prefix. If the refcount on a dentry with this flag set - becomes zero, the dentry is immediately discarded, rather than being - kept in the dcache. If a dentry that is not already in the dcache - is repeatedly accessed by filehandle (as NFSD might do), an new dentry - will be a allocated for each access, and discarded at the end of - the access. - - Note that such a dentry can acquire children, name, ancestors, etc. - without losing DCACHE_DISCONNECTED - that flag is only cleared when - subtree is successfully reconnected to root. Until then dentries - in such subtree are retained only as long as there are references; - refcount reaching zero means immediate eviction, same as for unhashed - dentries. That guarantees that we won't need to hunt them down upon - umount. - -b/ A primitive for creation of secondary roots - d_obtain_root(inode). - Those do _not_ bear DCACHE_DISCONNECTED. They are placed on the - per-superblock list (->s_roots), so they can be located at umount - time for eviction purposes. - -c/ Helper routines to allocate anonymous dentries, and to help attach - loose directory dentries at lookup time. They are: - d_obtain_alias(inode) will return a dentry for the given inode. - If the inode already has a dentry, one of those is returned. - If it doesn't, a new anonymous (IS_ROOT and - DCACHE_DISCONNECTED) dentry is allocated and attached. - In the case of a directory, care is taken that only one dentry - can ever be attached. - d_splice_alias(inode, dentry) will introduce a new dentry into the tree; - either the passed-in dentry or a preexisting alias for the given inode - (such as an anonymous one created by d_obtain_alias), if appropriate. - It returns NULL when the passed-in dentry is used, following the calling - convention of ->lookup. - -Filesystem Issues ------------------ - -For a filesystem to be exportable it must: - - 1/ provide the filehandle fragment routines described below. - 2/ make sure that d_splice_alias is used rather than d_add - when ->lookup finds an inode for a given parent and name. - - If inode is NULL, d_splice_alias(inode, dentry) is equivalent to - - d_add(dentry, inode), NULL - - Similarly, d_splice_alias(ERR_PTR(err), dentry) = ERR_PTR(err) - - Typically the ->lookup routine will simply end with a: - - return d_splice_alias(inode, dentry); - } - - - - A file system implementation declares that instances of the filesystem -are exportable by setting the s_export_op field in the struct -super_block. This field must point to a "struct export_operations" -struct which has the following members: - - encode_fh (optional) - Takes a dentry and creates a filehandle fragment which can later be used - to find or create a dentry for the same object. The default - implementation creates a filehandle fragment that encodes a 32bit inode - and generation number for the inode encoded, and if necessary the - same information for the parent. - - fh_to_dentry (mandatory) - Given a filehandle fragment, this should find the implied object and - create a dentry for it (possibly with d_obtain_alias). - - fh_to_parent (optional but strongly recommended) - Given a filehandle fragment, this should find the parent of the - implied object and create a dentry for it (possibly with - d_obtain_alias). May fail if the filehandle fragment is too small. - - get_parent (optional but strongly recommended) - When given a dentry for a directory, this should return a dentry for - the parent. Quite possibly the parent dentry will have been allocated - by d_alloc_anon. The default get_parent function just returns an error - so any filehandle lookup that requires finding a parent will fail. - ->lookup("..") is *not* used as a default as it can leave ".." entries - in the dcache which are too messy to work with. - - get_name (optional) - When given a parent dentry and a child dentry, this should find a name - in the directory identified by the parent dentry, which leads to the - object identified by the child dentry. If no get_name function is - supplied, a default implementation is provided which uses vfs_readdir - to find potential names, and matches inode numbers to find the correct - match. - - -A filehandle fragment consists of an array of 1 or more 4byte words, -together with a one byte "type". -The decode_fh routine should not depend on the stated size that is -passed to it. This size may be larger than the original filehandle -generated by encode_fh, in which case it will have been padded with -nuls. Rather, the encode_fh routine should choose a "type" which -indicates the decode_fh how much of the filehandle is valid, and how -it should be interpreted. diff --git a/Documentation/filesystems/nfs/exporting.rst b/Documentation/filesystems/nfs/exporting.rst new file mode 100644 index 000000000000..33d588a01ace --- /dev/null +++ b/Documentation/filesystems/nfs/exporting.rst @@ -0,0 +1,165 @@ +:orphan: + +Making Filesystems Exportable +============================= + +Overview +-------- + +All filesystem operations require a dentry (or two) as a starting +point. Local applications have a reference-counted hold on suitable +dentries via open file descriptors or cwd/root. However remote +applications that access a filesystem via a remote filesystem protocol +such as NFS may not be able to hold such a reference, and so need a +different way to refer to a particular dentry. As the alternative +form of reference needs to be stable across renames, truncates, and +server-reboot (among other things, though these tend to be the most +problematic), there is no simple answer like 'filename'. + +The mechanism discussed here allows each filesystem implementation to +specify how to generate an opaque (outside of the filesystem) byte +string for any dentry, and how to find an appropriate dentry for any +given opaque byte string. +This byte string will be called a "filehandle fragment" as it +corresponds to part of an NFS filehandle. + +A filesystem which supports the mapping between filehandle fragments +and dentries will be termed "exportable". + + + +Dcache Issues +------------- + +The dcache normally contains a proper prefix of any given filesystem +tree. This means that if any filesystem object is in the dcache, then +all of the ancestors of that filesystem object are also in the dcache. +As normal access is by filename this prefix is created naturally and +maintained easily (by each object maintaining a reference count on +its parent). + +However when objects are included into the dcache by interpreting a +filehandle fragment, there is no automatic creation of a path prefix +for the object. This leads to two related but distinct features of +the dcache that are not needed for normal filesystem access. + +1. The dcache must sometimes contain objects that are not part of the + proper prefix. i.e that are not connected to the root. +2. The dcache must be prepared for a newly found (via ->lookup) directory + to already have a (non-connected) dentry, and must be able to move + that dentry into place (based on the parent and name in the + ->lookup). This is particularly needed for directories as + it is a dcache invariant that directories only have one dentry. + +To implement these features, the dcache has: + +a. A dentry flag DCACHE_DISCONNECTED which is set on + any dentry that might not be part of the proper prefix. + This is set when anonymous dentries are created, and cleared when a + dentry is noticed to be a child of a dentry which is in the proper + prefix. If the refcount on a dentry with this flag set + becomes zero, the dentry is immediately discarded, rather than being + kept in the dcache. If a dentry that is not already in the dcache + is repeatedly accessed by filehandle (as NFSD might do), an new dentry + will be a allocated for each access, and discarded at the end of + the access. + + Note that such a dentry can acquire children, name, ancestors, etc. + without losing DCACHE_DISCONNECTED - that flag is only cleared when + subtree is successfully reconnected to root. Until then dentries + in such subtree are retained only as long as there are references; + refcount reaching zero means immediate eviction, same as for unhashed + dentries. That guarantees that we won't need to hunt them down upon + umount. + +b. A primitive for creation of secondary roots - d_obtain_root(inode). + Those do _not_ bear DCACHE_DISCONNECTED. They are placed on the + per-superblock list (->s_roots), so they can be located at umount + time for eviction purposes. + +c. Helper routines to allocate anonymous dentries, and to help attach + loose directory dentries at lookup time. They are: + + d_obtain_alias(inode) will return a dentry for the given inode. + If the inode already has a dentry, one of those is returned. + + If it doesn't, a new anonymous (IS_ROOT and + DCACHE_DISCONNECTED) dentry is allocated and attached. + + In the case of a directory, care is taken that only one dentry + can ever be attached. + + d_splice_alias(inode, dentry) will introduce a new dentry into the tree; + either the passed-in dentry or a preexisting alias for the given inode + (such as an anonymous one created by d_obtain_alias), if appropriate. + It returns NULL when the passed-in dentry is used, following the calling + convention of ->lookup. + +Filesystem Issues +----------------- + +For a filesystem to be exportable it must: + + 1. provide the filehandle fragment routines described below. + 2. make sure that d_splice_alias is used rather than d_add + when ->lookup finds an inode for a given parent and name. + + If inode is NULL, d_splice_alias(inode, dentry) is equivalent to:: + + d_add(dentry, inode), NULL + + Similarly, d_splice_alias(ERR_PTR(err), dentry) = ERR_PTR(err) + + Typically the ->lookup routine will simply end with a:: + + return d_splice_alias(inode, dentry); + } + + + +A file system implementation declares that instances of the filesystem +are exportable by setting the s_export_op field in the struct +super_block. This field must point to a "struct export_operations" +struct which has the following members: + + encode_fh (optional) + Takes a dentry and creates a filehandle fragment which can later be used + to find or create a dentry for the same object. The default + implementation creates a filehandle fragment that encodes a 32bit inode + and generation number for the inode encoded, and if necessary the + same information for the parent. + + fh_to_dentry (mandatory) + Given a filehandle fragment, this should find the implied object and + create a dentry for it (possibly with d_obtain_alias). + + fh_to_parent (optional but strongly recommended) + Given a filehandle fragment, this should find the parent of the + implied object and create a dentry for it (possibly with + d_obtain_alias). May fail if the filehandle fragment is too small. + + get_parent (optional but strongly recommended) + When given a dentry for a directory, this should return a dentry for + the parent. Quite possibly the parent dentry will have been allocated + by d_alloc_anon. The default get_parent function just returns an error + so any filehandle lookup that requires finding a parent will fail. + ->lookup("..") is *not* used as a default as it can leave ".." entries + in the dcache which are too messy to work with. + + get_name (optional) + When given a parent dentry and a child dentry, this should find a name + in the directory identified by the parent dentry, which leads to the + object identified by the child dentry. If no get_name function is + supplied, a default implementation is provided which uses vfs_readdir + to find potential names, and matches inode numbers to find the correct + match. + + +A filehandle fragment consists of an array of 1 or more 4byte words, +together with a one byte "type". +The decode_fh routine should not depend on the stated size that is +passed to it. This size may be larger than the original filehandle +generated by encode_fh, in which case it will have been padded with +nuls. Rather, the encode_fh routine should choose a "type" which +indicates the decode_fh how much of the filehandle is valid, and how +it should be interpreted. diff --git a/Documentation/filesystems/vfs.rst b/Documentation/filesystems/vfs.rst index 0f85ab21c2ca..7d4d09dd5e6d 100644 --- a/Documentation/filesystems/vfs.rst +++ b/Documentation/filesystems/vfs.rst @@ -20,7 +20,7 @@ kernel which allows different filesystem implementations to coexist. VFS system calls open(2), stat(2), read(2), write(2), chmod(2) and so on are called from a process context. Filesystem locking is described in -the document Documentation/filesystems/Locking. +the document Documentation/filesystems/locking.rst. Directory Entry Cache (dcache) diff --git a/fs/cifs/export.c b/fs/cifs/export.c index ce8b7f677c58..eb0bb8ca8e63 100644 --- a/fs/cifs/export.c +++ b/fs/cifs/export.c @@ -24,7 +24,7 @@ */ /* - * See Documentation/filesystems/nfs/Exporting + * See Documentation/filesystems/nfs/exporting.rst * and examples in fs/exportfs * * Since cifs is a network file system, an "fsid" must be included for diff --git a/fs/exportfs/expfs.c b/fs/exportfs/expfs.c index f0e549783caf..09bc68708d28 100644 --- a/fs/exportfs/expfs.c +++ b/fs/exportfs/expfs.c @@ -7,7 +7,7 @@ * and for mapping back from file handles to dentries. * * For details on why we do all the strange and hairy things in here - * take a look at Documentation/filesystems/nfs/Exporting. + * take a look at Documentation/filesystems/nfs/exporting.rst. */ #include #include diff --git a/fs/isofs/export.c b/fs/isofs/export.c index 85a9093769a9..35768a63fb1d 100644 --- a/fs/isofs/export.c +++ b/fs/isofs/export.c @@ -10,7 +10,7 @@ * * The following files are helpful: * - * Documentation/filesystems/nfs/Exporting + * Documentation/filesystems/nfs/exporting.rst * fs/exportfs/expfs.c. */ diff --git a/fs/orangefs/file.c b/fs/orangefs/file.c index 960f9a3c012d..a5612abc0936 100644 --- a/fs/orangefs/file.c +++ b/fs/orangefs/file.c @@ -555,7 +555,7 @@ static int orangefs_fsync(struct file *file, * Change the file pointer position for an instance of an open file. * * \note If .llseek is overriden, we must acquire lock as described in - * Documentation/filesystems/Locking. + * Documentation/filesystems/locking.rst. * * Future upgrade could support SEEK_DATA and SEEK_HOLE but would * require much changes to the FS diff --git a/include/linux/dcache.h b/include/linux/dcache.h index 9451011ac014..10090f11ab95 100644 --- a/include/linux/dcache.h +++ b/include/linux/dcache.h @@ -151,7 +151,7 @@ struct dentry_operations { /* * Locking rules for dentry_operations callbacks are to be found in - * Documentation/filesystems/Locking. Keep it updated! + * Documentation/filesystems/locking.rst. Keep it updated! * * FUrther descriptions are found in Documentation/filesystems/vfs.rst. * Keep it updated too! diff --git a/include/linux/exportfs.h b/include/linux/exportfs.h index 0d3037419bc7..cf6571fc9c01 100644 --- a/include/linux/exportfs.h +++ b/include/linux/exportfs.h @@ -139,7 +139,7 @@ struct fid { * @get_parent: find the parent of a given directory * @commit_metadata: commit metadata changes to stable storage * - * See Documentation/filesystems/nfs/Exporting for details on how to use + * See Documentation/filesystems/nfs/exporting.rst for details on how to use * this interface correctly. * * encode_fh: -- cgit v1.2.3 From 9cdd273e29f3b901712ec3c298b1d506861f48e3 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 31 Jul 2019 17:08:50 -0300 Subject: spi: docs: convert to ReST and add it to the kABI bookset While there's one file there with briefily describes the uAPI, the documentation was written just like most subsystems: focused on kernel developers. So, add it together with driver-api books. Signed-off-by: Mauro Carvalho Chehab Acked-by: Jonathan Cameron # for iio Signed-off-by: Jonathan Corbet --- Documentation/index.rst | 1 + Documentation/spi/butterfly | 68 ---- Documentation/spi/butterfly.rst | 74 ++++ Documentation/spi/index.rst | 22 ++ Documentation/spi/pxa2xx | 235 ------------ Documentation/spi/pxa2xx.rst | 240 ++++++++++++ Documentation/spi/spi-lm70llp | 79 ---- Documentation/spi/spi-lm70llp.rst | 84 +++++ Documentation/spi/spi-sc18is602 | 36 -- Documentation/spi/spi-sc18is602.rst | 39 ++ Documentation/spi/spi-summary | 631 ------------------------------- Documentation/spi/spi-summary.rst | 644 ++++++++++++++++++++++++++++++++ Documentation/spi/spidev | 149 -------- Documentation/spi/spidev.rst | 163 ++++++++ drivers/iio/dummy/iio_simple_dummy.c | 2 +- drivers/spi/Kconfig | 2 +- drivers/spi/spi-butterfly.c | 2 +- drivers/spi/spi-lm70llp.c | 2 +- include/linux/platform_data/sc18is602.h | 2 +- 19 files changed, 1272 insertions(+), 1203 deletions(-) delete mode 100644 Documentation/spi/butterfly create mode 100644 Documentation/spi/butterfly.rst create mode 100644 Documentation/spi/index.rst delete mode 100644 Documentation/spi/pxa2xx create mode 100644 Documentation/spi/pxa2xx.rst delete mode 100644 Documentation/spi/spi-lm70llp create mode 100644 Documentation/spi/spi-lm70llp.rst delete mode 100644 Documentation/spi/spi-sc18is602 create mode 100644 Documentation/spi/spi-sc18is602.rst delete mode 100644 Documentation/spi/spi-summary create mode 100644 Documentation/spi/spi-summary.rst delete mode 100644 Documentation/spi/spidev create mode 100644 Documentation/spi/spidev.rst (limited to 'include') diff --git a/Documentation/index.rst b/Documentation/index.rst index 6217acab92db..472b8abe52e9 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -116,6 +116,7 @@ needed). power/index target/index timers/index + spi/index watchdog/index virtual/index input/index diff --git a/Documentation/spi/butterfly b/Documentation/spi/butterfly deleted file mode 100644 index 9927af7a629c..000000000000 --- a/Documentation/spi/butterfly +++ /dev/null @@ -1,68 +0,0 @@ -spi_butterfly - parport-to-butterfly adapter driver -=================================================== - -This is a hardware and software project that includes building and using -a parallel port adapter cable, together with an "AVR Butterfly" to run -firmware for user interfacing and/or sensors. A Butterfly is a $US20 -battery powered card with an AVR microcontroller and lots of goodies: -sensors, LCD, flash, toggle stick, and more. You can use AVR-GCC to -develop firmware for this, and flash it using this adapter cable. - -You can make this adapter from an old printer cable and solder things -directly to the Butterfly. Or (if you have the parts and skills) you -can come up with something fancier, providing ciruit protection to the -Butterfly and the printer port, or with a better power supply than two -signal pins from the printer port. Or for that matter, you can use -similar cables to talk to many AVR boards, even a breadboard. - -This is more powerful than "ISP programming" cables since it lets kernel -SPI protocol drivers interact with the AVR, and could even let the AVR -issue interrupts to them. Later, your protocol driver should work -easily with a "real SPI controller", instead of this bitbanger. - - -The first cable connections will hook Linux up to one SPI bus, with the -AVR and a DataFlash chip; and to the AVR reset line. This is all you -need to reflash the firmware, and the pins are the standard Atmel "ISP" -connector pins (used also on non-Butterfly AVR boards). On the parport -side this is like "sp12" programming cables. - - Signal Butterfly Parport (DB-25) - ------ --------- --------------- - SCK = J403.PB1/SCK = pin 2/D0 - RESET = J403.nRST = pin 3/D1 - VCC = J403.VCC_EXT = pin 8/D6 - MOSI = J403.PB2/MOSI = pin 9/D7 - MISO = J403.PB3/MISO = pin 11/S7,nBUSY - GND = J403.GND = pin 23/GND - -Then to let Linux master that bus to talk to the DataFlash chip, you must -(a) flash new firmware that disables SPI (set PRR.2, and disable pullups -by clearing PORTB.[0-3]); (b) configure the mtd_dataflash driver; and -(c) cable in the chipselect. - - Signal Butterfly Parport (DB-25) - ------ --------- --------------- - VCC = J400.VCC_EXT = pin 7/D5 - SELECT = J400.PB0/nSS = pin 17/C3,nSELECT - GND = J400.GND = pin 24/GND - -Or you could flash firmware making the AVR into an SPI slave (keeping the -DataFlash in reset) and tweak the spi_butterfly driver to make it bind to -the driver for your custom SPI-based protocol. - -The "USI" controller, using J405, can also be used for a second SPI bus. -That would let you talk to the AVR using custom SPI-with-USI firmware, -while letting either Linux or the AVR use the DataFlash. There are plenty -of spare parport pins to wire this one up, such as: - - Signal Butterfly Parport (DB-25) - ------ --------- --------------- - SCK = J403.PE4/USCK = pin 5/D3 - MOSI = J403.PE5/DI = pin 6/D4 - MISO = J403.PE6/DO = pin 12/S5,nPAPEROUT - GND = J403.GND = pin 22/GND - - IRQ = J402.PF4 = pin 10/S6,ACK - GND = J402.GND(P2) = pin 25/GND - diff --git a/Documentation/spi/butterfly.rst b/Documentation/spi/butterfly.rst new file mode 100644 index 000000000000..e614a589547c --- /dev/null +++ b/Documentation/spi/butterfly.rst @@ -0,0 +1,74 @@ +=================================================== +spi_butterfly - parport-to-butterfly adapter driver +=================================================== + +This is a hardware and software project that includes building and using +a parallel port adapter cable, together with an "AVR Butterfly" to run +firmware for user interfacing and/or sensors. A Butterfly is a $US20 +battery powered card with an AVR microcontroller and lots of goodies: +sensors, LCD, flash, toggle stick, and more. You can use AVR-GCC to +develop firmware for this, and flash it using this adapter cable. + +You can make this adapter from an old printer cable and solder things +directly to the Butterfly. Or (if you have the parts and skills) you +can come up with something fancier, providing ciruit protection to the +Butterfly and the printer port, or with a better power supply than two +signal pins from the printer port. Or for that matter, you can use +similar cables to talk to many AVR boards, even a breadboard. + +This is more powerful than "ISP programming" cables since it lets kernel +SPI protocol drivers interact with the AVR, and could even let the AVR +issue interrupts to them. Later, your protocol driver should work +easily with a "real SPI controller", instead of this bitbanger. + + +The first cable connections will hook Linux up to one SPI bus, with the +AVR and a DataFlash chip; and to the AVR reset line. This is all you +need to reflash the firmware, and the pins are the standard Atmel "ISP" +connector pins (used also on non-Butterfly AVR boards). On the parport +side this is like "sp12" programming cables. + + ====== ============= =================== + Signal Butterfly Parport (DB-25) + ====== ============= =================== + SCK J403.PB1/SCK pin 2/D0 + RESET J403.nRST pin 3/D1 + VCC J403.VCC_EXT pin 8/D6 + MOSI J403.PB2/MOSI pin 9/D7 + MISO J403.PB3/MISO pin 11/S7,nBUSY + GND J403.GND pin 23/GND + ====== ============= =================== + +Then to let Linux master that bus to talk to the DataFlash chip, you must +(a) flash new firmware that disables SPI (set PRR.2, and disable pullups +by clearing PORTB.[0-3]); (b) configure the mtd_dataflash driver; and +(c) cable in the chipselect. + + ====== ============ =================== + Signal Butterfly Parport (DB-25) + ====== ============ =================== + VCC J400.VCC_EXT pin 7/D5 + SELECT J400.PB0/nSS pin 17/C3,nSELECT + GND J400.GND pin 24/GND + ====== ============ =================== + +Or you could flash firmware making the AVR into an SPI slave (keeping the +DataFlash in reset) and tweak the spi_butterfly driver to make it bind to +the driver for your custom SPI-based protocol. + +The "USI" controller, using J405, can also be used for a second SPI bus. +That would let you talk to the AVR using custom SPI-with-USI firmware, +while letting either Linux or the AVR use the DataFlash. There are plenty +of spare parport pins to wire this one up, such as: + + ====== ============= =================== + Signal Butterfly Parport (DB-25) + ====== ============= =================== + SCK J403.PE4/USCK pin 5/D3 + MOSI J403.PE5/DI pin 6/D4 + MISO J403.PE6/DO pin 12/S5,nPAPEROUT + GND J403.GND pin 22/GND + + IRQ J402.PF4 pin 10/S6,ACK + GND J402.GND(P2) pin 25/GND + ====== ============= =================== diff --git a/Documentation/spi/index.rst b/Documentation/spi/index.rst new file mode 100644 index 000000000000..06c34ea11bcf --- /dev/null +++ b/Documentation/spi/index.rst @@ -0,0 +1,22 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================================= +Serial Peripheral Interface (SPI) +================================= + +.. toctree:: + :maxdepth: 1 + + spi-summary + spidev + butterfly + pxa2xx + spi-lm70llp + spi-sc18is602 + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/spi/pxa2xx b/Documentation/spi/pxa2xx deleted file mode 100644 index 551325b66b23..000000000000 --- a/Documentation/spi/pxa2xx +++ /dev/null @@ -1,235 +0,0 @@ -PXA2xx SPI on SSP driver HOWTO -=================================================== -This a mini howto on the pxa2xx_spi driver. The driver turns a PXA2xx -synchronous serial port into a SPI master controller -(see Documentation/spi/spi-summary). The driver has the following features - -- Support for any PXA2xx SSP -- SSP PIO and SSP DMA data transfers. -- External and Internal (SSPFRM) chip selects. -- Per slave device (chip) configuration. -- Full suspend, freeze, resume support. - -The driver is built around a "spi_message" fifo serviced by workqueue and a -tasklet. The workqueue, "pump_messages", drives message fifo and the tasklet -(pump_transfer) is responsible for queuing SPI transactions and setting up and -launching the dma/interrupt driven transfers. - -Declaring PXA2xx Master Controllers ------------------------------------ -Typically a SPI master is defined in the arch/.../mach-*/board-*.c as a -"platform device". The master configuration is passed to the driver via a table -found in include/linux/spi/pxa2xx_spi.h: - -struct pxa2xx_spi_controller { - u16 num_chipselect; - u8 enable_dma; -}; - -The "pxa2xx_spi_controller.num_chipselect" field is used to determine the number of -slave device (chips) attached to this SPI master. - -The "pxa2xx_spi_controller.enable_dma" field informs the driver that SSP DMA should -be used. This caused the driver to acquire two DMA channels: rx_channel and -tx_channel. The rx_channel has a higher DMA service priority the tx_channel. -See the "PXA2xx Developer Manual" section "DMA Controller". - -NSSP MASTER SAMPLE ------------------- -Below is a sample configuration using the PXA255 NSSP. - -static struct resource pxa_spi_nssp_resources[] = { - [0] = { - .start = __PREG(SSCR0_P(2)), /* Start address of NSSP */ - .end = __PREG(SSCR0_P(2)) + 0x2c, /* Range of registers */ - .flags = IORESOURCE_MEM, - }, - [1] = { - .start = IRQ_NSSP, /* NSSP IRQ */ - .end = IRQ_NSSP, - .flags = IORESOURCE_IRQ, - }, -}; - -static struct pxa2xx_spi_controller pxa_nssp_master_info = { - .num_chipselect = 1, /* Matches the number of chips attached to NSSP */ - .enable_dma = 1, /* Enables NSSP DMA */ -}; - -static struct platform_device pxa_spi_nssp = { - .name = "pxa2xx-spi", /* MUST BE THIS VALUE, so device match driver */ - .id = 2, /* Bus number, MUST MATCH SSP number 1..n */ - .resource = pxa_spi_nssp_resources, - .num_resources = ARRAY_SIZE(pxa_spi_nssp_resources), - .dev = { - .platform_data = &pxa_nssp_master_info, /* Passed to driver */ - }, -}; - -static struct platform_device *devices[] __initdata = { - &pxa_spi_nssp, -}; - -static void __init board_init(void) -{ - (void)platform_add_device(devices, ARRAY_SIZE(devices)); -} - -Declaring Slave Devices ------------------------ -Typically each SPI slave (chip) is defined in the arch/.../mach-*/board-*.c -using the "spi_board_info" structure found in "linux/spi/spi.h". See -"Documentation/spi/spi-summary" for additional information. - -Each slave device attached to the PXA must provide slave specific configuration -information via the structure "pxa2xx_spi_chip" found in -"include/linux/spi/pxa2xx_spi.h". The pxa2xx_spi master controller driver -will uses the configuration whenever the driver communicates with the slave -device. All fields are optional. - -struct pxa2xx_spi_chip { - u8 tx_threshold; - u8 rx_threshold; - u8 dma_burst_size; - u32 timeout; - u8 enable_loopback; - void (*cs_control)(u32 command); -}; - -The "pxa2xx_spi_chip.tx_threshold" and "pxa2xx_spi_chip.rx_threshold" fields are -used to configure the SSP hardware fifo. These fields are critical to the -performance of pxa2xx_spi driver and misconfiguration will result in rx -fifo overruns (especially in PIO mode transfers). Good default values are - - .tx_threshold = 8, - .rx_threshold = 8, - -The range is 1 to 16 where zero indicates "use default". - -The "pxa2xx_spi_chip.dma_burst_size" field is used to configure PXA2xx DMA -engine and is related the "spi_device.bits_per_word" field. Read and understand -the PXA2xx "Developer Manual" sections on the DMA controller and SSP Controllers -to determine the correct value. An SSP configured for byte-wide transfers would -use a value of 8. The driver will determine a reasonable default if -dma_burst_size == 0. - -The "pxa2xx_spi_chip.timeout" fields is used to efficiently handle -trailing bytes in the SSP receiver fifo. The correct value for this field is -dependent on the SPI bus speed ("spi_board_info.max_speed_hz") and the specific -slave device. Please note that the PXA2xx SSP 1 does not support trailing byte -timeouts and must busy-wait any trailing bytes. - -The "pxa2xx_spi_chip.enable_loopback" field is used to place the SSP porting -into internal loopback mode. In this mode the SSP controller internally -connects the SSPTX pin to the SSPRX pin. This is useful for initial setup -testing. - -The "pxa2xx_spi_chip.cs_control" field is used to point to a board specific -function for asserting/deasserting a slave device chip select. If the field is -NULL, the pxa2xx_spi master controller driver assumes that the SSP port is -configured to use SSPFRM instead. - -NOTE: the SPI driver cannot control the chip select if SSPFRM is used, so the -chipselect is dropped after each spi_transfer. Most devices need chip select -asserted around the complete message. Use SSPFRM as a GPIO (through cs_control) -to accommodate these chips. - - -NSSP SLAVE SAMPLE ------------------ -The pxa2xx_spi_chip structure is passed to the pxa2xx_spi driver in the -"spi_board_info.controller_data" field. Below is a sample configuration using -the PXA255 NSSP. - -/* Chip Select control for the CS8415A SPI slave device */ -static void cs8415a_cs_control(u32 command) -{ - if (command & PXA2XX_CS_ASSERT) - GPCR(2) = GPIO_bit(2); - else - GPSR(2) = GPIO_bit(2); -} - -/* Chip Select control for the CS8405A SPI slave device */ -static void cs8405a_cs_control(u32 command) -{ - if (command & PXA2XX_CS_ASSERT) - GPCR(3) = GPIO_bit(3); - else - GPSR(3) = GPIO_bit(3); -} - -static struct pxa2xx_spi_chip cs8415a_chip_info = { - .tx_threshold = 8, /* SSP hardward FIFO threshold */ - .rx_threshold = 8, /* SSP hardward FIFO threshold */ - .dma_burst_size = 8, /* Byte wide transfers used so 8 byte bursts */ - .timeout = 235, /* See Intel documentation */ - .cs_control = cs8415a_cs_control, /* Use external chip select */ -}; - -static struct pxa2xx_spi_chip cs8405a_chip_info = { - .tx_threshold = 8, /* SSP hardward FIFO threshold */ - .rx_threshold = 8, /* SSP hardward FIFO threshold */ - .dma_burst_size = 8, /* Byte wide transfers used so 8 byte bursts */ - .timeout = 235, /* See Intel documentation */ - .cs_control = cs8405a_cs_control, /* Use external chip select */ -}; - -static struct spi_board_info streetracer_spi_board_info[] __initdata = { - { - .modalias = "cs8415a", /* Name of spi_driver for this device */ - .max_speed_hz = 3686400, /* Run SSP as fast a possbile */ - .bus_num = 2, /* Framework bus number */ - .chip_select = 0, /* Framework chip select */ - .platform_data = NULL; /* No spi_driver specific config */ - .controller_data = &cs8415a_chip_info, /* Master chip config */ - .irq = STREETRACER_APCI_IRQ, /* Slave device interrupt */ - }, - { - .modalias = "cs8405a", /* Name of spi_driver for this device */ - .max_speed_hz = 3686400, /* Run SSP as fast a possbile */ - .bus_num = 2, /* Framework bus number */ - .chip_select = 1, /* Framework chip select */ - .controller_data = &cs8405a_chip_info, /* Master chip config */ - .irq = STREETRACER_APCI_IRQ, /* Slave device interrupt */ - }, -}; - -static void __init streetracer_init(void) -{ - spi_register_board_info(streetracer_spi_board_info, - ARRAY_SIZE(streetracer_spi_board_info)); -} - - -DMA and PIO I/O Support ------------------------ -The pxa2xx_spi driver supports both DMA and interrupt driven PIO message -transfers. The driver defaults to PIO mode and DMA transfers must be enabled -by setting the "enable_dma" flag in the "pxa2xx_spi_controller" structure. The DMA -mode supports both coherent and stream based DMA mappings. - -The following logic is used to determine the type of I/O to be used on -a per "spi_transfer" basis: - -if !enable_dma then - always use PIO transfers - -if spi_message.len > 8191 then - print "rate limited" warning - use PIO transfers - -if spi_message.is_dma_mapped and rx_dma_buf != 0 and tx_dma_buf != 0 then - use coherent DMA mode - -if rx_buf and tx_buf are aligned on 8 byte boundary then - use streaming DMA mode - -otherwise - use PIO transfer - -THANKS TO ---------- - -David Brownell and others for mentoring the development of this driver. - diff --git a/Documentation/spi/pxa2xx.rst b/Documentation/spi/pxa2xx.rst new file mode 100644 index 000000000000..882d3cc72cc2 --- /dev/null +++ b/Documentation/spi/pxa2xx.rst @@ -0,0 +1,240 @@ +============================== +PXA2xx SPI on SSP driver HOWTO +============================== + +This a mini howto on the pxa2xx_spi driver. The driver turns a PXA2xx +synchronous serial port into a SPI master controller +(see Documentation/spi/spi-summary.rst). The driver has the following features + +- Support for any PXA2xx SSP +- SSP PIO and SSP DMA data transfers. +- External and Internal (SSPFRM) chip selects. +- Per slave device (chip) configuration. +- Full suspend, freeze, resume support. + +The driver is built around a "spi_message" fifo serviced by workqueue and a +tasklet. The workqueue, "pump_messages", drives message fifo and the tasklet +(pump_transfer) is responsible for queuing SPI transactions and setting up and +launching the dma/interrupt driven transfers. + +Declaring PXA2xx Master Controllers +----------------------------------- +Typically a SPI master is defined in the arch/.../mach-*/board-*.c as a +"platform device". The master configuration is passed to the driver via a table +found in include/linux/spi/pxa2xx_spi.h:: + + struct pxa2xx_spi_controller { + u16 num_chipselect; + u8 enable_dma; + }; + +The "pxa2xx_spi_controller.num_chipselect" field is used to determine the number of +slave device (chips) attached to this SPI master. + +The "pxa2xx_spi_controller.enable_dma" field informs the driver that SSP DMA should +be used. This caused the driver to acquire two DMA channels: rx_channel and +tx_channel. The rx_channel has a higher DMA service priority the tx_channel. +See the "PXA2xx Developer Manual" section "DMA Controller". + +NSSP MASTER SAMPLE +------------------ +Below is a sample configuration using the PXA255 NSSP:: + + static struct resource pxa_spi_nssp_resources[] = { + [0] = { + .start = __PREG(SSCR0_P(2)), /* Start address of NSSP */ + .end = __PREG(SSCR0_P(2)) + 0x2c, /* Range of registers */ + .flags = IORESOURCE_MEM, + }, + [1] = { + .start = IRQ_NSSP, /* NSSP IRQ */ + .end = IRQ_NSSP, + .flags = IORESOURCE_IRQ, + }, + }; + + static struct pxa2xx_spi_controller pxa_nssp_master_info = { + .num_chipselect = 1, /* Matches the number of chips attached to NSSP */ + .enable_dma = 1, /* Enables NSSP DMA */ + }; + + static struct platform_device pxa_spi_nssp = { + .name = "pxa2xx-spi", /* MUST BE THIS VALUE, so device match driver */ + .id = 2, /* Bus number, MUST MATCH SSP number 1..n */ + .resource = pxa_spi_nssp_resources, + .num_resources = ARRAY_SIZE(pxa_spi_nssp_resources), + .dev = { + .platform_data = &pxa_nssp_master_info, /* Passed to driver */ + }, + }; + + static struct platform_device *devices[] __initdata = { + &pxa_spi_nssp, + }; + + static void __init board_init(void) + { + (void)platform_add_device(devices, ARRAY_SIZE(devices)); + } + +Declaring Slave Devices +----------------------- +Typically each SPI slave (chip) is defined in the arch/.../mach-*/board-*.c +using the "spi_board_info" structure found in "linux/spi/spi.h". See +"Documentation/spi/spi-summary.rst" for additional information. + +Each slave device attached to the PXA must provide slave specific configuration +information via the structure "pxa2xx_spi_chip" found in +"include/linux/spi/pxa2xx_spi.h". The pxa2xx_spi master controller driver +will uses the configuration whenever the driver communicates with the slave +device. All fields are optional. + +:: + + struct pxa2xx_spi_chip { + u8 tx_threshold; + u8 rx_threshold; + u8 dma_burst_size; + u32 timeout; + u8 enable_loopback; + void (*cs_control)(u32 command); + }; + +The "pxa2xx_spi_chip.tx_threshold" and "pxa2xx_spi_chip.rx_threshold" fields are +used to configure the SSP hardware fifo. These fields are critical to the +performance of pxa2xx_spi driver and misconfiguration will result in rx +fifo overruns (especially in PIO mode transfers). Good default values are:: + + .tx_threshold = 8, + .rx_threshold = 8, + +The range is 1 to 16 where zero indicates "use default". + +The "pxa2xx_spi_chip.dma_burst_size" field is used to configure PXA2xx DMA +engine and is related the "spi_device.bits_per_word" field. Read and understand +the PXA2xx "Developer Manual" sections on the DMA controller and SSP Controllers +to determine the correct value. An SSP configured for byte-wide transfers would +use a value of 8. The driver will determine a reasonable default if +dma_burst_size == 0. + +The "pxa2xx_spi_chip.timeout" fields is used to efficiently handle +trailing bytes in the SSP receiver fifo. The correct value for this field is +dependent on the SPI bus speed ("spi_board_info.max_speed_hz") and the specific +slave device. Please note that the PXA2xx SSP 1 does not support trailing byte +timeouts and must busy-wait any trailing bytes. + +The "pxa2xx_spi_chip.enable_loopback" field is used to place the SSP porting +into internal loopback mode. In this mode the SSP controller internally +connects the SSPTX pin to the SSPRX pin. This is useful for initial setup +testing. + +The "pxa2xx_spi_chip.cs_control" field is used to point to a board specific +function for asserting/deasserting a slave device chip select. If the field is +NULL, the pxa2xx_spi master controller driver assumes that the SSP port is +configured to use SSPFRM instead. + +NOTE: the SPI driver cannot control the chip select if SSPFRM is used, so the +chipselect is dropped after each spi_transfer. Most devices need chip select +asserted around the complete message. Use SSPFRM as a GPIO (through cs_control) +to accommodate these chips. + + +NSSP SLAVE SAMPLE +----------------- +The pxa2xx_spi_chip structure is passed to the pxa2xx_spi driver in the +"spi_board_info.controller_data" field. Below is a sample configuration using +the PXA255 NSSP. + +:: + + /* Chip Select control for the CS8415A SPI slave device */ + static void cs8415a_cs_control(u32 command) + { + if (command & PXA2XX_CS_ASSERT) + GPCR(2) = GPIO_bit(2); + else + GPSR(2) = GPIO_bit(2); + } + + /* Chip Select control for the CS8405A SPI slave device */ + static void cs8405a_cs_control(u32 command) + { + if (command & PXA2XX_CS_ASSERT) + GPCR(3) = GPIO_bit(3); + else + GPSR(3) = GPIO_bit(3); + } + + static struct pxa2xx_spi_chip cs8415a_chip_info = { + .tx_threshold = 8, /* SSP hardward FIFO threshold */ + .rx_threshold = 8, /* SSP hardward FIFO threshold */ + .dma_burst_size = 8, /* Byte wide transfers used so 8 byte bursts */ + .timeout = 235, /* See Intel documentation */ + .cs_control = cs8415a_cs_control, /* Use external chip select */ + }; + + static struct pxa2xx_spi_chip cs8405a_chip_info = { + .tx_threshold = 8, /* SSP hardward FIFO threshold */ + .rx_threshold = 8, /* SSP hardward FIFO threshold */ + .dma_burst_size = 8, /* Byte wide transfers used so 8 byte bursts */ + .timeout = 235, /* See Intel documentation */ + .cs_control = cs8405a_cs_control, /* Use external chip select */ + }; + + static struct spi_board_info streetracer_spi_board_info[] __initdata = { + { + .modalias = "cs8415a", /* Name of spi_driver for this device */ + .max_speed_hz = 3686400, /* Run SSP as fast a possbile */ + .bus_num = 2, /* Framework bus number */ + .chip_select = 0, /* Framework chip select */ + .platform_data = NULL; /* No spi_driver specific config */ + .controller_data = &cs8415a_chip_info, /* Master chip config */ + .irq = STREETRACER_APCI_IRQ, /* Slave device interrupt */ + }, + { + .modalias = "cs8405a", /* Name of spi_driver for this device */ + .max_speed_hz = 3686400, /* Run SSP as fast a possbile */ + .bus_num = 2, /* Framework bus number */ + .chip_select = 1, /* Framework chip select */ + .controller_data = &cs8405a_chip_info, /* Master chip config */ + .irq = STREETRACER_APCI_IRQ, /* Slave device interrupt */ + }, + }; + + static void __init streetracer_init(void) + { + spi_register_board_info(streetracer_spi_board_info, + ARRAY_SIZE(streetracer_spi_board_info)); + } + + +DMA and PIO I/O Support +----------------------- +The pxa2xx_spi driver supports both DMA and interrupt driven PIO message +transfers. The driver defaults to PIO mode and DMA transfers must be enabled +by setting the "enable_dma" flag in the "pxa2xx_spi_controller" structure. The DMA +mode supports both coherent and stream based DMA mappings. + +The following logic is used to determine the type of I/O to be used on +a per "spi_transfer" basis:: + + if !enable_dma then + always use PIO transfers + + if spi_message.len > 8191 then + print "rate limited" warning + use PIO transfers + + if spi_message.is_dma_mapped and rx_dma_buf != 0 and tx_dma_buf != 0 then + use coherent DMA mode + + if rx_buf and tx_buf are aligned on 8 byte boundary then + use streaming DMA mode + + otherwise + use PIO transfer + +THANKS TO +--------- + +David Brownell and others for mentoring the development of this driver. diff --git a/Documentation/spi/spi-lm70llp b/Documentation/spi/spi-lm70llp deleted file mode 100644 index 463f6d01fa15..000000000000 --- a/Documentation/spi/spi-lm70llp +++ /dev/null @@ -1,79 +0,0 @@ -spi_lm70llp : LM70-LLP parport-to-SPI adapter -============================================== - -Supported board/chip: - * National Semiconductor LM70 LLP evaluation board - Datasheet: http://www.national.com/pf/LM/LM70.html - -Author: - Kaiwan N Billimoria - -Description ------------ -This driver provides glue code connecting a National Semiconductor LM70 LLP -temperature sensor evaluation board to the kernel's SPI core subsystem. - -This is a SPI master controller driver. It can be used in conjunction with -(layered under) the LM70 logical driver (a "SPI protocol driver"). -In effect, this driver turns the parallel port interface on the eval board -into a SPI bus with a single device, which will be driven by the generic -LM70 driver (drivers/hwmon/lm70.c). - - -Hardware Interfacing --------------------- -The schematic for this particular board (the LM70EVAL-LLP) is -available (on page 4) here: - - http://www.national.com/appinfo/tempsensors/files/LM70LLPEVALmanual.pdf - -The hardware interfacing on the LM70 LLP eval board is as follows: - - Parallel LM70 LLP - Port Direction JP2 Header - ----------- --------- ---------------- - D0 2 - - - D1 3 --> V+ 5 - D2 4 --> V+ 5 - D3 5 --> V+ 5 - D4 6 --> V+ 5 - D5 7 --> nCS 8 - D6 8 --> SCLK 3 - D7 9 --> SI/O 5 - GND 25 - GND 7 - Select 13 <-- SI/O 1 - ----------- --------- ---------------- - -Note that since the LM70 uses a "3-wire" variant of SPI, the SI/SO pin -is connected to both pin D7 (as Master Out) and Select (as Master In) -using an arrangement that lets either the parport or the LM70 pull the -pin low. This can't be shared with true SPI devices, but other 3-wire -devices might share the same SI/SO pin. - -The bitbanger routine in this driver (lm70_txrx) is called back from -the bound "hwmon/lm70" protocol driver through its sysfs hook, using a -spi_write_then_read() call. It performs Mode 0 (SPI/Microwire) bitbanging. -The lm70 driver then inteprets the resulting digital temperature value -and exports it through sysfs. - -A "gotcha": National Semiconductor's LM70 LLP eval board circuit schematic -shows that the SI/O line from the LM70 chip is connected to the base of a -transistor Q1 (and also a pullup, and a zener diode to D7); while the -collector is tied to VCC. - -Interpreting this circuit, when the LM70 SI/O line is High (or tristate -and not grounded by the host via D7), the transistor conducts and switches -the collector to zero, which is reflected on pin 13 of the DB25 parport -connector. When SI/O is Low (driven by the LM70 or the host) on the other -hand, the transistor is cut off and the voltage tied to it's collector is -reflected on pin 13 as a High level. - -So: the getmiso inline routine in this driver takes this fact into account, -inverting the value read at pin 13. - - -Thanks to ---------- -o David Brownell for mentoring the SPI-side driver development. -o Dr.Craig Hollabaugh for the (early) "manual" bitbanging driver version. -o Nadir Billimoria for help interpreting the circuit schematic. diff --git a/Documentation/spi/spi-lm70llp.rst b/Documentation/spi/spi-lm70llp.rst new file mode 100644 index 000000000000..07631aef4343 --- /dev/null +++ b/Documentation/spi/spi-lm70llp.rst @@ -0,0 +1,84 @@ +============================================== +spi_lm70llp : LM70-LLP parport-to-SPI adapter +============================================== + +Supported board/chip: + + * National Semiconductor LM70 LLP evaluation board + + Datasheet: http://www.national.com/pf/LM/LM70.html + +Author: + Kaiwan N Billimoria + +Description +----------- +This driver provides glue code connecting a National Semiconductor LM70 LLP +temperature sensor evaluation board to the kernel's SPI core subsystem. + +This is a SPI master controller driver. It can be used in conjunction with +(layered under) the LM70 logical driver (a "SPI protocol driver"). +In effect, this driver turns the parallel port interface on the eval board +into a SPI bus with a single device, which will be driven by the generic +LM70 driver (drivers/hwmon/lm70.c). + + +Hardware Interfacing +-------------------- +The schematic for this particular board (the LM70EVAL-LLP) is +available (on page 4) here: + + http://www.national.com/appinfo/tempsensors/files/LM70LLPEVALmanual.pdf + +The hardware interfacing on the LM70 LLP eval board is as follows: + + ======== == ========= ========== + Parallel LM70 LLP + Port . Direction JP2 Header + ======== == ========= ========== + D0 2 - - + D1 3 --> V+ 5 + D2 4 --> V+ 5 + D3 5 --> V+ 5 + D4 6 --> V+ 5 + D5 7 --> nCS 8 + D6 8 --> SCLK 3 + D7 9 --> SI/O 5 + GND 25 - GND 7 + Select 13 <-- SI/O 1 + ======== == ========= ========== + +Note that since the LM70 uses a "3-wire" variant of SPI, the SI/SO pin +is connected to both pin D7 (as Master Out) and Select (as Master In) +using an arrangement that lets either the parport or the LM70 pull the +pin low. This can't be shared with true SPI devices, but other 3-wire +devices might share the same SI/SO pin. + +The bitbanger routine in this driver (lm70_txrx) is called back from +the bound "hwmon/lm70" protocol driver through its sysfs hook, using a +spi_write_then_read() call. It performs Mode 0 (SPI/Microwire) bitbanging. +The lm70 driver then inteprets the resulting digital temperature value +and exports it through sysfs. + +A "gotcha": National Semiconductor's LM70 LLP eval board circuit schematic +shows that the SI/O line from the LM70 chip is connected to the base of a +transistor Q1 (and also a pullup, and a zener diode to D7); while the +collector is tied to VCC. + +Interpreting this circuit, when the LM70 SI/O line is High (or tristate +and not grounded by the host via D7), the transistor conducts and switches +the collector to zero, which is reflected on pin 13 of the DB25 parport +connector. When SI/O is Low (driven by the LM70 or the host) on the other +hand, the transistor is cut off and the voltage tied to it's collector is +reflected on pin 13 as a High level. + +So: the getmiso inline routine in this driver takes this fact into account, +inverting the value read at pin 13. + + +Thanks to +--------- + +- David Brownell for mentoring the SPI-side driver development. +- Dr.Craig Hollabaugh for the (early) "manual" bitbanging driver version. +- Nadir Billimoria for help interpreting the circuit schematic. diff --git a/Documentation/spi/spi-sc18is602 b/Documentation/spi/spi-sc18is602 deleted file mode 100644 index 0feffd5af411..000000000000 --- a/Documentation/spi/spi-sc18is602 +++ /dev/null @@ -1,36 +0,0 @@ -Kernel driver spi-sc18is602 -=========================== - -Supported chips: - * NXP SI18IS602/602B/603 - Datasheet: http://www.nxp.com/documents/data_sheet/SC18IS602_602B_603.pdf - -Author: - Guenter Roeck - - -Description ------------ - -This driver provides connects a NXP SC18IS602/603 I2C-bus to SPI bridge to the -kernel's SPI core subsystem. - -The driver does not probe for supported chips, since the SI18IS602/603 does not -support Chip ID registers. You will have to instantiate the devices explicitly. -Please see Documentation/i2c/instantiating-devices.rst for details. - - -Usage Notes ------------ - -This driver requires the I2C adapter driver to support raw I2C messages. I2C -adapter drivers which can only handle the SMBus protocol are not supported. - -The maximum SPI message size supported by SC18IS602/603 is 200 bytes. Attempts -to initiate longer transfers will fail with -EINVAL. EEPROM read operations and -similar large accesses have to be split into multiple chunks of no more than -200 bytes per SPI message (128 bytes of data per message is recommended). This -means that programs such as "cp" or "od", which automatically use large block -sizes to access a device, can not be used directly to read data from EEPROM. -Programs such as dd, where the block size can be specified, should be used -instead. diff --git a/Documentation/spi/spi-sc18is602.rst b/Documentation/spi/spi-sc18is602.rst new file mode 100644 index 000000000000..2a31dc722321 --- /dev/null +++ b/Documentation/spi/spi-sc18is602.rst @@ -0,0 +1,39 @@ +=========================== +Kernel driver spi-sc18is602 +=========================== + +Supported chips: + + * NXP SI18IS602/602B/603 + + Datasheet: http://www.nxp.com/documents/data_sheet/SC18IS602_602B_603.pdf + +Author: + Guenter Roeck + + +Description +----------- + +This driver provides connects a NXP SC18IS602/603 I2C-bus to SPI bridge to the +kernel's SPI core subsystem. + +The driver does not probe for supported chips, since the SI18IS602/603 does not +support Chip ID registers. You will have to instantiate the devices explicitly. +Please see Documentation/i2c/instantiating-devices.rst for details. + + +Usage Notes +----------- + +This driver requires the I2C adapter driver to support raw I2C messages. I2C +adapter drivers which can only handle the SMBus protocol are not supported. + +The maximum SPI message size supported by SC18IS602/603 is 200 bytes. Attempts +to initiate longer transfers will fail with -EINVAL. EEPROM read operations and +similar large accesses have to be split into multiple chunks of no more than +200 bytes per SPI message (128 bytes of data per message is recommended). This +means that programs such as "cp" or "od", which automatically use large block +sizes to access a device, can not be used directly to read data from EEPROM. +Programs such as dd, where the block size can be specified, should be used +instead. diff --git a/Documentation/spi/spi-summary b/Documentation/spi/spi-summary deleted file mode 100644 index 1a63194b74d7..000000000000 --- a/Documentation/spi/spi-summary +++ /dev/null @@ -1,631 +0,0 @@ -Overview of Linux kernel SPI support -==================================== - -02-Feb-2012 - -What is SPI? ------------- -The "Serial Peripheral Interface" (SPI) is a synchronous four wire serial -link used to connect microcontrollers to sensors, memory, and peripherals. -It's a simple "de facto" standard, not complicated enough to acquire a -standardization body. SPI uses a master/slave configuration. - -The three signal wires hold a clock (SCK, often on the order of 10 MHz), -and parallel data lines with "Master Out, Slave In" (MOSI) or "Master In, -Slave Out" (MISO) signals. (Other names are also used.) There are four -clocking modes through which data is exchanged; mode-0 and mode-3 are most -commonly used. Each clock cycle shifts data out and data in; the clock -doesn't cycle except when there is a data bit to shift. Not all data bits -are used though; not every protocol uses those full duplex capabilities. - -SPI masters use a fourth "chip select" line to activate a given SPI slave -device, so those three signal wires may be connected to several chips -in parallel. All SPI slaves support chipselects; they are usually active -low signals, labeled nCSx for slave 'x' (e.g. nCS0). Some devices have -other signals, often including an interrupt to the master. - -Unlike serial busses like USB or SMBus, even low level protocols for -SPI slave functions are usually not interoperable between vendors -(except for commodities like SPI memory chips). - - - SPI may be used for request/response style device protocols, as with - touchscreen sensors and memory chips. - - - It may also be used to stream data in either direction (half duplex), - or both of them at the same time (full duplex). - - - Some devices may use eight bit words. Others may use different word - lengths, such as streams of 12-bit or 20-bit digital samples. - - - Words are usually sent with their most significant bit (MSB) first, - but sometimes the least significant bit (LSB) goes first instead. - - - Sometimes SPI is used to daisy-chain devices, like shift registers. - -In the same way, SPI slaves will only rarely support any kind of automatic -discovery/enumeration protocol. The tree of slave devices accessible from -a given SPI master will normally be set up manually, with configuration -tables. - -SPI is only one of the names used by such four-wire protocols, and -most controllers have no problem handling "MicroWire" (think of it as -half-duplex SPI, for request/response protocols), SSP ("Synchronous -Serial Protocol"), PSP ("Programmable Serial Protocol"), and other -related protocols. - -Some chips eliminate a signal line by combining MOSI and MISO, and -limiting themselves to half-duplex at the hardware level. In fact -some SPI chips have this signal mode as a strapping option. These -can be accessed using the same programming interface as SPI, but of -course they won't handle full duplex transfers. You may find such -chips described as using "three wire" signaling: SCK, data, nCSx. -(That data line is sometimes called MOMI or SISO.) - -Microcontrollers often support both master and slave sides of the SPI -protocol. This document (and Linux) supports both the master and slave -sides of SPI interactions. - - -Who uses it? On what kinds of systems? ---------------------------------------- -Linux developers using SPI are probably writing device drivers for embedded -systems boards. SPI is used to control external chips, and it is also a -protocol supported by every MMC or SD memory card. (The older "DataFlash" -cards, predating MMC cards but using the same connectors and card shape, -support only SPI.) Some PC hardware uses SPI flash for BIOS code. - -SPI slave chips range from digital/analog converters used for analog -sensors and codecs, to memory, to peripherals like USB controllers -or Ethernet adapters; and more. - -Most systems using SPI will integrate a few devices on a mainboard. -Some provide SPI links on expansion connectors; in cases where no -dedicated SPI controller exists, GPIO pins can be used to create a -low speed "bitbanging" adapter. Very few systems will "hotplug" an SPI -controller; the reasons to use SPI focus on low cost and simple operation, -and if dynamic reconfiguration is important, USB will often be a more -appropriate low-pincount peripheral bus. - -Many microcontrollers that can run Linux integrate one or more I/O -interfaces with SPI modes. Given SPI support, they could use MMC or SD -cards without needing a special purpose MMC/SD/SDIO controller. - - -I'm confused. What are these four SPI "clock modes"? ------------------------------------------------------ -It's easy to be confused here, and the vendor documentation you'll -find isn't necessarily helpful. The four modes combine two mode bits: - - - CPOL indicates the initial clock polarity. CPOL=0 means the - clock starts low, so the first (leading) edge is rising, and - the second (trailing) edge is falling. CPOL=1 means the clock - starts high, so the first (leading) edge is falling. - - - CPHA indicates the clock phase used to sample data; CPHA=0 says - sample on the leading edge, CPHA=1 means the trailing edge. - - Since the signal needs to stablize before it's sampled, CPHA=0 - implies that its data is written half a clock before the first - clock edge. The chipselect may have made it become available. - -Chip specs won't always say "uses SPI mode X" in as many words, -but their timing diagrams will make the CPOL and CPHA modes clear. - -In the SPI mode number, CPOL is the high order bit and CPHA is the -low order bit. So when a chip's timing diagram shows the clock -starting low (CPOL=0) and data stabilized for sampling during the -trailing clock edge (CPHA=1), that's SPI mode 1. - -Note that the clock mode is relevant as soon as the chipselect goes -active. So the master must set the clock to inactive before selecting -a slave, and the slave can tell the chosen polarity by sampling the -clock level when its select line goes active. That's why many devices -support for example both modes 0 and 3: they don't care about polarity, -and always clock data in/out on rising clock edges. - - -How do these driver programming interfaces work? ------------------------------------------------- -The header file includes kerneldoc, as does the -main source code, and you should certainly read that chapter of the -kernel API document. This is just an overview, so you get the big -picture before those details. - -SPI requests always go into I/O queues. Requests for a given SPI device -are always executed in FIFO order, and complete asynchronously through -completion callbacks. There are also some simple synchronous wrappers -for those calls, including ones for common transaction types like writing -a command and then reading its response. - -There are two types of SPI driver, here called: - - Controller drivers ... controllers may be built into System-On-Chip - processors, and often support both Master and Slave roles. - These drivers touch hardware registers and may use DMA. - Or they can be PIO bitbangers, needing just GPIO pins. - - Protocol drivers ... these pass messages through the controller - driver to communicate with a Slave or Master device on the - other side of an SPI link. - -So for example one protocol driver might talk to the MTD layer to export -data to filesystems stored on SPI flash like DataFlash; and others might -control audio interfaces, present touchscreen sensors as input interfaces, -or monitor temperature and voltage levels during industrial processing. -And those might all be sharing the same controller driver. - -A "struct spi_device" encapsulates the controller-side interface between -those two types of drivers. - -There is a minimal core of SPI programming interfaces, focussing on -using the driver model to connect controller and protocol drivers using -device tables provided by board specific initialization code. SPI -shows up in sysfs in several locations: - - /sys/devices/.../CTLR ... physical node for a given SPI controller - - /sys/devices/.../CTLR/spiB.C ... spi_device on bus "B", - chipselect C, accessed through CTLR. - - /sys/bus/spi/devices/spiB.C ... symlink to that physical - .../CTLR/spiB.C device - - /sys/devices/.../CTLR/spiB.C/modalias ... identifies the driver - that should be used with this device (for hotplug/coldplug) - - /sys/bus/spi/drivers/D ... driver for one or more spi*.* devices - - /sys/class/spi_master/spiB ... symlink (or actual device node) to - a logical node which could hold class related state for the SPI - master controller managing bus "B". All spiB.* devices share one - physical SPI bus segment, with SCLK, MOSI, and MISO. - - /sys/devices/.../CTLR/slave ... virtual file for (un)registering the - slave device for an SPI slave controller. - Writing the driver name of an SPI slave handler to this file - registers the slave device; writing "(null)" unregisters the slave - device. - Reading from this file shows the name of the slave device ("(null)" - if not registered). - - /sys/class/spi_slave/spiB ... symlink (or actual device node) to - a logical node which could hold class related state for the SPI - slave controller on bus "B". When registered, a single spiB.* - device is present here, possible sharing the physical SPI bus - segment with other SPI slave devices. - -Note that the actual location of the controller's class state depends -on whether you enabled CONFIG_SYSFS_DEPRECATED or not. At this time, -the only class-specific state is the bus number ("B" in "spiB"), so -those /sys/class entries are only useful to quickly identify busses. - - -How does board-specific init code declare SPI devices? ------------------------------------------------------- -Linux needs several kinds of information to properly configure SPI devices. -That information is normally provided by board-specific code, even for -chips that do support some of automated discovery/enumeration. - -DECLARE CONTROLLERS - -The first kind of information is a list of what SPI controllers exist. -For System-on-Chip (SOC) based boards, these will usually be platform -devices, and the controller may need some platform_data in order to -operate properly. The "struct platform_device" will include resources -like the physical address of the controller's first register and its IRQ. - -Platforms will often abstract the "register SPI controller" operation, -maybe coupling it with code to initialize pin configurations, so that -the arch/.../mach-*/board-*.c files for several boards can all share the -same basic controller setup code. This is because most SOCs have several -SPI-capable controllers, and only the ones actually usable on a given -board should normally be set up and registered. - -So for example arch/.../mach-*/board-*.c files might have code like: - - #include /* for mysoc_spi_data */ - - /* if your mach-* infrastructure doesn't support kernels that can - * run on multiple boards, pdata wouldn't benefit from "__init". - */ - static struct mysoc_spi_data pdata __initdata = { ... }; - - static __init board_init(void) - { - ... - /* this board only uses SPI controller #2 */ - mysoc_register_spi(2, &pdata); - ... - } - -And SOC-specific utility code might look something like: - - #include - - static struct platform_device spi2 = { ... }; - - void mysoc_register_spi(unsigned n, struct mysoc_spi_data *pdata) - { - struct mysoc_spi_data *pdata2; - - pdata2 = kmalloc(sizeof *pdata2, GFP_KERNEL); - *pdata2 = pdata; - ... - if (n == 2) { - spi2->dev.platform_data = pdata2; - register_platform_device(&spi2); - - /* also: set up pin modes so the spi2 signals are - * visible on the relevant pins ... bootloaders on - * production boards may already have done this, but - * developer boards will often need Linux to do it. - */ - } - ... - } - -Notice how the platform_data for boards may be different, even if the -same SOC controller is used. For example, on one board SPI might use -an external clock, where another derives the SPI clock from current -settings of some master clock. - - -DECLARE SLAVE DEVICES - -The second kind of information is a list of what SPI slave devices exist -on the target board, often with some board-specific data needed for the -driver to work correctly. - -Normally your arch/.../mach-*/board-*.c files would provide a small table -listing the SPI devices on each board. (This would typically be only a -small handful.) That might look like: - - static struct ads7846_platform_data ads_info = { - .vref_delay_usecs = 100, - .x_plate_ohms = 580, - .y_plate_ohms = 410, - }; - - static struct spi_board_info spi_board_info[] __initdata = { - { - .modalias = "ads7846", - .platform_data = &ads_info, - .mode = SPI_MODE_0, - .irq = GPIO_IRQ(31), - .max_speed_hz = 120000 /* max sample rate at 3V */ * 16, - .bus_num = 1, - .chip_select = 0, - }, - }; - -Again, notice how board-specific information is provided; each chip may need -several types. This example shows generic constraints like the fastest SPI -clock to allow (a function of board voltage in this case) or how an IRQ pin -is wired, plus chip-specific constraints like an important delay that's -changed by the capacitance at one pin. - -(There's also "controller_data", information that may be useful to the -controller driver. An example would be peripheral-specific DMA tuning -data or chipselect callbacks. This is stored in spi_device later.) - -The board_info should provide enough information to let the system work -without the chip's driver being loaded. The most troublesome aspect of -that is likely the SPI_CS_HIGH bit in the spi_device.mode field, since -sharing a bus with a device that interprets chipselect "backwards" is -not possible until the infrastructure knows how to deselect it. - -Then your board initialization code would register that table with the SPI -infrastructure, so that it's available later when the SPI master controller -driver is registered: - - spi_register_board_info(spi_board_info, ARRAY_SIZE(spi_board_info)); - -Like with other static board-specific setup, you won't unregister those. - -The widely used "card" style computers bundle memory, cpu, and little else -onto a card that's maybe just thirty square centimeters. On such systems, -your arch/.../mach-.../board-*.c file would primarily provide information -about the devices on the mainboard into which such a card is plugged. That -certainly includes SPI devices hooked up through the card connectors! - - -NON-STATIC CONFIGURATIONS - -Developer boards often play by different rules than product boards, and one -example is the potential need to hotplug SPI devices and/or controllers. - -For those cases you might need to use spi_busnum_to_master() to look -up the spi bus master, and will likely need spi_new_device() to provide the -board info based on the board that was hotplugged. Of course, you'd later -call at least spi_unregister_device() when that board is removed. - -When Linux includes support for MMC/SD/SDIO/DataFlash cards through SPI, those -configurations will also be dynamic. Fortunately, such devices all support -basic device identification probes, so they should hotplug normally. - - -How do I write an "SPI Protocol Driver"? ----------------------------------------- -Most SPI drivers are currently kernel drivers, but there's also support -for userspace drivers. Here we talk only about kernel drivers. - -SPI protocol drivers somewhat resemble platform device drivers: - - static struct spi_driver CHIP_driver = { - .driver = { - .name = "CHIP", - .owner = THIS_MODULE, - .pm = &CHIP_pm_ops, - }, - - .probe = CHIP_probe, - .remove = CHIP_remove, - }; - -The driver core will automatically attempt to bind this driver to any SPI -device whose board_info gave a modalias of "CHIP". Your probe() code -might look like this unless you're creating a device which is managing -a bus (appearing under /sys/class/spi_master). - - static int CHIP_probe(struct spi_device *spi) - { - struct CHIP *chip; - struct CHIP_platform_data *pdata; - - /* assuming the driver requires board-specific data: */ - pdata = &spi->dev.platform_data; - if (!pdata) - return -ENODEV; - - /* get memory for driver's per-chip state */ - chip = kzalloc(sizeof *chip, GFP_KERNEL); - if (!chip) - return -ENOMEM; - spi_set_drvdata(spi, chip); - - ... etc - return 0; - } - -As soon as it enters probe(), the driver may issue I/O requests to -the SPI device using "struct spi_message". When remove() returns, -or after probe() fails, the driver guarantees that it won't submit -any more such messages. - - - An spi_message is a sequence of protocol operations, executed - as one atomic sequence. SPI driver controls include: - - + when bidirectional reads and writes start ... by how its - sequence of spi_transfer requests is arranged; - - + which I/O buffers are used ... each spi_transfer wraps a - buffer for each transfer direction, supporting full duplex - (two pointers, maybe the same one in both cases) and half - duplex (one pointer is NULL) transfers; - - + optionally defining short delays after transfers ... using - the spi_transfer.delay_usecs setting (this delay can be the - only protocol effect, if the buffer length is zero); - - + whether the chipselect becomes inactive after a transfer and - any delay ... by using the spi_transfer.cs_change flag; - - + hinting whether the next message is likely to go to this same - device ... using the spi_transfer.cs_change flag on the last - transfer in that atomic group, and potentially saving costs - for chip deselect and select operations. - - - Follow standard kernel rules, and provide DMA-safe buffers in - your messages. That way controller drivers using DMA aren't forced - to make extra copies unless the hardware requires it (e.g. working - around hardware errata that force the use of bounce buffering). - - If standard dma_map_single() handling of these buffers is inappropriate, - you can use spi_message.is_dma_mapped to tell the controller driver - that you've already provided the relevant DMA addresses. - - - The basic I/O primitive is spi_async(). Async requests may be - issued in any context (irq handler, task, etc) and completion - is reported using a callback provided with the message. - After any detected error, the chip is deselected and processing - of that spi_message is aborted. - - - There are also synchronous wrappers like spi_sync(), and wrappers - like spi_read(), spi_write(), and spi_write_then_read(). These - may be issued only in contexts that may sleep, and they're all - clean (and small, and "optional") layers over spi_async(). - - - The spi_write_then_read() call, and convenience wrappers around - it, should only be used with small amounts of data where the - cost of an extra copy may be ignored. It's designed to support - common RPC-style requests, such as writing an eight bit command - and reading a sixteen bit response -- spi_w8r16() being one its - wrappers, doing exactly that. - -Some drivers may need to modify spi_device characteristics like the -transfer mode, wordsize, or clock rate. This is done with spi_setup(), -which would normally be called from probe() before the first I/O is -done to the device. However, that can also be called at any time -that no message is pending for that device. - -While "spi_device" would be the bottom boundary of the driver, the -upper boundaries might include sysfs (especially for sensor readings), -the input layer, ALSA, networking, MTD, the character device framework, -or other Linux subsystems. - -Note that there are two types of memory your driver must manage as part -of interacting with SPI devices. - - - I/O buffers use the usual Linux rules, and must be DMA-safe. - You'd normally allocate them from the heap or free page pool. - Don't use the stack, or anything that's declared "static". - - - The spi_message and spi_transfer metadata used to glue those - I/O buffers into a group of protocol transactions. These can - be allocated anywhere it's convenient, including as part of - other allocate-once driver data structures. Zero-init these. - -If you like, spi_message_alloc() and spi_message_free() convenience -routines are available to allocate and zero-initialize an spi_message -with several transfers. - - -How do I write an "SPI Master Controller Driver"? -------------------------------------------------- -An SPI controller will probably be registered on the platform_bus; write -a driver to bind to the device, whichever bus is involved. - -The main task of this type of driver is to provide an "spi_master". -Use spi_alloc_master() to allocate the master, and spi_master_get_devdata() -to get the driver-private data allocated for that device. - - struct spi_master *master; - struct CONTROLLER *c; - - master = spi_alloc_master(dev, sizeof *c); - if (!master) - return -ENODEV; - - c = spi_master_get_devdata(master); - -The driver will initialize the fields of that spi_master, including the -bus number (maybe the same as the platform device ID) and three methods -used to interact with the SPI core and SPI protocol drivers. It will -also initialize its own internal state. (See below about bus numbering -and those methods.) - -After you initialize the spi_master, then use spi_register_master() to -publish it to the rest of the system. At that time, device nodes for the -controller and any predeclared spi devices will be made available, and -the driver model core will take care of binding them to drivers. - -If you need to remove your SPI controller driver, spi_unregister_master() -will reverse the effect of spi_register_master(). - - -BUS NUMBERING - -Bus numbering is important, since that's how Linux identifies a given -SPI bus (shared SCK, MOSI, MISO). Valid bus numbers start at zero. On -SOC systems, the bus numbers should match the numbers defined by the chip -manufacturer. For example, hardware controller SPI2 would be bus number 2, -and spi_board_info for devices connected to it would use that number. - -If you don't have such hardware-assigned bus number, and for some reason -you can't just assign them, then provide a negative bus number. That will -then be replaced by a dynamically assigned number. You'd then need to treat -this as a non-static configuration (see above). - - -SPI MASTER METHODS - - master->setup(struct spi_device *spi) - This sets up the device clock rate, SPI mode, and word sizes. - Drivers may change the defaults provided by board_info, and then - call spi_setup(spi) to invoke this routine. It may sleep. - - Unless each SPI slave has its own configuration registers, don't - change them right away ... otherwise drivers could corrupt I/O - that's in progress for other SPI devices. - - ** BUG ALERT: for some reason the first version of - ** many spi_master drivers seems to get this wrong. - ** When you code setup(), ASSUME that the controller - ** is actively processing transfers for another device. - - master->cleanup(struct spi_device *spi) - Your controller driver may use spi_device.controller_state to hold - state it dynamically associates with that device. If you do that, - be sure to provide the cleanup() method to free that state. - - master->prepare_transfer_hardware(struct spi_master *master) - This will be called by the queue mechanism to signal to the driver - that a message is coming in soon, so the subsystem requests the - driver to prepare the transfer hardware by issuing this call. - This may sleep. - - master->unprepare_transfer_hardware(struct spi_master *master) - This will be called by the queue mechanism to signal to the driver - that there are no more messages pending in the queue and it may - relax the hardware (e.g. by power management calls). This may sleep. - - master->transfer_one_message(struct spi_master *master, - struct spi_message *mesg) - The subsystem calls the driver to transfer a single message while - queuing transfers that arrive in the meantime. When the driver is - finished with this message, it must call - spi_finalize_current_message() so the subsystem can issue the next - message. This may sleep. - - master->transfer_one(struct spi_master *master, struct spi_device *spi, - struct spi_transfer *transfer) - The subsystem calls the driver to transfer a single transfer while - queuing transfers that arrive in the meantime. When the driver is - finished with this transfer, it must call - spi_finalize_current_transfer() so the subsystem can issue the next - transfer. This may sleep. Note: transfer_one and transfer_one_message - are mutually exclusive; when both are set, the generic subsystem does - not call your transfer_one callback. - - Return values: - negative errno: error - 0: transfer is finished - 1: transfer is still in progress - - master->set_cs_timing(struct spi_device *spi, u8 setup_clk_cycles, - u8 hold_clk_cycles, u8 inactive_clk_cycles) - This method allows SPI client drivers to request SPI master controller - for configuring device specific CS setup, hold and inactive timing - requirements. - - DEPRECATED METHODS - - master->transfer(struct spi_device *spi, struct spi_message *message) - This must not sleep. Its responsibility is to arrange that the - transfer happens and its complete() callback is issued. The two - will normally happen later, after other transfers complete, and - if the controller is idle it will need to be kickstarted. This - method is not used on queued controllers and must be NULL if - transfer_one_message() and (un)prepare_transfer_hardware() are - implemented. - - -SPI MESSAGE QUEUE - -If you are happy with the standard queueing mechanism provided by the -SPI subsystem, just implement the queued methods specified above. Using -the message queue has the upside of centralizing a lot of code and -providing pure process-context execution of methods. The message queue -can also be elevated to realtime priority on high-priority SPI traffic. - -Unless the queueing mechanism in the SPI subsystem is selected, the bulk -of the driver will be managing the I/O queue fed by the now deprecated -function transfer(). - -That queue could be purely conceptual. For example, a driver used only -for low-frequency sensor access might be fine using synchronous PIO. - -But the queue will probably be very real, using message->queue, PIO, -often DMA (especially if the root filesystem is in SPI flash), and -execution contexts like IRQ handlers, tasklets, or workqueues (such -as keventd). Your driver can be as fancy, or as simple, as you need. -Such a transfer() method would normally just add the message to a -queue, and then start some asynchronous transfer engine (unless it's -already running). - - -THANKS TO ---------- -Contributors to Linux-SPI discussions include (in alphabetical order, -by last name): - -Mark Brown -David Brownell -Russell King -Grant Likely -Dmitry Pervushin -Stephen Street -Mark Underwood -Andrew Victor -Linus Walleij -Vitaly Wool diff --git a/Documentation/spi/spi-summary.rst b/Documentation/spi/spi-summary.rst new file mode 100644 index 000000000000..f1daffe10d78 --- /dev/null +++ b/Documentation/spi/spi-summary.rst @@ -0,0 +1,644 @@ +==================================== +Overview of Linux kernel SPI support +==================================== + +02-Feb-2012 + +What is SPI? +------------ +The "Serial Peripheral Interface" (SPI) is a synchronous four wire serial +link used to connect microcontrollers to sensors, memory, and peripherals. +It's a simple "de facto" standard, not complicated enough to acquire a +standardization body. SPI uses a master/slave configuration. + +The three signal wires hold a clock (SCK, often on the order of 10 MHz), +and parallel data lines with "Master Out, Slave In" (MOSI) or "Master In, +Slave Out" (MISO) signals. (Other names are also used.) There are four +clocking modes through which data is exchanged; mode-0 and mode-3 are most +commonly used. Each clock cycle shifts data out and data in; the clock +doesn't cycle except when there is a data bit to shift. Not all data bits +are used though; not every protocol uses those full duplex capabilities. + +SPI masters use a fourth "chip select" line to activate a given SPI slave +device, so those three signal wires may be connected to several chips +in parallel. All SPI slaves support chipselects; they are usually active +low signals, labeled nCSx for slave 'x' (e.g. nCS0). Some devices have +other signals, often including an interrupt to the master. + +Unlike serial busses like USB or SMBus, even low level protocols for +SPI slave functions are usually not interoperable between vendors +(except for commodities like SPI memory chips). + + - SPI may be used for request/response style device protocols, as with + touchscreen sensors and memory chips. + + - It may also be used to stream data in either direction (half duplex), + or both of them at the same time (full duplex). + + - Some devices may use eight bit words. Others may use different word + lengths, such as streams of 12-bit or 20-bit digital samples. + + - Words are usually sent with their most significant bit (MSB) first, + but sometimes the least significant bit (LSB) goes first instead. + + - Sometimes SPI is used to daisy-chain devices, like shift registers. + +In the same way, SPI slaves will only rarely support any kind of automatic +discovery/enumeration protocol. The tree of slave devices accessible from +a given SPI master will normally be set up manually, with configuration +tables. + +SPI is only one of the names used by such four-wire protocols, and +most controllers have no problem handling "MicroWire" (think of it as +half-duplex SPI, for request/response protocols), SSP ("Synchronous +Serial Protocol"), PSP ("Programmable Serial Protocol"), and other +related protocols. + +Some chips eliminate a signal line by combining MOSI and MISO, and +limiting themselves to half-duplex at the hardware level. In fact +some SPI chips have this signal mode as a strapping option. These +can be accessed using the same programming interface as SPI, but of +course they won't handle full duplex transfers. You may find such +chips described as using "three wire" signaling: SCK, data, nCSx. +(That data line is sometimes called MOMI or SISO.) + +Microcontrollers often support both master and slave sides of the SPI +protocol. This document (and Linux) supports both the master and slave +sides of SPI interactions. + + +Who uses it? On what kinds of systems? +--------------------------------------- +Linux developers using SPI are probably writing device drivers for embedded +systems boards. SPI is used to control external chips, and it is also a +protocol supported by every MMC or SD memory card. (The older "DataFlash" +cards, predating MMC cards but using the same connectors and card shape, +support only SPI.) Some PC hardware uses SPI flash for BIOS code. + +SPI slave chips range from digital/analog converters used for analog +sensors and codecs, to memory, to peripherals like USB controllers +or Ethernet adapters; and more. + +Most systems using SPI will integrate a few devices on a mainboard. +Some provide SPI links on expansion connectors; in cases where no +dedicated SPI controller exists, GPIO pins can be used to create a +low speed "bitbanging" adapter. Very few systems will "hotplug" an SPI +controller; the reasons to use SPI focus on low cost and simple operation, +and if dynamic reconfiguration is important, USB will often be a more +appropriate low-pincount peripheral bus. + +Many microcontrollers that can run Linux integrate one or more I/O +interfaces with SPI modes. Given SPI support, they could use MMC or SD +cards without needing a special purpose MMC/SD/SDIO controller. + + +I'm confused. What are these four SPI "clock modes"? +----------------------------------------------------- +It's easy to be confused here, and the vendor documentation you'll +find isn't necessarily helpful. The four modes combine two mode bits: + + - CPOL indicates the initial clock polarity. CPOL=0 means the + clock starts low, so the first (leading) edge is rising, and + the second (trailing) edge is falling. CPOL=1 means the clock + starts high, so the first (leading) edge is falling. + + - CPHA indicates the clock phase used to sample data; CPHA=0 says + sample on the leading edge, CPHA=1 means the trailing edge. + + Since the signal needs to stablize before it's sampled, CPHA=0 + implies that its data is written half a clock before the first + clock edge. The chipselect may have made it become available. + +Chip specs won't always say "uses SPI mode X" in as many words, +but their timing diagrams will make the CPOL and CPHA modes clear. + +In the SPI mode number, CPOL is the high order bit and CPHA is the +low order bit. So when a chip's timing diagram shows the clock +starting low (CPOL=0) and data stabilized for sampling during the +trailing clock edge (CPHA=1), that's SPI mode 1. + +Note that the clock mode is relevant as soon as the chipselect goes +active. So the master must set the clock to inactive before selecting +a slave, and the slave can tell the chosen polarity by sampling the +clock level when its select line goes active. That's why many devices +support for example both modes 0 and 3: they don't care about polarity, +and always clock data in/out on rising clock edges. + + +How do these driver programming interfaces work? +------------------------------------------------ +The header file includes kerneldoc, as does the +main source code, and you should certainly read that chapter of the +kernel API document. This is just an overview, so you get the big +picture before those details. + +SPI requests always go into I/O queues. Requests for a given SPI device +are always executed in FIFO order, and complete asynchronously through +completion callbacks. There are also some simple synchronous wrappers +for those calls, including ones for common transaction types like writing +a command and then reading its response. + +There are two types of SPI driver, here called: + + Controller drivers ... + controllers may be built into System-On-Chip + processors, and often support both Master and Slave roles. + These drivers touch hardware registers and may use DMA. + Or they can be PIO bitbangers, needing just GPIO pins. + + Protocol drivers ... + these pass messages through the controller + driver to communicate with a Slave or Master device on the + other side of an SPI link. + +So for example one protocol driver might talk to the MTD layer to export +data to filesystems stored on SPI flash like DataFlash; and others might +control audio interfaces, present touchscreen sensors as input interfaces, +or monitor temperature and voltage levels during industrial processing. +And those might all be sharing the same controller driver. + +A "struct spi_device" encapsulates the controller-side interface between +those two types of drivers. + +There is a minimal core of SPI programming interfaces, focussing on +using the driver model to connect controller and protocol drivers using +device tables provided by board specific initialization code. SPI +shows up in sysfs in several locations:: + + /sys/devices/.../CTLR ... physical node for a given SPI controller + + /sys/devices/.../CTLR/spiB.C ... spi_device on bus "B", + chipselect C, accessed through CTLR. + + /sys/bus/spi/devices/spiB.C ... symlink to that physical + .../CTLR/spiB.C device + + /sys/devices/.../CTLR/spiB.C/modalias ... identifies the driver + that should be used with this device (for hotplug/coldplug) + + /sys/bus/spi/drivers/D ... driver for one or more spi*.* devices + + /sys/class/spi_master/spiB ... symlink (or actual device node) to + a logical node which could hold class related state for the SPI + master controller managing bus "B". All spiB.* devices share one + physical SPI bus segment, with SCLK, MOSI, and MISO. + + /sys/devices/.../CTLR/slave ... virtual file for (un)registering the + slave device for an SPI slave controller. + Writing the driver name of an SPI slave handler to this file + registers the slave device; writing "(null)" unregisters the slave + device. + Reading from this file shows the name of the slave device ("(null)" + if not registered). + + /sys/class/spi_slave/spiB ... symlink (or actual device node) to + a logical node which could hold class related state for the SPI + slave controller on bus "B". When registered, a single spiB.* + device is present here, possible sharing the physical SPI bus + segment with other SPI slave devices. + +Note that the actual location of the controller's class state depends +on whether you enabled CONFIG_SYSFS_DEPRECATED or not. At this time, +the only class-specific state is the bus number ("B" in "spiB"), so +those /sys/class entries are only useful to quickly identify busses. + + +How does board-specific init code declare SPI devices? +------------------------------------------------------ +Linux needs several kinds of information to properly configure SPI devices. +That information is normally provided by board-specific code, even for +chips that do support some of automated discovery/enumeration. + +Declare Controllers +^^^^^^^^^^^^^^^^^^^ + +The first kind of information is a list of what SPI controllers exist. +For System-on-Chip (SOC) based boards, these will usually be platform +devices, and the controller may need some platform_data in order to +operate properly. The "struct platform_device" will include resources +like the physical address of the controller's first register and its IRQ. + +Platforms will often abstract the "register SPI controller" operation, +maybe coupling it with code to initialize pin configurations, so that +the arch/.../mach-*/board-*.c files for several boards can all share the +same basic controller setup code. This is because most SOCs have several +SPI-capable controllers, and only the ones actually usable on a given +board should normally be set up and registered. + +So for example arch/.../mach-*/board-*.c files might have code like:: + + #include /* for mysoc_spi_data */ + + /* if your mach-* infrastructure doesn't support kernels that can + * run on multiple boards, pdata wouldn't benefit from "__init". + */ + static struct mysoc_spi_data pdata __initdata = { ... }; + + static __init board_init(void) + { + ... + /* this board only uses SPI controller #2 */ + mysoc_register_spi(2, &pdata); + ... + } + +And SOC-specific utility code might look something like:: + + #include + + static struct platform_device spi2 = { ... }; + + void mysoc_register_spi(unsigned n, struct mysoc_spi_data *pdata) + { + struct mysoc_spi_data *pdata2; + + pdata2 = kmalloc(sizeof *pdata2, GFP_KERNEL); + *pdata2 = pdata; + ... + if (n == 2) { + spi2->dev.platform_data = pdata2; + register_platform_device(&spi2); + + /* also: set up pin modes so the spi2 signals are + * visible on the relevant pins ... bootloaders on + * production boards may already have done this, but + * developer boards will often need Linux to do it. + */ + } + ... + } + +Notice how the platform_data for boards may be different, even if the +same SOC controller is used. For example, on one board SPI might use +an external clock, where another derives the SPI clock from current +settings of some master clock. + +Declare Slave Devices +^^^^^^^^^^^^^^^^^^^^^ + +The second kind of information is a list of what SPI slave devices exist +on the target board, often with some board-specific data needed for the +driver to work correctly. + +Normally your arch/.../mach-*/board-*.c files would provide a small table +listing the SPI devices on each board. (This would typically be only a +small handful.) That might look like:: + + static struct ads7846_platform_data ads_info = { + .vref_delay_usecs = 100, + .x_plate_ohms = 580, + .y_plate_ohms = 410, + }; + + static struct spi_board_info spi_board_info[] __initdata = { + { + .modalias = "ads7846", + .platform_data = &ads_info, + .mode = SPI_MODE_0, + .irq = GPIO_IRQ(31), + .max_speed_hz = 120000 /* max sample rate at 3V */ * 16, + .bus_num = 1, + .chip_select = 0, + }, + }; + +Again, notice how board-specific information is provided; each chip may need +several types. This example shows generic constraints like the fastest SPI +clock to allow (a function of board voltage in this case) or how an IRQ pin +is wired, plus chip-specific constraints like an important delay that's +changed by the capacitance at one pin. + +(There's also "controller_data", information that may be useful to the +controller driver. An example would be peripheral-specific DMA tuning +data or chipselect callbacks. This is stored in spi_device later.) + +The board_info should provide enough information to let the system work +without the chip's driver being loaded. The most troublesome aspect of +that is likely the SPI_CS_HIGH bit in the spi_device.mode field, since +sharing a bus with a device that interprets chipselect "backwards" is +not possible until the infrastructure knows how to deselect it. + +Then your board initialization code would register that table with the SPI +infrastructure, so that it's available later when the SPI master controller +driver is registered:: + + spi_register_board_info(spi_board_info, ARRAY_SIZE(spi_board_info)); + +Like with other static board-specific setup, you won't unregister those. + +The widely used "card" style computers bundle memory, cpu, and little else +onto a card that's maybe just thirty square centimeters. On such systems, +your ``arch/.../mach-.../board-*.c`` file would primarily provide information +about the devices on the mainboard into which such a card is plugged. That +certainly includes SPI devices hooked up through the card connectors! + + +Non-static Configurations +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Developer boards often play by different rules than product boards, and one +example is the potential need to hotplug SPI devices and/or controllers. + +For those cases you might need to use spi_busnum_to_master() to look +up the spi bus master, and will likely need spi_new_device() to provide the +board info based on the board that was hotplugged. Of course, you'd later +call at least spi_unregister_device() when that board is removed. + +When Linux includes support for MMC/SD/SDIO/DataFlash cards through SPI, those +configurations will also be dynamic. Fortunately, such devices all support +basic device identification probes, so they should hotplug normally. + + +How do I write an "SPI Protocol Driver"? +---------------------------------------- +Most SPI drivers are currently kernel drivers, but there's also support +for userspace drivers. Here we talk only about kernel drivers. + +SPI protocol drivers somewhat resemble platform device drivers:: + + static struct spi_driver CHIP_driver = { + .driver = { + .name = "CHIP", + .owner = THIS_MODULE, + .pm = &CHIP_pm_ops, + }, + + .probe = CHIP_probe, + .remove = CHIP_remove, + }; + +The driver core will automatically attempt to bind this driver to any SPI +device whose board_info gave a modalias of "CHIP". Your probe() code +might look like this unless you're creating a device which is managing +a bus (appearing under /sys/class/spi_master). + +:: + + static int CHIP_probe(struct spi_device *spi) + { + struct CHIP *chip; + struct CHIP_platform_data *pdata; + + /* assuming the driver requires board-specific data: */ + pdata = &spi->dev.platform_data; + if (!pdata) + return -ENODEV; + + /* get memory for driver's per-chip state */ + chip = kzalloc(sizeof *chip, GFP_KERNEL); + if (!chip) + return -ENOMEM; + spi_set_drvdata(spi, chip); + + ... etc + return 0; + } + +As soon as it enters probe(), the driver may issue I/O requests to +the SPI device using "struct spi_message". When remove() returns, +or after probe() fails, the driver guarantees that it won't submit +any more such messages. + + - An spi_message is a sequence of protocol operations, executed + as one atomic sequence. SPI driver controls include: + + + when bidirectional reads and writes start ... by how its + sequence of spi_transfer requests is arranged; + + + which I/O buffers are used ... each spi_transfer wraps a + buffer for each transfer direction, supporting full duplex + (two pointers, maybe the same one in both cases) and half + duplex (one pointer is NULL) transfers; + + + optionally defining short delays after transfers ... using + the spi_transfer.delay_usecs setting (this delay can be the + only protocol effect, if the buffer length is zero); + + + whether the chipselect becomes inactive after a transfer and + any delay ... by using the spi_transfer.cs_change flag; + + + hinting whether the next message is likely to go to this same + device ... using the spi_transfer.cs_change flag on the last + transfer in that atomic group, and potentially saving costs + for chip deselect and select operations. + + - Follow standard kernel rules, and provide DMA-safe buffers in + your messages. That way controller drivers using DMA aren't forced + to make extra copies unless the hardware requires it (e.g. working + around hardware errata that force the use of bounce buffering). + + If standard dma_map_single() handling of these buffers is inappropriate, + you can use spi_message.is_dma_mapped to tell the controller driver + that you've already provided the relevant DMA addresses. + + - The basic I/O primitive is spi_async(). Async requests may be + issued in any context (irq handler, task, etc) and completion + is reported using a callback provided with the message. + After any detected error, the chip is deselected and processing + of that spi_message is aborted. + + - There are also synchronous wrappers like spi_sync(), and wrappers + like spi_read(), spi_write(), and spi_write_then_read(). These + may be issued only in contexts that may sleep, and they're all + clean (and small, and "optional") layers over spi_async(). + + - The spi_write_then_read() call, and convenience wrappers around + it, should only be used with small amounts of data where the + cost of an extra copy may be ignored. It's designed to support + common RPC-style requests, such as writing an eight bit command + and reading a sixteen bit response -- spi_w8r16() being one its + wrappers, doing exactly that. + +Some drivers may need to modify spi_device characteristics like the +transfer mode, wordsize, or clock rate. This is done with spi_setup(), +which would normally be called from probe() before the first I/O is +done to the device. However, that can also be called at any time +that no message is pending for that device. + +While "spi_device" would be the bottom boundary of the driver, the +upper boundaries might include sysfs (especially for sensor readings), +the input layer, ALSA, networking, MTD, the character device framework, +or other Linux subsystems. + +Note that there are two types of memory your driver must manage as part +of interacting with SPI devices. + + - I/O buffers use the usual Linux rules, and must be DMA-safe. + You'd normally allocate them from the heap or free page pool. + Don't use the stack, or anything that's declared "static". + + - The spi_message and spi_transfer metadata used to glue those + I/O buffers into a group of protocol transactions. These can + be allocated anywhere it's convenient, including as part of + other allocate-once driver data structures. Zero-init these. + +If you like, spi_message_alloc() and spi_message_free() convenience +routines are available to allocate and zero-initialize an spi_message +with several transfers. + + +How do I write an "SPI Master Controller Driver"? +------------------------------------------------- +An SPI controller will probably be registered on the platform_bus; write +a driver to bind to the device, whichever bus is involved. + +The main task of this type of driver is to provide an "spi_master". +Use spi_alloc_master() to allocate the master, and spi_master_get_devdata() +to get the driver-private data allocated for that device. + +:: + + struct spi_master *master; + struct CONTROLLER *c; + + master = spi_alloc_master(dev, sizeof *c); + if (!master) + return -ENODEV; + + c = spi_master_get_devdata(master); + +The driver will initialize the fields of that spi_master, including the +bus number (maybe the same as the platform device ID) and three methods +used to interact with the SPI core and SPI protocol drivers. It will +also initialize its own internal state. (See below about bus numbering +and those methods.) + +After you initialize the spi_master, then use spi_register_master() to +publish it to the rest of the system. At that time, device nodes for the +controller and any predeclared spi devices will be made available, and +the driver model core will take care of binding them to drivers. + +If you need to remove your SPI controller driver, spi_unregister_master() +will reverse the effect of spi_register_master(). + + +Bus Numbering +^^^^^^^^^^^^^ + +Bus numbering is important, since that's how Linux identifies a given +SPI bus (shared SCK, MOSI, MISO). Valid bus numbers start at zero. On +SOC systems, the bus numbers should match the numbers defined by the chip +manufacturer. For example, hardware controller SPI2 would be bus number 2, +and spi_board_info for devices connected to it would use that number. + +If you don't have such hardware-assigned bus number, and for some reason +you can't just assign them, then provide a negative bus number. That will +then be replaced by a dynamically assigned number. You'd then need to treat +this as a non-static configuration (see above). + + +SPI Master Methods +^^^^^^^^^^^^^^^^^^ + +``master->setup(struct spi_device *spi)`` + This sets up the device clock rate, SPI mode, and word sizes. + Drivers may change the defaults provided by board_info, and then + call spi_setup(spi) to invoke this routine. It may sleep. + + Unless each SPI slave has its own configuration registers, don't + change them right away ... otherwise drivers could corrupt I/O + that's in progress for other SPI devices. + + .. note:: + + BUG ALERT: for some reason the first version of + many spi_master drivers seems to get this wrong. + When you code setup(), ASSUME that the controller + is actively processing transfers for another device. + +``master->cleanup(struct spi_device *spi)`` + Your controller driver may use spi_device.controller_state to hold + state it dynamically associates with that device. If you do that, + be sure to provide the cleanup() method to free that state. + +``master->prepare_transfer_hardware(struct spi_master *master)`` + This will be called by the queue mechanism to signal to the driver + that a message is coming in soon, so the subsystem requests the + driver to prepare the transfer hardware by issuing this call. + This may sleep. + +``master->unprepare_transfer_hardware(struct spi_master *master)`` + This will be called by the queue mechanism to signal to the driver + that there are no more messages pending in the queue and it may + relax the hardware (e.g. by power management calls). This may sleep. + +``master->transfer_one_message(struct spi_master *master, struct spi_message *mesg)`` + The subsystem calls the driver to transfer a single message while + queuing transfers that arrive in the meantime. When the driver is + finished with this message, it must call + spi_finalize_current_message() so the subsystem can issue the next + message. This may sleep. + +``master->transfer_one(struct spi_master *master, struct spi_device *spi, struct spi_transfer *transfer)`` + The subsystem calls the driver to transfer a single transfer while + queuing transfers that arrive in the meantime. When the driver is + finished with this transfer, it must call + spi_finalize_current_transfer() so the subsystem can issue the next + transfer. This may sleep. Note: transfer_one and transfer_one_message + are mutually exclusive; when both are set, the generic subsystem does + not call your transfer_one callback. + + Return values: + + * negative errno: error + * 0: transfer is finished + * 1: transfer is still in progress + +``master->set_cs_timing(struct spi_device *spi, u8 setup_clk_cycles, u8 hold_clk_cycles, u8 inactive_clk_cycles)`` + This method allows SPI client drivers to request SPI master controller + for configuring device specific CS setup, hold and inactive timing + requirements. + +Deprecated Methods +^^^^^^^^^^^^^^^^^^ + +``master->transfer(struct spi_device *spi, struct spi_message *message)`` + This must not sleep. Its responsibility is to arrange that the + transfer happens and its complete() callback is issued. The two + will normally happen later, after other transfers complete, and + if the controller is idle it will need to be kickstarted. This + method is not used on queued controllers and must be NULL if + transfer_one_message() and (un)prepare_transfer_hardware() are + implemented. + + +SPI Message Queue +^^^^^^^^^^^^^^^^^ + +If you are happy with the standard queueing mechanism provided by the +SPI subsystem, just implement the queued methods specified above. Using +the message queue has the upside of centralizing a lot of code and +providing pure process-context execution of methods. The message queue +can also be elevated to realtime priority on high-priority SPI traffic. + +Unless the queueing mechanism in the SPI subsystem is selected, the bulk +of the driver will be managing the I/O queue fed by the now deprecated +function transfer(). + +That queue could be purely conceptual. For example, a driver used only +for low-frequency sensor access might be fine using synchronous PIO. + +But the queue will probably be very real, using message->queue, PIO, +often DMA (especially if the root filesystem is in SPI flash), and +execution contexts like IRQ handlers, tasklets, or workqueues (such +as keventd). Your driver can be as fancy, or as simple, as you need. +Such a transfer() method would normally just add the message to a +queue, and then start some asynchronous transfer engine (unless it's +already running). + + +THANKS TO +--------- +Contributors to Linux-SPI discussions include (in alphabetical order, +by last name): + +- Mark Brown +- David Brownell +- Russell King +- Grant Likely +- Dmitry Pervushin +- Stephen Street +- Mark Underwood +- Andrew Victor +- Linus Walleij +- Vitaly Wool diff --git a/Documentation/spi/spidev b/Documentation/spi/spidev deleted file mode 100644 index 3d14035b1766..000000000000 --- a/Documentation/spi/spidev +++ /dev/null @@ -1,149 +0,0 @@ -SPI devices have a limited userspace API, supporting basic half-duplex -read() and write() access to SPI slave devices. Using ioctl() requests, -full duplex transfers and device I/O configuration are also available. - - #include - #include - #include - #include - #include - -Some reasons you might want to use this programming interface include: - - * Prototyping in an environment that's not crash-prone; stray pointers - in userspace won't normally bring down any Linux system. - - * Developing simple protocols used to talk to microcontrollers acting - as SPI slaves, which you may need to change quite often. - -Of course there are drivers that can never be written in userspace, because -they need to access kernel interfaces (such as IRQ handlers or other layers -of the driver stack) that are not accessible to userspace. - - -DEVICE CREATION, DRIVER BINDING -=============================== -The simplest way to arrange to use this driver is to just list it in the -spi_board_info for a device as the driver it should use: the "modalias" -entry is "spidev", matching the name of the driver exposing this API. -Set up the other device characteristics (bits per word, SPI clocking, -chipselect polarity, etc) as usual, so you won't always need to override -them later. - -(Sysfs also supports userspace driven binding/unbinding of drivers to -devices. That mechanism might be supported here in the future.) - -When you do that, the sysfs node for the SPI device will include a child -device node with a "dev" attribute that will be understood by udev or mdev. -(Larger systems will have "udev". Smaller ones may configure "mdev" into -busybox; it's less featureful, but often enough.) For a SPI device with -chipselect C on bus B, you should see: - - /dev/spidevB.C ... character special device, major number 153 with - a dynamically chosen minor device number. This is the node - that userspace programs will open, created by "udev" or "mdev". - - /sys/devices/.../spiB.C ... as usual, the SPI device node will - be a child of its SPI master controller. - - /sys/class/spidev/spidevB.C ... created when the "spidev" driver - binds to that device. (Directory or symlink, based on whether - or not you enabled the "deprecated sysfs files" Kconfig option.) - -Do not try to manage the /dev character device special file nodes by hand. -That's error prone, and you'd need to pay careful attention to system -security issues; udev/mdev should already be configured securely. - -If you unbind the "spidev" driver from that device, those two "spidev" nodes -(in sysfs and in /dev) should automatically be removed (respectively by the -kernel and by udev/mdev). You can unbind by removing the "spidev" driver -module, which will affect all devices using this driver. You can also unbind -by having kernel code remove the SPI device, probably by removing the driver -for its SPI controller (so its spi_master vanishes). - -Since this is a standard Linux device driver -- even though it just happens -to expose a low level API to userspace -- it can be associated with any number -of devices at a time. Just provide one spi_board_info record for each such -SPI device, and you'll get a /dev device node for each device. - - -BASIC CHARACTER DEVICE API -========================== -Normal open() and close() operations on /dev/spidevB.D files work as you -would expect. - -Standard read() and write() operations are obviously only half-duplex, and -the chipselect is deactivated between those operations. Full-duplex access, -and composite operation without chipselect de-activation, is available using -the SPI_IOC_MESSAGE(N) request. - -Several ioctl() requests let your driver read or override the device's current -settings for data transfer parameters: - - SPI_IOC_RD_MODE, SPI_IOC_WR_MODE ... pass a pointer to a byte which will - return (RD) or assign (WR) the SPI transfer mode. Use the constants - SPI_MODE_0..SPI_MODE_3; or if you prefer you can combine SPI_CPOL - (clock polarity, idle high iff this is set) or SPI_CPHA (clock phase, - sample on trailing edge iff this is set) flags. - Note that this request is limited to SPI mode flags that fit in a - single byte. - - SPI_IOC_RD_MODE32, SPI_IOC_WR_MODE32 ... pass a pointer to a uin32_t - which will return (RD) or assign (WR) the full SPI transfer mode, - not limited to the bits that fit in one byte. - - SPI_IOC_RD_LSB_FIRST, SPI_IOC_WR_LSB_FIRST ... pass a pointer to a byte - which will return (RD) or assign (WR) the bit justification used to - transfer SPI words. Zero indicates MSB-first; other values indicate - the less common LSB-first encoding. In both cases the specified value - is right-justified in each word, so that unused (TX) or undefined (RX) - bits are in the MSBs. - - SPI_IOC_RD_BITS_PER_WORD, SPI_IOC_WR_BITS_PER_WORD ... pass a pointer to - a byte which will return (RD) or assign (WR) the number of bits in - each SPI transfer word. The value zero signifies eight bits. - - SPI_IOC_RD_MAX_SPEED_HZ, SPI_IOC_WR_MAX_SPEED_HZ ... pass a pointer to a - u32 which will return (RD) or assign (WR) the maximum SPI transfer - speed, in Hz. The controller can't necessarily assign that specific - clock speed. - -NOTES: - - - At this time there is no async I/O support; everything is purely - synchronous. - - - There's currently no way to report the actual bit rate used to - shift data to/from a given device. - - - From userspace, you can't currently change the chip select polarity; - that could corrupt transfers to other devices sharing the SPI bus. - Each SPI device is deselected when it's not in active use, allowing - other drivers to talk to other devices. - - - There's a limit on the number of bytes each I/O request can transfer - to the SPI device. It defaults to one page, but that can be changed - using a module parameter. - - - Because SPI has no low-level transfer acknowledgement, you usually - won't see any I/O errors when talking to a non-existent device. - - -FULL DUPLEX CHARACTER DEVICE API -================================ - -See the spidev_fdx.c sample program for one example showing the use of the -full duplex programming interface. (Although it doesn't perform a full duplex -transfer.) The model is the same as that used in the kernel spi_sync() -request; the individual transfers offer the same capabilities as are -available to kernel drivers (except that it's not asynchronous). - -The example shows one half-duplex RPC-style request and response message. -These requests commonly require that the chip not be deselected between -the request and response. Several such requests could be chained into -a single kernel request, even allowing the chip to be deselected after -each response. (Other protocol options include changing the word size -and bitrate for each transfer segment.) - -To make a full duplex request, provide both rx_buf and tx_buf for the -same transfer. It's even OK if those are the same buffer. diff --git a/Documentation/spi/spidev.rst b/Documentation/spi/spidev.rst new file mode 100644 index 000000000000..f05dbc5ccdbc --- /dev/null +++ b/Documentation/spi/spidev.rst @@ -0,0 +1,163 @@ +================= +SPI userspace API +================= + +SPI devices have a limited userspace API, supporting basic half-duplex +read() and write() access to SPI slave devices. Using ioctl() requests, +full duplex transfers and device I/O configuration are also available. + +:: + + #include + #include + #include + #include + #include + +Some reasons you might want to use this programming interface include: + + * Prototyping in an environment that's not crash-prone; stray pointers + in userspace won't normally bring down any Linux system. + + * Developing simple protocols used to talk to microcontrollers acting + as SPI slaves, which you may need to change quite often. + +Of course there are drivers that can never be written in userspace, because +they need to access kernel interfaces (such as IRQ handlers or other layers +of the driver stack) that are not accessible to userspace. + + +DEVICE CREATION, DRIVER BINDING +=============================== +The simplest way to arrange to use this driver is to just list it in the +spi_board_info for a device as the driver it should use: the "modalias" +entry is "spidev", matching the name of the driver exposing this API. +Set up the other device characteristics (bits per word, SPI clocking, +chipselect polarity, etc) as usual, so you won't always need to override +them later. + +(Sysfs also supports userspace driven binding/unbinding of drivers to +devices. That mechanism might be supported here in the future.) + +When you do that, the sysfs node for the SPI device will include a child +device node with a "dev" attribute that will be understood by udev or mdev. +(Larger systems will have "udev". Smaller ones may configure "mdev" into +busybox; it's less featureful, but often enough.) For a SPI device with +chipselect C on bus B, you should see: + + /dev/spidevB.C ... + character special device, major number 153 with + a dynamically chosen minor device number. This is the node + that userspace programs will open, created by "udev" or "mdev". + + /sys/devices/.../spiB.C ... + as usual, the SPI device node will + be a child of its SPI master controller. + + /sys/class/spidev/spidevB.C ... + created when the "spidev" driver + binds to that device. (Directory or symlink, based on whether + or not you enabled the "deprecated sysfs files" Kconfig option.) + +Do not try to manage the /dev character device special file nodes by hand. +That's error prone, and you'd need to pay careful attention to system +security issues; udev/mdev should already be configured securely. + +If you unbind the "spidev" driver from that device, those two "spidev" nodes +(in sysfs and in /dev) should automatically be removed (respectively by the +kernel and by udev/mdev). You can unbind by removing the "spidev" driver +module, which will affect all devices using this driver. You can also unbind +by having kernel code remove the SPI device, probably by removing the driver +for its SPI controller (so its spi_master vanishes). + +Since this is a standard Linux device driver -- even though it just happens +to expose a low level API to userspace -- it can be associated with any number +of devices at a time. Just provide one spi_board_info record for each such +SPI device, and you'll get a /dev device node for each device. + + +BASIC CHARACTER DEVICE API +========================== +Normal open() and close() operations on /dev/spidevB.D files work as you +would expect. + +Standard read() and write() operations are obviously only half-duplex, and +the chipselect is deactivated between those operations. Full-duplex access, +and composite operation without chipselect de-activation, is available using +the SPI_IOC_MESSAGE(N) request. + +Several ioctl() requests let your driver read or override the device's current +settings for data transfer parameters: + + SPI_IOC_RD_MODE, SPI_IOC_WR_MODE ... + pass a pointer to a byte which will + return (RD) or assign (WR) the SPI transfer mode. Use the constants + SPI_MODE_0..SPI_MODE_3; or if you prefer you can combine SPI_CPOL + (clock polarity, idle high iff this is set) or SPI_CPHA (clock phase, + sample on trailing edge iff this is set) flags. + Note that this request is limited to SPI mode flags that fit in a + single byte. + + SPI_IOC_RD_MODE32, SPI_IOC_WR_MODE32 ... + pass a pointer to a uin32_t + which will return (RD) or assign (WR) the full SPI transfer mode, + not limited to the bits that fit in one byte. + + SPI_IOC_RD_LSB_FIRST, SPI_IOC_WR_LSB_FIRST ... + pass a pointer to a byte + which will return (RD) or assign (WR) the bit justification used to + transfer SPI words. Zero indicates MSB-first; other values indicate + the less common LSB-first encoding. In both cases the specified value + is right-justified in each word, so that unused (TX) or undefined (RX) + bits are in the MSBs. + + SPI_IOC_RD_BITS_PER_WORD, SPI_IOC_WR_BITS_PER_WORD ... + pass a pointer to + a byte which will return (RD) or assign (WR) the number of bits in + each SPI transfer word. The value zero signifies eight bits. + + SPI_IOC_RD_MAX_SPEED_HZ, SPI_IOC_WR_MAX_SPEED_HZ ... + pass a pointer to a + u32 which will return (RD) or assign (WR) the maximum SPI transfer + speed, in Hz. The controller can't necessarily assign that specific + clock speed. + +NOTES: + + - At this time there is no async I/O support; everything is purely + synchronous. + + - There's currently no way to report the actual bit rate used to + shift data to/from a given device. + + - From userspace, you can't currently change the chip select polarity; + that could corrupt transfers to other devices sharing the SPI bus. + Each SPI device is deselected when it's not in active use, allowing + other drivers to talk to other devices. + + - There's a limit on the number of bytes each I/O request can transfer + to the SPI device. It defaults to one page, but that can be changed + using a module parameter. + + - Because SPI has no low-level transfer acknowledgement, you usually + won't see any I/O errors when talking to a non-existent device. + + +FULL DUPLEX CHARACTER DEVICE API +================================ + +See the spidev_fdx.c sample program for one example showing the use of the +full duplex programming interface. (Although it doesn't perform a full duplex +transfer.) The model is the same as that used in the kernel spi_sync() +request; the individual transfers offer the same capabilities as are +available to kernel drivers (except that it's not asynchronous). + +The example shows one half-duplex RPC-style request and response message. +These requests commonly require that the chip not be deselected between +the request and response. Several such requests could be chained into +a single kernel request, even allowing the chip to be deselected after +each response. (Other protocol options include changing the word size +and bitrate for each transfer segment.) + +To make a full duplex request, provide both rx_buf and tx_buf for the +same transfer. It's even OK if those are the same buffer. diff --git a/drivers/iio/dummy/iio_simple_dummy.c b/drivers/iio/dummy/iio_simple_dummy.c index d28974ad9e0e..6cb02299a215 100644 --- a/drivers/iio/dummy/iio_simple_dummy.c +++ b/drivers/iio/dummy/iio_simple_dummy.c @@ -695,7 +695,7 @@ static int iio_dummy_remove(struct iio_sw_device *swd) * i2c: * Documentation/i2c/writing-clients.rst * spi: - * Documentation/spi/spi-summary + * Documentation/spi/spi-summary.rst */ static const struct iio_sw_device_ops iio_dummy_device_ops = { .probe = iio_dummy_probe, diff --git a/drivers/spi/Kconfig b/drivers/spi/Kconfig index 3a1d8f1170de..d5a24fe983e7 100644 --- a/drivers/spi/Kconfig +++ b/drivers/spi/Kconfig @@ -543,7 +543,7 @@ config SPI_PXA2XX help This enables using a PXA2xx or Sodaville SSP port as a SPI master controller. The driver can be configured to use any SSP port and - additional documentation can be found a Documentation/spi/pxa2xx. + additional documentation can be found a Documentation/spi/pxa2xx.rst. config SPI_PXA2XX_PCI def_tristate SPI_PXA2XX && PCI && COMMON_CLK diff --git a/drivers/spi/spi-butterfly.c b/drivers/spi/spi-butterfly.c index 8c77d1114ad3..7e71a351f3b7 100644 --- a/drivers/spi/spi-butterfly.c +++ b/drivers/spi/spi-butterfly.c @@ -23,7 +23,7 @@ * with a battery powered AVR microcontroller and lots of goodies. You * can use GCC to develop firmware for this. * - * See Documentation/spi/butterfly for information about how to build + * See Documentation/spi/butterfly.rst for information about how to build * and use this custom parallel port cable. */ diff --git a/drivers/spi/spi-lm70llp.c b/drivers/spi/spi-lm70llp.c index f18f912c9dea..174dba29b1dd 100644 --- a/drivers/spi/spi-lm70llp.c +++ b/drivers/spi/spi-lm70llp.c @@ -34,7 +34,7 @@ * available (on page 4) here: * http://www.national.com/appinfo/tempsensors/files/LM70LLPEVALmanual.pdf * - * Also see Documentation/spi/spi-lm70llp. The SPI<->parport code here is + * Also see Documentation/spi/spi-lm70llp.rst. The SPI<->parport code here is * (heavily) based on spi-butterfly by David Brownell. * * The LM70 LLP connects to the PC parallel port in the following manner: diff --git a/include/linux/platform_data/sc18is602.h b/include/linux/platform_data/sc18is602.h index e066d3b0d6d8..0e91489edfe6 100644 --- a/include/linux/platform_data/sc18is602.h +++ b/include/linux/platform_data/sc18is602.h @@ -4,7 +4,7 @@ * * Copyright (C) 2012 Guenter Roeck * - * For further information, see the Documentation/spi/spi-sc18is602 file. + * For further information, see the Documentation/spi/spi-sc18is602.rst file. */ /** -- cgit v1.2.3