i2c: mvtwsi: Add documentation

Add full documentation to all driver functions.

Signed-off-by: Mario Six <mario.six@gdsys.cc>
Reviewed-by: Stefan Roese <sr@denx.de>
This commit is contained in:
mario.six@gdsys.cc 2016-07-21 11:57:13 +02:00 committed by Heiko Schocher
parent c68c624320
commit 6e677caf8c

View File

@ -157,6 +157,12 @@ enum mvtwsi_ack_flags {
MVTWSI_READ_ACK = 1,
};
/*
* calc_tick() - Calculate the duration of a clock cycle from the I2C speed
*
* @speed: The speed in Hz to calculate the clock cycle duration for.
* @return The duration of a clock cycle in ns.
*/
inline uint calc_tick(uint speed)
{
/* One tick = the duration of a period at the specified speed in ns (we
@ -167,9 +173,11 @@ inline uint calc_tick(uint speed)
#ifndef CONFIG_DM_I2C
/*
* MVTWSI controller base
* twsi_get_base() - Get controller register base for specified adapter
*
* @adap: Adapter to get the register base for.
* @return Register base for the specified adapter.
*/
static struct mvtwsi_registers *twsi_get_base(struct i2c_adapter *adap)
{
switch (adap->hwadapnr) {
@ -238,8 +246,10 @@ inline uint mvtwsi_error(uint ec, uint lc, uint ls, uint es)
}
/*
* Wait for IFLG to raise, or return 'timeout.' Then, if the status is as
* expected, return 0 (ok) or 'wrong status' otherwise.
* twsi_wait() - Wait for I2C bus interrupt flag and check status, or time out.
*
* @return Zero if status is as expected, or a non-zero code if either a time
* out occurred, or the status was not the expected one.
*/
static int twsi_wait(struct mvtwsi_registers *twsi, int expected_status,
uint tick)
@ -266,8 +276,17 @@ static int twsi_wait(struct mvtwsi_registers *twsi, int expected_status,
}
/*
* Assert the START condition, either in a single I2C transaction
* or inside back-to-back ones (repeated starts).
* twsi_start() - Assert a START condition on the bus.
*
* This function is used in both single I2C transactions and inside
* back-to-back transactions (repeated starts).
*
* @twsi: The MVTWSI register structure to use.
* @expected_status: The I2C bus status expected to be asserted after the
* operation completion.
* @tick: The duration of a clock cycle at the current I2C speed.
* @return Zero if status is as expected, or a non-zero code if either a time
* out occurred or the status was not the expected one.
*/
static int twsi_start(struct mvtwsi_registers *twsi, int expected_status,
uint tick)
@ -280,7 +299,17 @@ static int twsi_start(struct mvtwsi_registers *twsi, int expected_status,
}
/*
* Send a byte (i2c address or data).
* twsi_send() - Send a byte on the I2C bus.
*
* The byte may be part of an address byte or data.
*
* @twsi: The MVTWSI register structure to use.
* @byte: The byte to send.
* @expected_status: The I2C bus status expected to be asserted after the
* operation completion.
* @tick: The duration of a clock cycle at the current I2C speed.
* @return Zero if status is as expected, or a non-zero code if either a time
* out occurred or the status was not the expected one.
*/
static int twsi_send(struct mvtwsi_registers *twsi, u8 byte,
int expected_status, uint tick)
@ -295,7 +324,17 @@ static int twsi_send(struct mvtwsi_registers *twsi, u8 byte,
}
/*
* Receive a byte.
* twsi_recv() - Receive a byte on the I2C bus.
*
* The static variable mvtwsi_control_flags controls whether we ack or nak.
*
* @twsi: The MVTWSI register structure to use.
* @byte: The byte to send.
* @ack_flag: Flag that determines whether the received byte should
* be acknowledged by the controller or not (sent ACK/NAK).
* @tick: The duration of a clock cycle at the current I2C speed.
* @return Zero if status is as expected, or a non-zero code if either a time
* out occurred or the status was not the expected one.
*/
static int twsi_recv(struct mvtwsi_registers *twsi, u8 *byte, int ack_flag,
uint tick)
@ -318,8 +357,15 @@ static int twsi_recv(struct mvtwsi_registers *twsi, u8 *byte, int ack_flag,
}
/*
* Assert the STOP condition.
* This is also used to force the bus back to idle (SDA = SCL = 1).
* twsi_stop() - Assert a STOP condition on the bus.
*
* This function is also used to force the bus back to idle state (SDA =
* SCL = 1).
*
* @twsi: The MVTWSI register structure to use.
* @tick: The duration of a clock cycle at the current I2C speed.
* @return Zero if the operation succeeded, or a non-zero code if a time out
* occurred.
*/
static int twsi_stop(struct mvtwsi_registers *twsi, uint tick)
{
@ -344,6 +390,13 @@ static int twsi_stop(struct mvtwsi_registers *twsi, uint tick)
return status;
}
/*
* twsi_calc_freq() - Compute I2C frequency depending on m and n parameters.
*
* @n: Parameter 'n' for the frequency calculation algorithm.
* @m: Parameter 'm' for the frequency calculation algorithm.
* @return The I2C frequency corresponding to the passed m and n parameters.
*/
static uint twsi_calc_freq(const int n, const int m)
{
#ifdef CONFIG_SUNXI
@ -354,9 +407,12 @@ static uint twsi_calc_freq(const int n, const int m)
}
/*
* Reset controller.
* Controller reset also resets the baud rate and slave address, so
* they must be re-established afterwards.
* twsi_reset() - Reset the I2C controller.
*
* Resetting the controller also resets the baud rate and slave address, hence
* they must be re-established after the reset.
*
* @twsi: The MVTWSI register structure to use.
*/
static void twsi_reset(struct mvtwsi_registers *twsi)
{
@ -367,7 +423,15 @@ static void twsi_reset(struct mvtwsi_registers *twsi)
}
/*
* Sets baud to the highest possible value not exceeding the requested one.
* __twsi_i2c_set_bus_speed() - Set the speed of the I2C controller.
*
* This function sets baud rate to the highest possible value that does not
* exceed the requested rate.
*
* @twsi: The MVTWSI register structure to use.
* @requested_speed: The desired frequency the controller should run at
* in Hz.
* @return The actual frequency the controller was configured to.
*/
static uint __twsi_i2c_set_bus_speed(struct mvtwsi_registers *twsi,
uint requested_speed)
@ -400,6 +464,18 @@ static uint __twsi_i2c_set_bus_speed(struct mvtwsi_registers *twsi,
return highest_speed;
}
/*
* __twsi_i2c_init() - Initialize the I2C controller.
*
* @twsi: The MVTWSI register structure to use.
* @speed: The initial frequency the controller should run at
* in Hz.
* @slaveadd: The I2C address to be set for the I2C master.
* @actual_speed: A output parameter that receives the actual frequency
* in Hz the controller was set to by the function.
* @return Zero if the operation succeeded, or a non-zero code if a time out
* occurred.
*/
static void __twsi_i2c_init(struct mvtwsi_registers *twsi, int speed,
int slaveadd, uint *actual_speed)
{
@ -419,8 +495,21 @@ static void __twsi_i2c_init(struct mvtwsi_registers *twsi, int speed,
}
/*
* Begin I2C transaction with expected start status, at given address.
* Expected address status will derive from direction bit (bit 0) in addr.
* i2c_begin() - Start a I2C transaction.
*
* Begin a I2C transaction with a given expected start status and chip address.
* A START is asserted, and the address byte is sent to the I2C controller. The
* expected address status will be derived from the direction bit (bit 0) of
* the address byte.
*
* @twsi: The MVTWSI register structure to use.
* @expected_start_status: The I2C status the controller is expected to
* assert after the address byte was sent.
* @addr: The address byte to be sent.
* @tick: The duration of a clock cycle at the current
* I2C speed.
* @return Zero if the operation succeeded, or a non-zero code if a time out or
* unexpected I2C status occurred.
*/
static int i2c_begin(struct mvtwsi_registers *twsi, int expected_start_status,
u8 addr, uint tick)
@ -443,7 +532,16 @@ static int i2c_begin(struct mvtwsi_registers *twsi, int expected_start_status,
}
/*
* Begin read, nak data byte, end.
* __twsi_i2c_probe_chip() - Probe the given I2C chip address.
*
* This function begins a I2C read transaction, does a dummy read and NAKs; if
* the procedure succeeds, the chip is considered to be present.
*
* @twsi: The MVTWSI register structure to use.
* @chip: The chip address to probe.
* @tick: The duration of a clock cycle at the current I2C speed.
* @return Zero if the operation succeeded, or a non-zero code if a time out or
* unexpected I2C status occurred.
*/
static int __twsi_i2c_probe_chip(struct mvtwsi_registers *twsi, uchar chip,
uint tick)
@ -463,12 +561,26 @@ static int __twsi_i2c_probe_chip(struct mvtwsi_registers *twsi, uchar chip,
}
/*
* Begin write, send address byte(s), begin read, receive data bytes, end.
* __twsi_i2c_read() - Read data from a I2C chip.
*
* This function begins a I2C write transaction, and transmits the address
* bytes; then begins a I2C read transaction, and receives the data bytes.
*
* NOTE: Some devices want a stop right before the second start, while some
* will choke if it is there. Since deciding this is not yet supported in
* higher level APIs, we need to make a decision here, and for the moment that
* will be a repeated start without a preceding stop.
*
* @twsi: The MVTWSI register structure to use.
* @chip: The chip address to read from.
* @addr: The address bytes to send.
* @alen: The length of the address bytes in bytes.
* @data: The buffer to receive the data read from the chip (has to have
* a size of at least 'length' bytes).
* @length: The amount of data to be read from the chip in bytes.
* @tick: The duration of a clock cycle at the current I2C speed.
* @return Zero if the operation succeeded, or a non-zero code if a time out or
* unexpected I2C status occurred.
*/
static int __twsi_i2c_read(struct mvtwsi_registers *twsi, uchar chip,
u8 *addr, int alen, uchar *data, int length,
@ -504,7 +616,20 @@ static int __twsi_i2c_read(struct mvtwsi_registers *twsi, uchar chip,
}
/*
* Begin write, send address byte(s), send data bytes, end.
* __twsi_i2c_write() - Send data to a I2C chip.
*
* This function begins a I2C write transaction, and transmits the address
* bytes; then begins a new I2C write transaction, and sends the data bytes.
*
* @twsi: The MVTWSI register structure to use.
* @chip: The chip address to read from.
* @addr: The address bytes to send.
* @alen: The length of the address bytes in bytes.
* @data: The buffer containing the data to be sent to the chip.
* @length: The length of data to be sent to the chip in bytes.
* @tick: The duration of a clock cycle at the current I2C speed.
* @return Zero if the operation succeeded, or a non-zero code if a time out or
* unexpected I2C status occurred.
*/
static int __twsi_i2c_write(struct mvtwsi_registers *twsi, uchar chip,
u8 *addr, int alen, uchar *data, int length,