@c                                                  -*-Texinfo-*-
@c Contents of LynxOS datasheet or chapter.  For use as a chapter,
@c surround inclusion of this file with `@lowersections' and `@raisesections'.

@menu
* LYNXNames::	What the tools are called for LynxOS
* LYNXGCC::		Compiling for LynxOS
* LYNXGDB::		LynxOS debugging with GDB.
* LYNXLibs::	LynxOS subroutine libraries
* LYNXObjcode::	Object formats supported
* LYNXConfig::	Configuring GNU source for LynxOS
* LYNXRefs::	LynxOS documentation.
@end menu

@node LYNXNames
@chapter What to Call the Tools

Aside from considerations of @sc{cpu} architecture, there are two forms of
the Cygnus Developer's Kit tools for LynxOS systems.  You can run the
development tools @dfn{native}, that is directly on a Lynx system; or
you can run them as @dfn{cross-development} tools, using another system
as the development @dfn{host} while generating or managing code for the
Lynx @dfn{target}.

Cross-development tools in the Cygnus Developer's Kit are normally
installed with names that reflect the target machine, so that you can
install more than one set of tools in the same binary directory.  Native
tools, on the other hand, are called by simple names like @code{gcc}
(the compiler) or @code{gdb} (the debugger).

@heading Native development

On native configurations, you still need to be careful that your
execution path is set up to get the right @emph{versions} of the
development tools.  For example, LynxOS itself is distributed with
@file{/bin/gcc} installed---but that's a very old release (version 1) of
GNU CC.  The tools from the Cygnus Developer's Kit are normally
installed so that you can find them in @file{/usr/progressive/bin}.
(See the Cygnus @cite{Installation Notes} for LynxOS 2.2, for details on
how to set up the Cygnus Developer's Kit installation, and suggestions
to keep execution paths simple.) For example, you should get output like
this from the system utility @code{which}:

@cartouche
@example
$ which gcc
/usr/progressive/bin/gcc
@end example
@end cartouche

@noindent
You can also run GNU CC with the @samp{-v} option to make sure you're
running a version 2 compiler.

@heading Cross development

The tool names for cross-development are constructed by using, as a
prefix, the name of the configured target (i.e., the string specified
with @w{@samp{--target}} to the @code{configure} script).  For example, the
cross-compiler for LynxOS is called:

@table @code
@c SPARC coming 94q1
@item i386-lynx-gcc
@i{If configured to generate code for Intel 386 architectures.}

@item m68k-lynx-gcc
@i{If configured to generate code for Motorola 680x0 architectures.}

@item sparc-lynx-gcc
@i{If configured to generate code for @sc{sparc} architectures.}
@end table

@node LYNXGCC
@chapter Compiling for LynxOS

The @sc{gnu} compiler has a variety of options to cover many needs.  This
note discusses the options specifically intended for use with LynxOS.
For information on all the @sc{gcc} command-line options, see @ref{Invoking
GCC,,GNU CC Command Options,gcc.info,Using GNU CC}.

@menu
* LYNXInvoking GCC::	Compiler options for LynxOS.
* LYNXDefaults::		Default options for your environment.
* LYNXCPP::			Predefined preprocessor macros.
@end menu

@node LYNXInvoking GCC
@section Compiler options for LynxOS

When you run @sc{gcc}, you can use these command-line options to choose some
details specific to LynxOS.  There are also compiler options specific to
the machine architecture; see @ref{M680x0 Options,,M680x0 Options,
gcc.info, Using GNU CC}, and @ref{i386 Options,,Intel 386 Options,
gcc.info, Using GNU CC}.

@table @code
@item -mposix
Use the Posix-compatible version of the Lynx C library, and define the
preprocessor macro @w{@code{_POSIX_SOURCE}}.  (This is similar to the
effect of @samp{-X} with version 1 of @sc{gcc} as distributed with LynxOS.)

@item -msystem-v
Use this option for backward compatibility: it selects header files and
libraries compatible with Unix System V release 3, and marks the output
files with a ``magic number'' that identifies them as System V compatible.
(This is similar to the effect of @samp{-V} with version 1 of @sc{gcc} as
distributed with LynxOS.)

@emph{Warning:} if you use this option, you may not use
@w{@samp{-mthreads}}, @w{@samp{-p}}, or @w{@samp{-pg}}.  If you specify
@w{@samp{-mposix}} together with @w{@samp{-msystem-v}}, @w{@samp{-mposix}} is
ignored.

