UnifiedAPIs

<?plugin CreateToc jshide||=1 with_toclink||=1 ?>

Introduction

Over the past few months, I have been trying to come up with a plan for how to neatly, cleanly and efficiently merge the various PCI and Interrupt APIs. This is a thorn in all our sides and difficult to explain at best.

There are a handful of problems to getting to the goal.

• Defining a single API
• Fixing everywhere the old API is used
• Lack of universal knowledge on all CPUs and BSPs
• It's intimidating :>

In short, no one is completely comfortable doing all the work and it doesn't seem easy to subdivide or implement incrementally. This is what I think I have solved. We can argue about individual issues one at a time along the way and incrementally fix BSPs and device drivers impacted.

I want to be extremely clear about one key point. This is not about where the implementation resides in the source tree -- it is about having a common API that is implemented as appropriate for each port.

The Process

This process is designed to be manageable. We focus on a single issue, we resolve that, and we move along. The previous attempts at this have failed because the problem space is too large.

• Define name/location of universal PCI and interrupt .h files.

• Create initial version of the unified PCI and IRQ files. Remove the old files and convert to using the single .h file.

which is at first structured so the different APIs continue to exist but all drivers and BSPs using the APIs must be corrected to use the new common .h files. These common files could be structured like this:

... common stuff TBD ...

#if defined(x86)
... All of do it x86 way ...
#else another CPU
... All of do it CPU way...
#endif

• Initiate Transition chapter in BSP Guide.

• Next address one issue that is different in the existing APIs. Fix that and make it shared. Every time we come to consensus on that single issue, fix all BSPs and drivers that this SINGLE action impacted. Reflect this in the Transition chapter. It doesn't particularly matter the order in which the differences are reduced or modifications are made as long as they do reduce differences. We could define the objective API and then incrementall implement it. Alternatively, we could just note that the APIs differ for the name of say the "attach ISR" service and we resolve that. Order is not as critical as making incremental progress is. The file now looks like this:

... common stuff defined so far...
#if defined(x86)
... Remaining part of do it x86 way ...
#else another CPU
... Remaining part of do it CPU way...
#endif

• Rinse and repeat previous step until complete.

Common Issues

• Externally maintained BSPs will break. This is unavoidable since this is an API change.

• TBD

Interrupt API

• Interrupt service routines should have at least have the vector number and a context pointer (void *) as arguments.

• Distinction between exceptions and interrupts although I do not yet fully grasp what an exception is allowed to do relative to RTEMS.

PCI API

• GOAL: Be as compatible as possible with the *BSD PCI driver APIs so we can more easily port code.

• The PowerPC PCI .h files define helper constants which are not available on the x86 port. I noticed this in the dec21140.c driver where the PowerPC sections have nice constants and the x86 sections have hard-coded numbers.