VMM Coding Guidelines
The guidelines extends the VBox coding guidelines (VBox Coding Guidelines
) and consists of a compulsory part and an optional part. It is very important that the rules of the compusory part is followed. That will prevent obvious bugs, and it will ease porting the code to 32/64 and 64/32 bits setups.
It is of vital importance is to distiguish between addresses - both virtual and physical - applying to Guest Context and Host Context. To assist the coder in this, a set of types and macros have been created. Another vital thing is that structures shared between the two contexts ends up with the same size and member offsets in both places. There are types and macros for that too.
- Use RTGCPTR and RTHCPTR when dealing with the other context in none shared structures, parameter lists, stack variables and such.
- Following the above rules, pointers will in a context other than the one a pointer was defined for, appear as unsigned integers.
- It is NOT permitted to subject a pointer from the other context to pointer types of the current context by direct cast or by definition.
- When doing pointer arithmetic cast using uintptr_t, intptr_t or char *. Never cast a pointer to anything else for this purpose, that will not work everywhere! (1)
- Physical addresses are also specific to their context. Use RTGCPHYS and RTHCPHYS when dealing when them. Both types are unsigned integers.
- Integers in shared structures should be using a RT integer type or any of the [u]int[0-9]+_t types. (2)
- If code is shared between the contexts, GCTYPE() can be used to declare things differently. If GCTYPE() usage is extensive, don't share the code.
- The context is part of all public symbols which are specific to a single context.
(1) Talking about porting between 32-bit and 64-bit architectures and even between 64-bit platforms. On 64-bit linux int is 32-bit, long is 64-bit. However on 64-bit windows both int and long are 32-bit - there is no standard 64 bit type (_int64 is not a standard type, it's an stupid extension).
(2) The VBox integer types are RTINT, RTUINT, RTGCINT, RTGCUINT, RTGCINTPTR, RTGCUINTPTR, RTHCINT, RTHCUINT, RTHCINTPTR and RTHCUINTPTR.
There are the general VBox guidelines, see Optional
. In addition to these for the following rules applies to the VMM
- Prefixes GCPtr and HCPtr are prefered over suffixes HC and GC of pointers.
- Prefixes GCPhys and HCPhys are generally used for physical addresses, types RTGCPHYS and RTHCPHYS respectively.