Add I2C HAL API overhaul design document

[ghost]

Description

This PR adds the Request For Comment document for the I2C HAL API overhaul.

This document is meant to serve as the design document for defining what we plan for the API.

Document readable here.

Pull request type:

[ ] Fix
[ ] Refactor
[ ] New target
[x] Feature
[ ] Breaking change

@ithinuel @c1728p9

[ghost]

@AnotherButler

[cmonr]

@mbed-os-core @ARMmbed/mbed-os-hal @c1728p9 @ithinuel @AnotherButler

It would be good to get eyes on this PR since it's been open for a while.

[AnotherButler]

I'll wait to edit this until some reviews are in and we know the content won't change too much.

[ithinuel]

Apart from the commentary about i2c_frequency, it looks good to me :)

[0xc0170]

@donatieng do you want to review or anyone else should or happy with the approvals as they are and we can progress with this design document?

[cmonr]

@AnotherButler It seems that this PR has settled a bit.

[SenRamakri]

@scartmell-arm - Whys is this document under hal, please move this to docs/design-documents/hal, you may create another folder there if you like. This document is not in the prescribed format all other design docs are. Please take a look at - https://github.com/ARMmbed/mbed-os/tree/master/docs/design-documents

[ghost]

@scartmell-arm - Whys is this document under hal, please move this to docs/design-documents/hal, you may create another folder there if you like. This document is not in the prescribed format all other design docs are. Please take a look at - https://github.com/ARMmbed/mbed-os/tree/master/docs/design-documents

Because it was initially written before either of those were added.

[cmonr]

@scartmell-arm Any updates?

[ghost]

@scartmell-arm Any updates?

There were a number of minor changes made to the API after this was written, I'm in the process of updating it to match.

[cmonr]

@scartmell-arm Are there more updates in the pipeline, or should we start poking reviewers again?

[0xc0170]

Is this 5.12 release target? The label is set to it but has not been moved for some time, let us know. In case this is not targeting 5.12, we should remove the 5.12 label.

[SenRamakri]

@scartmell-arm - Please follow the design-document template if this needs to be put under docs/design-documents directory - https://github.com/ARMmbed/mbed-os/blob/master/docs/design-documents/design_template.md

[bulislaw]

This PR is at risk of missing 5.12 release as it's marked as "needs: work". Code freeze is coming! On Friday 1st. Please make necessary updates ASAP and make sure the reviewers are aligned for prompt code inspection.

[cmonr]

@scartmell-arm I've been wondering. Don't we have a feature-i2c branch? Shouldn't this be going there instead?

At the current rate, this being on master doesn't seem like it's going to happen before code freeze.

[donatieng]

This should target the feature I2C branch.

[ghost]

Please follow the design-document template if this needs to be put under docs/design-documents directory

It seems excessive to rewrite the whole design document in that format. Especially when the overhaul in question is primarily just tidying up the function parameters of an existing API.

[cmonr]

@scartmell-arm Are there any available updates on this PR?

[adbridge]

@bulislaw as Steve is leaving, who is taking on the ownership of this PR ?

[bulislaw]

@ithinuel can you take the ownership?

[cmonr]

@ithinuel Ping?

[ithinuel]

Should this be reviewed independently of #10374 ?

[adbridge]

@ithinuel any update on this ?

[ithinuel]

@adbridge I don't remember any answer to my previous question.

[adbridge]

Should this be reviewed independently of #10374 ?

@bulislaw can you comment ?

[maciejbocianski]

@donatieng @ithinuel
Work on this document will be continued in #10374
Update for both doc and reference implementation will be available within this week

[bulislaw]

Thanks @maciejbocianski does it mean we can close this PR?

[maciejbocianski]

Yes please close it. Doc was moved to #10374