CODING_GUIDELINES

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