@item -mthreads
Use alternate versions of system libraries that support multi-thread
programming, and define the preprocessor macro
@w{@code{_MULTITHREADED}}.  (This is similar to the effect of @samp{-m}
with version 1 of @sc{gcc} as distributed with LynxOS.)
@end table

In the older version of @sc{gcc} distributed with LynxOS, there was also
a @samp{-k} option to specify @sc{coff} object format.  No option is
needed for this purpose with the Cygnus Developer's Kit version of the
compiler, since the output format is always @sc{coff}.

@node LYNXDefaults
@section Default options for your environment

If you always invoke @sc{gcc} with a particular combination of options, you
can collect these options in the environment variable
@w{@code{GCC_DEFAULT_OPTIONS}} instead of listing them on the command line
each time.@footnote{The Cygnus tools do @emph{not} recognize these
environment variables used by older ports of the @sc{gnu} tools to
LynxOS: @code{COFFLD}, @code{SYSVCC}, @code{POSIXCC}.}

@c example intentionally omitted, since we don't really want people to
@c use this.

@emph{Warning:} The compiler developers at Cygnus recommend you
@emph{avoid} this environment variable, since it adds one more layer of
complexity to using the compiler.  In particular, its use may lead to
these problems:

@enumerate
@item The relative order of these options must be fixed, and will always
be wrong for some purposes.  With the current implementation, options
from @w{@code{GCC_DEFAULT_OPTIONS}} are always first on the command line
(so that you can override them).  This means that you cannot usefully
include library options (such as @w{@samp{-lm}}), since you need to put them
at the end of the command line.

@item If you set the environment variable and forget about it, the
compiler's behavior may be mysterious.

@item Bugreports may take longer to resolve, since the environment
variable setting is one more important datum that may be accidentally
omitted from bug reports.
@end enumerate

@node LYNXCPP
@section Predefined preprocessor macros

@sc{gcc} defines the following preprocessor macros for LynxOS
configurations:

@table @emph
@item Any LynxOS system:
@code{unix}, @code{__unix__}, @code{__unix}, @code{Lynx},
@code{__Lynx__}, @code{__Lynx}, @code{IBITS32}, @code{__IBITS32__},
@code{__IBITS32}

@item Motorola 680x0 systems:
@code{mc68000}, @code{M68K}, @code{__mc68000__}, @code{__M68K__},
@code{__mc68000}, @code{__M68K}
@c asserts: -Asystem(unix) -Asystem(lynx) -Acpu(m68k) -Amachine(m68k)

@item Intel 80x86 systems:
@code{i386}, @code{I386}, @code{__i386__},
@code{__I386__}, @code{__i386}, @code{__I386},

@item SPARC systems:
@code{sparc}, @code{__sparc__}, @code{__sparc}
@end table

@node LYNXGDB
@chapter LynxOS Debugging with GDB

Two aspects of using the @sc{gnu} debugger can differ significantly on LynxOS
from many other systems.  First, you can debug multithread programs;
second, you may want to use the @code{gdbserver} program for
cross-debugging.

@menu
* LYNXThreads::	Multithread debugging on LynxOS
* LYNXServer::	Cross debugging with gdbserver
@end menu

@node LYNXThreads
@section Multithread debugging on LynxOS

@sc{gdb} provides these facilities for debugging multi-thread programs:

@itemize @bullet
@item automatic notification of new threads
@item @samp{thread @var{threadno}}, a command to switch among threads
@item @samp{info threads}, a command to inquire about existing threads
@item thread-specific breakpoints
@end itemize

The @sc{gdb} thread debugging facility allows you to observe all
threads while your program runs---but whenever @sc{gdb} takes
control, one thread in particular is always the focus of debugging.
This thread is called the @dfn{current thread}.  Debugging commands show
program information from the perspective of the current thread.

Whenever @sc{gdb} detects a new thread in your program, it displays
the LynxOS identification for it with a message like this:

@example
[New process 35 thread 27]
@end example

@menu
* LYNXSwitching Threads::		Switching and inquiring on threads
* LYNXBreakpoints::			Breakpoint features for threads
* LYNXWatchpoints::			Watchpoint limitations for threads
@end menu

@node LYNXSwitching Threads
@subsection Switching and inquiring on threads

For debugging purposes, @sc{gdb} associates its own thread
number---always a single integer---with each thread in your program.

