VirtualBox

source: vbox/trunk/src/VBox/VMM/Docs-CodingGuidelines.cpp@ 96686

Last change on this file since 96686 was 96407, checked in by vboxsync, 2 years ago

scm copyright and license note update

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id Revision
File size: 4.0 KB
Line 
1/* $Id: Docs-CodingGuidelines.cpp 96407 2022-08-22 17:43:14Z vboxsync $ */
2/** @file
3 * VMM - Coding Guidelines.
4 */
5
6/*
7 * Copyright (C) 2006-2022 Oracle and/or its affiliates.
8 *
9 * This file is part of VirtualBox base platform packages, as
10 * available from https://www.virtualbox.org.
11 *
12 * This program is free software; you can redistribute it and/or
13 * modify it under the terms of the GNU General Public License
14 * as published by the Free Software Foundation, in version 3 of the
15 * License.
16 *
17 * This program is distributed in the hope that it will be useful, but
18 * WITHOUT ANY WARRANTY; without even the implied warranty of
19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20 * General Public License for more details.
21 *
22 * You should have received a copy of the GNU General Public License
23 * along with this program; if not, see <https://www.gnu.org/licenses>.
24 *
25 * SPDX-License-Identifier: GPL-3.0-only
26 */
27
28
29/** @page pg_vmm_guideline VMM Coding Guidelines
30 *
31 * The guidelines extends the VBox coding guidelines (@ref pg_vbox_guideline)
32 * and consists of a compulsory part and an optional part. It is very important
33 * that the rules of the compulsory part is followed. That will prevent obvious
34 * bugs, and it will ease porting the code to 32/64 and 64/32 bits setups.
35 *
36 *
37 *
38 * @section sec_vmm_guideline_compulsory Compulsory
39 *
40 * It is of vital importance is to distinguish between addresses - both virtual
41 * and physical - applying to Guest Context and Host Context. To assist the
42 * coder in this, a set of types and macros have been created. Another vital
43 * thing is that structures shared between the two contexts ends up with the
44 * same size and member offsets in both places. There are types and macros
45 * for that too.
46 *
47 *
48 * The rules:
49 *
50 * - When declaring pointers in shared structures use the RCPTRTYPE(),
51 * R0PTRTYPE() and R3PTRTYPE() macros.
52 *
53 * - Use RTGCPTR and RTHCPTR when dealing with the other context in
54 * none shared structures, parameter lists, stack variables and such.
55 *
56 * - Following the above rules, pointers will in a context other than the
57 * one a pointer was defined for, appear as unsigned integers.
58 *
59 * - It is NOT permitted to subject a pointer from the other context to pointer
60 * types of the current context by direct cast or by definition.
61 *
62 * - When doing pointer arithmetic cast using uintptr_t, intptr_t or char *.
63 * Never cast a pointer to anything else for this purpose, that will not
64 * work everywhere! (1)
65 *
66 * - Physical addresses are also specific to their context. Use RTGCPHYS
67 * and RTHCPHYS when dealing when them. Both types are unsigned integers.
68 *
69 * - Integers in shared structures should be using a RT integer type or
70 * any of the [u]int[0-9]+_t types. (2)
71 *
72 * - If code is shared between the contexts, GCTYPE() can be used to declare
73 * things differently. If GCTYPE() usage is extensive, don't share the code.
74 *
75 * - The context is part of all public symbols which are specific to a single
76 * context.
77 *
78 *
79 * (1) Talking about porting between 32-bit and 64-bit architectures and even
80 * between 64-bit platforms. On 64-bit linux int is 32-bit, long is 64-bit.
81 * However on 64-bit windows both int and long are 32-bit - there is no
82 * standard 64 bit type (_int64 is not a standard type, it's an stupid
83 * extension).
84 *
85 * (2) The VBox integer types are RTINT, RTUINT, RTGCINT, RTGCUINT,
86 * RTGCINTPTR, RTGCUINTPTR, RTHCINT, RTHCUINT, RTHCINTPTR and
87 * RTHCUINTPTR.
88 *
89 *
90 *
91 * @section sec_vmm_guideline_optional Optional
92 *
93 * There are the general VBox guidelines, see @ref sec_vbox_guideline_optional.
94 * In addition to these for the following rules applies to the VMM:
95 *
96 * - Prefixes GCPtr and HCPtr are preferred over suffixes HC and GC of
97 * pointers.
98 *
99 * - Prefixes GCPhys and HCPhys are generally used for physical addresses,
100 * types RTGCPHYS and RTHCPHYS respectively.
101 *
102 */
103
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette