packages/hal/synth/arch/v2_0/doc/synth-install.html

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