@table @code
@item info threads
Display a summary of all threads currently in your
program.  @sc{gdb} displays for each thread (in this order):

@enumerate
@item the thread number assigned by @sc{gdb}

@item the system's thread identifier

@item the current stack frame summary for that thread
@end enumerate

@noindent
An asterisk @samp{*} to the left of the @sc{gdb} thread number
indicates the current thread.

For example, 

@cartouche
@smallexample
(gdb) info threads
  3 process 35 thread 27  0x34e5 in sigpause ()
  2 process 35 thread 23  0x34e5 in sigpause ()
* 1 process 35 thread 13  main (argc=1, argv=0x7ffffff8)
    at threadtest.c:68
@end smallexample
@end cartouche

@item thread @var{threadno}
Make thread number @var{threadno} the current thread.  The command
argument @var{threadno} is the internal @sc{gdb} thread number, as
shown in the first field of the @samp{info threads} display.
@sc{gdb} responds by displaying the system identifier of the thread
you selected, and its current stack frame summary:

@cartouche
@smallexample
(gdb) thread 2
[Switching to process 35 thread 23]
0x34e5 in sigpause ()
@end smallexample
@end cartouche
@end table

Whenever @sc{gdb} stops your program, due to a breakpoint or a
signal, it automatically selects the thread where that breakpoint or
signal happened.  @sc{gdb} alerts you to the context switch with a
message of the form @samp{[Switching to process @var{n} thread @var{m}]}
to identify the thread.

@node LYNXBreakpoints
@subsection Breakpoint features for LynxOS threads

You can choose whether to set breakpoints on all threads, or on a
particular thread of your program.

@table @code
@item break @var{linespec} thread @var{threadno}
@itemx break @var{linespec} thread @var{threadno} if @dots{}
Use the qualifier @samp{thread @var{threadno}} with a breakpoint command
to specify that you only want @sc{gdb} to stop the program when a
particular thread reaches this breakpoint.  @var{threadno} is one of
@sc{gdb}'s numeric thread identifiers, shown in the first column of
the @samp{info threads} display.

If you do not specify @samp{thread @var{threadno}} when you set a
breakpoint, the breakpoint applies to @emph{all} threads of your
program.

You can use the @code{thread} qualifier on conditional breakpoints as
well; in this case, place @samp{thread @var{threadno}} before the
breakpoint condition, like this:

@cartouche
@smallexample
(gdb) break frik.c:13 thread 28 if bartab > lim
@end smallexample
@end cartouche
@end table

Whenever your program stops under @sc{gdb} for any reason, @emph{all} threads
of execution stop, not just the current thread.  This allows you to
examine the overall state of the program, and to switch between threads,
without worrying that things may change underfoot.

Conversely, whenever you restart the program, @emph{all} threads start
executing.  @emph{This is true even when single-stepping} with commands
like @code{step} or @code{next}.

In particular, @sc{gdb} cannot single-step all threads in lockstep.  Since
thread scheduling is up to LynxOS, rather than controlled by @sc{gdb}, other
threads may execute more than one statement while the current thread
completes a single step.  Moreover, in general other threads stop in the
middle of a statement, rather than at a clean statement boundary, when
the program stops.

You might even find your program stopped in another thread after
continuing or even single-stepping.  This happens whenever some other
thread runs into a breakpoint, a signal, or an exception before the
first thread completes whatever you requested.

@node LYNXWatchpoints
@subsection Watchpoint limitations for LynxOS threads

@emph{Warning:} in multi-thread programs, watchpoints have only limited
usefulness.  With the current watchpoint implementation, @sc{gdb}
can only watch the value of an expression @emph{in a single thread}.  If
you are confident that the expression can only change due to the current
thread's activity (and if you are also confident that the same thread
will remain current), then you can use watchpoints as usual.  However,
@sc{gdb} may not notice when a non-current thread's activity changes
the expression.

@node LYNXServer
@section Cross debugging with @code{gdbserver}

When a LynxOS system is configured for production real-time use, the
tradeoffs required may make it more convenient to do as much development
work as possible on another system, for example by cross-compiling.  You
can make a similar choice with the @sc{gnu} debugger, using an auxiliary
program called @code{gdbserver}.

