$Id: README 1.4 2025/11/19 14:07:54Z martin.burnicki REL_M $

This is the README file for mbgtools-fbsd-1.4.0
-----------------------------------------------

Please send comments and required modifications
to Meinberg support <support@meinberg.de>, or to
the author, <martin.burnicki@meinberg.de>.


Contents
--------
  1.     Notes and Description
  2.     Driver Files and Programs
  3.     Installation
  3.1    Getting the Sources
  3.1.1  Cloning the Git Repository
  3.1.2  Downloading and Unpacking an Archive File
  3.2    Compiling the Driver
  3.3    Installing the Driver
  3.4    Loading the Kernel Module
  4.     Using the Driver With 'ntpd'


1. Notes and Description
------------------------
The driver package supports all PCI card types manufactured by Meinberg
which have been introduced up to the release date of the driver version.

The driver should compile fine under FreeBSD 8.1 through 14, and possibly
on older or newer versions. Supported platforms are x86 and amd64.

Please note that this driver package, unlike the Linux version, does
*not* support Meinberg USB devices.


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

Each of the user space programs can be run with parameter '-?' to show
the supported parameters.

mbgclock.ko
  A kernel module which implements the device driver and
  creates device nodes /dev/mbgclock<n>.
  Supports multiple PCI cards simultaneously, even different types.

mbgsvcd
  The Meinberg Service Daemon which needs to be started to feed the
  timestamps from the device(s) to shared memory of the NTP daemon.

  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 allows 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.

mbgstatus
  This program prints some status information for a device. The
  kind of information printed depends on the specific type of
  the card. One or more parameters '-v' increase verbosity.

mbgctrl
  This program can be used to do some basic configuration of a card.

mbgirigcfg
  This program can be used to check and configure IRIG settings of
  cards which provide an IRIG time code input or output.

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.

mbgshowsignal
  This program displays the modulation (i.e. the second marks) of a
  received longwave signal, e.g. from DCF77, if supported by the device.

mbggpscap
  This example program reads time capture events from a card's time
  capture buffer. This works only with cards that provide time capture
  inputs, and the DIP switches on those cards must have been 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 that support memory mapped I/O.
  Current PCI Express cards support this feature, but older PCI cards may
  not.

mbgxhrtime
  !! This program has not yet been fully ported to FreeBSD,
  !! and therefore, it is not yet built.
  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 Getting the Sources
-----------------------

The source code of the driver package can either be
cloned from a read-only Git repository, or downloaded
as a .tar.gz archive file.

If you are familiar with git, it's easy to clone the
git repository. The advantage is that you can easily
switch between different specific versions, or upgrade
the package.


3.1.1  Cloning the Git Repository
---------------------------------

Use the command

  git clone https://git.meinbergglobal.com/drivers/mbgtools-fbsd.git

to clone the repo to your local computer. This will
create a directory 'mbgtools-fbsd' with the current
release version of the package.

If the repo already exists, change into that directory
and run

  git pull

to upgrade to the latest version, or run the usual git
commands to checkout a different version, if preferred.


3.1.2  Downloading and Unpacking an Archive File
------------------------------------------------

A .tar.gz archive of the driver package can be downloaded
from the Meinberg git repo page at

https://git.meinbergglobal.com/drivers/mbgtools-fbsd.git

Just click on download link associated with the version
you want to download.

The current release version is also availailable via the
link on the Meinberg download page:

https://www.meinbergglobal.com/english/sw/#freebsd

Unpack the downloaded archive file using the command

  tar xvzf mbgtools-fbsd*.tar.gz

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



3.2 Compiling the Driver
------------------------
Make sure your working directory is the driver base directory.

If the driver package has already been built before, run

  make clean

first to remove old object files and binaries.


Then simply type

  make

to compile the utility programs first, then the kernel module.
If *any* error or warning messages are displayed, 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 from the device 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 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. Making Sure Programs are Loaded After Boot
---------------------------------------------

First we need to make sure that the kernel module is loaded
automatically at boot time.

Edit or create the text file /boot/loader.conf and add the
following line:

mbgclock_load="YES"


If ntpd is to use the PCI card as reference time source,
make sure the mbgsvcd daemon is started. Run the following
command to copy the service control script to the appropriate
directory:

  cp scripts/mbgsvcd /etc/rc.d/

Then edit the text file /etc/rc.conf and add the following line:

mbgsvcd_enable="YES"



5. Using the Driver With 'ntpd'
-------------------------------
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 need 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 that 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.
