diff options
Diffstat (limited to 'Documentation/i2c/i2c-topology')
| -rw-r--r-- | Documentation/i2c/i2c-topology | 376 |
1 files changed, 0 insertions, 376 deletions
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. |