PageRenderTime 25ms CodeModel.GetById 11ms app.highlight 7ms RepoModel.GetById 1ms app.codeStats 0ms

/contrib/ntp/html/parsenew.html

https://bitbucket.org/freebsd/freebsd-head/
HTML | 198 lines | 175 code | 23 blank | 0 comment | 0 complexity | b65b71828a47d9c80405aa30b031727d MD5 | raw file
  1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
  2
  3<html>
  4
  5	<head>
  6		<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
  7		<title>Making PARSE Clocks</title>
  8		<link href="scripts/style.css" type="text/css" rel="stylesheet">
  9	</head>
 10
 11	<body>
 12		<h3>How to build new PARSE clocks</h3>
 13		<p>Here is an attempt to sketch out what you need to do in order to add another clock to the parse driver: Currently the implementation is being cleaned up - so not all information in here is completely correct. Refer to the included code where in doubt.</p>
 14		<p>Prerequisites:</p>
 15		<ul>
 16			<li>Does the system you want the clock connect to have the include files termio.h or termios.h ? (You need that for the parse driver)
 17		</ul>
 18		<p>What to do:</p>
 19		<p>Make a conversion module (libparse/clk_*.c)</p>
 20		<ol>
 21			<li>What ist the time code format ?
 22				<ul>
 23					<li>find year, month, day, hour, minute, second, status (synchronised or not), possibly time zone information (you need to give the offset to UTC) You will have to convert the data from a string into a struct clocktime:
 24						<pre>
 25      struct clocktime                /* clock time broken up from time code */
 26      {
 27	long day;
 28	long month;
 29	long year;
 30	long hour;
 31	long minute;
 32	long second;
 33	long usecond;
 34	long utcoffset;       /* in seconds */
 35	time_t utcoffset;     /* true utc time instead of date/time */
 36	long flags;           /* current clock status */
 37      };
 38</pre>
 39						<p>Conversion is usually simple and straight forward. For the flags following values can be OR'ed together:</p>
 40						<pre>
 41     PARSEB_ANNOUNCE           switch time zone warning (informational only)
 42     PARSEB_POWERUP            no synchronisation - clock confused (must set then)
 43     PARSEB_NOSYNC             timecode currently not confirmed (must set then)
 44                               usually on reception error when there is still a
 45                               chance the the generated time is still ok.
 46
 47     PARSEB_DST                DST in effect (informational only)
 48     PARSEB_UTC                timecode contains UTC time (informational only)
 49     PARSEB_LEAPADD            LEAP addition warning (prior to leap happening - must set when imminent)
 50			       also used for time code that do not encode the
 51			       direction (as this is currently the default).
 52     PARSEB_LEAPDEL            LEAP deletion warning (prior to leap happening - must set when imminent)
 53     PARSEB_ALTERNATE          backup transmitter (informational only)
 54     PARSEB_POSITION           geographic position available (informational only)
 55     PARSEB_LEAPSECOND         actual leap second (this time code is the leap
 56                               second - informational only)
 57</pre>
 58						<p>These are feature flags denoting items that are supported by the clock:</p>
 59						<pre>
 60     PARSEB_S_LEAP             supports LEAP - might set PARSEB_LEAP
 61     PARSEB_S_ANTENNA          supports ANTENNA - might set PARSEB_ALTERNATE
 62     PARSEB_S_PPS              supports PPS time stamping
 63     PARSEB_S_POSITION         supports position information (GPS)
 64   </pre>
 65						<p>If the utctime field is non zero this value will be take as time code value. This allows for conversion routines that already have the utc time value. The utctime field gives the seconds since Jan 1st 1970, 0:00:00. The useconds field gives the respective usec value. The fields for date and time (down to second resolution) will be ignored.</p>
 66						<p>Conversion is done in the cvt_* routine in parse/clk_*.c files. look in them for examples. The basic structure is:</p>
 67						<pre>
 68     struct clockformat &lt;yourclock&gt;_format = {
 69       lots of fields for you to fill out (see below)
 70     };
 71
 72     static cvt_&lt;yourclock&gt;()
 73       ...
 74     {
 75       if (&lt;I do not recognize my time code&gt;) {
 76         return CVT_NONE;
 77       } else {
 78         if (&lt;conversion into clockformat is ok&gt;) {
 79           &lt;set all necessary flags&gt;;
 80           return CVT_OK;
 81         } else {
 82           return CVT_FAIL|CVT_BADFMT;
 83         }
 84       }
 85</pre>
 86						<p>The struct clockformat is the interface to the rest of the parse driver - it holds all information necessary for finding the clock message and doing the appropriate time stamping.</p>
 87						<pre>
 88struct clockformat
 89{
 90  u_long (*input)();
 91  /* input routine - your routine - cvt_&lt;yourclock&gt; */
 92  u_long (*convert)();
 93  /* conversion routine - your routine - cvt_&lt;yourclock&gt; */
 94  /* routine for handling RS232 sync events (time stamps) - usually sync_simple */
 95  u_long (*syncpps)(); 
 96  /* PPS input routine - usually pps_one */
 97  void           *data;
 98  /* local parameters - any parameters/data/configuration info your conversion
 99     routine might need */
100  char           *name;
101  /* clock format name - Name of the time code */
102  unsigned short  length;
103  /* maximum length of data packet for your clock format */
104  u_long   flags;
105 /* information for the parser what to look for */
106};
107</pre>
108						<p>The above should have given you some hints on how to build a clk_*.c file with the time code conversion. See the examples and pick a clock closest to yours and tweak the code to match your clock.</p>
109						<p>In order to make your clk_*.c file usable a reference to the clockformat structure must be put into parse_conf.c.</p>
110				</ul>
111			<li>TTY setup and initialisation/configuration will be done in ntpd/refclock_parse.c.
112				<ul>
113					<li>Find out the exact tty settings for your clock (baud rate, parity, stop bits, character size, ...) and note them in terms of termio*.h c_cflag macros.
114					<li>in ntpd/refclock_parse.c fill out a new the struct clockinfo element (that allocates a new &quot;IP&quot; address - see comments) (see all the other clocks for example)
115						<pre>
116   struct clockinfo
117     {
118      u_long  cl_flags;             /* operation flags (io modes) */
119	 PARSE_F_PPSPPS       use loopfilter PPS code (CIOGETEV)
120	 PARSE_F_PPSONSECOND  PPS pulses are on second
121	 usually flags stay 0 as they are used only for special setups
122
123    void  (*cl_poll)();           /* active poll routine */
124         The routine to call when the clock needs data sent to it in order to
125         get a time code from the clock (e.g. Trimble clock)
126
127    int   (*cl_init)();           /* active poll init routine */
128         The routine to call for very special initializations.
129
130    void  (*cl_event)();          /* special event handling (e.g. reset clock) */
131         What to do, when an event happens - used to re-initialize clocks on timeout.
132
133    void  (*cl_end)();            /* active poll end routine */
134         The routine to call to undo any special initialisation (free memory/timers)
135
136    void   *cl_data;              /* local data area for &quot;poll&quot; mechanism */
137         local data for polling routines
138
139    u_fp    cl_rootdelay;         /* rootdelay */
140         NTP rootdelay estimate (usually 0)
141
142	     u_long  cl_basedelay;         /* current offset - unsigned l_fp
143                                              fractional part (fraction) by
144                                              which the RS232 time code is
145                                              delayed from the actual time. */
146
147    u_long  cl_ppsdelay;          /* current PPS offset - unsigned l_fp fractional
148         time (fraction) by which the PPS time stamp is delayed (usually 0)
149   part */
150
151    char   *cl_id;                /* ID code (usually &quot;DCF&quot;) */
152         Refclock id - (max 4 chars)
153
154    char   *cl_description;       /* device name */
155         Name of this device.
156
157    char   *cl_format;            /* fixed format */
158         If the data format cann not ne detected automatically this is the name
159	 as in clk_*.c clockformat.
160
161    u_char  cl_type;              /* clock type (ntp control) */
162         Type if clock as in clock status word (ntp control messages) - usually 0
163	 
164    u_long  cl_maxunsync;         /* time to trust oscillator after losing synch
165  */
166         seconds a clock can be trusted after losing synchronisation.
167
168    u_long  cl_speed;             /* terminal input &amp; output baudrate */
169    u_long  cl_cflag;             /* terminal io flags */
170    u_long  cl_iflag;             /* terminal io flags */
171    u_long  cl_oflag;             /* terminal io flags */
172    u_long  cl_lflag;             /* terminal io flags */
173         termio*.h tty modes.
174
175    u_long  cl_samples;           /* samples for median filter */
176    u_long  cl_keep;              /* samples for median filter to keep */
177         median filter parameters - smoothing and rejection of bad samples
178  } clockinfo[] = {
179  ...,&lt;other clocks&gt;,...
180  { &lt; your parameters&gt; },
181  };
182
183</pre>
184				</ul>
185		</ol>
186		<p>Well, this is very sketchy, i know. But I hope it helps a little bit. The best way is to look which clock comes closest to your and tweak that code.</p>
187		<p>Two sorts of clocks are used with parse. Clocks that automatically send their time code (once a second) do not need entries in the poll routines because they send the data all the time. The second sort are the clocks that need a command sent to them in order to reply with a time code (like the Trimble clock).</p>
188		<p>For questions: <a href="mailto:%20kardel <AT> acm.org">kardel 
189				<AT>
190				acm.org</a>.</p>
191		<p>Please include an exact description on how your clock works. (initialisation, TTY modes, strings to be sent to it, responses received from the clock).</p>
192		<hr>
193		<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
194	</body>
195
196	<body></body>
197
198</html>