From 976e737d87526fec6437c5ec9a847335f0fe3efe Mon Sep 17 00:00:00 2001 From: Maciej Bocianski Date: Mon, 8 Jul 2019 10:11:47 +0200 Subject: [PATCH 1/5] Add porting guide for HAL I2C API --- docs/porting/target/i2c.md | 116 +++++++++++++++++++++++++++++++++++++ 1 file changed, 116 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..2956d22770 --- /dev/null +++ b/docs/porting/target/i2c.md @@ -0,0 +1,116 @@ +## 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 + +#### Defined Behaviours + +- `i2c_init`: + - 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. +- `i2c_get_capabilities`: + - Fills the contents of the `i2c_capabilities_t` parameter +- `i2c_frequency`: + - Sets the frequency to use for the transfer. + - Returns the actual frequency that will be used. + - Must leave all other configuration unchanged. +- `i2c_timeout`: + - Sets the transmision timeout to use for the following blocking transfers. + - If the timeout is not set the default timeout is used. + - Default timeout value is based on I2C frequency. Is computed as triple amount of time it would take to send data over I2C +- `i2c_write`: + - Writes `length` number of symbols to the bus. + - Returns the number of symbols sent to the bus. + - Returns an error code 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 transfer takes longer than the configured timeout duration. +- `i2c_read`: + - Reads `length` symbols from the bus. + - Returns the number of symbols received from the bus. + - Returns an error code 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 transfer takes 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_status`: + - 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 in 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 or error occurs. + - 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. + - May handle transfer collisions and loss of arbitration if the platform supports multimaster in hardware and enabled in API. + - `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_slave_address` +- Setting an address using `i2c_slave_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. +- 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/feature-i2c/docs/design-documents/hal/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_fpga_ci_test_shield-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 8a53da992c3c416542eb767707e5502996e3ea09 Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Mon, 8 Jul 2019 14:08:10 -0500 Subject: [PATCH 2/5] Edit i2c.md Edit file, mostly for consistent tense and international spelling. --- docs/porting/target/i2c.md | 121 ++++++++++++++++++------------------- 1 file changed, 60 insertions(+), 61 deletions(-) diff --git a/docs/porting/target/i2c.md b/docs/porting/target/i2c.md index 2956d22770..3f4224a479 100644 --- a/docs/porting/target/i2c.md +++ b/docs/porting/target/i2c.md @@ -1,108 +1,107 @@ -## Inter-Integrated Circuit (I2C) +# 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. +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 -#### Defined Behaviours +- Serial Clock (SCL). +- Serial Data (SDA). + +## Defined behaviors - `i2c_init`: - - 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. + - 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. + - Resets the pins used to initialize the peripheral to their default state. + - Disables the peripheral clock. - `i2c_get_capabilities`: - - Fills the contents of the `i2c_capabilities_t` parameter + - Fills the contents of the `i2c_capabilities_t` parameter. - `i2c_frequency`: - - Sets the frequency to use for the transfer. - - Returns the actual frequency that will be used. - - Must leave all other configuration unchanged. + - Sets the frequency to use for the transfer. + - Returns the actual frequency used. + - Must leave all other configuration unchanged. - `i2c_timeout`: - - Sets the transmision timeout to use for the following blocking transfers. - - If the timeout is not set the default timeout is used. - - Default timeout value is based on I2C frequency. Is computed as triple amount of time it would take to send data over I2C + - Sets the transmision timeout to use for the following blocking transfers. + - If the timeout is not set, the default timeout is used. + - Default timeout value is based on I2C frequency and computed as triple the amount of time it takes to send data over I2C. - `i2c_write`: - - Writes `length` number of symbols to the bus. - - Returns the number of symbols sent to the bus. - - Returns an error code 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 transfer takes longer than the configured timeout duration. + - Writes `length` number of symbols to the bus. + - Returns the number of symbols sent to the bus. + - Returns an error code 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 times out and returns `I2C_ERROR_TIMEOUT ` if the transfer takes longer than the configured timeout duration. - `i2c_read`: - - Reads `length` symbols from the bus. - - Returns the number of symbols received from the bus. - - Returns an error code 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 transfer takes longer than the configured timeout duration. + - Reads `length` symbols from the bus. + - Returns the number of symbols received from the bus. + - Returns an error code 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 times out and returns `I2C_ERROR_TIMEOUT ` if the transfer takes 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. + - 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. + - Generates I2C STOP condition on the bus in master mode. + - Does nothing if called when the peripheral is configured in slave mode. - `i2c_slave_status`: - - Indicates which mode the peripheral has been addressed in. - - Returns not addressed when called in master mode. + - Indicates in which mode the peripheral has been addressed. + - 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 in master mode. + - Sets the address of the peripheral to the `address` parameter. + - Does nothing if called in 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 or error occurs. - - 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. - - May handle transfer collisions and loss of arbitration if the platform supports multimaster in hardware and enabled in API. - - `i2c_async_event_t` must be filled with the number of symbols sent to the bus during transfer. + - Returns immediately with a `bool` indicating whether the transfer was successfully scheduled. + - The callback given to `i2c_transfer_async` is invoked when the transfer finishes or error occurs. + - 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. + - May handle transfer collisions and loss of arbitration if the platform supports multimaster in hardware and enabled in API. + - `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. + - Aborts any ongoing async transfers. -#### Undefined behaviours +## Undefined behaviors - 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_slave_address` -- Setting an address using `i2c_slave_address` after initialising the peripheral in master mode. +- Initializing the `I2C` peripheral with invalid `SDA` and `SCL` pins. +- Initializing 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_slave_address`. +- Setting an address using `i2c_slave_address` after initializing 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` +- 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. - 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 +## Notes -You can find more details about the design choices on the [HAL RFC #01](https://github.com/ARMmbed/mbed-os/blob/feature-i2c/docs/design-documents/hal/0001-i2c-overhaul.md). +You can find more details about the design choices in the [HAL code design document](https://github.com/ARMmbed/mbed-os/blob/feature-i2c/docs/design-documents/hal/0001-i2c-overhaul.md). -### Dependencies +## Dependencies Hardware I2C capabilities. -### Implementing the I2C API +## 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) +[![View code](https://www.mbed.com/embed/?type=library)](http://os.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 +## 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: @@ -112,5 +111,5 @@ mbed test -t -m -n "tests-mbed_hal_fpga_ci_test_shield-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) +[![View code](https://www.mbed.com/embed/?type=library)](http://os.mbed.com/docs/development/feature-hal-i2c-doxy/group__hal__i2c__tests.html) From 70f9623d632c70138cf957e626554c2b88366fdb Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Mon, 8 Jul 2019 14:29:12 -0500 Subject: [PATCH 3/5] Fix links in i2c.md Fix outdated links that don't work anymore. --- docs/porting/target/i2c.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/porting/target/i2c.md b/docs/porting/target/i2c.md index 3f4224a479..e04fffa35f 100644 --- a/docs/porting/target/i2c.md +++ b/docs/porting/target/i2c.md @@ -94,7 +94,7 @@ Hardware I2C capabilities. 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.mbed.com/docs/development/feature-i2c-doxy/classmbed_1_1_i_2_c.html) +[![View code](https://www.mbed.com/embed/?type=library)](https://os.mbed.com/docs/mbed-os/development/feature-i2c-doxy/classmbed_1_1_i2_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. @@ -111,5 +111,5 @@ mbed test -t -m -n "tests-mbed_hal_fpga_ci_test_shield-i2c" You can read more about the test cases: -[![View code](https://www.mbed.com/embed/?type=library)](http://os.mbed.com/docs/development/feature-hal-i2c-doxy/group__hal__i2c__tests.html) +[![View code](https://www.mbed.com/embed/?type=library)](https://os.mbed.com/docs/mbed-os/development/feature-i2c-doxy/group__hal__i2c__tests.html) From af1dc2d47267ba49acc7a85c0455e11fda7d4ef7 Mon Sep 17 00:00:00 2001 From: Maciej Bocianski Date: Tue, 16 Jul 2019 14:42:46 +0200 Subject: [PATCH 4/5] i2c porting guide: add i2c_set_clock_stretching --- docs/porting/target/i2c.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/porting/target/i2c.md b/docs/porting/target/i2c.md index e04fffa35f..41751c2a24 100644 --- a/docs/porting/target/i2c.md +++ b/docs/porting/target/i2c.md @@ -23,6 +23,9 @@ The interface is made up of two lines for all communication: - Sets the frequency to use for the transfer. - Returns the actual frequency used. - Must leave all other configuration unchanged. +- `i2c_set_clock_stretching`: + - Enables or disables clock stretching for the peripheral when in slave mode. + - Does nothing when called in master mode. - `i2c_timeout`: - Sets the transmision timeout to use for the following blocking transfers. - If the timeout is not set, the default timeout is used. From ccdbaac777bbfd9baa054d92f2d13a6dfe280739 Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Wed, 24 Jul 2019 10:42:24 -0500 Subject: [PATCH 5/5] Add warning to i2c.md Add warning about code being on a feature branch to match docs in the rest of the section. --- docs/porting/target/i2c.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/porting/target/i2c.md b/docs/porting/target/i2c.md index 41751c2a24..e57ad9b9c2 100644 --- a/docs/porting/target/i2c.md +++ b/docs/porting/target/i2c.md @@ -7,6 +7,8 @@ The interface is made up of two lines for all communication: - Serial Clock (SCL). - Serial Data (SDA). +**Warning:** We are introducing the I2C API in an upcoming release of Mbed OS. This page documents code that exists on a feature branch of Mbed OS. You can find details on how it may affect you in the [implementing the I2C API](#implementing-the-i2c-api) section. + ## Defined behaviors - `i2c_init`: