VMMCodingGuidelines.cpp revision d099ccfb66d26601f93e7967e8e73cee4b9c62df
35ab1c5bca11317474fe12bdd8d22c17cdaf2697Robert Wapshott * VMM - Coding Guidelines.
35ab1c5bca11317474fe12bdd8d22c17cdaf2697Robert Wapshott * Copyright (C) 2006-2007 Sun Microsystems, Inc.
35ab1c5bca11317474fe12bdd8d22c17cdaf2697Robert Wapshott * This file is part of VirtualBox Open Source Edition (OSE), as
35ab1c5bca11317474fe12bdd8d22c17cdaf2697Robert Wapshott * available from http://www.virtualbox.org. This file is free software;
35ab1c5bca11317474fe12bdd8d22c17cdaf2697Robert Wapshott * you can redistribute it and/or modify it under the terms of the GNU
35ab1c5bca11317474fe12bdd8d22c17cdaf2697Robert Wapshott * General Public License (GPL) as published by the Free Software
1d407e39b7d8f68d9a2b1e178f35fab037d9835aRobert Wapshott * Foundation, in version 2 as it comes in the "COPYING" file of the
1d407e39b7d8f68d9a2b1e178f35fab037d9835aRobert Wapshott * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
1d407e39b7d8f68d9a2b1e178f35fab037d9835aRobert Wapshott * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
35ab1c5bca11317474fe12bdd8d22c17cdaf2697Robert Wapshott * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
35ab1c5bca11317474fe12bdd8d22c17cdaf2697Robert Wapshott * Clara, CA 95054 USA or visit http://www.sun.com if you need
35ab1c5bca11317474fe12bdd8d22c17cdaf2697Robert Wapshott * additional information or have any questions.
35ab1c5bca11317474fe12bdd8d22c17cdaf2697Robert Wapshott/** @page pg_vmm_guideline VMM Coding Guidelines
35ab1c5bca11317474fe12bdd8d22c17cdaf2697Robert Wapshott * The guidelines extends the VBox coding guidelines (@ref pg_vbox_guideline)
35ab1c5bca11317474fe12bdd8d22c17cdaf2697Robert Wapshott * and consists of a compulsory part and an optional part. It is very important
35ab1c5bca11317474fe12bdd8d22c17cdaf2697Robert Wapshott * that the rules of the compusory part is followed. That will prevent obvious
35ab1c5bca11317474fe12bdd8d22c17cdaf2697Robert Wapshott * bugs, and it will ease porting the code to 32/64 and 64/32 bits setups.
1d407e39b7d8f68d9a2b1e178f35fab037d9835aRobert Wapshott * @section sec_vmm_guideline_compulsory Compulsory
6e9ce46f56bfb7663e3af5aa571d51e8f61f0240Gabor Melkvi * It is of vital importance is to distiguish between addresses - both virtual
35ab1c5bca11317474fe12bdd8d22c17cdaf2697Robert Wapshott * and physical - applying to Guest Context and Host Context. To assist the
35ab1c5bca11317474fe12bdd8d22c17cdaf2697Robert Wapshott * coder in this, a set of types and macros have been created. Another vital
1d407e39b7d8f68d9a2b1e178f35fab037d9835aRobert Wapshott * thing is that structures shared between the two contexts ends up with the
35ab1c5bca11317474fe12bdd8d22c17cdaf2697Robert Wapshott * same size and member offsets in both places. There are types and macros
35ab1c5bca11317474fe12bdd8d22c17cdaf2697Robert Wapshott * for that too.
35ab1c5bca11317474fe12bdd8d22c17cdaf2697Robert Wapshott * - When declaring pointers in shared structures use the RCPTRTYPE(),
35ab1c5bca11317474fe12bdd8d22c17cdaf2697Robert Wapshott * R0PTRTYPE() and R3PTRTYPE() macros.
35ab1c5bca11317474fe12bdd8d22c17cdaf2697Robert Wapshott * - Use RTGCPTR and RTHCPTR when dealing with the other context in
1d407e39b7d8f68d9a2b1e178f35fab037d9835aRobert Wapshott * none shared structures, parameter lists, stack variables and such.
35ab1c5bca11317474fe12bdd8d22c17cdaf2697Robert Wapshott * - Following the above rules, pointers will in a context other than the
35ab1c5bca11317474fe12bdd8d22c17cdaf2697Robert Wapshott * one a pointer was defined for, appear as unsigned integers.
35ab1c5bca11317474fe12bdd8d22c17cdaf2697Robert Wapshott * - It is NOT permitted to subject a pointer from the other context to pointer
1d407e39b7d8f68d9a2b1e178f35fab037d9835aRobert Wapshott * types of the current context by direct cast or by definition.
1d407e39b7d8f68d9a2b1e178f35fab037d9835aRobert Wapshott * - When doing pointer arithmetic cast using uintptr_t, intptr_t or char *.
6e9ce46f56bfb7663e3af5aa571d51e8f61f0240Gabor Melkvi * Never cast a pointer to anything else for this purpose, that will not
6e9ce46f56bfb7663e3af5aa571d51e8f61f0240Gabor Melkvi * work everywhere! (1)
35ab1c5bca11317474fe12bdd8d22c17cdaf2697Robert Wapshott * - Physical addresses are also specific to their context. Use RTGCPHYS
1d407e39b7d8f68d9a2b1e178f35fab037d9835aRobert Wapshott * and RTHCPHYS when dealing when them. Both types are unsigned integers.
35ab1c5bca11317474fe12bdd8d22c17cdaf2697Robert Wapshott * - Integers in shared structures should be using a RT integer type or
1d407e39b7d8f68d9a2b1e178f35fab037d9835aRobert Wapshott * any of the [u]int[0-9]+_t types. (2)
35ab1c5bca11317474fe12bdd8d22c17cdaf2697Robert Wapshott * - If code is shared between the contexts, GCTYPE() can be used to declare
35ab1c5bca11317474fe12bdd8d22c17cdaf2697Robert Wapshott * things differently. If GCTYPE() usage is extensive, don't share the code.