CODING_GUIDELINES

   1 This is a set of guidelines for how to understand and write code for
   2 the V3 Hypervisor.
   3 ================================
   4
   5 "The use of equal negative space, as a balance to positive space, in a
   6 composition is considered by many as good design. This basic and often
   7 overlooked principle of design gives the eye a "place to rest,"
   8 increasing the appeal of a composition through subtle means."
   9 Translation: Use the f@$#ing spacebar.
  10
  11 Fail Stop:
  12 Because booting a basic linux kernel results in over 1 million VM exits
  13 it is catching silent errors is next to impossible. For this reason
  14 ANY time your code has an error it should return -1, and expect the
  15 execution to halt.
  16
  17 This includes unimplemented features and unhandled cases. These cases
  18 should ALWAYS return -1.
  19
  20
  21 Function names:
  22 To ease porting externally visible function names should be used
  23 rarely and have unique names. Currently we have several techniques for
  24 achieving this:
  25
  26 1. #ifdefs in the header file
  27 When the V3 Hypervisor is compiled it defines the symbol
  28 __V3VEE__. Any function that is not needed outside the Hypervisor
  29 context should be inside an #ifdef __V3VEE__ block, this will make it
  30 invisible to the host environment.
  31
  32 2. static functions
  33 Any utility functions that are only needed in the .c file where they
  34 are defined should be declared as static and not included in the
  35 header file.
  36
  37 3. "v3_" prefix
  38 Major interface functions should be named with the prefix "v3_". This
  39 allows easy understanding of how to interact with the subsystems. And
  40 in the case that they need to be externally visible to the host os,
  41 make them unlikely to collide with other functions.
  42
  43
  44
  45
  46 Debugging Output:
  47 Debugging output is sent through the host os via functions in the
  48 os_hooks structure. These functions have various wrappers of the form
  49 Print*, with printf style semantics.
  50
  51 Two functions of note are PrintDebug and PrintError.
  52
  53 PrintDebug:
  54 Should be used for debugging output that will often be
  55 turned off selectively by the VMM configuration.
  56
  57 PrintError:
  58 Should be used when an error occurs, this will never be optimized out
  59 and will always print.
  60