doc/html/ref/synth-install.html

   1 <!-- Copyright (C) 2003 Red Hat, Inc.                                -->
   2 <!-- This material may be distributed only subject to the terms      -->
   3 <!-- and conditions set forth in the Open Publication License, v1.0  -->
   4 <!-- or later (the latest version is presently available at          -->
   5 <!-- http://www.opencontent.org/openpub/).                           -->
   6 <!-- Distribution of the work or derivative of the work in any       -->
   7 <!-- standard (paper) book form is prohibited unless prior           -->
   8 <!-- permission is obtained from the copyright holder.               -->
   9 <HTML
  10 ><HEAD
  11 ><TITLE
  12 >Installation</TITLE
  13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
  14 <META
  15 NAME="GENERATOR"
  16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
  17 "><LINK
  18 REL="HOME"
  19 TITLE="eCos Reference Manual"
  20 HREF="ecos-ref.html"><LINK
  21 REL="UP"
  22 TITLE="eCos Synthetic Target"
  23 HREF="hal-synth-arch.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="Overview"
  26 HREF="synth.html"><LINK
  27 REL="NEXT"
  28 TITLE="Running a Synthetic Target Application"
  29 HREF="synth-running.html"></HEAD
  30 ><BODY
  31 CLASS="REFENTRY"
  32 BGCOLOR="#FFFFFF"
  33 TEXT="#000000"
  34 LINK="#0000FF"
  35 VLINK="#840084"
  36 ALINK="#0000FF"
  37 ><DIV
  38 CLASS="NAVHEADER"
  39 ><TABLE
  40 SUMMARY="Header navigation table"
  41 WIDTH="100%"
  42 BORDER="0"
  43 CELLPADDING="0"
  44 CELLSPACING="0"
  45 ><TR
  46 ><TH
  47 COLSPAN="3"
  48 ALIGN="center"
  49 >eCos Reference Manual</TH
  50 ></TR
  51 ><TR
  52 ><TD
  53 WIDTH="10%"
  54 ALIGN="left"
  55 VALIGN="bottom"
  56 ><A
  57 HREF="synth.html"
  58 ACCESSKEY="P"
  59 >Prev</A
  60 ></TD
  61 ><TD
  62 WIDTH="80%"
  63 ALIGN="center"
  64 VALIGN="bottom"
  65 ></TD
  66 ><TD
  67 WIDTH="10%"
  68 ALIGN="right"
  69 VALIGN="bottom"
  70 ><A
  71 HREF="synth-running.html"
  72 ACCESSKEY="N"
  73 >Next</A
  74 ></TD
  75 ></TR
  76 ></TABLE
  77 ><HR
  78 ALIGN="LEFT"
  79 WIDTH="100%"></DIV
  80 ><H1
  81 ><A
  82 NAME="SYNTH-INSTALL">Installation</H1
  83 ><DIV
  84 CLASS="REFNAMEDIV"
  85 ><A
  86 NAME="AEN17701"
  87 ></A
  88 ><H2
  89 >Name</H2
  90 >Installation&nbsp;--&nbsp;Preparing to use the synthetic target</DIV
  91 ><DIV
  92 CLASS="REFSECT1"
  93 ><A
  94 NAME="SYNTH-INSTALL-HOST"
  95 ></A
  96 ><H2
  97 >Host-side Software</H2
  98 ><P
  99 >To get the full functionality of the synthetic target, users must
 100 build and install the I/O auxiliary ecosynth and various support
 101 files. It is possible to develop applications for the synthetic target
 102 without the auxiliary, but only limited I/O facilities will be
 103 available. The relevant code resides in the <TT
 104 CLASS="FILENAME"
 105 >host</TT
 106 > subdirectory of the synthetic target
 107 architectural HAL package, and building it involves the standard
 108 <B
 109 CLASS="COMMAND"
 110 >configure</B
 111 >, <B
 112 CLASS="COMMAND"
 113 >make</B
 114 >, and
 115 <B
 116 CLASS="COMMAND"
 117 >make install</B
 118 > steps.
 119     </P
 120 ><P
 121 >There are two main ways of building the host-side software. It is
 122 possible to build both the generic host-side software and all
 123 package-specific host-side software, including the I/O auxiliary. in a
 124 single build tree. This involves using the
 125 <B
 126 CLASS="COMMAND"
 127 >configure</B
 128 > script at the toplevel of the eCos
 129 repository, which will automatically search the <TT
 130 CLASS="FILENAME"
 131 >packages</TT
 132 > hierarchy for host-side
 133 software. For more information on this, see the
 134 <TT
 135 CLASS="FILENAME"
 136 >README.host</TT
 137 > file at the top of the repository.
 138 Note that if you have an existing build tree which does not include
 139 the synthetic target architectural HAL package then it will be
 140 necessary to rerun the toplevel configure script: the search for
 141 appropriate packages happens at configure time.
 142     </P
 143 ><P
 144 >The alternative is to build just the host-side for this package.
 145 This involves creating a suitable build directory and running the
 146 <B
 147 CLASS="COMMAND"
 148 >configure</B
 149 > script. Note that building directly in
 150 the source tree is not allowed.
 151     </P
 152 ><TABLE
 153 BORDER="5"
 154 BGCOLOR="#E0E0F0"
 155 WIDTH="70%"
 156 ><TR
 157 ><TD
 158 ><PRE
 159 CLASS="SCREEN"
 160 >$ cd &lt;somewhere suitable&gt;
 161 $ mkdir synth_build
 162 $ cd synth_build
 163 $ &lt;repo&lt;&gt;/packages/hal/synth/arch/&lt;version&gt;/host/configure &lt;options&gt;
 164 $ make
 165 $ make install</PRE
 166 ></TD
 167 ></TR
 168 ></TABLE
 169 ><P
 170 >The code makes extensive use of Tcl/TK and requires version 8.3 or
 171 later. This is checked by the <B
 172 CLASS="COMMAND"
 173 >configure</B
 174 > script. By
 175 default it will use the system's Tcl installation in <TT
 176 CLASS="FILENAME"
 177 >/usr</TT
 178 >. If a different, more recent Tcl
 179 installation should be used then its location can be specified using
 180 the options <TT
 181 CLASS="OPTION"
 182 >--with-tcl=&lt;path&gt;</TT
 183 >,
 184 <TT
 185 CLASS="OPTION"
 186 >--with-tcl-header=&lt;path&gt;</TT
 187 > and
 188 <TT
 189 CLASS="OPTION"
 190 >--with-tcl-lib=&lt;path&gt;</TT
 191 >. For more information on these options
 192 see the <TT
 193 CLASS="FILENAME"
 194 >README.host</TT
 195 > file at the toplevel of the
 196 eCos repository.
 197     </P
 198 ><P
 199 >Some users may also want to specify the install location using a
 200 <TT
 201 CLASS="OPTION"
 202 >--prefix=&lt;path&gt;</TT
 203 > option. The default install
 204 location is <TT
 205 CLASS="FILENAME"
 206 >/usr/local</TT
 207 >. It is
 208 essential that the <TT
 209 CLASS="FILENAME"
 210 >bin</TT
 211 >
 212 subdirectory of the install location is on the user's search
 213 <TT
 214 CLASS="ENVAR"
 215 >PATH</TT
 216 >, otherwise the eCos application will be unable to
 217 locate and execute the I/O auxiliary ecosynth.
 218     </P
 219 ><P
 220 >Because ecosynth is run automatically by an eCos application rather
 221 than explicitly by the user, it is not installed in the <TT
 222 CLASS="FILENAME"
 223 >bin</TT
 224 > subdirectory itself. Instead it is
 225 installed below <TT
 226 CLASS="FILENAME"
 227 >libexec</TT
 228 >,
 229 together with various support files such as images. At configure time
 230 it is usually possible to specify an alternative location for
 231 <TT
 232 CLASS="FILENAME"
 233 >libexec</TT
 234 > using
 235 <TT
 236 CLASS="OPTION"
 237 >--exec-prefix=&lt;path&gt;</TT
 238 > or
 239 <TT
 240 CLASS="OPTION"
 241 >--libexecdir=&lt;path&gt;</TT
 242 >. These options should not
 243 be used for this package because the eCos application is built
 244 completely separately and does not know how the host-side was
 245 configured.
 246     </P
 247 ></DIV
 248 ><DIV
 249 CLASS="REFSECT1"
 250 ><A
 251 NAME="SYNTH-TOOLS"
 252 ></A
 253 ><H2
 254 >Toolchain</H2
 255 ><P
 256 >When developing eCos applications for a normal embedded target it is
 257 necessary to use a suitable cross-compiler and related tools such as
 258 the linker. Developing for the synthetic target is easier because you
 259 can just use the standard GNU tools (gcc, g++, ld, &#8230;) which
 260 were provided with your Linux distribution, or which you used to build
 261 your own Linux setup. Any reasonably recent version of the tools, for
 262 example gcc 2.96(Red Hat) as shipped with Red Hat Linux 7, should be
 263 sufficient.
 264     </P
 265 ><P
 266 >There is one important limitation when using these tools: current gdb
 267 will not support debugging of eCos threads on the synthetic target. As
 268 far as gdb is concerned a synthetic target application is
 269 indistinguishable from a normal Linux application, so it assumes that
 270 any threads will be created by calls to the Linux
 271 <TT
 272 CLASS="FUNCTION"
 273 >pthread_create</TT
 274 > function provided by the C
 275 library. Obviously this is not the case since the application is never
 276 linked with that library. Therefore gdb never notices the eCos thread
 277 mechanisms and assumes the application is single-threaded. Fixing this
 278 is possible but would involve non-trivial changes to gdb.
 279     </P
 280 ><P
 281 >Theoretically it is possible to develop synthetic target applications
 282 on, for example, a PC running Windows and then run the resulting
 283 executables on another machine that runs Linux. This is rarely useful:
 284 if a Linux machine is available then usually that machine will also be
 285 used for building ecos and the application. However, if for some
 286 reason it is necessary or desirable to build on another machine then
 287 this requires a suitable cross-compiler and related tools. If the
 288 application will be running on a typical PC with an x86 processor then
 289 a suitable configure triplet would be
 290 <TT
 291 CLASS="USERINPUT"
 292 ><B
 293 >i686-pc-linux-gnu</B
 294 ></TT
 295 >. The installation
 296 instructions for the various GNU tools should be consulted for further
 297 information.
 298     </P
 299 ></DIV
 300 ><DIV
 301 CLASS="REFSECT1"
 302 ><A
 303 NAME="SYNTH-HARDWARE"
 304 ></A
 305 ><H2
 306 >Hardware Preparation</H2
 307 ><P
 308 >Preparing a real embedded target for eCos development can be tricky.
 309 Often the first step is to install suitable firmware, usually RedBoot.
 310 This means creating and building a special configuration for eCos with
 311 the RedBoot template, then somehow updating the target's flash chips
 312 with the resulting RedBoot image. Typically it will also be necessary
 313 to get a working serial connection, and possibly set up ethernet as
 314 well. Although usually none of the individual steps are particularly
 315 complicated, there are plenty of ways in which things can go wrong and
 316 it can be hard to figure out what is actually happening. Of course
 317 some board manufacturers make life easier for their developers by
 318 shipping hardware with RedBoot preinstalled, but even then it is still
 319 necessary to set up communication between host and target.
 320     </P
 321 ><P
 322 >None of this is applicable to the synthetic target. Instead you can
 323 just build a normal eCos configuration, link your application with the
 324 resulting libraries, and you end up with an executable that you can
 325 run directly on your Linux machine or via gdb. A useful side effect of
 326 this is that application development can start before any real
 327 embedded hardware is actually available.
 328     </P
 329 ><P
 330 >Typically the memory map for a synthetic target application will be
 331 set up such that there is a read-only ROM region containing all the
 332 code and constant data, and a read-write RAM region for the data. The
 333 default locations and sizes of these regions depend on the specific
 334 platform being used for development. Note that the application always
 335 executes out of ROM: on a real embedded target much of the development
 336 would involve running RedBoot firmware there, with application code
 337 and data loaded into RAM; usually this would change for the final
 338 system; the firmware would be replaced by the eCos application itself,
 339 configured for ROM bootstrap, and it would perform the appropriate
 340 hardware initialization. Therefore the synthetic target actually
 341 emulates the behaviour of a final system, not of a development
 342 environment. In practice this is rarely significant, although having
 343 the code in read-only memory can help catch some problems in
 344 application code.
 345     </P
 346 ></DIV
 347 ><DIV
 348 CLASS="NAVFOOTER"
 349 ><HR
 350 ALIGN="LEFT"
 351 WIDTH="100%"><TABLE
 352 SUMMARY="Footer navigation table"
 353 WIDTH="100%"
 354 BORDER="0"
 355 CELLPADDING="0"
 356 CELLSPACING="0"
 357 ><TR
 358 ><TD
 359 WIDTH="33%"
 360 ALIGN="left"
 361 VALIGN="top"
 362 ><A
 363 HREF="synth.html"
 364 ACCESSKEY="P"
 365 >Prev</A
 366 ></TD
 367 ><TD
 368 WIDTH="34%"
 369 ALIGN="center"
 370 VALIGN="top"
 371 ><A
 372 HREF="ecos-ref.html"
 373 ACCESSKEY="H"
 374 >Home</A
 375 ></TD
 376 ><TD
 377 WIDTH="33%"
 378 ALIGN="right"
 379 VALIGN="top"
 380 ><A
 381 HREF="synth-running.html"
 382 ACCESSKEY="N"
 383 >Next</A
 384 ></TD
 385 ></TR
 386 ><TR
 387 ><TD
 388 WIDTH="33%"
 389 ALIGN="left"
 390 VALIGN="top"
 391 >Overview</TD
 392 ><TD
 393 WIDTH="34%"
 394 ALIGN="center"
 395 VALIGN="top"
 396 ><A
 397 HREF="hal-synth-arch.html"
 398 ACCESSKEY="U"
 399 >Up</A
 400 ></TD
 401 ><TD
 402 WIDTH="33%"
 403 ALIGN="right"
 404 VALIGN="top"
 405 >Running a Synthetic Target Application</TD
 406 ></TR
 407 ></TABLE
 408 ></DIV
 409 ></BODY
 410 ></HTML
 411 >