Document ABI conventions

[X512]

ABI conventions used by Haiku for each architecture (x86 gcc2, x86 gcc4+, x86_64) should be documented in some way (in web site, HaikuBook etc.).

At least following topics should be documented:

• Preserved registers, including SIMD registers etc.
• FPU state.
• Passing arguments to function and return value.
• Stack alignment including alignment origin.
• Exception handling and stack unwinding.
• Executable format.

If Haiku use some existing ABI, it should be referenced in documentation with Haiku specific changes, if any.

I tried to port some non C/C++ compiler (target ABI: x86 gcc4+) and make Haiku API bindings and experience various problems such as:

• Structs passed by value (such as pattern) are stored on stack as is, but classes such as BPoint are passed by pointer.
• BView::StrokeLine(BPoint, BPoint, pattern) is not working if stack is not aligned.

[X512]

Related discussions:

• #10509
• ​https://www.haiku-os.org/blog/pulkomandy/2013-12-20_webkit_weekly_report_12/

[waddlesplash]

We do not do anything special here, Haiku just uses GCC (now 8) with no particular ABI customizations, so we are following the Itanium C++ ABI, which is already well documented: ​https://itanium-cxx-abi.github.io/cxx-abi/abi.html

Structs passed by value (such as pattern) are stored on stack as is, but classes such as BPoint are passed by pointer.

Yes, this is because BPoint is somehow not trivially copyable (I think it has an explicit copy constructor), so as per the Itanium ABI, it cannot be passed in registers.

BView::StrokeLine(BPoint, BPoint, pattern) is not working if stack is not aligned.

GCC assumes the stack is aligned as per the architecture's general requirements. This is also not Haiku specific at all.

[X512]

Replying to waddlesplash:

We do not do anything special here, Haiku just uses GCC (now 8) with no particular ABI customizations, so we are following the Itanium C++ ABI, which is already well documented: ​https://itanium-cxx-abi.github.io/cxx-abi/abi.html

This should be mentioned in documentation.

[X512]

Replying to waddlesplash:

GCC assumes the stack is aligned as per the architecture's general requirements. This is also not Haiku specific at all.

GCC2 seems to have different stack alignment.

[pulkomandy]

Yes, gcc2 has smaller alignment because sse2 didn't exist back then.