@code{gdbserver} is a control program for Unix-like systems, which
allows you to connect your LynxOS program with a @sc{gdb} that runs on
another machine.  On the remote machine, you use the @sc{gdb} command
@code{target remote} to connect to the LynxOS system.
@footnote{@code{target remote} is otherwise used to debug bare-board
systems, in which case it requires linking in special @dfn{stub}
subroutines with your programs; with @code{gdbserver}, no such special
stubs are needed.}

@sc{gdb} and @code{gdbserver} communicate via either a serial line
or a @sc{tcp} connection, using the standard @sc{gdb} remote serial
protocol.

@table @emph
@item On the LynxOS (target) machine,
you need to have a copy of the program you want to debug.
@code{gdbserver} does not need your program's symbol table, so you can
strip the program if necessary to save space.  @sc{gdb} on the host
system does all the symbol handling.

To use the server, you must tell it how to communicate with @sc{gdb};
the name of your program; and the arguments for your program.  The
syntax is:

@smallexample
target> gdbserver @var{comm} @var{program} [ @var{args} @dots{} ]
@end smallexample

@var{comm} is either a device name (to use a serial line) or a @sc{tcp}
hostname and portnumber.  For example, to debug Emacs with the argument
@samp{foo.txt} and communicate with @sc{gdb} over the serial port
@file{/dev/com1}:

@smallexample
target> gdbserver /dev/com1 emacs foo.txt
@end smallexample

@noindent
@code{gdbserver} waits passively for the host @sc{gdb} to communicate
with it.

To use a @sc{tcp} connection instead of a serial line:

@smallexample
target> gdbserver host:2345 emacs foo.txt
@end smallexample

The only difference from the first example is the first argument,
specifying that you are communicating with the host @sc{gdb} via
@sc{tcp}.  The @samp{host:2345} argument means that @code{gdbserver} is
to expect a @sc{tcp} connection from machine @samp{host} to local
@sc{tcp} port 2345.  (Currently, the @samp{host} part is ignored.)  You
can choose any number you want for the port number as long as it does
not conflict with any @sc{tcp} ports already in use on the target system
(for example, @code{23} is reserved for @code{telnet}. If you choose a
port number that conflicts with another service, @code{gdbserver} prints
an error message and exits). You must use the same port number with the
host @sc{gdb} @code{target remote} command.

@item On the host,
you need an unstripped copy of your program, since @sc{gdb} needs symbols and
debugging information.  Start up @sc{gdb} as usual, using the name of the
local copy of your program as the first argument.  (You may also need
the @w{@samp{--baud}} option if the serial line is running at anything other
than 9600 bps.)  After that, use @code{target remote} to establish
communications with @code{gdbserver}.  Its argument is either a device
name (usually a serial device, like @file{/dev/ttyb}), or a @sc{tcp} port
descriptor in the form @code{@var{host}:@var{port}}.  For example:

@smallexample
(gdb) target remote /dev/ttyb
@end smallexample

@noindent
communicates with the server via serial line @file{/dev/ttyb}, and

@smallexample
(gdb) target remote the-target:2345
@end smallexample

@noindent
communicates via a @sc{tcp} connection to port 2345 on host
@w{@file{the-target}}.  For @sc{tcp} connections, you must start up
@code{gdbserver} prior to using the @code{target remote} command.
Otherwise you may get an error whose text depends on the host system,
but which usually looks something like @samp{Connection refused}.
@end table

@node LYNXLibs
@chapter LynxOS Subroutine Libraries

One of the major effects of the compiler command-line options
@samp{-mposix}, @samp{-msystem-v}, and @samp{-mthreads} is to choose
versions of the C subroutine libraries.

The compiler links by default with the standard Cygnus C subroutine
library.
@ifinfo
@xref{Top,,The Cygnus C Support Library,The Cygnus C Support Library,
libc.info}, for details on that library.
@end ifinfo
@iftex
See @cite{The Cygnus C Support Library} for details on that library.
@end iftex
Since LynxOS is a complete system, however, you have no need to define
``stub'' routines (@pxref{Syscalls,,System Calls, libc.info, The Cygnus
C Support Library}); LynxOS provides the necessary system calls.

Your Cygnus Developer's Kit also includes a mathematical subroutine
library.
@ifinfo
@xref{Top,,LIBM,The Cygnus Mathematical C Library, libm.info}, for
details.
@end ifinfo
See @cite{The Cygnus C Math Library} for more information.

If you specify @samp{-msystem-v}, the compiler does @emph{not} use the
Cygnus libraries; instead, your code links with the LynxOS System V.3
compatibility library.

