feat(PeriphDrivers): Add MAX32657 I3C driver

[ttmut]

Description

Add I3C driver for MAX32657. Basic controller and target APIs are provided.

Note: Will be tested when the test environment is ready.

I3C has been tested with an LPS22HH pressure and temperature sensor.
Legacy I2C has been tested with an AT24C04 EEPROM.

1. Read provisioned ID, using static address (0x5C) as dynamic address.
   

2. Read pressure data, using static address (0x5C) as dynamic address.
   

Pressure value = (0x3D << 16) | (0xC5 << 8) | 0x31;
Pressure value = 4048177;
Pressure(hPa) = Pressure value / Sensitivity
Pressure(hPa) = 4048177 / 4096 = 988hPa;
Pressure(kPa) = 98.8kPa (Atmospheric pressure at sea level is 101kPa)

3. Assign 0x34 as dynamic address. Written to device as 0x68, 1-bit shifted to the left.
   

4. Read WHO_AM_I register using newly assigned dynamic address 0x34.
   

5. I2C write 8 bytes to EEPROM
   

6. I2C read 8 bytes from EEPROM
   

Checklist Before Requesting Review

• PR Title follows correct guidelines.
• Description of changes and all other relevant information.
• (Optional) Provide info on any relevant functional testing/validation. For API changes or significant features, this is not optional.

[sihyung-maxim]

Please refer to the feat/ME30 branch to keep in sync with all design and user guide changes. All internal teams requiring the bare metal SDK are referencing this branch.

The i3c_regs.h file is scrubbed for the user guide and synced with design's finalization of the IP configuration.

Also, please note that the I3C source drivers will require hardware revision files for easier portability across parts. That means, there will at least be an i3c_me30.c, i3c_reva.c, i3c_reva.h, and i3c_reva_regs.h files.

The i3c_me30.c level only contains code specific to the ME30 (such as pin configuration, enabling I3C peripheral clock, and any peripheral API setup), and it generally does not contain any direct register access to the I3C IP.

The i3c_reva* files contain the pure driver implementation of the IP at the register level. This file contains the functions that the i3c_me30.c file will call. The i3c_reva_regs.h file is the universal, superset register file that i3c_reva.* uses. The i3c_regs.h file contains the register set specific to an MCU, and design could vary the IP configuration/register set depending on customer needs for future MCUs reusing the same IP, so having a "universal" register file prevents build errors resulting from feature differences.

You can reference our other peripheral drivers to see how this is all set up. Let me know if you have any questions.

[ttmut]

I missed the latest register updates so put my own for the work in progress. I will look into adapting into feat/ME30 branch. Thanks for the response.

[Jake-Carter]

Thanks @ttmut, some minor change requests below

[ttmut]

Thanks @Jake-Carter for your review. I have addressed your comments so could you have a look once more?

[sihyung-maxim]

Might be a good idea to bring these out as enumerated definitions in the register file so you don't have to hardcode these values.

[sihyung-maxim]

Just curious, are the number of retries given by the spec or something we chose that is probably a good amount?

[ttmut]

For the first one, I observed that it gets stuck there sometimes, i.e., TARG_START is continuously being set even after IBI request is handled. Therefore, I made it fall through after 20 retries, expecting less than 20 devices on the bus. I3C specs do not put a limit on the number of supported devices on an I3C bus. In earlier specs it was given as 11.

Second one is used for delay though I realize now that 10 loops is too short for a delay. The reason I did not want to use MXC_Delay function for delays is that it could conflict with Zephyr OS which also uses SysTick for timing and delays.

[ttmut]

On a second look, it seems I forgot to clear TARG_START bit. I will try to see if it solves the problem I mentioned.

[sihyung-maxim]

Looks good.

If you want to be consistent with the Controller vs Target names, the Docs team and I have been separating these two terms on the ME30 for readability because this IP is designed with a clear separation between these two features.

As a general naming rule with controller and target:

The register-fields would either have a CONT_/TARG_ prefix or _CONT/_TARG suffix in their names. So CONT_INTEN/TARG_INTEN is used instead of CONTINTEN/TARGINTEN for the interrupt enable register names.

