README.rtems

   1 Instructions how to compile ORTE for RTEMS
   2 ==========================================
   3
   4 Build process of ORTE for RTEMS differs from build
   5 for Linux and Windows even that all required changes
   6 to actual source files are included in the common
   7 source base.
   8
   9 The build for RTEMS requires access to the RTEMS BSP
  10 and executive include files and libraries in addition
  11 to selection cross-compiler and associated C library
  12 files. It should be possible through autoconf/configure
  13 options but we have not tested that approach because
  14 we use OMK system for many of our Linux, RTEMS, etc.
  15 projects and OMK provides rules suitable for RTEMS
  16 projects.
  17
  18 See OMK homepage for more details about OMK
  19
  20   http://rtime.felk.cvut.cz/omk/
  21
  22 Example/template application (rtems-omk-template)
  23 for RTEMS OMK project is provided in repository
  24
  25   http://rtime.felk.cvut.cz/gitweb/rtems-devel.git
  26
  27 The RTEMS specific OMK rules are used for ORTE build
  28
  29   cp Makefile.rules.rtems Makefile.rules
  30
  31 Then RTEMS target BSP is selected by specifying
  32 RTEMS_MAKEFILE_PATH definition written into "config.target"
  33 file
  34
  35   echo RTEMS_MAKEFILE_PATH=/opt/rtems4.10/powerpc-rtems4.10/icecube >config.target
  36
  37 This declaration selects directory where RTEMS Makefile.inc
  38 file for given BSP is located.
  39
  40 The ORTE components can be configured in "config.omk" file
  41
  42   echo "# ORTE for RTEMS configuration"         >config.omk
  43
  44 The RTEMS cannot run multiple processes. It is not problem
  45 for RTEMS because it allows to specify and maintain multiple
  46 domains and applications in single address space. Even ORTE
  47 manager can be started directly from user application.
  48 But standalone applications are used for testing
  49 and standalone manager is easiest way to start development
  50 too. The problem of independent starting of multiple
  51 services in RTEMS environment had been solved by providing
  52 applications as libraries with renamed C main() function.
  53 This arrangement is selected for manager by
  54
  55   echo CONFIG_OC_ETH_ORTE_MANAGER_AS_LIBRARY=y  >>config.omk
  56
  57 The same way examples and their build as libraries can be selected
  58
  59   echo CONFIG_OC_ETH_ORTE_EXAMPLES=y            >>config.omk
  60   echo CONFIG_OC_ETH_ORTE_EXAMPLES_AS_LIBRARY=y >>config.omk
  61
  62 Option to start the ORTE examples and manager interactively
  63 is usesfull for testing. That is why commands for services
  64 invocations from RTEMS shell are provided
  65
  66   echo CONFIG_OC_ETH_ORTE_RTEMS_SHELL=y         >>config.omk
  67
  68 The commands set includes even "spawn" command implementation
  69 to run services in background/parallel.
  70
  71 User application can include commands provided by "orte_rtems_shell"
  72 and other ORTE services libraries ("ortemanager", "orteping",
  73 "ortespy", ...) by registerring corersponding commands
  74
  75   rtems_shell_add_cmd("ortemanager", "orte",
  76                 "start orte manager",
  77                 ortemanager_main);
  78
  79   rtems_shell_add_cmd("orteping", "orte",
  80                 "start orteping",
  81                 orte_ping_main);
  82
  83   ...
  84
  85
  86   rtems_shell_add_cmd("spawn", "orte",
  87                 "spawn task or command in background",
  88                 orte_spawn_main);
  89
  90
  91 The example application (orte/examples/rtems-shell) for RTEMS
  92 testing is provided. Default provided network configuration
  93 for this example uses DHCP failsafe option.
  94
  95   orte/examples/rtems-shell/networkconfig.h
  96
  97 The application binary image linked with RTEMS system
  98 is available in "_compiled/<bsp_name>/bin" directory.
  99 I.e.
 100
 101   _compiled/lpc17xx_ea_ram/bin/orte_rtems_shell_example
 102
 103
 104 The build is tarted by simple "make" command after above
 105 configuration
 106
 107   make V=1
 108
 109 provides invoked full commands printing.
 110
 111   make clean
 112
 113 or
 114
 115   make distclean
 116
 117 can be used to clean the project. Project can be build for multiple
 118 BSPs when "RTEMS_MAKEFILE_PATH" is used directly as argument
 119 of "make" command. Each BSP specific build uses its separate
 120 build "_build/<bsp>" and output "_compiled/<bsp>" directory.
 121
 122 Example ORTE ping run under RTEMS
 123 =================================
 124
 125 The ORTE applications require to start "ortemanager"
 126 on each node. Manager "help" is shown when manager
 127 command is invoked in RTEMS shell
 128
 129   ortemanager -h
 130
 131 It can be started in background by
 132
 133   spawn ortemanager -e
 134
 135 If more networked nodes are used then they need to be specified
 136 when manager is started
 137
 138   spawn ortemanager -e -p 192.168.1.9 -k 192.168.1.51
 139
 140 ORTE ping publisher can be started now
 141
 142   spawn orteping -p
 143
 144 same as subscriber
 145
 146   spawn orteping -s
 147
 148 Both can be started specifying both -p and -s option.
 149 Log level can be elevated as well
 150
 151   spawn orteping -p -s -v ALL.6
 152
 153
 154 Limitations when ORTE is build and used with RTEMS
 155 ==================================================
 156
 157 The ORTE IDL compiler cannot be build to run on RTEMS
 158 (CONFIG_OC_ETH_ORTE_IDL=n). But it can be build as part
 159 of Linux build and used for RTEMS sources generation.
 160
 161 ORTE/DDS RTPS standard is based on building whole
 162 network model on each participating node. That requires
 163 considerable amount of memory. ORTE has little use
 164 for devices equipped with less than 2 or 4 MB of RAM.
 165 The situation is even worse for above describe examples
 166 because each is run as separate application and each builds
 167 its own copy of model/database (This is not a problem for
 168 real application which registers all publishers and subscribers
 169 to single domain at given node).
 170
 171 ORTE has full support for big and little endian interoperability
 172 provided by IDL and types registration. The XDR serialization
 173 and deserialization is used for all management/control communications.
 174 But orteping uses delivery of 4 byte raw content in the test
 175 without IDL or application local endianess resolution.
 176 This results in byte-reversed numbers print when test is run
 177 between nodes with different endiannes.
 178