Documentation/rmodules.md

   1 # Relocatable Modules (rmodules)
   2
   3 Relocatable modules are currently only used on x86.  Relocatable
   4 modules are executables. Exectuables which can be executed anywhere in
   5 memory. Anywhere means that the module does not need to be executed
   6 at a defined memory address which is known at build/link time. For
   7 coreboot stages like bootblock and romstage it is known at build
   8 time at which addresses they are executed.  For some exectuables it
   9 is however not known at which specific address they are executed in
  10 runtime (for example postcar and ramstage). Relocateable modules
  11 usually allocate the space for the modules just before they are
  12 supposed to be executed. After enough space is allocated, CBMEM will
  13 return the location of the allocated space. Now the relocation can be
  14 done by fixing up all relocation entries in the relocatable module
  15 based on the location of the binary (which was returned by CBMEM
  16 at runtime).
  17
  18 # Implementation Details
  19
  20 ## build time
  21
  22 At build time the rmodtool (util/cbfstool/rmodtool.c) is used to
  23 create relocatable modules. The rmodtool basically takes an ELF
  24 file as an input and writes an ELF as output. It basically does
  25 a simple conversion from one ELF file to another slighty changed
  26 ELF file. First the tool makes sure that the ELF file fits a few
  27 requirements. For example there can only be one segment (loadable
  28 program header) in the input ELF file. After that it goes through
  29 the ELF relocation table and takes any entry that applies to the one
  30 segment we want to load at runtime. The rmodtool will then write all
  31 these relocation entires in a new ELF section called ".reloc". After
  32 that the ELF relocation table will be cleared.
  33
  34 One can split the rmodules in two different kinds:
  35 1. coreboot stages (postcar, ramstage)
  36 2. simple binaries (smm, smmstub, sipi\_vector)
  37
  38 They are actually handled the same by the build system and only differ
  39 in the fact, that they are either coreboot stages or they are not.
  40
  41 In the end the ELF files will have three different ELF sections,
  42 which are all created by the rmodtool.
  43 1. relocation header (.header)
  44 2. program (.program)
  45 3. relocation entries (.relocs)
  46
  47 ## runtime
  48
  49 Either rmodule\_load (lib/rmodule.c) is used directly or through the
  50 rmodule\_stage\_load (lib/rmodule.c) wrapper. It is used to load the
  51 stages (postcar and ramstage) or small programs like (sipi\_vector,
  52 smm, smmstub) into memory before jumping to them. In the case of a
  53 coreboot stage, CBMEM is used to allocate space for the stage in memory
  54 via the rmodule\_cbfs\_allocater (lib/rmodule.c). At this point the
  55 location of the stage in memory is known and all relocation (address
  56 fixups) need to be done now. This is basically just a simple loop that
  57 goes through each relocation entry. Each relocation entry is just an
  58 address pointing to a location that needs relocation. The relocation
  59 itself is just a simple addition, that adds an offset from where the
  60 image was "supposed" to be at link time, to where it is now relocated.
  61
  62 ## module\_parameters
  63
  64 module\_parameters is a section inside the rmodule ELF file. Its
  65 basically a way to pass runtime information to an rmodule
  66 before jumping to it. The caller will use rmodule\_parameters()
  67 (lib/rmodule.c) to get the runtime address of the module\_parameters
  68 and the callee (the rmodule itself) usually appends the section to
  69 specific types via compiler attributes. For example:
  70 ```
  71 static const
  72 volatile __attribute((aligned(4), __section__(".module_parameters")))
  73 struct smm_runtime smm_runtime;
  74 ```
  75
  76 # x86 why rmodules
  77 //TODO
  78 x86: postcar and ramstage cannot conflict with payload regarding
  79 memory placement. Therefore payload location is usually fixed and
  80 postcar/ramstage can be placed at a location in memory that is
  81 figured out at runtime.