The function names would have a section dedicated to these two blocks, _Controller_ and _Target_, if one generic function can't handle a feature for both the controller and target.

The general format for the function name:
MXC_{PERIPH}_{Sub-Blocks, if any}_{FunctionName}(...)

Following the format, for example, the MXC_I3C_ControllerEnableInt(...) function would be MXC_I3C_Controller_EnableInt(...). And MXC_I3C_TargetEnableInt(...) => MXC_I3C_Target_EnableInt(...)

Hope this made sense. A good example of this function naming convention is with the Crypto Tool Box (CTB) in the ME13, ME18, ME21, and ME55.

[ttmut]

Looks good.

If you want to be consistent with the Controller vs Target names, the Docs team and I have been separating these two terms on the ME30 for readability because this IP is designed with a clear separation between these two features.

As a general naming rule with controller and target:

The register-fields would either have a CONT_/TARG_ prefix or _CONT/_TARG suffix in their names. So CONT_INTEN/TARG_INTEN is used instead of CONTINTEN/TARGINTEN for the interrupt enable register names.

The function names would have a section dedicated to these two blocks, _Controller_ and _Target_, if one generic function can't handle a feature for both the controller and target.

The general format for the function name: MXC_{PERIPH}_{Sub-Blocks, if any}_{FunctionName}(...)

Following the format, for example, the MXC_I3C_ControllerEnableInt(...) function would be MXC_I3C_Controller_EnableInt(...). And MXC_I3C_TargetEnableInt(...) => MXC_I3C_Target_EnableInt(...)

Hope this made sense. A good example of this function naming convention is with the Crypto Tool Box (CTB) in the ME13, ME18, ME21, and ME55.

I see your point. I was just trying to avoid using Controller_, Target_ prefixes whenever possible to prevent function names becoming too long. For example, clock can only be generated by controller so MXC_I3C_SetXXFrequency functions are inherently controller-specific. Anyway, I will update the function names accordingly. Thanks for your detailed response.

[sihyung-maxim]

Looks good.
If you want to be consistent with the Controller vs Target names, the Docs team and I have been separating these two terms on the ME30 for readability because this IP is designed with a clear separation between these two features.
As a general naming rule with controller and target:
The register-fields would either have a CONT_/TARG_ prefix or _CONT/_TARG suffix in their names. So CONT_INTEN/TARG_INTEN is used instead of CONTINTEN/TARGINTEN for the interrupt enable register names.
The function names would have a section dedicated to these two blocks, _Controller_ and _Target_, if one generic function can't handle a feature for both the controller and target.
The general format for the function name: MXC_{PERIPH}_{Sub-Blocks, if any}_{FunctionName}(...)
Following the format, for example, the MXC_I3C_ControllerEnableInt(...) function would be MXC_I3C_Controller_EnableInt(...). And MXC_I3C_TargetEnableInt(...) => MXC_I3C_Target_EnableInt(...)
Hope this made sense. A good example of this function naming convention is with the Crypto Tool Box (CTB) in the ME13, ME18, ME21, and ME55.

I see your point. I was just trying to avoid using Controller_, Target_ prefixes whenever possible to prevent function names becoming too long. For example, clock can only be generated by controller so MXC_I3C_SetXXFrequency functions are inherently controller-specific. Anyway, I will update the function names accordingly. Thanks for your detailed response.

It's not a hard rule. I was mainly referring to "duplicate" functions like _Enable/DisableInt(...) and _Clear/GetFlags(...) where the target and controller need to be identified. If a function is inherently controller-specific and there's no target equivalent like MXC_I3C_SetXXFrequency(...), then it's probably fine to not add the _Controller_ name. As long as the documentation indicates it, it's your call on whatever you decide is best for the end user who matters most!

[Jake-Carter]

Thanks @ttmut, let me know when you are ready to merge

[ttmut]

Thanks @ttmut, let me know when you are ready to merge

I do not have anything else to add at the moment. Let's also wait @sihyung-maxim's approval.