← Back to branch summary

~ubuntu-branches/ubuntu/raring/virtualbox-ose/raring

« back to all changes in this revision

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

  • Committer: Bazaar Package Importer
  • Author(s): Felix Geyer
  • Date: 2011-01-30 23:27:25 UTC
  • mfrom: (0.3.12 upstream)
  • Revision ID: james.westby@ubuntu.com-20110130232725-2ouajjd2ggdet0zd
Tags: 4.0.2-dfsg-1ubuntu1
* Merge from Debian unstable, remaining changes:
  - Add Apport hook.
    - debian/virtualbox-ose.files/source_virtualbox-ose.py
    - debian/virtualbox-ose.install
  - Drop *-source packages.
* Drop ubuntu-01-fix-build-gcc45.patch, fixed upstream.
* Drop ubuntu-02-as-needed.patch, added to the Debian package.

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/VBox/VMM/VMMCodingGuidelines.cpp
1
 
/* $Id: VMMCodingGuidelines.cpp $ */
2
 
/** @file
3
 
 * VMM - Coding Guidelines.
4
 
 */
5
 
 
6
 
/*
7
 
 * Copyright (C) 2006-2007 Oracle Corporation
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 (GPL) as published by the Free Software
13
 
 * Foundation, in version 2 as it comes in the "COPYING" file of the
14
 
 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
15
 
 * hope that it will 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 RCPTRTYPE(),
41
 
 *        R0PTRTYPE() and R3PTRTYPE() 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