VirtualBox

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

Last change on this file since 65828 was 62478, checked in by vboxsync, 8 years ago

(C) 2016

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id Revision
File size: 3.7 KB
Line 
1/* $Id: Docs-CodingGuidelines.cpp 62478 2016-07-22 18:29:06Z vboxsync $ */
2/** @file
3 * VMM - Coding Guidelines.
4 */
5
6/*
7 * Copyright (C) 2006-2016 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 compulsory 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 distinguish 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 preferred 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
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