Universal means of describing what functions a library should expose

Question

I am busy with a hobby OS and I am planning on making the project open-source and eventually have support for multiple platforms. With this in mind I have taken the approach of putting all hardware specific code in a separate Hardware Abstraction Layer (HAL) library so that the kernel does not need to know how the specific hardware handles things such as memory and interrupts. The kernel will just call the HAL function asking for some memory or to hook an interrupt by calling hal_memory_malloc(...); and hal_interrupts_hook(...); respectively.

My question is, I would like to know if there are any universal means of describing what functions the library has to expose if a developer wants to port the HAL to another platform. Seeing the Kernel knows the name of the function because it's in the kernel's header files the library just needs to have a function with that specific name in it. As the kernel I don't care how your function works as long as its there and I can call it.

Edit My kernel and library is written in C so the library will be a normal statically linked libray

At the moment I have a Word Document that has a diagram showing the different functions but this is going to become a mess soon.

Any advice would be greatly appreciated.

Answer 1

Define it with C header file containing all the prototypes declared extern. Documented with comments in the file itself using doxygen or similar format. That way the compiler will check that the functions have correct signatures when building the library. Doxygen is fully suitable for writing complete documentation and being a text format it is easily versionable, which word or similar binary document formats are not.

But there is not much reason to make it a library anyway. You certainly do want to separate what has to be implemented for each platform and what is generic. But on each platform you only need one HAL and since you still have to compile the generic part for each platform separately (because the object form is not generic), you can just compile it all together.

Besides there are things where you probably should define as C or preprocessor definitions in the platform dependent header included by the generic part for performance reasons, so just a library won't do. While general rule is to not bother with micro-optimizations, some things in kernel like locks (with disabling interrupts in some cases) and atomic operations (for reference counting and other lockless concurrent operations) really need to be inlined.