Add/tidy API doxygen for the new pico_i2c_slave library (#1233)

This commit is contained in:
andygpz11 2023-02-08 16:48:02 +00:00 committed by GitHub
parent 8c8006d457
commit f54ca1a42e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

View File

@ -15,12 +15,20 @@ extern "C" {
#endif #endif
/** \file pico/i2c_slave.h /** \file pico/i2c_slave.h
* \defgrup pico_i2c_slave pico_i2c_slave * \defgroup pico_i2c_slave pico_i2c_slave
* \brief I2C slave helper library, which takes care of hooking the I2C IRQ and calling back the user with I2C events. *
* Functions providing an interrupt driven I2C slave interface.
*
* This I2C slave helper library configures slave mode and hooks the relevant I2C IRQ
* so that a user supplied handler is called with enumerated I2C events.
*
* An example application \c slave_mem_i2c, which makes use of this library, can be found in
* <a href="https://github.com/raspberrypi/pico-examples/blob/master/i2c/slave_mem_i2c/slave_mem_i2c.c">pico_examples</a>.
*/ */
/** /**
* \brief I2C slave event types. * \brief I2C slave event types.
* \ingroup pico_i2c_slave
*/ */
typedef enum i2c_slave_event_t typedef enum i2c_slave_event_t
{ {
@ -31,31 +39,32 @@ typedef enum i2c_slave_event_t
/** /**
* \brief I2C slave event handler * \brief I2C slave event handler
* \ingroup pico_i2c_slave
* *
* The event handler will run from the I2C ISR, so it should return quickly (under 25 us at 400 kb/s). * The event handler will run from the I2C ISR, so it should return quickly (under 25 us at 400 kb/s).
* Avoid blocking inside the handler and split large data transfers across multiple calls for best results. * Avoid blocking inside the handler and split large data transfers across multiple calls for best results.
* When sending data to master, up to `i2c_get_write_available()` bytes can be written without blocking. * When sending data to master, up to \ref i2c_get_write_available() bytes can be written without blocking.
* When receiving data from master, up to `i2c_get_read_available()` bytes can be read without blocking. * When receiving data from master, up to \ref 2c_get_read_available() bytes can be read without blocking.
* *
* \param i2c Slave I2C instance. * \param i2c Either \ref i2c0 or \ref i2c1
* \param event Event type. * \param event Event type.
*/ */
typedef void (*i2c_slave_handler_t)(i2c_inst_t *i2c, i2c_slave_event_t event); typedef void (*i2c_slave_handler_t)(i2c_inst_t *i2c, i2c_slave_event_t event);
/** /**
* \brief Configure I2C instance for slave mode. * \brief Configure an I2C instance for slave mode.
* * \ingroup pico_i2c_slave
* \param i2c I2C instance. * \param i2c I2C instance.
* \param address 7-bit slave address. * \param address 7-bit slave address.
* \param handler Called on events from I2C master. It will run from the I2C ISR, on the CPU core * \param handler Callback for events from I2C master. It will run from the I2C ISR, on the CPU core
* where the slave was initialized. * where the slave was initialised.
*/ */
void i2c_slave_init(i2c_inst_t *i2c, uint8_t address, i2c_slave_handler_t handler); void i2c_slave_init(i2c_inst_t *i2c, uint8_t address, i2c_slave_handler_t handler);
/** /**
* \brief Restore I2C instance to master mode. * \brief Restore an I2C instance to master mode.
* * \ingroup pico_i2c_slave
* \param i2c I2C instance. * \param i2c Either \ref i2c0 or \ref i2c1
*/ */
void i2c_slave_deinit(i2c_inst_t *i2c); void i2c_slave_deinit(i2c_inst_t *i2c);