If you specify @samp{-mposix}, you get @emph{both} Posix-compatible subroutine
libraries from LynxOS, and the standard Cygnus libraries.  The Posix
compatibility library overrides the Cygnus library for any subroutines
present in both.

@quotation
@emph{Warning:} None of these libraries are called @file{libc.a}, but
LynxOS does ship with an older library (still present for compatibility)
with that name.  This means that @emph{if you specify @samp{-lc}
explicitly, you should specify it last} on the compiler's command line.
You may not need @samp{-lc} at all, but some LynxOS releases include
additional subroutines for special purposes in this library.
@end quotation

In most situations, you should use one of the @samp{-m} options rather
than specifying the libraries directly with @samp{-l}.  However, if you
must insert your own library to override some of the system or Cygnus
libraries, you may have to specify the equivalent series of @samp{-l}
commands explicitly.  Here are the equivalences:

@c FIXME!! Check appearance of this carefully.  Might be worth an @tex
@c \halign table.
@table @code
@item @emph{default}
For consistency with the libraries used by default (with no @samp{-m}
options), specify these libraries.  The @samp{stdc} and @samp{stdm}
libraries are the Cygnus C library and the Cygnus mathematical
subroutine library, respectively.

@example
-llynx -lstdc -lstdm -lstub
@end example

@item -mposix
If you want the Posix compliant library, use a library list like this to
allow the @samp{posix1} library to override parts of the Cygnus
libraries:

@example
-llynx -lposix1 -lstdc -lstdm -lstub
@end example

@item -msystem-v
For the System V release 3 compatible library, use @samp{-lc_v}.

@item -mthreads
This option does not imply additional libraries; instead, it uses an
alternate library search path to find different versions of the same
libraries.
@end table

@node LYNXObjcode
@chapter Object formats supported

The @sc{gnu} compiler and assembler produce @sc{coff} format object code for
the standard Lynx configurations.  However, since older LynxOS tools
generated a.out object code, the linker, debugger, and binary utilities
are still able to read a.out object code format.  This allows you
to use and manage older libraries and object modules, and even to debug
older complete programs, regardless of the change in object code format.

@node LYNXConfig
@chapter Configuring GNU source for LynxOS

Your Cygnus Developer's Kit includes precompiled, ready-to-run binaries,
with all defaults configured for your LynxOS system.

However, you may have occasion to reconfigure or rebuild the source.
For example, you may want to rebuild after receiving a bugfix in
source-patch form.

You can use the script @code{configure} to specify many prearranged
kinds of variations in the source.  @xref{Rebuilding,, Rebuilding From
Source, release.info, Release Notes}, for a discussion of the source
configuration process.

To configure for the LynxOS environment, you should use one of these
@code{configure} options:

@c FIXME! eventual sparc target

@table @code
@item --target=i386-lynx
To build code for LynxOS on Intel 386-based systems.

@item --target=m68k-lynx
To build code for LynxOS on MVME147 or MVME167 boards.

@item --target=sparc-lynx
To build code for LynxOS on @sc{sparc}-based systems.
@end table

@emph{Warning:} The Free Software Foundation's Internet distributions of
@sc{gcc} support another Lynx configuration, because the @sc{gcc}
distribution is available independently of the other @sc{gnu} tools.
If you configure and rebuild @sc{gcc} alone, also specify these options
to @code{configure}:

@table @code
@item --with-gnu-as
Allow @sc{gcc} to generate code suitable for the current @sc{gnu}
assembler, rather than restricting its output to the assembler found on
LynxOS by default.

@item --with-gnu-ld
Allow @sc{gcc} to use the current @sc{gnu} linker, rather than the
linker found on LynxOS by default.
@end table

@noindent
If you reconfigure and rebuild the entire tool chain as distributed by
Cygnus, rather than @sc{gcc} alone, these two options are applied to the
compiler configuration automatically.

@node LYNXRefs
@chapter LynxOS Documentation

For general information about programming in LynxOS, see the
@cite{LynxOS Application Writer's Guide}.

For compatibility information about the alternative subroutine libraries
on your LynxOS system, see the ``Unix Compatibility'' chapter in
@cite{LynxOS User's Manual: Volume 2, Supplementary Guides & Documents}.

Both documents are available from Lynx Real-Time Systems Inc., 16780
Lark Ave., Los Gatos, California 95030.
