#
#  README,v 1.3 2002/08/16 23:24:35 joel Exp
#

Building and Installing NTP
===========================

0.  Ensure that your RTEMS source has the required modifications to
    support NTP.  This involves the addition of one function and
    ensuring your BSP's 's bsp_specs support -nostdlib

       (a) adjtime() was added to RTEMS as part of this porting effort.
       You will have to add it to your RTEMS source tree or build it as
       part of your application if using an RTEMS without adjtime().
       It should be placed in the posix/src directory of the executive.
       The ntpd-demo/adjtime.c file contains the implementation that was merged
       into the RTEMS source after the 20020807 snapshot.  Any snapshot
       newer than that will have adjtime() support when posix is enabled.

       (b) Your BSP's bsp_specs file should honor -nostdlib.  No
       bsp_specs up to and including the 20020807 snapshot.  This is
       how the *lib: and *startfile: rules look in the jmr3904 BSP:

           *lib:
           %{!qrtems: %(old_lib)} %{!nostdlib: %{qrtems: --start-group \
           %{!qrtems_debug: -lrtemsbsp -lrtemscpu} \
             %{qrtems_debug: -lrtemsbsp_g -lrtemscpu_g} \
           -lc -lgcc --end-group \
           %{!qnolinkcmds: -T linkcmds%s}}}

           *startfile:
           %{!qrtems: %(old_startfile)} %{!nostdlib: %{qrtems: \
           %{!qrtems_debug: start.o%s} \
           %{qrtems_debug: start_g.o%s}}}

       Note that the "qrtems set" code is now wrapped in a "not
       no stdlibs" test.  This is logically saying that RTEMS 
       and its start.o are standard libraries and is used by the
       NTP build procedure when producing "executables".  Its
       executables are actually relocatables which can safely
       be linked in with your application.
   
1.  Build and install RTEMS for your BSP with POSIX and networking
    enabled.   The following is a prototypical command sequence that
    would be used to do this for the mips-rtems target and jmr3904 BSP.

    mkdir b-rtems
    cd b-rtems
    ..../rtems-XXX/configure --target=mips-rtems --enable-rtemsbsp=jmr3904 \
     --enable-posix --enable-networking --prefix=/opt/rtems
   make
   make install

   Once this is done, return to this directory and proceed with the
   NTP build.

   NOTE: The file dummynetcfg.c in this directory contains enough stub
   code to link one of the "executables" produced by NTP.  It was only
   used to test build ntp and should not be used in your application.

2. Set the RTEMS_MAKEFILE_PATH to point to the above BSP.

   export RTEMS_MAKEFILE_PATH=/opt/rtems/mips-rtems/jmr3904

3. Review the bit_ntp script in this directory to determine if there
   are any configure options you want to change.  NTP has a LOT of
   configuration flags and the settings are chosen to produce the 
   smallest possible ntpd binary for RTEMS.   For example, support
   for all reference clocks except the local clock is disabled as well
   as all cryptographic support.

   NOTE: Examine the prefix used as well. 


5. Execute the bit_ntp script.  It will make a b-ntp subdirectory,
   configure and build NTP in that directory, and then install NTP.

NTP builds and installs executables.  The installed "executables"
for an RTEMS build are actually relocatables which can be linked
into your application.  For the mips-rtems/jmr3904 build example,
this resulted in the following files being installed:

/opt/rtems/bin/mips-rtems-ntp-wait
/opt/rtems/bin/mips-rtems-ntpd
/opt/rtems/bin/mips-rtems-ntpdate
/opt/rtems/bin/mips-rtems-ntptimeset
/opt/rtems/bin/mips-rtems-ntpdc
/opt/rtems/bin/mips-rtems-ntpq
/opt/rtems/bin/mips-rtems-ntptrace
/opt/rtems/bin/mips-rtems-tickadj
/opt/rtems/bin/mips-rtems-ntp-genkeys

It is important to note that mips-rtems-ntp-wait is a perl program,
unuseable on an RTEMS target, and consequently removed from the
install point by the bit_ntp script.

Integrating NTP Executables Into Your Application
================================================= 
As stated above, NTP builds and "executables" which are actually
relocatables that are subsequently linked with your application.
You as the application developer are responsible for creating and
starting a "server task wrapper".  This wrapper invokes the
NTPXXXmain() "main wrapper" with the appropriate arguments.
These wrappers assume 10 (char *) pointers which are transformed
into the argc/argv arguments to the real main() for the service.
The following is a simple task wrapper for ntpd and is from
the ntpd-demo/init.c file.

rtems_task ntpd_task_wrapper(
  rtems_task_argument argument
)
{
  /* call the wrapper which takes 10 char * arguments */
  ntpd(
    NULL,  /* arg  1 */
    NULL,  /* arg  2 */
    NULL,  /* arg  3 */
    NULL,  /* arg  4 */
    NULL,  /* arg  5 */
    NULL,  /* arg  6 */
    NULL,  /* arg  7 */
    NULL,  /* arg  8 */
    NULL,  /* arg  9 */
    NULL   /* arg 10 */
 );
}

The ntpd-demo is a slightly modified version of the rtems ntp
client network demo application.  It should serve as a test
case for ntpd as well as an example of how to use the NTP services
in your application.

Joel Sherrill
joel@OARcorp.com
