Add full documentation to all driver functions.
Signed-off-by: Mario Six mario.six@gdsys.cc Reviewed-by: Stefan Roese sr@denx.de ---
Changes for v2: None
--- drivers/i2c/mvtwsi.c | 163 +++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 144 insertions(+), 19 deletions(-)
diff --git a/drivers/i2c/mvtwsi.c b/drivers/i2c/mvtwsi.c index f060cd1..ab7481a 100644 --- a/drivers/i2c/mvtwsi.c +++ b/drivers/i2c/mvtwsi.c @@ -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, -- 2.9.0