/** library to communicate using SMBus as master
 *  @file
 *  @author King Kévin <kingkevin@cuvoodoo.info>
 *  @copyright SPDX-License-Identifier: GPL-3.0-or-later
 *  @date 2017-2020
 *  @note peripherals used: I²C/SMBus @ref smbus_master_i2c
 *  @note SMBus functions not used: alert, ARP; SMBus functions used: PEC
 */
#pragma once

/** SMBus return codes */
enum smbus_master_rc {
	SMBUS_MASTER_RC_NONE = 0, /**< no error */
	SMBUS_MASTER_RC_START_STOP_IN_PROGESS, /**< a start or stop condition is already in progress */
	SMBUS_MASTER_RC_NOT_MASTER, /**< not in master mode */
	SMBUS_MASTER_RC_NOT_TRANSMIT, /**< not in transmit mode */
	SMBUS_MASTER_RC_NOT_RECEIVE, /**< not in receive mode */
	SMBUS_MASTER_RC_NOT_READY, /**< slave is not read (previous operations has been NACKed) */
	SMBUS_MASTER_RC_NAK, /**< not acknowledge received */
	SMBUS_MASTER_RC_PECERR, /**< device dais the PER is corrupted */
	SMBUS_MASTER_RC_BUS_ERROR, /**< an error on the SMBus bus occurred */
	SMBUS_MASTER_RC_TIMEOUT, /**< a timeout has occurred because an operation has not completed in the expected time */
	SMBUS_MASTER_RC_OTHER, /** any other error (does not have to be SMBus related) */
};

/** setup SMBus peripheral
 *  @param[in] frequency frequency to use in kHz (10-100)
 *  @param[in] pec if Packet Error Code is used
 */
void smbus_master_setup(uint8_t frequency, bool pec);
/** release SMBus peripheral
 */
void smbus_master_release(void);
/** reset SMBus peripheral, fixing any locked state
 *  @warning the SMBus peripheral needs to be re-setup
 *  @note to be used after failed start or stop, and bus error
 */
void smbus_master_reset(void);
/** check if SDA and SCL signals are pulled up externally
 *  @return SDA and SCL signals are pulled up externally
 */
bool smbus_master_check_signals(void);
/** send start condition
 *  @return SMBus return code
 */
enum smbus_master_rc smbus_master_start(void);
/** select SMBus slave device
 *  @warning a start condition should be sent before this operation
 *  @param[in] slave SMBus 7-bit address of slave device to select
 *  @param[in] write this transaction will be followed by a read (false) or write (true) operation
 *  @note 10-bit address are not specified by SMBus 3.1
 *  @return SMBus return code
 */
enum smbus_master_rc smbus_master_select_slave(uint8_t slave, bool write);
/** read data over SMBus
 *  @param[out] data array to store bytes read
 *  @param[in] data_size number of bytes to read
 *  @return SMBus return code
 *  @warning the slave device must be selected before this operation
 *  @note a stop condition will be sent at the end (I²C peripheral does not permit multiple reads, and this is necessary for 1-byte transfer)
 */
enum smbus_master_rc smbus_master_read(uint8_t* data, size_t data_size);
/** write data over SMBus
 *  @param[in] data array of byte to write to slave
 *  @param[in] data_size number of bytes to write
 *  @return SMBus return code
 *  @warning the slave device must be selected before this operation
 *  @note no stop condition or optional PEC are sent at the end, allowing multiple writes
 */
enum smbus_master_rc smbus_master_write(const uint8_t* data, size_t data_size);
/** sent stop condition
 *  @return SMBus return code
 */
enum smbus_master_rc smbus_master_stop(void);
/** read data from slave device
 *  @param[in] slave SMBus 7-bit address of slave device to select
 *  @param[out] data array to store bytes read
 *  @param[in] data_size number of bytes to read
 *  @return SMBus return code
 *  @note start and stop conditions, and optional PEC are included
 *  @note 10-bit address are not specified by SMBus 3.1
 */
enum smbus_master_rc smbus_master_slave_read(uint8_t slave, uint8_t* data, size_t data_size);
/** write data to slave device
 *  @param[in] slave SMBus 7-bit address of slave device to select
 *  @param[in] data array of byte to write to slave
 *  @param[in] data_size number of bytes to write
 *  @return SMBus return code
 *  @note start and stop conditions, and optional PEC are included
 *  @note 10-bit address are not specified by SMBus 3.1
 */
enum smbus_master_rc smbus_master_slave_write(uint8_t slave, const uint8_t* data, size_t data_size);
/** read data after sending read command from on an SMBus memory slave
 *  @param[in] slave SMBus 7-bit address of slave device to select
 *  @param[in] command command code
 *  @param[out] data array to store bytes read
 *  @param[in] data_size number of bytes to read
 *  @return SMBus return code
 *  @note start and stop conditions, and optional PEC are included
 *  @note 10-bit address are not specified by SMBus 3.1
 */
enum smbus_master_rc smbus_master_command_read(uint8_t slave, uint8_t command, uint8_t* data, size_t data_size);
/** write data after sending write command on an SMBus memory slave
 *  @param[in] slave SMBus 7-bit address of slave device to select
 *  @param[in] command command code
 *  @param[in] data array of byte to write to slave
 *  @param[in] data_size number of bytes to write
 *  @return SMBus return code
 *  @note start and stop conditions, and optional PEC are included
 *  @note 10-bit address are not specified by SMBus 3.1
 */
enum smbus_master_rc smbus_master_command_write(uint8_t slave, uint8_t command, const uint8_t* data, size_t data_size);