Proposed I2C driver and MOS API implementation

[envenomator]

Hi!
This proposed driver for I2C has the following API to user programs:
mos_i2c_open - to open the channel with a given frequency id (57.6Khz, 115.200Khz, 230Khz)
mos_i2c_close - to close the channel
mos_i2c_write - to send a I2C datagram to a given slave address, with length and pointer to a send buffer
mos_i2c_read - to read a I2C datagram from a given slave address, with length and pointer to a read buffer

Currently, the following functional limitations apply to the driver:

7bit addressing only
32byte datagram length maximum, aligning with several Linux driver implementations
Master (write/read) role only. Talking to sensors and displays uses this mode, but configuring the Agon as an I2C slave is not yet implemented
2sec arbitration timeout on the channel, allowing very slow sensors to reply before the channel times out, while not locking up the Agon if a sensor borks.
I'll publish example code to use this driver interface a.s.a.p.

[breakintoprogram]

Thanks. I think this'll be the last change I'll squeeze into RC3 - want to get a release out at some point!

[breakintoprogram]

@envenomator I've just added the defines to mos_api.inc and tweaked the read and write functions to promote a 16-bit buffer address to 24 bits if running in Z80 mode, as per other functions. Not had chance to test but have merged into main as there is no risk of it affecting normal operation. Let me know if the changes are okay, and thank you for submitting.

[envenomator]

Perfect! I've just completed testing the merged main and it's still fine with ADL code. This code has been in dev a long time at my end, very tricky to test and debug with the embedded I2C state machine running entirely in the interrupt handler.
I was striving to keep the API as simple as possible, to just send/receive I2C datagrams, that is hopefully also easy to implement in BBC Basic. The trick for people using this, will be to implement their own sensor-specific code that uses it.
Hope everything is well,
Best,
Jeroen