// SPDX-License-Identifier: GPL-2.0-only
/*
* I2C adapter for the IMG Serial Control Bus (SCB) IP block.
*
* Copyright (C) 2009, 2010, 2012, 2014 Imagination Technologies Ltd.
*
* There are three ways that this I2C controller can be driven:
*
* - Raw control of the SDA and SCK signals.
*
* This corresponds to MODE_RAW, which takes control of the signals
* directly for a certain number of clock cycles (the INT_TIMING
* interrupt can be used for timing).
*
* - Atomic commands. A low level I2C symbol (such as generate
* start/stop/ack/nack bit, generate byte, receive byte, and receive
* ACK) is given to the hardware, with detection of completion by bits
* in the LINESTAT register.
*
* This mode of operation is used by MODE_ATOMIC, which uses an I2C
* state machine in the interrupt handler to compose/react to I2C
* transactions using atomic mode commands, and also by MODE_SEQUENCE,
* which emits a simple fixed sequence of atomic mode commands.
*
* Due to software control, the use of atomic commands usually results
* in suboptimal use of the bus, with gaps between the I2C symbols while
* the driver decides what to do next.
*
* - Automatic mode. A bus address, and whether to read/write is
* specified, and the hardware takes care of the I2C state machine,
* using a FIFO to send/receive bytes of data to an I2C slave. The
* driver just has to keep the FIFO drained or filled in response to the
* appropriate FIFO interrupts.
*
* This corresponds to MODE_AUTOMATIC, which manages the FIFOs and deals
* with control of repeated start bits between I2C messages.
*
* Use of automatic mode and the FIFO can make much more efficient use
* of the bus compared to individual atomic commands, with potentially
* no wasted time between I2C symbols or I2C messages.
*
* In most cases MODE_AUTOMATIC is used, however if any of the messages in
* a transaction are zero byte writes (e.g. used by i2cdetect for probing
* the bus), MODE_ATOMIC must be used since automatic mode is normally
* started by the writing of data into the FIFO.
*
* The other modes are used in specific circumstances where MODE_ATOMIC and
* MODE_AUTOMATIC aren't appropriate. MODE_RAW is used to implement a bus
* recovery routine. MODE_SEQUENCE is used to reset the bus and make sure
* it is in a sane state.
*
* Notice that the driver implements a timer-