path: root/README

$Id: README 1.1 2011/03/29 13:35:05 martin TEST $

This is the README file for mbgtools-fbsd-dev-2011-02-04
--------------------------------------------------------


Please send comments and required modifications to
Meinberg support <support@meinberg.de>


Contents
--------
  1.   Notes and description
  2.   Driver files and programs
  3.   Installation
  3.1  Unpacking the sources
  3.2  Compiling the driver
  3.3  Installing the driver
  3.4  Loading the kernel module
  4.   Using the driver with NTP


1. Notes and description
------------------------
This driver package has been implemented for FreeBSD 8.1
on standard PCs (i386 architecture) and on Intel/AMD 64 bit
systems (amd64 architecture).

Unless the BSD kernel API calls have changed the driver should
also work properly under earlier versions of FreeBSD. However,
other target platforms than i386 and amd64 are not yet supported.

The driver supports all PCI cards manufactured by Meinberg which
have been shipped up to the release date of this driver version.

This version of the driver package should compile fine
under FreeBSD 8.1 for kernels 2.6.x, .



2. Driver files and programs
----------------------------
mbgtools for Linux is based on Meinberg's common driver library mbglib
and implements the following programs each of which can be found in
its own subdirectory:

mbgclock.ko
  A kernel module which implements the device driver.

mbgstatus
  This program prints some status information for a device. The
  kind of information to be printed depends on the specific type
  of the card.

mbgsvcd
  This program periodically calls the kernel driver to retrieve
  time stamps of both the system time and the PCI card as close
  as possible after each other, and feeds the time stamp pairs
  into a shared memory segment compatible with the NTP daemon ntpd.
  This enables ntpd to use up to 4 PCI card(s) as refererence time
  source, if configured accordingly.

  Usually the program runs as daemon, but using the -f parameter
  it can also run in the foreground where it also prints the time
  stamps and the time differences between the system time and the
  PCI card's time on the console.

  This mode can be used to monitor how accurately the system time
  is actually disciplined, even if the system time is disciplined
  by some other means.

mbgctrl
  This program can be used to do some basic configuration of a card.
  Run mbgctrl -? to get a list of valid options.

mbgirigcfg
  This program can be used to check and configure IRIG settings of
  cards which provide an IRIG input or output.
  Type "mbgirigcfg -h" for help.

mbgsetsystime
  This program reads the time from a device and sets the system time.
  If NTP is used on a system which has an unreliable clock, this
  program can be used to set the system time initially (before the
  NTP daemon starts). The program should not be run if NTP is active
  and controls the system time since NTP achieves a higher accuracy.

mbgdcfmod
  This program displays the modulation (i.e. the second marks) of a
  received longwave signal, e.g. from DCF77.

mbggpscap
  This example program reads time capture events from a card's time
  capture buffer. This works only with cards which provide time capture
  inputs, and the DIP switches on those cards must be set up properly
  to enable time capturing.

mbghrtime
  This example program checks whether a card supports high-resolution
  time and reads those time stamps from the device, if supported.

mbgfasttstamp
  This examle program demonstrates how to read high resolution time stamps
  from a card very much faster than mbghrtime. However, this works only
  with cards which support memory mapped I/O.
  As of this writing this applies to the GPS170PEX only.

mbgxhrtime
  This example program also shows how to get time stamps faster than
  shown in mbghrtime. This is not as easy as mbgfasttstamp but can be
  used with every card which can be used with mbghrtime, even if the
  card does not support memory mapped I/O.
  The program starts a polling thread which reads a high resolution
  time stamp from the card once per second, and then uses the CPU's
  time stamp counter to extrapolate the time.
  A limitation of this approach is that the CPU's time stamp counters
  may return different values on different CPUs. So the program
  takes care to have the code executed always on the same CPU. Also,
  power saving mechanisms (Intel Speedstep, or AMD Cool'n'Quiet)
  should be disabled to prevent the extrapolated times from being
  messed up.



3. Installation
---------------

3.1 Unpacking the sources
-------------------------
Unpack the archive file using the command

  tar xvzf mbgtools-fbsd*.tar.gz

After the archive file has been unpacked cd to the base directory
that has been created corresponding to the name and version of
the package.



3.2 Compiling the driver
------------------------
If the driver package has already been built before then

  make clean

should be run first to remove old object files and binaries.

Make sure your working directory is the driver base directory and
simply type

  make

to compile the utility programs first, then the kernel module.
If *any* error or warning messages are displayed then please
report to Meinberg.



3.3 Installing the driver
-------------------------
Installation must be done as user root. Type

  make install

to copy the compiled binaries to their target directories. Programs
which only read the clock to display some information are copied to
/usr/local/bin, whereas programs which may change the device
configuration, or set the system time, are copied to /usr/local/sbin.



3.4 Loading the kernel module
-----------------------------
After the binaries have been installed the module can be loaded
for the first time. The command syntax is:

  kldload mbgclock

When the module is loaded some some startup messages are generated which
can be checked in the syslog, or using the dmesg command. If the module
was loaded successfully it should be listed if you type

  kldstat

You may try to display the device status by entering

  mbgstatus

The output shows some information on the device status,
depending on the type of the clock.

Once the module has been loaded, the other utility programs can be
used accordingly.



4. Using the driver with NTP
----------------------------
The NTP daemon can be configured to use up to 4 Meinberg PCI cards
as reference time source to discipline the system time. In order to
achieve this, ntpd needs to be configured to use its shared memory
driver (SHM, type 28).

The following entries needd to be made in the ntp.conf file
to enable support for 4 PCI cards:

  server 127.127.28.0 minpoll 4 maxpoll 4 iburst
  fudge 127.127.28.0 refid SHM0

  server 127.127.28.1 minpoll 4 maxpoll 4 iburst
  fudge 127.127.28.1 refid SHM1

  server 127.127.28.2 minpoll 4 maxpoll 4 iburst
  fudge 127.127.28.2 refid SHM2

  server 127.127.28.3 minpoll 4 maxpoll 4 iburst
  fudge 127.127.28.3 refid SHM3

Of course, only the first entry is required if only a single PCI card
is installed.

Please keep in mind the mbgsvcd program also needs to be running to feed
time stamp pairs of the system time and the PCI card's time into the
shared memory segment(s).

If the NTP daemon is already running restart it and check the syslog file
for messages generated by the daemon.

The NTP daemon shipped with a FreeBSD may have been compiled without
support for the SHM driver. If this is the case you will find a message
in the syslog saying the daemon is unable to handle 127.127.28.<n>.
In this case you need to recompile the NTP package with support
for the SHM driver.

Simply download the NTP source packge of your choice from
http://support.ntp.org

Then unpack the sources and compile the package with the usual instructions:

./configure
make
make install

By default this installs the NTP binaries under /usr/local rather than /usr/sbin,
so be sure the right instance of ntpd is started on reboot or when you run the
"service ntpd start" command.

-----------------------------------------------------------------------------------
Recompile ntpd with modified configuration (FreeBSD 5.3):

root# cd /usr/ports/net/ntp/
root# vi Makefile

Add line:
  CONFIGURE_ARGS+=        --enable-MEINBERG

root# make install clean