lcr/README.lcr

   1 Live Component Replacement
   2 --------------------------
   3 All software is composed of components, which contain multiple software classes.
   4 Components generally depend upon other components and sometimes classes from
   5 other components.
   6
   7 Some components of openais are the evt service, the ckpt service, the clm
   8 service, the totem protocol, and others.  If a defect is found in any of
   9 these components, the entire ais executive must be stopped, replaced, and
  10 restarted.
  11
  12 The lcr code formalizes the concept of components into dynamic libraries.  A
  13 component may have multiple classes.  Each class (the lcr code uses the word
  14 interface) may have multiple functions within the class.  Each interface may
  15 depend upon other interfaces, and those interfaces are then loaded prior to the
  16 requested interface being referenced.
  17
  18 Note that with recent changes, the lcr interface factory can be used when
  19 statically linking without additional steps.  The interface for notifying
  20 lcr of a component has changed.
  21
  22 A list of shared objects is scanned each time an interface is requested to
  23 load via the following interface:
  24
  25 int lcr_ifact_reference (
  26         void **handle,
  27         char *iface_name,
  28         int version,
  29         void **interface,
  30         void *context);
  31
  32 The iface_name is the name of the interface, the version is the version,
  33 the void **interface is the list of functions returned once the interface
  34 has been dynamically loaded and referenced, and context is passed to the
  35 constructor and destructor.
  36
  37 The interface is loaded, the interface constructor is called, and the list
  38 of interfaces is returned back to the caller.
  39
  40 First the list of interfaces is described in an iface_list data structure:
  41 struct iface_list iface_list = {
  42         .iface1_func1           = iface1_func1,
  43         .iface1_func2           = iface1_func2,
  44         .iface1_func3           = iface1_func3,
  45 };
  46 iface1_func1 is a simple function call.
  47
  48 Then the lcr_iface data structure is defined for the c file:
  49
  50 struct lcr_iface iface1_ver0 = {
  51         .name                   = "iface1",
  52         .version                = 0,
  53         .versions_replace       = 0,
  54         .versions_replace_count = 0,
  55         .dependencies           = 0,
  56         .dependency_count       = 0,
  57         .constructor            = iface1_constructor,
  58         .destructor             = iface1_destructor,
  59         .interfaces             = (void **)&iface_list,
  60 };
  61
  62 The name and version fields provide naming and versioning.  The constructor
  63 and destructor functions execute at reference and release times.  Finally
  64 the .interfaces type describes the list of functions used for the interface.
  65
  66 Next, an lcr_comp must be described:
  67
  68 struct lcr_comp test_comp = {
  69         .iface_count            = 2,
  70         .ifaces                 = lcr_ifaces
  71 };
  72
  73 the iface count describes the number of interfaces within the component,
  74 and lcr_ifaces is an array of pointers to lcr_iface data types.
  75
  76 The lcr_comp_get method has been replaced.  The final step is to setup a
  77 constructor that is started when the task is started.  This ctor will
  78 register the component with the lcr framework.
  79
  80 static void register_this_component (void) {
  81         lcr_component_register (&test_comp);
  82 }
  83
  84 static void (*const __init_this_component[1]) (void) __attribute__ ((section(".ctors"))) = { register_this_component };
  85
  86
  87 Now the component can be referenced and used in another application.
  88 int main ()
  89 {
  90
  91 .....
  92
  93         lcr_ifact_reference (
  94                 &ifact_handle_ver0,
  95                 "iface1",
  96                 0, /* version 0 */
  97                 (void **)&iface_ver0,
  98                 (void *)0xdeadbeef);
  99
 100         iface_ver0->func1();
 101         iface_ver0->func2();
 102         iface_ver0->func3();
 103 }
 104
 105
 106 See libtest_a and libtest_b for two sample components.  The test program
 107 demonstrates usage.  The test_static demonstrates operation when statically
 108 linked.  Note the dynamic inteface factory is still available for use when
 109 statically linking components.
 110
 111 On startup, a thread is created which listens for requests from the "uic"
 112 application.  These requests are then processed by the lcr service which
 113 would execute a live replacement.