From f4decf6edcfb91ef4da715ddbd53e6f1786373f8 Mon Sep 17 00:00:00 2001 From: Steve Cartmell Date: Thu, 25 Oct 2018 14:34:49 +0100 Subject: [PATCH 1/3] Add base porting guide for HAL I2C API --- docs/porting/target/i2c.md | 114 +++++++++++++++++++++++++++++++++++++ 1 file changed, 114 insertions(+) create mode 100644 docs/porting/target/i2c.md diff --git a/docs/porting/target/i2c.md b/docs/porting/target/i2c.md new file mode 100644 index 0000000000..4a401aeaf3 --- /dev/null +++ b/docs/porting/target/i2c.md @@ -0,0 +1,114 @@ +## Inter-Integrated Circuit (I2C) + +I2C is a serial protocol for two-wire interface to connect low-speed devices +in embedded systems. The I2C API allows control and configuration of this +interface. + +The interface is made up of two lines for all communication: + - SCL: Serial Clock + - SDA: Serial Data + +### Assumptions + +#### Defined Behaviours + +- `i2c_init`: + - Initialises the peripheral pins specified in the input parameters. + - Initialises the peripheral in master mode if `is_slave` is false. + - Initialises the peripheral in slave mode if `is_slave` is true and `supports_slave_mode` is true. +- `i2c_free`: + - Resets the pins used to initialise the peripheral to their default state. + - Disables the peripheral clock. +- `i2c_get_capabilities`: + - Fills the contents of the `i2c_capabilities_t` parameter +- `i2c_frequency`: + - Sets the frequency to use for the transfer. + - Must leave all other configuration unchanged. +- `i2c_timeout`: + - Sets the clock stretching timeout to use for the following transfers. + - If the timeout is set to 0, disables clock stretching. +- `i2c_write`: + - Writes `length` number of symbols to the bus. + - Returns the number of symbols sent to the bus. + - Returns an error status if transfer fails. + - Generates a stop condition on the bus at the end of the transfer if `stop` parameter is true. + - Handles transfer collisions and loss of arbitration if the platform supports multimaster in hardware. + - The transfer will timeout and return `I2C_ERROR_TIMEOUT ` if the slave stretches the clock for longer than the configured timeout duration. +- `i2c_read`: + - Reads `rx_len` symbols from the bus. + - Returns the number of symbols received from the bus. + - Returns an error code if transfer fails. + - Handles transfer collisions and loss of arbitration if the platform supports multimaster in hardware. + - The transfer will timeout and return `I2C_ERROR_TIMEOUT ` if the slave stretches the clock for longer than the configured timeout duration. +- `i2c_start`: + - Generates I2C START condition on the bus in master mode. + - Does nothing if called when the peripheral is configured in slave mode. +- `i2c_stop`: + - Generates I2C STOP condition on the bus in master mode. + - Does nothing if called when the peripheral is configured in slave mode. +- `i2c_slave_receive`: + - Indicates which mode the peripheral has been addressed in. + - Returns not addressed when called in master mode. +- `i2c_slave_address`: + - Sets the address of the peripheral to the `address` parameter. + - Does nothing if called master mode. +- `i2c_transfer_async`: + - Returns immediately with a `bool` indicating whether the transfer was successfully scheduled or not. + - The callback given to `i2c_transfer_async` is invoked when the transfer finishes. + - Must save the handler and context pointers inside the `obj` pointer. + - The context pointer is passed to the callback on transfer completion. + - The callback must be invoked on completion unless the transfer is aborted. + - `i2c_async_event_t` must be filled with the number of symbols sent to the bus during transfer. +- `i2c_abort_async`: + - Aborts any on-going async transfers. + +#### Undefined Behaviours + +- Use of a `null` pointer as an argument to any function. +- Calling any `I2C` function before calling `i2c_init` or after calling `i2c_free`. +- Initialising the `I2C` peripheral with invalid `SDA` and `SCL` pins. +- Initialising the peripheral in slave mode if slave mode is not supported, indicated by `i2c_get_capabilities`. +- Operating the peripheral in slave mode without first specifying and address using `i2c_address` +- Setting an address using `i2c_address` after initialising the peripheral in master mode. +- Setting an address to an `I2C` reserved value. +- Setting an address larger than the 7-bit supported maximum if 10-bit addressing is not supported. +- Setting an address larger than the 10-bit supported maximum. +- Setting a frequency outside the supported range given by `i2c_get_capabilities` +- Using the device in a multimaster configuration when `supports_multimaster_mode` is false. +- Setting the timeout outside the supported range given by `i2c_get_capabilities`. +- Specifying an invalid address when calling any `read` or `write` functions. +- Setting the length of the transfer or receive buffers to larger than the buffers are. +- Passing an invalid pointer as `handler` to `i2c_transfer_async`. +- Calling `i2c_transfer_abort` when no transfer is currently in progress. + +### Notes + +You can find more details about the design choices on the [HAL RFC #01](https://github.com/ARMmbed/mbed-os/blob/master/hal/rfcs/0001-i2c-overhaul.md). + +### Dependencies + +Hardware I2C capabilities. + +### Implementing the I2C API + +You can find the API and specification for the I2C API in the following class reference: + +[![View code](https://www.mbed.com/embed/?type=library)](http://os-doc-builder.test.mbed.com/docs/development/feature-i2c-doxy/classmbed_1_1_i_2_c.html) + +To enable I2C support in Mbed OS, add the `I2C` label in the `device_has` option of the target's section in the `targets.json` file. + +You can also add the `I2C_ASYNCH` label in the `device_has` option to enable the asynchronous API, +and `I2CSLAVE` to enable the I2CSlave API. + +### Testing + +The Mbed OS HAL provides a set of conformance tests for I2C. You can use these tests to validate the correctness of your implementation. To run the I2C HAL tests, use the following command: + +``` +mbed test -t -m -n "tests-mbed_hal-i2c*" +``` + +You can read more about the test cases: + +[![View code](https://www.mbed.com/embed/?type=library)](http://os-doc-builder.test.mbed.com/docs/development/feature-hal-i2c-doxy/group__hal__i2c__tests.html) + From 906c2ec716e3e7f8546b3a5cbac3da27ea38b08a Mon Sep 17 00:00:00 2001 From: Steve Cartmell Date: Mon, 4 Mar 2019 13:43:03 +0000 Subject: [PATCH 2/3] docs(hal-i2c): Remove unused 'Assumptions' section from porting guide --- docs/porting/target/i2c.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/porting/target/i2c.md b/docs/porting/target/i2c.md index 4a401aeaf3..5232b66b96 100644 --- a/docs/porting/target/i2c.md +++ b/docs/porting/target/i2c.md @@ -8,8 +8,6 @@ The interface is made up of two lines for all communication: - SCL: Serial Clock - SDA: Serial Data -### Assumptions - #### Defined Behaviours - `i2c_init`: From 1a8f64d725c97bfb3718bb27e838fc6897c128ef Mon Sep 17 00:00:00 2001 From: Steve Cartmell Date: Mon, 4 Mar 2019 13:45:56 +0000 Subject: [PATCH 3/3] docs(hal-i2c): Add init behavior to porting guide and fix spelling --- docs/porting/target/i2c.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/porting/target/i2c.md b/docs/porting/target/i2c.md index 5232b66b96..c25d5f38b2 100644 --- a/docs/porting/target/i2c.md +++ b/docs/porting/target/i2c.md @@ -11,9 +11,10 @@ The interface is made up of two lines for all communication: #### Defined Behaviours - `i2c_init`: - - Initialises the peripheral pins specified in the input parameters. - - Initialises the peripheral in master mode if `is_slave` is false. - - Initialises the peripheral in slave mode if `is_slave` is true and `supports_slave_mode` is true. + - Initializes the peripheral pins specified in the input parameters. + - Initializes the peripheral in master mode if `is_slave` is false. + - Initializes the peripheral in slave mode if `is_slave` is true and `supports_slave_mode` is true. + - Initializes all `i2c_t` object fields. - `i2c_free`: - Resets the pins used to initialise the peripheral to their default state. - Disables the peripheral clock.