← Back to branch summary

~ubuntu-branches/ubuntu/gutsy/virtualbox-ose/gutsy

« back to all changes in this revision

Viewing changes to src/VBox/VMM/VMMCodingGuidelines.cpp

  • Committer: Bazaar Package Importer
  • Author(s): Steve Kowalik
  • Date: 2007-09-08 16:44:58 UTC
  • Revision ID: james.westby@ubuntu.com-20070908164458-wao29470vqtr8ksy
Tags: upstream-1.5.0-dfsg2
Import upstream version 1.5.0-dfsg2

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/VBox/VMM/VMMCodingGuidelines.cpp
 
1
/* $Id: VMMCodingGuidelines.cpp 4071 2007-08-07 17:07:59Z vboxsync $ */
 
2
/** @file
 
3
 * VMM - Coding Guidelines.
 
4
 */
 
5
 
 
6
/*
 
7
 * Copyright (C) 2006-2007 innotek GmbH
 
8
 *
 
9
 * This file is part of VirtualBox Open Source Edition (OSE), as
 
10
 * available from http://www.virtualbox.org. This file is free software;
 
11
 * you can redistribute it and/or modify it under the terms of the GNU
 
12
 * General Public License as published by the Free Software Foundation,
 
13
 * in version 2 as it comes in the "COPYING" file of the VirtualBox OSE
 
14
 * distribution. VirtualBox OSE is distributed in the hope that it will
 
15
 * be useful, but WITHOUT ANY WARRANTY of any kind.
 
16
 */
 
17
 
 
18
 
 
19
/** @page pg_vmm_guideline                  VMM Coding Guidelines
 
20
 *
 
21
 * The guidelines extends the VBox coding guidelines (@ref pg_vbox_guideline)
 
22
 * and consists of a compulsory part and an optional part. It is very important
 
23
 * that the rules of the compusory part is followed. That will prevent obvious
 
24
 * bugs, and it will ease porting the code to 32/64 and 64/32 bits setups.
 
25
 *
 
26
 *
 
27
 *
 
28
 * @section sec_vmm_guideline_compulsory        Compulsory
 
29
 *
 
30
 * It is of vital importance is to distiguish between addresses - both virtual
 
31
 * and physical - applying to Guest Context and Host Context. To assist the
 
32
 * coder in this, a set of types and macros have been created. Another vital
 
33
 * thing is that structures shared between the two contexts ends up with the
 
34
 * same size and member offsets in both places. There are types and macros
 
35
 * for that too.
 
36
 *
 
37
 *
 
38
 * The rules:
 
39
 *
 
40
 *      - When declaring pointers in shared structures use the GCPTRTYPE() and
 
41
 *        HCPTRTYPE() macros.
 
42
 *
 
43
 *      - Use RTGCPTR and RTHCPTR when dealing with the other context in
 
44
 *        none shared structures, parameter lists, stack variables and such.
 
45
 *
 
46
 *      - Following the above rules, pointers will in a context other than the
 
47
 *        one a pointer was defined for, appear as unsigned integers.
 
48
 *
 
49
 *      - It is NOT permitted to subject a pointer from the other context to pointer
 
50
 *        types of the current context by direct cast or by definition.
 
51
 *
 
52
 *      - When doing pointer arithmetic cast using uintptr_t, intptr_t or char *.
 
53
 *        Never cast a pointer to anything else for this purpose, that will not
 
54
 *        work everywhere! (1)
 
55
 *
 
56
 *      - Physical addresses are also specific to their context. Use RTGCPHYS
 
57
 *        and RTHCPHYS when dealing when them. Both types are unsigned integers.
 
58
 *
 
59
 *      - Integers in shared structures should be using a RT integer type or
 
60
 *        any of the [u]int[0-9]+_t types. (2)
 
61
 *
 
62
 *      - If code is shared between the contexts, GCTYPE() can be used to declare
 
63
 *        things differently. If GCTYPE() usage is extensive, don't share the code.
 
64
 *
 
65
 *      - The context is part of all public symbols which are specific to a single
 
66
 *        context.
 
67
 *
 
68
 *
 
69
 * (1) Talking about porting between 32-bit and 64-bit architectures and even
 
70
 *     between 64-bit platforms. On 64-bit linux int is 32-bit, long is 64-bit.
 
71
 *     However on 64-bit windows both int and long are 32-bit - there is no
 
72
 *     standard 64 bit type (_int64 is not a standard type, it's an stupid
 
73
 *     extension).
 
74
 *
 
75
 * (2) The VBox integer types are RTINT, RTUINT, RTGCINT, RTGCUINT,
 
76
 *     RTGCINTPTR, RTGCUINTPTR, RTHCINT, RTHCUINT, RTHCINTPTR and
 
77
 *     RTHCUINTPTR.
 
78
 *
 
79
 *
 
80
 *
 
81
 * @section sec_vmm_guideline_optional          Optional
 
82
 *
 
83
 * There are the general VBox guidelines, see @ref sec_vbox_guideline_optional.
 
84
 * In addition to these for the following rules applies to the VMM:
 
85
 *
 
86
 *      - Prefixes GCPtr and HCPtr are prefered over suffixes HC and GC of
 
87
 *        pointers.
 
88
 *
 
89
 *      - Prefixes GCPhys and HCPhys are generally used for physical addresses,
 
90
 *        types RTGCPHYS and RTHCPHYS respectively.
 
91
 *
 
92
 */
 
93