|
1586
|
1 <!-- {{{ Banner --> |
|
|
2 |
|
|
3 <!-- =============================================================== --> |
|
|
4 <!-- --> |
|
|
5 <!-- ppp.sgml --> |
|
|
6 <!-- --> |
|
|
7 <!-- eCos PPP code --> |
|
|
8 <!-- --> |
|
|
9 <!-- =============================================================== --> |
|
|
10 <!-- ####COPYRIGHTBEGIN#### --> |
|
|
11 <!-- --> |
|
|
12 <!-- =============================================================== --> |
|
|
13 <!-- Copyright (C) 2003, 2004 eCosCentric Ltd. --> |
|
|
14 <!-- This material may be distributed only subject to the terms --> |
|
|
15 <!-- and conditions set forth in the Open Publication License, v1.0 --> |
|
|
16 <!-- or later (the latest version is presently available at --> |
|
|
17 <!-- http://www.opencontent.org/openpub/) --> |
|
|
18 <!-- =============================================================== --> |
|
|
19 <!-- --> |
|
|
20 <!-- ####COPYRIGHTEND#### --> |
|
|
21 <!-- =============================================================== --> |
|
|
22 <!-- #####DESCRIPTIONBEGIN#### --> |
|
|
23 <!-- --> |
|
|
24 <!-- ####DESCRIPTIONEND#### --> |
|
|
25 <!-- =============================================================== --> |
|
|
26 |
|
|
27 <!-- }}} --> |
|
|
28 |
|
|
29 |
|
|
30 <part id="ppp"> |
|
|
31 <title><productname>eCos</productname> PPP User Guide</title> |
|
|
32 |
|
|
33 <partintro> |
|
|
34 <para> |
|
|
35 This package provides support for PPP (Point-to-Point Protocol) in the |
|
|
36 <productname>eCos</productname> FreeBSD TCP/IP networking stack. |
|
|
37 </para> |
|
|
38 </partintro> |
|
|
39 |
|
|
40 <!-- {{{ Features --> |
|
|
41 |
|
|
42 <chapter id="ppp-features"> |
|
|
43 <title>Features</title> |
|
|
44 <para> |
|
|
45 The <productname>eCos</productname> PPP implementation provides the |
|
|
46 following features: |
|
|
47 </para> |
|
|
48 <itemizedlist> |
|
|
49 |
|
|
50 <listitem> |
|
|
51 <para> |
|
|
52 PPP line protocol including VJ compression. |
|
|
53 </para> |
|
|
54 </listitem> |
|
|
55 |
|
|
56 <listitem> |
|
|
57 <para> |
|
|
58 LCP, IPCP and CCP control protocols. |
|
|
59 </para> |
|
|
60 </listitem> |
|
|
61 |
|
|
62 <listitem> |
|
|
63 <para> |
|
|
64 PAP and CHAP authentication. |
|
|
65 </para> |
|
|
66 </listitem> |
|
|
67 |
|
|
68 <listitem> |
|
|
69 <para> |
|
|
70 CHAT subset connection scripting. |
|
|
71 </para> |
|
|
72 </listitem> |
|
|
73 |
|
|
74 <listitem> |
|
|
75 <para> |
|
|
76 Modem control line support. |
|
|
77 </para> |
|
|
78 </listitem> |
|
|
79 |
|
|
80 </itemizedlist> |
|
|
81 </chapter> |
|
|
82 |
|
|
83 <!-- }}} --> |
|
|
84 <!-- {{{ Using --> |
|
|
85 |
|
|
86 <chapter id="ppp-using"> |
|
|
87 <title>Using PPP</title> |
|
|
88 <para> |
|
|
89 Before going into detail, let's look at a simple example of how the |
|
|
90 <productname>eCos</productname> PPP package is used. Consider the |
|
|
91 following example: |
|
|
92 </para> |
|
|
93 |
|
|
94 <programlisting width=72> |
|
|
95 static void ppp_up(void) |
|
|
96 { |
|
|
97 cyg_ppp_options_t options; |
|
|
98 cyg_ppp_handle_t ppp_handle; |
|
|
99 |
|
|
100 // Bring up the TCP/IP network |
|
|
101 init_all_network_interfaces(); |
|
|
102 |
|
|
103 // Initialize the options |
|
|
104 cyg_ppp_options_init( &options ); |
|
|
105 |
|
|
106 // Start up PPP |
|
|
107 ppp_handle = cyg_ppp_up( "/dev/ser0", &options ); |
|
|
108 |
|
|
109 // Wait for it to get running |
|
|
110 if( cyg_ppp_wait_up( ppp_handle ) == 0 ) |
|
|
111 { |
|
|
112 // Make use of PPP |
|
|
113 use_ppp(); |
|
|
114 |
|
|
115 // Bring PPP link down |
|
|
116 cyg_ppp_down( ppp_handle ); |
|
|
117 |
|
|
118 // Wait for connection to go down. |
|
|
119 cyg_ppp_wait_down( ppp_handle ); |
|
|
120 } |
|
|
121 } |
|
|
122 </programlisting> |
|
|
123 |
|
|
124 <para> |
|
|
125 This is a simple example of how to bring up a simple PPP connection to |
|
|
126 another computer over a directly connected serial line. The other end |
|
|
127 is assumed to already be running PPP on the line and waiting for a |
|
|
128 connection. |
|
|
129 </para> |
|
|
130 |
|
|
131 <para> |
|
|
132 The first thing this code does is to call |
|
|
133 <function>init_all_network_interfaces()</function> to bring up the |
|
|
134 TCP/IP stack and initialize any other network interfaces. It then |
|
|
135 calls <function>cyg_ppp_options_init()</function> to initialize the |
|
|
136 PPP options structure to the defaults. As it happens, the default |
|
|
137 options are exactly what we want for this example, so we don't need to |
|
|
138 make any further changes. We go straight on to bring the PPP interface |
|
|
139 up by calling <function>cyg_ppp_up()</function>. The arguments to this |
|
|
140 function give the name of the serial device to use, in this case |
|
|
141 <literal>"/dev/ser0"</literal>, and a pointer to the options. |
|
|
142 </para> |
|
|
143 |
|
|
144 <para> |
|
|
145 When <function>cyg_ppp_up()</function> returns, it passes back a |
|
|
146 handle to the PPP connection which is to be used in other calls. The |
|
|
147 PPP link will not necessarily have been fully initialized at this |
|
|
148 time. There is a certain amount of negotiation that goes on between |
|
|
149 the ends of a PPP link before it is ready to pass packets. An |
|
|
150 application can wait until the link is ready by calling |
|
|
151 <function>cyg_ppp_wait_up()</function>, which returns |
|
|
152 zero if the link is up and running, or |
|
|
153 <literal>-1</literal> if it has gone down or failed to come up. |
|
|
154 </para> |
|
|
155 |
|
|
156 <para> |
|
|
157 After a successful return from <function>cyg_ppp_wait_up()</function>, |
|
|
158 the application may make use of the PPP connection. This is |
|
|
159 represented here by the call to <function>use_ppp()</function> but |
|
|
160 it may, of course, be accessed by any thread. While the connection is |
|
|
161 up the application may use the standard socket calls to make or accept |
|
|
162 network connections and transfer data in the normal way. |
|
|
163 </para> |
|
|
164 |
|
|
165 <para> |
|
|
166 Once the application has finished with the PPP link, it can bring it |
|
|
167 down by calling <function>cyg_ppp_down()</function>. As with bringing |
|
|
168 the connection up, this call is asynchronous, it simply informs the |
|
|
169 PPP subsystem to start bringing the link down. The application can |
|
|
170 wait for the link to go down fully by calling |
|
|
171 <function>cyg_ppp_wait_down()</function>. |
|
|
172 </para> |
|
|
173 |
|
|
174 <para> |
|
|
175 That example showed how to use PPP to connect to a local peer. PPP is |
|
|
176 more often used to connect via a modem to a remote server, such as an |
|
|
177 ISP. The following example shows how this works: |
|
|
178 </para> |
|
|
179 |
|
|
180 <programlisting width=72> |
|
|
181 |
|
|
182 static char *isp_script[] = |
|
|
183 { |
|
|
184 "ABORT" , "BUSY" , |
|
|
185 "ABORT" , "NO CARRIER" , |
|
|
186 "ABORT" , "ERROR" , |
|
|
187 "" , "ATZ" , |
|
|
188 "OK" , "AT S7=45 S0=0 L1 V1 X4 &C1 E1 Q0" , |
|
|
189 "OK" , "ATD" CYGPKG_PPP_DEFAULT_DIALUP_NUMBER , |
|
|
190 "ogin:--ogin:" , CYGPKG_PPP_AUTH_DEFAULT_USER , |
|
|
191 "assword:" , CYGPKG_PPP_AUTH_DEFAULT_PASSWD , |
|
|
192 "otocol:" , "ppp" , |
|
|
193 "HELLO" , "\\c" , |
|
|
194 0 |
|
|
195 }; |
|
|
196 |
|
|
197 static void ppp_up(void) |
|
|
198 { |
|
|
199 cyg_ppp_options_t options; |
|
|
200 cyg_ppp_handle_t ppp_handle; |
|
|
201 |
|
|
202 // Bring up the TCP/IP network |
|
|
203 init_all_network_interfaces(); |
|
|
204 |
|
|
205 // Initialize the options |
|
|
206 cyg_ppp_options_init( &options ); |
|
|
207 |
|
|
208 options.script = isp_script; |
|
|
209 options.modem = 1; |
|
|
210 |
|
|
211 // Start up PPP |
|
|
212 ppp_handle = cyg_ppp_up( "/dev/ser0", &options ); |
|
|
213 |
|
|
214 // Wait for it to get running |
|
|
215 if( cyg_ppp_wait_up( ppp_handle ) == 0 ) |
|
|
216 { |
|
|
217 // Make use of PPP |
|
|
218 use_ppp(); |
|
|
219 |
|
|
220 // Bring PPP link down |
|
|
221 cyg_ppp_down( ppp_handle ); |
|
|
222 |
|
|
223 // Wait for connection to go down. |
|
|
224 cyg_ppp_wait_down( ppp_handle ); |
|
|
225 } |
|
|
226 } |
|
|
227 </programlisting> |
|
|
228 |
|
|
229 <para> |
|
|
230 The majority of this code is exactly the same as the previous |
|
|
231 example. The main difference is in the setting of a couple of options |
|
|
232 before calling <function>cyg_ppp_up()</function>. The |
|
|
233 <structfield>script</structfield> option is set to point to a CHAT |
|
|
234 script to manage the setup of the connection. The |
|
|
235 <structfield>modem</structfield> option is set to cause the PPP system |
|
|
236 to make use of the modem control lines. |
|
|
237 </para> |
|
|
238 |
|
|
239 <para> |
|
|
240 During the PPP bring-up a call will be made to |
|
|
241 <function>cyg_ppp_chat()</function> to run the CHAT script (see <xref |
|
|
242 linkend="ppp-chat">). In the example this script sets up various modem |
|
|
243 options and then dials a number supplied as part of the PPP package |
|
|
244 configuration (see <xref linkend="ppp-config">). When the connection |
|
|
245 has been established, the script log on to the server, using a name |
|
|
246 and password also supplied by the configuration, and then starts PPP |
|
|
247 on the remote end. If this script succeeds the PPP connection will be |
|
|
248 brought up and will then function as expected. |
|
|
249 </para> |
|
|
250 |
|
|
251 <para> |
|
|
252 The <structfield>modem</structfield> option causes the PPP system to |
|
|
253 make use of the modem control lines. In particular it waits for |
|
|
254 <literal>Carrier Detect</literal> to be asserted, and will bring the |
|
|
255 link down if it is lost. See <xref linkend="ppp-options-init"> |
|
|
256 for more details. |
|
|
257 </para> |
|
|
258 |
|
|
259 </chapter> |
|
|
260 |
|
|
261 <!-- }}} --> |
|
|
262 <!-- {{{ Interface --> |
|
|
263 |
|
|
264 <chapter id="ppp-interface"> |
|
|
265 <title>PPP Interface</title> |
|
|
266 |
|
|
267 <!-- {{{ cyg_ppp_options_init --> |
|
|
268 |
|
|
269 <refentry id="ppp-options-init"> |
|
|
270 |
|
|
271 <refmeta> |
|
|
272 <refentrytitle>cyg_ppp_options_init()</refentrytitle> |
|
|
273 </refmeta> |
|
|
274 |
|
|
275 <refnamediv> |
|
|
276 <refname>cyg_ppp_options_init</refname> |
|
|
277 <refpurpose>Initialize PPP link options</refpurpose> |
|
|
278 </refnamediv> |
|
|
279 |
|
|
280 <refsynopsisdiv> |
|
|
281 <funcsynopsis> |
|
|
282 <funcsynopsisinfo> |
|
|
283 #include <cyg/ppp/ppp.h> |
|
|
284 </funcsynopsisinfo> |
|
|
285 <funcprototype> |
|
|
286 <funcdef>cyg_int32 <function>cyg_ppp_options_init</function></funcdef> |
|
|
287 <paramdef>cyg_ppp_options_t <parameter>*options</parameter></paramdef> |
|
|
288 </funcprototype> |
|
|
289 </funcsynopsis> |
|
|
290 </refsynopsisdiv> |
|
|
291 |
|
|
292 <refsect1><title id="ppp-options-init-description">Description</title> |
|
|
293 <para> |
|
|
294 This function initializes the PPP options, pointed to by the |
|
|
295 <parameter>options</parameter> parameter, to the default state. Once |
|
|
296 the defaults have been initialized, application code may adjust them |
|
|
297 by assigning new values to the the fields of the |
|
|
298 <structname>cyg_ppp_options_t</structname> structure. |
|
|
299 </para> |
|
|
300 |
|
|
301 <para> |
|
|
302 This function returns zero if the options were initialized |
|
|
303 successfully. It returns -1 if the <parameter>options</parameter> |
|
|
304 argument is NULL, or the options could not be initialized. |
|
|
305 </para> |
|
|
306 |
|
|
307 <para> |
|
|
308 The option fields, their functions and default values are as follows: |
|
|
309 </para> |
|
|
310 |
|
|
311 <variablelist> |
|
|
312 |
|
|
313 <varlistentry> |
|
|
314 <term>debug</term> |
|
|
315 <listitem> |
|
|
316 <para> If set to 1 this enables the reporting of debug messages |
|
|
317 from the PPP system. These will be generated using |
|
|
318 <function>diag_printf()</function> and will appear on the standard |
|
|
319 debug channel. Note that <function>diag_printf()</function> |
|
|
320 disables interrupts during output: this may cause the PPP link |
|
|
321 device to overrun and miss characters. It is quite possible for |
|
|
322 this option to cause errors and even make the PPP link fail |
|
|
323 completely. Consequently, this option should be used with care. |
|
|
324 </para> |
|
|
325 <para> |
|
|
326 Default value: 0 |
|
|
327 </para> |
|
|
328 </listitem> |
|
|
329 </varlistentry> |
|
|
330 |
|
|
331 <varlistentry> |
|
|
332 <term>kdebugflag</term> |
|
|
333 <listitem> |
|
|
334 <para> This five bit field enables low level debugging messages from |
|
|
335 the PPP device layer in the TCP/IP stack. As with the |
|
|
336 <structfield>debug</structfield> option, this may result in missed |
|
|
337 characters and cause errors. The bits of the field have the |
|
|
338 following meanings: |
|
|
339 </para> |
|
|
340 <informaltable frame="all"> |
|
|
341 <tgroup cols="3" colsep="1" rowsep="1" align="left"> |
|
|
342 <thead> |
|
|
343 <row> |
|
|
344 <entry>Bit</entry> |
|
|
345 <entry>BSD Name</entry> |
|
|
346 <entry>Description</entry> |
|
|
347 </row> |
|
|
348 </thead> |
|
|
349 <tbody> |
|
|
350 <row> |
|
|
351 <entry>0x01</entry> |
|
|
352 <entry>SC_DEBUG</entry> |
|
|
353 <entry>Enable debug messages</entry> |
|
|
354 </row> |
|
|
355 <row> |
|
|
356 <entry>0x02</entry> |
|
|
357 <entry>SC_LOG_INPKT</entry> |
|
|
358 <entry>Log contents of good packets received</entry> |
|
|
359 </row> |
|
|
360 <row> |
|
|
361 <entry>0x04</entry> |
|
|
362 <entry>SC_LOG_OUTPKT</entry> |
|
|
363 <entry>Log contents of packets sent</entry> |
|
|
364 </row> |
|
|
365 <row> |
|
|
366 <entry>0x08</entry> |
|
|
367 <entry>SC_LOG_RAWIN</entry> |
|
|
368 <entry>Log all characters received</entry> |
|
|
369 </row> |
|
|
370 <row> |
|
|
371 <entry>0x10</entry> |
|
|
372 <entry>SC_LOG_FLUSH</entry> |
|
|
373 <entry>Log all characters flushed</entry> |
|
|
374 </row> |
|
|
375 </tbody> |
|
|
376 </tgroup> |
|
|
377 </informaltable> |
|
|
378 <para> |
|
|
379 Default value: 0 |
|
|
380 </para> |
|
|
381 </listitem> |
|
|
382 </varlistentry> |
|
|
383 |
|
|
384 <varlistentry> |
|
|
385 <term>default_route</term> |
|
|
386 <listitem> |
|
|
387 <para> If set to 1 this option causes the PPP subsystem to install |
|
|
388 a default route in the TCP/IP stack's routing tables using the |
|
|
389 peer as the gateway. This entry will be removed when the PPP link |
|
|
390 is broken. If there is already an existing working network |
|
|
391 connection, such as an ethernet device, then there may already be |
|
|
392 a default route established. If this is the case, then this option |
|
|
393 will have no effect. |
|
|
394 </para> |
|
|
395 <para> |
|
|
396 Default value: 1 |
|
|
397 </para> |
|
|
398 </listitem> |
|
|
399 </varlistentry> |
|
|
400 |
|
|
401 <varlistentry> |
|
|
402 <term>modem</term> |
|
|
403 <listitem> |
|
|
404 <para> If this option is set to 1, then the modem lines will be |
|
|
405 used during the connection. Specifically, the PPP subsystem will |
|
|
406 wait until the <literal>carrier detect</literal> signal is |
|
|
407 asserted before bringing up the PPP link, and will take the PPP |
|
|
408 link down if this signal is de-asserted. |
|
|
409 </para> |
|
|
410 <para> |
|
|
411 Default value: 0 |
|
|
412 </para> |
|
|
413 </listitem> |
|
|
414 </varlistentry> |
|
|
415 |
|
|
416 <varlistentry> |
|
|
417 <term>flowctl</term> |
|
|
418 <listitem> |
|
|
419 <para> This option is used to specify the mechanism used to |
|
|
420 control data flow across the serial line. It can take one of the |
|
|
421 following values: |
|
|
422 </para> |
|
|
423 <variablelist> |
|
|
424 <varlistentry> |
|
|
425 <term><literal>CYG_PPP_FLOWCTL_DEFAULT</literal></term> |
|
|
426 <listitem> |
|
|
427 <para> |
|
|
428 The flow control mechanism is not changed and is left at |
|
|
429 whatever value was set before bringing PPP up. This allows |
|
|
430 a non-standard flow control mechanism to be used, or for it to |
|
|
431 be chosen and set by some other means. |
|
|
432 </para> |
|
|
433 </listitem> |
|
|
434 </varlistentry> |
|
|
435 <varlistentry> |
|
|
436 <term><literal>CYG_PPP_FLOWCTL_NONE</literal></term> |
|
|
437 <listitem> |
|
|
438 <para> |
|
|
439 Flow control is turned off. It is not recommended that this |
|
|
440 option be used unless the baud rate is set low or the two |
|
|
441 communicating machines are particularly fast. |
|
|
442 </para> |
|
|
443 </listitem> |
|
|
444 </varlistentry> |
|
|
445 <varlistentry> |
|
|
446 <term><literal>CYG_PPP_FLOWCTL_HARDWARE</literal></term> |
|
|
447 <listitem> |
|
|
448 <para> |
|
|
449 Use hardware flow control via the RTS/CTS lines. This is the |
|
|
450 most effective flow control mechanism and should always be |
|
|
451 used if available. Availability of this mechanism depends on |
|
|
452 whether the serial device hardware has the ability to control |
|
|
453 these lines, whether they have been connected to the socket |
|
|
454 pins and whether the device driver has the necessary support. |
|
|
455 </para> |
|
|
456 </listitem> |
|
|
457 </varlistentry> |
|
|
458 <varlistentry> |
|
|
459 <term><literal>CYG_PPP_FLOWCTL_SOFTWARE</literal></term> |
|
|
460 <listitem> |
|
|
461 <para> |
|
|
462 Use software flow control by embedding XON/XOFF characters in |
|
|
463 the data stream. This is somewhat less effective that hardware |
|
|
464 flow control since it is subject to the propagation time of |
|
|
465 the serial cable and the latency of the communicating |
|
|
466 devices. Since it does not rely on any hardware support, this |
|
|
467 flow control mechanism is always available. |
|
|
468 </para> |
|
|
469 </listitem> |
|
|
470 </varlistentry> |
|
|
471 </variablelist> |
|
|
472 <para> |
|
|
473 Default value: CYG_PPP_FLOWCTL_HARDWARE |
|
|
474 </para> |
|
|
475 </listitem> |
|
|
476 </varlistentry> |
|
|
477 |
|
|
478 <varlistentry> |
|
|
479 <term>refuse_pap</term> |
|
|
480 <listitem> |
|
|
481 <para> If this option is set to 1, then the PPP subsystem will not |
|
|
482 agree to authenticate itself to the peer with PAP. When dialling |
|
|
483 in to a remote server it is normal to authenticate the |
|
|
484 client. There are three ways this can be done, using a |
|
|
485 straightforward login mechanism via the CHAT script, with the |
|
|
486 Password Authentication Protocol (PAP), or with the Challenge |
|
|
487 Handshake Authentication Protocol (CHAP). For PAP to work the |
|
|
488 <structfield>user</structfield> and |
|
|
489 <structfield>passwd</structfield> options must be set to the |
|
|
490 expected values. If they are not, then this option should be set |
|
|
491 to force CHAP authentication. |
|
|
492 </para> |
|
|
493 <para> |
|
|
494 Default value: 0 |
|
|
495 </para> |
|
|
496 </listitem> |
|
|
497 </varlistentry> |
|
|
498 |
|
|
499 <varlistentry> |
|
|
500 <term>refuse_chap</term> |
|
|
501 <listitem> |
|
|
502 <para> If this option is set to 1, then the PPP subsystem will not |
|
|
503 agree to authenticate itself to the peer with CHAP. CHAP |
|
|
504 authentication will only work if the |
|
|
505 <structfield>passwd</structfield> option has been set to the |
|
|
506 required CHAP secret for the destination server. Otherwise this |
|
|
507 option should be disabled. |
|
|
508 </para> |
|
|
509 <para> |
|
|
510 If both <structfield>refuse_pap</structfield> and |
|
|
511 <structfield>refuse_chap</structfield> are set, then either no |
|
|
512 authentication will be carried out, or it is the responsibility of |
|
|
513 the <command>chat</command> script to do it. If the peer does not |
|
|
514 require any authentication, then the setting of these options is |
|
|
515 irrelevant. |
|
|
516 </para> |
|
|
517 <para> |
|
|
518 Default value: 0 |
|
|
519 </para> |
|
|
520 </listitem> |
|
|
521 </varlistentry> |
|
|
522 |
|
|
523 <varlistentry> |
|
|
524 <term>baud</term> |
|
|
525 <listitem> |
|
|
526 <para> This option is set to the baud rate at which the serial |
|
|
527 connection should be run. The default value is the rate at which |
|
|
528 modems conventionally operate. This field is an instance of the |
|
|
529 <type>cyg_serial_baud_rate_t</type> enum defined in the |
|
|
530 <literal>serialio.h</literal> header and may only take one of the |
|
|
531 baud rate constants defined in there. |
|
|
532 </para> |
|
|
533 <para> |
|
|
534 Default value: <literal>CYGNUM_SERIAL_BAUD_115200</literal> |
|
|
535 </para> |
|
|
536 </listitem> |
|
|
537 </varlistentry> |
|
|
538 |
|
|
539 <varlistentry> |
|
|
540 <term>idle_time_limit</term> |
|
|
541 <listitem> |
|
|
542 <para> This is the number of seconds that the PPP connection may |
|
|
543 be idle before it is shut down automatically. |
|
|
544 </para> |
|
|
545 <para> |
|
|
546 Default value: 60 |
|
|
547 </para> |
|
|
548 </listitem> |
|
|
549 </varlistentry> |
|
|
550 |
|
|
551 <varlistentry> |
|
|
552 <term>maxconnect</term> |
|
|
553 <listitem> |
|
|
554 <para> This causes the connection to terminate when it has been up |
|
|
555 for this number of seconds. The default value of zero means that |
|
|
556 the connection will stay up indefinitely, until either end |
|
|
557 explicitly brings it down, or the link is lost. |
|
|
558 </para> |
|
|
559 <para> |
|
|
560 Default value: 0 |
|
|
561 </para> |
|
|
562 </listitem> |
|
|
563 </varlistentry> |
|
|
564 |
|
|
565 <varlistentry> |
|
|
566 <term>our_address</term> |
|
|
567 <listitem> |
|
|
568 <para> This is the IP address, in network byte order, to be |
|
|
569 attached to the local end of the PPP connection. The default value |
|
|
570 of <literal>INADDR_ANY</literal> causes the local address to be |
|
|
571 obtained from the peer. |
|
|
572 </para> |
|
|
573 <para> |
|
|
574 Default value: <literal>INADDR_ANY</literal> |
|
|
575 </para> |
|
|
576 </listitem> |
|
|
577 </varlistentry> |
|
|
578 |
|
|
579 <varlistentry> |
|
|
580 <term>his_address</term> |
|
|
581 <listitem> |
|
|
582 <para> This is the IP address, in network byte order, to be |
|
|
583 attached to the remote end of the PPP connection. The default |
|
|
584 value of <literal>INADDR_ANY</literal> causes the remote address |
|
|
585 to be obtained from the peer. |
|
|
586 </para> |
|
|
587 <para> |
|
|
588 Default value: <literal>INADDR_ANY</literal> |
|
|
589 </para> |
|
|
590 </listitem> |
|
|
591 </varlistentry> |
|
|
592 |
|
|
593 <varlistentry> |
|
|
594 <term>script</term> |
|
|
595 <listitem> |
|
|
596 <para> This is a pointer to a CHAT script suitable for passing to |
|
|
597 <function>cyg_ppp_chat()</function>. See <xref linkend="ppp-chat"> |
|
|
598 for details of the format and contents of this script. |
|
|
599 </para> |
|
|
600 <para> |
|
|
601 Default value: <literal>NULL</literal> |
|
|
602 </para> |
|
|
603 </listitem> |
|
|
604 </varlistentry> |
|
|
605 |
|
|
606 <varlistentry> |
|
|
607 <term>user</term> |
|
|
608 <listitem> |
|
|
609 <para> This array contains the user name to be used for PAP |
|
|
610 authentication. This field is not used for CHAP authentication. By |
|
|
611 default the value of this option is set from the |
|
|
612 <literal>CYGPKG_PPP_AUTH_DEFAULT_USER</literal> configuration |
|
|
613 option. |
|
|
614 </para> |
|
|
615 <para> |
|
|
616 Default value: <literal>CYGPKG_PPP_AUTH_DEFAULT_USER</literal> |
|
|
617 </para> |
|
|
618 </listitem> |
|
|
619 </varlistentry> |
|
|
620 |
|
|
621 <varlistentry> |
|
|
622 <term>passwd</term> |
|
|
623 <listitem> |
|
|
624 <para> This array contains the password to be used for PAP |
|
|
625 authentication, or the secret to be used during CHAP |
|
|
626 authentication. By default the value of this option is set from |
|
|
627 the <literal>CYGPKG_PPP_AUTH_DEFAULT_PASSWD</literal> |
|
|
628 configuration option. |
|
|
629 </para> |
|
|
630 <para> |
|
|
631 Default value: <literal>CYGPKG_PPP_AUTH_DEFAULT_PASSWD</literal> |
|
|
632 </para> |
|
|
633 </listitem> |
|
|
634 </varlistentry> |
|
|
635 |
|
|
636 </variablelist> |
|
|
637 |
|
|
638 </refsect1> |
|
|
639 |
|
|
640 </refentry> |
|
|
641 |
|
|
642 <!-- }}} --> |
|
|
643 <!-- {{{ cyg_ppp_up --> |
|
|
644 |
|
|
645 <refentry id="ppp-up"> |
|
|
646 |
|
|
647 <refmeta> |
|
|
648 <refentrytitle>cyg_ppp_up()</refentrytitle> |
|
|
649 </refmeta> |
|
|
650 |
|
|
651 <refnamediv> |
|
|
652 <refname>cyg_ppp_up</refname> |
|
|
653 <refpurpose>Bring PPP connection up</refpurpose> |
|
|
654 </refnamediv> |
|
|
655 |
|
|
656 <refsynopsisdiv> |
|
|
657 <funcsynopsis> |
|
|
658 <funcsynopsisinfo> |
|
|
659 #include <cyg/ppp/ppp.h> |
|
|
660 </funcsynopsisinfo> |
|
|
661 <funcprototype> |
|
|
662 <funcdef>cyg_ppp_handle_t <function>cyg_ppp_up</function></funcdef> |
|
|
663 <paramdef>char <parameter>*devnam</parameter></paramdef> |
|
|
664 <paramdef>const cyg_ppp_options_t <parameter>*options</parameter></paramdef> |
|
|
665 </funcprototype> |
|
|
666 </funcsynopsis> |
|
|
667 </refsynopsisdiv> |
|
|
668 |
|
|
669 <refsect1><title id="ppp-up-description">Description</title> |
|
|
670 <para> |
|
|
671 This function starts up a PPP connection. The |
|
|
672 <parameter>devnam</parameter> argument is the name of the device to be |
|
|
673 used for the connection, typically <literal>"/dev/ser0"</literal> or |
|
|
674 <literal>"/dev/ser1"</literal>. The <structfield>options</structfield> |
|
|
675 argument should point to an initialized |
|
|
676 <structname>cyg_ppp_options_t</structname> object. |
|
|
677 </para> |
|
|
678 |
|
|
679 <para> |
|
|
680 The return value will either be zero, indicating a failure, or a |
|
|
681 <type>cyg_ppp_handle_t</type> object that may be used as an argument |
|
|
682 to other PPP functions. |
|
|
683 </para> |
|
|
684 |
|
|
685 <note> |
|
|
686 <para> |
|
|
687 Although the PPP API is designed to permit several simultaneous |
|
|
688 connections to co-exist, at present only one PPP connection is |
|
|
689 actually implemented. Any attempt to create a second connection while |
|
|
690 there is already one open will fail. |
|
|
691 </para> |
|
|
692 </note> |
|
|
693 |
|
|
694 </refsect1> |
|
|
695 |
|
|
696 </refentry> |
|
|
697 |
|
|
698 <!-- }}} --> |
|
|
699 <!-- {{{ cyg_ppp_down --> |
|
|
700 |
|
|
701 <refentry id="ppp-down"> |
|
|
702 |
|
|
703 <refmeta> |
|
|
704 <refentrytitle>cyg_ppp_down()</refentrytitle> |
|
|
705 </refmeta> |
|
|
706 |
|
|
707 <refnamediv> |
|
|
708 <refname>cyg_ppp_down</refname> |
|
|
709 <refpurpose>Bring PPP connection down</refpurpose> |
|
|
710 </refnamediv> |
|
|
711 |
|
|
712 <refsynopsisdiv> |
|
|
713 <funcsynopsis> |
|
|
714 <funcsynopsisinfo> |
|
|
715 #include <cyg/ppp/ppp.h> |
|
|
716 </funcsynopsisinfo> |
|
|
717 <funcprototype> |
|
|
718 <funcdef>cyg_int32 <function>cyg_ppp_down</function></funcdef> |
|
|
719 <paramdef>cyg_ppp_handle_t <parameter>handle</parameter></paramdef> |
|
|
720 </funcprototype> |
|
|
721 </funcsynopsis> |
|
|
722 </refsynopsisdiv> |
|
|
723 |
|
|
724 <refsect1><title id="ppp-down-description">Description</title> |
|
|
725 <para> |
|
|
726 This function brings the PPP connection down. The |
|
|
727 <parameter>handle</parameter> argument is the result of a successful |
|
|
728 call to <function>cyg_ppp_up()</function>. This function only signals |
|
|
729 to the PPP subsystem that the link should be brought down. The link |
|
|
730 will be terminated asynchronously. If the application needs to wait |
|
|
731 for the link to terminate, then it should call |
|
|
732 <function>cyg_ppp_wait_down()</function> after calling |
|
|
733 <function>cyg_ppp_down()</function>. |
|
|
734 </para> |
|
|
735 |
|
|
736 <para> |
|
|
737 The function returns zero if it was able to start the termination of |
|
|
738 the PPP connection successfully. It will return -1 if the connection |
|
|
739 is not running, or if it could not otherwise start the termination. |
|
|
740 </para> |
|
|
741 |
|
|
742 </refsect1> |
|
|
743 |
|
|
744 </refentry> |
|
|
745 |
|
|
746 <!-- }}} --> |
|
|
747 <!-- {{{ cyg_ppp_wait_up --> |
|
|
748 |
|
|
749 <refentry id="ppp-wait-up"> |
|
|
750 |
|
|
751 <refmeta> |
|
|
752 <refentrytitle>cyg_ppp_wait_up()</refentrytitle> |
|
|
753 </refmeta> |
|
|
754 |
|
|
755 <refnamediv> |
|
|
756 <refname>cyg_ppp_wait_up</refname> |
|
|
757 <refpurpose>Wait for PPP connection to come up</refpurpose> |
|
|
758 </refnamediv> |
|
|
759 |
|
|
760 <refsynopsisdiv> |
|
|
761 <funcsynopsis> |
|
|
762 <funcsynopsisinfo> |
|
|
763 #include <cyg/ppp/ppp.h> |
|
|
764 </funcsynopsisinfo> |
|
|
765 <funcprototype> |
|
|
766 <funcdef>cyg_int32 <function>cyg_ppp_wait_up</function></funcdef> |
|
|
767 <paramdef>cyg_ppp_handle_t <parameter>handle</parameter></paramdef> |
|
|
768 </funcprototype> |
|
|
769 </funcsynopsis> |
|
|
770 </refsynopsisdiv> |
|
|
771 |
|
|
772 <refsect1><title id="ppp-wait-up-description">Description</title> |
|
|
773 <para> |
|
|
774 This function waits until the PPP connection is running and then |
|
|
775 returns. This is needed because the actual bring up of the connection |
|
|
776 happens mostly after the call to <function>cyg_ppp_up()</function> |
|
|
777 returns, and may take some time to complete, especially if dialling a |
|
|
778 remote server. |
|
|
779 </para> |
|
|
780 |
|
|
781 <para> |
|
|
782 The result of this call will be zero when the connection is running, |
|
|
783 or -1 if the connection failed to start for some reason. If the |
|
|
784 connection is already running when this call is made it will return |
|
|
785 immediately with a zero result. If the connection is not in the |
|
|
786 process of coming up, or has failed, or has terminated, then a result |
|
|
787 of -1 will be returned immediately. Thus this function may also be |
|
|
788 used to test that the connection is still running at any point. |
|
|
789 </para> |
|
|
790 |
|
|
791 </refsect1> |
|
|
792 |
|
|
793 </refentry> |
|
|
794 |
|
|
795 <!-- }}} --> |
|
|
796 <!-- {{{ cyg_ppp_wait_down --> |
|
|
797 |
|
|
798 <refentry id="ppp-wait-down"> |
|
|
799 |
|
|
800 <refmeta> |
|
|
801 <refentrytitle>cyg_ppp_wait_down()</refentrytitle> |
|
|
802 </refmeta> |
|
|
803 |
|
|
804 <refnamediv> |
|
|
805 <refname>cyg_ppp_wait_down</refname> |
|
|
806 <refpurpose>Wait for PPP connection to terminate</refpurpose> |
|
|
807 </refnamediv> |
|
|
808 |
|
|
809 <refsynopsisdiv> |
|
|
810 <funcsynopsis> |
|
|
811 <funcsynopsisinfo> |
|
|
812 #include <cyg/ppp/ppp.h> |
|
|
813 </funcsynopsisinfo> |
|
|
814 <funcprototype> |
|
|
815 <funcdef>void <function>cyg_ppp_wait_down</function></funcdef> |
|
|
816 <paramdef>cyg_ppp_handle_t <parameter>handle</parameter></paramdef> |
|
|
817 </funcprototype> |
|
|
818 </funcsynopsis> |
|
|
819 </refsynopsisdiv> |
|
|
820 |
|
|
821 <refsect1><title id="ppp-wait-down-description">Description</title> |
|
|
822 <para> |
|
|
823 This function waits for the PPP connection to terminate. The link may |
|
|
824 be terminated with a call to <function>cyg_ppp_down()</function>, by |
|
|
825 the remote end, or by the telephone line being dropped or lost. |
|
|
826 </para> |
|
|
827 |
|
|
828 <para> |
|
|
829 This function has no return value. If the PPP connection is not |
|
|
830 running, or has terminated, it will return. Applications should use |
|
|
831 <function>cyg_ppp_wait_up()</function> to test the link state. |
|
|
832 </para> |
|
|
833 |
|
|
834 </refsect1> |
|
|
835 |
|
|
836 </refentry> |
|
|
837 |
|
|
838 <!-- }}} --> |
|
|
839 <!-- {{{ cyg_ppp_chat --> |
|
|
840 |
|
|
841 <refentry id="ppp-chat-fn"> |
|
|
842 |
|
|
843 <refmeta> |
|
|
844 <refentrytitle>cyg_ppp_chat()</refentrytitle> |
|
|
845 </refmeta> |
|
|
846 |
|
|
847 <refnamediv> |
|
|
848 <refname>cyg_ppp_chat</refname> |
|
|
849 <refpurpose>Execute chat script</refpurpose> |
|
|
850 </refnamediv> |
|
|
851 |
|
|
852 <refsynopsisdiv> |
|
|
853 <funcsynopsis> |
|
|
854 <funcsynopsisinfo> |
|
|
855 #include <cyg/ppp/ppp.h> |
|
|
856 </funcsynopsisinfo> |
|
|
857 <funcprototype> |
|
|
858 <funcdef>cyg_int32 <function>cyg_ppp_chat</function></funcdef> |
|
|
859 <paramdef>const char <parameter>*devname</parameter></paramdef> |
|
|
860 <paramdef>const char <parameter>*script[]</parameter></paramdef> |
|
|
861 </funcprototype> |
|
|
862 </funcsynopsis> |
|
|
863 </refsynopsisdiv> |
|
|
864 |
|
|
865 <refsect1><title id="ppp-chat-description">Description</title> |
|
|
866 <para> |
|
|
867 This function implements a subset of the automated conversational |
|
|
868 scripting as defined by the <command>chat</command> program. The first |
|
|
869 argument is the name of the serial device to be used, typically |
|
|
870 <literal>"/dev/ser0"</literal> or <literal>"/dev/ser1"</literal>. The |
|
|
871 <parameter>script</parameter> argument is a pointer to a zero |
|
|
872 terminated array of strings that comprise the chat script. See <xref |
|
|
873 linkend="ppp-using"> for an example script, and <xref |
|
|
874 linkend="ppp-chat"> for full detail of the script used. |
|
|
875 </para> |
|
|
876 |
|
|
877 <para> |
|
|
878 Under normal use this function is called from the PPP subsystem if the |
|
|
879 <structname>cyg_ppp_options_t</structname> |
|
|
880 <structfield>script</structfield> field is set to a |
|
|
881 non-<literal>NULL</literal> value. This function should only be used |
|
|
882 directly if the application needs to undertake special processing |
|
|
883 between running the chat script, and bringing up the PPP connections. |
|
|
884 </para> |
|
|
885 |
|
|
886 </refsect1> |
|
|
887 |
|
|
888 </refentry> |
|
|
889 |
|
|
890 <!-- }}} --> |
|
|
891 |
|
|
892 |
|
|
893 <!--IOCTLs???? --> |
|
|
894 |
|
|
895 </chapter> |
|
|
896 |
|
|
897 <!-- }}} --> |
|
|
898 <!-- {{{ Install and Config --> |
|
|
899 |
|
|
900 <chapter id="ppp-config"> |
|
|
901 <title>Installing and Configuring PPP</title> |
|
|
902 |
|
|
903 <sect1 id="ppp-config-include"> |
|
|
904 <title>Including PPP in a Configuration</title> |
|
|
905 |
|
|
906 <para> |
|
|
907 PPP is contained entirely within a single |
|
|
908 <productname>eCos</productname> package. So to include PPP in a |
|
|
909 configuration all you need to do is add that package. |
|
|
910 </para> |
|
|
911 |
|
|
912 <para> |
|
|
913 In the GUI configuration tool use the |
|
|
914 <command>Build->Packages</command> menu item, find the "PPP Support" |
|
|
915 package in the left-hand pane and use the <command>Add</command> button |
|
|
916 to add it to the list of packages in use in the right-hand pane. |
|
|
917 </para> |
|
|
918 |
|
|
919 <para> |
|
|
920 In the command-line tool <command>ecosconfig</command>, you can use the |
|
|
921 following command during the configuration phase to add the PPP package: |
|
|
922 </para> |
|
|
923 |
|
|
924 <programlisting width=72> |
|
|
925 |
|
|
926 $ ecosconfig add ppp |
|
|
927 |
|
|
928 </programlisting> |
|
|
929 |
|
|
930 <para> |
|
|
931 In addition to the PPP package you will also need to have the |
|
|
932 <literal>"Network"</literal> package and the <literal>"Serial Device |
|
|
933 Drivers"</literal> package in the configuration. The dependencies and |
|
|
934 requirements of the networking package are such that it is strongly |
|
|
935 recommended that you start with the <literal>net</literal> template. |
|
|
936 </para> |
|
|
937 |
|
|
938 <para> |
|
|
939 See the <productname>eCos</productname> User Guide for full details on |
|
|
940 how to configure and build <productname>eCos</productname>. |
|
|
941 </para> |
|
|
942 |
|
|
943 </sect1> |
|
|
944 |
|
|
945 |
|
|
946 <sect1 id="ppp-config-config"> |
|
|
947 <title>Configuring PPP</title> |
|
|
948 <para> |
|
|
949 The PPP package contains a number of configuration options that may be |
|
|
950 changed to affect its behaviour. |
|
|
951 |
|
|
952 <variablelist> |
|
|
953 |
|
|
954 <varlistentry> |
|
|
955 <term>CYGNUM_PPP_PPPD_THREAD_PRIORITY</term> |
|
|
956 <listitem> |
|
|
957 <para> |
|
|
958 The PPP system contains two threads, One is used for receiving |
|
|
959 data from the link and processing control packets. The other is |
|
|
960 used to transmit data asynchronously to the link when it cannot be |
|
|
961 completed synchronously. The receive thread runs at the priority |
|
|
962 given here, and the transmit thread runs at the next lower |
|
|
963 priority. The exact priority needed here depends on the |
|
|
964 importance of the PPP subsystem relative to the rest of the |
|
|
965 system. The default is to put it in the middle of the priority |
|
|
966 range to provide reasonable response without impacting genuine |
|
|
967 high priority threads. |
|
|
968 </para> |
|
|
969 <para> |
|
|
970 Default value: <literal>CYGNUM_KERNEL_SCHED_PRIORITIES/2</literal> |
|
|
971 </para> |
|
|
972 </listitem> |
|
|
973 </varlistentry> |
|
|
974 |
|
|
975 <varlistentry> |
|
|
976 <term>CYGPKG_PPP_DEBUG_WARN_ONLY</term> |
|
|
977 <listitem> |
|
|
978 <para> |
|
|
979 The runtime <varname>debug</varname> option enables logging of |
|
|
980 high level debug messages. Too many of these can interfere with |
|
|
981 the PPP device and may result in missed messages. This is because |
|
|
982 these messages are emitted via the diag_printf() mechanism, which |
|
|
983 disables interrupts while it prints. By default, therefore, we |
|
|
984 only report errors and warnings, and not all events. Setting this |
|
|
985 option to zero will enable the logging of all events. |
|
|
986 </para> |
|
|
987 <para> |
|
|
988 Default value: <literal>1</literal> |
|
|
989 </para> |
|
|
990 </listitem> |
|
|
991 </varlistentry> |
|
|
992 |
|
|
993 <varlistentry> |
|
|
994 <term>CYGPKG_PPP_AUTH_DEFAULT_USER</term> |
|
|
995 <listitem> |
|
|
996 <para> |
|
|
997 This option gives the default value for the user name used to |
|
|
998 initialize the <structfield>user</structfield> field in the PPP |
|
|
999 options. |
|
|
1000 </para> |
|
|
1001 <para> |
|
|
1002 Default value: <literal>"eCos"</literal> |
|
|
1003 </para> |
|
|
1004 </listitem> |
|
|
1005 </varlistentry> |
|
|
1006 |
|
|
1007 <varlistentry> |
|
|
1008 <term>CYGPKG_PPP_AUTH_DEFAULT_PASSWD</term> |
|
|
1009 <listitem> |
|
|
1010 <para> |
|
|
1011 This option gives the default value for the password used to |
|
|
1012 initialize the <structfield>passwd</structfield> field in the PPP |
|
|
1013 options. |
|
|
1014 </para> |
|
|
1015 <para> |
|
|
1016 Default value: <literal>"secret"</literal> |
|
|
1017 </para> |
|
|
1018 </listitem> |
|
|
1019 </varlistentry> |
|
|
1020 |
|
|
1021 <varlistentry> |
|
|
1022 <term>CYGPKG_PPP_DEFAULT_DIALUP_NUMBER</term> |
|
|
1023 <listitem> |
|
|
1024 <para> |
|
|
1025 This option provides a default dialup number for use in |
|
|
1026 <command>chat</command> scripts. This value is not used anywhere |
|
|
1027 in the PPP package, but is provided to complete the information |
|
|
1028 needed, alongside the user name and password, for accessing a |
|
|
1029 typical dialup server. |
|
|
1030 </para> |
|
|
1031 <para> |
|
|
1032 Default value: <literal>"5551234"</literal> |
|
|
1033 </para> |
|
|
1034 </listitem> |
|
|
1035 </varlistentry> |
|
|
1036 |
|
|
1037 <varlistentry> |
|
|
1038 <term>CYGPKG_PPP_PAP</term> |
|
|
1039 <listitem> |
|
|
1040 <para> |
|
|
1041 This component enables the inclusion of PAP authentication |
|
|
1042 support. |
|
|
1043 </para> |
|
|
1044 <para> |
|
|
1045 Default value: 1 |
|
|
1046 </para> |
|
|
1047 </listitem> |
|
|
1048 </varlistentry> |
|
|
1049 |
|
|
1050 <varlistentry> |
|
|
1051 <term>CYGPKG_PPP_CHAP</term> |
|
|
1052 <listitem> |
|
|
1053 <para> |
|
|
1054 This component enables the inclusion of CHAT authentication |
|
|
1055 support. |
|
|
1056 </para> |
|
|
1057 <para> |
|
|
1058 Default value: 1 |
|
|
1059 </para> |
|
|
1060 </listitem> |
|
|
1061 </varlistentry> |
|
|
1062 |
|
|
1063 <varlistentry> |
|
|
1064 <term>CYGPKG_PPP_COMPRESSION</term> |
|
|
1065 <listitem> |
|
|
1066 <para> |
|
|
1067 This component provides control over PPP compression |
|
|
1068 features. WARNING: at present there are problems with this option, |
|
|
1069 and and in any case the compression code needs to allocate large |
|
|
1070 amounts of memory. Hence this option is currently disabled and |
|
|
1071 should remain so. |
|
|
1072 </para> |
|
|
1073 <para> |
|
|
1074 Default value: 0 |
|
|
1075 </para> |
|
|
1076 </listitem> |
|
|
1077 </varlistentry> |
|
|
1078 |
|
|
1079 <varlistentry> |
|
|
1080 <term>PPP_BSDCOMP</term> |
|
|
1081 <listitem> |
|
|
1082 <para> |
|
|
1083 This option enables inclusion of BSD compression into the PPP |
|
|
1084 protocol. |
|
|
1085 </para> |
|
|
1086 <para> |
|
|
1087 Default value: 0 |
|
|
1088 </para> |
|
|
1089 </listitem> |
|
|
1090 </varlistentry> |
|
|
1091 |
|
|
1092 <varlistentry> |
|
|
1093 <term>PPP_DEFLATE</term> |
|
|
1094 <listitem> |
|
|
1095 <para> |
|
|
1096 This option enables inclusion of ZLIB compression into the PPP |
|
|
1097 protocol. |
|
|
1098 </para> |
|
|
1099 <para> |
|
|
1100 Default value: 0 |
|
|
1101 </para> |
|
|
1102 </listitem> |
|
|
1103 </varlistentry> |
|
|
1104 |
|
|
1105 <varlistentry> |
|
|
1106 <term>CYGPKG_PPP_CHAT</term> |
|
|
1107 <listitem> |
|
|
1108 <para> |
|
|
1109 This component enables the inclusion of a simple scripting system |
|
|
1110 to bring up PPP connections. It implements a subset of the |
|
|
1111 <command>chat</command> scripting language. |
|
|
1112 </para> |
|
|
1113 <para> |
|
|
1114 Default value: 1 |
|
|
1115 </para> |
|
|
1116 </listitem> |
|
|
1117 </varlistentry> |
|
|
1118 |
|
|
1119 <varlistentry> |
|
|
1120 <term>CYGNUM_PPP_CHAT_ABORTS_MAX</term> |
|
|
1121 <listitem> |
|
|
1122 <para> |
|
|
1123 This option defines the maximum number of <literal>ABORT</literal> |
|
|
1124 strings that the CHAT system will store. |
|
|
1125 </para> |
|
|
1126 <para> |
|
|
1127 Default value: 10 |
|
|
1128 </para> |
|
|
1129 </listitem> |
|
|
1130 </varlistentry> |
|
|
1131 |
|
|
1132 <varlistentry> |
|
|
1133 <term>CYGNUM_PPP_CHAT_ABORTS_SIZE</term> |
|
|
1134 <listitem> |
|
|
1135 <para> |
|
|
1136 This option defines the maximum size of each |
|
|
1137 <literal>ABORT</literal> strings that the <command>chat</command> |
|
|
1138 system will store. |
|
|
1139 </para> |
|
|
1140 <para> |
|
|
1141 Default value: 20 |
|
|
1142 </para> |
|
|
1143 </listitem> |
|
|
1144 </varlistentry> |
|
|
1145 |
|
|
1146 <varlistentry> |
|
|
1147 <term>CYGNUM_PPP_CHAT_STRING_LENGTH</term> |
|
|
1148 <listitem> |
|
|
1149 <para> |
|
|
1150 This option defines the maximum size of any expect or reply |
|
|
1151 strings that the <command>chat</command> system will be given. |
|
|
1152 </para> |
|
|
1153 <para> |
|
|
1154 Default value: 256 |
|
|
1155 </para> |
|
|
1156 </listitem> |
|
|
1157 </varlistentry> |
|
|
1158 |
|
|
1159 <varlistentry> |
|
|
1160 <term>CYGPKG_PPP_TEST_DEVICE</term> |
|
|
1161 <listitem> |
|
|
1162 <para> |
|
|
1163 This option defines the serial device to be used for PPP test |
|
|
1164 programs. |
|
|
1165 </para> |
|
|
1166 <para> |
|
|
1167 Default value: <literal>"/dev/ser0"</literal> |
|
|
1168 </para> |
|
|
1169 </listitem> |
|
|
1170 </varlistentry> |
|
|
1171 |
|
|
1172 <varlistentry> |
|
|
1173 <term>CYGPKG_PPP_TESTS_AUTOMATE</term> |
|
|
1174 <listitem> |
|
|
1175 <para> |
|
|
1176 This option enables automated testing features in certain test |
|
|
1177 programs. These programs will interact with a test server at the |
|
|
1178 remote end of the serial link to run a variety of tests in |
|
|
1179 different conditions. Without this option most tests default to |
|
|
1180 running a single test instance and are suitable for being run by |
|
|
1181 hand for debugging purposes. |
|
|
1182 </para> |
|
|
1183 <para> |
|
|
1184 Default value: 0 |
|
|
1185 </para> |
|
|
1186 </listitem> |
|
|
1187 </varlistentry> |
|
|
1188 |
|
|
1189 <varlistentry> |
|
|
1190 <term>CYGDAT_PPP_TEST_BAUD_RATES</term> |
|
|
1191 <listitem> |
|
|
1192 <para> |
|
|
1193 This option supplies a list of baud rates at which certain tests |
|
|
1194 will run if the <literal>CYGPKG_PPP_TESTS_AUTOMATE</literal> |
|
|
1195 option is set. |
|
|
1196 </para> |
|
|
1197 <para> |
|
|
1198 Default value: <literal>"CYGNUM_SERIAL_BAUD_19200,CYGNUM_SERIAL_BAUD_38400,CYGNUM_SERIAL_BAUD_57600,CYGNUM_SERIAL_BAUD_115200"</literal> |
|
|
1199 </para> |
|
|
1200 </listitem> |
|
|
1201 </varlistentry> |
|
|
1202 |
|
|
1203 </variablelist> |
|
|
1204 |
|
|
1205 |
|
|
1206 </para> |
|
|
1207 |
|
|
1208 </sect1> |
|
|
1209 |
|
|
1210 |
|
|
1211 </chapter> |
|
|
1212 |
|
|
1213 <!-- }}} --> |
|
|
1214 <!-- {{{ Chat --> |
|
|
1215 |
|
|
1216 <chapter id="ppp-chat"> |
|
|
1217 <title>CHAT Scripts</title> |
|
|
1218 <para> |
|
|
1219 The automated conversational scripting supported by the |
|
|
1220 <productname>eCos</productname> PPP package is a subset of the |
|
|
1221 scripting language provided by the <command>chat</command> command |
|
|
1222 found on most UNIX and Linux systems. |
|
|
1223 </para> |
|
|
1224 |
|
|
1225 <para> |
|
|
1226 Unlike the <command>chat</command> command, the |
|
|
1227 <productname>eCos</productname> <function>cyg_ppp_chat()</function> |
|
|
1228 function takes as a parameter a zero-terminated array of pointers to |
|
|
1229 strings. In most programs this will be defined by means of an |
|
|
1230 initializer for a static array, although there is nothing to stop the |
|
|
1231 application constructing it at runtime. A simple script would be |
|
|
1232 defined like this: |
|
|
1233 </para> |
|
|
1234 |
|
|
1235 <programlisting width=72> |
|
|
1236 |
|
|
1237 static char *chat_script[] = |
|
|
1238 { |
|
|
1239 "ABORT" , "BUSY" , |
|
|
1240 "ABORT" , "NO CARRIER" , |
|
|
1241 "" , "ATD5551234" , |
|
|
1242 "ogin:--ogin:" , "ppp" , |
|
|
1243 "ssword:" , "hithere" , |
|
|
1244 0 |
|
|
1245 }; |
|
|
1246 |
|
|
1247 </programlisting> |
|
|
1248 |
|
|
1249 <para> |
|
|
1250 The following sections have been abstracted from the public domain |
|
|
1251 documentation for the <command>chat</command> command. |
|
|
1252 </para> |
|
|
1253 |
|
|
1254 |
|
|
1255 <sect1 id="ppp-chat-script"> |
|
|
1256 <title>Chat Script</title> |
|
|
1257 <para> |
|
|
1258 A script consists of one or more "expect-send" pairs of |
|
|
1259 strings, separated by spaces, with an optional "subexpect- |
|
|
1260 subsend" string pair, separated by a dash as in the following |
|
|
1261 example: |
|
|
1262 </para> |
|
|
1263 |
|
|
1264 <programlisting width=72> |
|
|
1265 |
|
|
1266 "ogin:--ogin:" , "ppp" , |
|
|
1267 "ssword:" , "hello2u2" , |
|
|
1268 0 |
|
|
1269 |
|
|
1270 </programlisting> |
|
|
1271 |
|
|
1272 <para> |
|
|
1273 This script fragment indicates that the |
|
|
1274 <function>cyg_ppp_chat()</function> function should expect the |
|
|
1275 string "ogin:". If it fails to receive a login prompt within |
|
|
1276 the time interval allotted, it is to send a carriage return |
|
|
1277 to the remote and then expect the string "ogin:" again. If |
|
|
1278 the first "ogin:" is received then the carriage return is not |
|
|
1279 generated. |
|
|
1280 </para> |
|
|
1281 <para> |
|
|
1282 Once it received the login prompt the |
|
|
1283 <function>cyg_ppp_chat()</function> function will send the |
|
|
1284 string "ppp" and then expect the prompt "ssword:". When it |
|
|
1285 receives the prompt for the password, it will send the password |
|
|
1286 "hello2u2". |
|
|
1287 </para> |
|
|
1288 <para> |
|
|
1289 A carriage return is normally sent following the reply string. |
|
|
1290 It is not expected in the "expect" string unless it is |
|
|
1291 specifically requested by using the "\r" character sequence. |
|
|
1292 </para> |
|
|
1293 <para> |
|
|
1294 The expect sequence should contain only what is needed to |
|
|
1295 identify the string. It should not contain variable |
|
|
1296 information. It is generally not acceptable to look for time |
|
|
1297 strings, network identification strings, or other variable |
|
|
1298 pieces of data as an expect string. |
|
|
1299 </para> |
|
|
1300 <para> |
|
|
1301 To help correct for characters which may be corrupted during |
|
|
1302 the initial sequence, look for the string "ogin:" rather than |
|
|
1303 "login:". It is possible that the leading "l" character may be |
|
|
1304 received in error and you may never find the string even though |
|
|
1305 it was sent by the system. For this reason, scripts look for |
|
|
1306 "ogin:" rather than "login:" and "ssword:" rather than |
|
|
1307 "password:". |
|
|
1308 </para> |
|
|
1309 <para> |
|
|
1310 A very simple script might look like this: |
|
|
1311 </para> |
|
|
1312 <programlisting width=72> |
|
|
1313 |
|
|
1314 "ogin:" , "ppp" , |
|
|
1315 "ssword:" , " hello2u2" , |
|
|
1316 0 |
|
|
1317 |
|
|
1318 </programlisting> |
|
|
1319 |
|
|
1320 <para> |
|
|
1321 In other words, expect "....ogin:", send "ppp", expect "...ssword:", |
|
|
1322 send "hello2u2". |
|
|
1323 </para> |
|
|
1324 <para> |
|
|
1325 In actual practice, simple scripts are rare. At the very least, |
|
|
1326 you should include sub-expect sequences should the original |
|
|
1327 string not be received. For example, consider the following |
|
|
1328 script: |
|
|
1329 </para> |
|
|
1330 <programlisting width=72> |
|
|
1331 |
|
|
1332 "ogin:--ogin:" , "ppp" , |
|
|
1333 "ssword:" , "hello2u2", |
|
|
1334 0 |
|
|
1335 |
|
|
1336 </programlisting> |
|
|
1337 <para> |
|
|
1338 This would be a better script than the simple one used earlier. |
|
|
1339 This would look for the same "login:" prompt, however, if one |
|
|
1340 was not received, a single return sequence is sent and then it |
|
|
1341 will look for "login:" again. Should line noise obscure the |
|
|
1342 first login prompt then sending the empty line will usually |
|
|
1343 generate a login prompt again. |
|
|
1344 </para> |
|
|
1345 |
|
|
1346 </sect1> |
|
|
1347 |
|
|
1348 <sect1 id="ppp-chat-abort"> |
|
|
1349 <title>ABORT Strings</title> |
|
|
1350 |
|
|
1351 <para> |
|
|
1352 Many modems will report the status of the call as a |
|
|
1353 string. These strings may be CONNECTED or NO CARRIER or |
|
|
1354 BUSY. It is often desirable to terminate the script should the |
|
|
1355 modem fail to connect to the remote. The difficulty is that a |
|
|
1356 script would not know exactly which modem string it may |
|
|
1357 receive. On one attempt, it may receive BUSY while the next |
|
|
1358 time it may receive NO CARRIER. |
|
|
1359 </para> |
|
|
1360 <para> |
|
|
1361 These "abort" strings may be specified in the script using |
|
|
1362 the ABORT sequence. It is written in the script as in the |
|
|
1363 following example: |
|
|
1364 </para> |
|
|
1365 <programlisting width=72> |
|
|
1366 |
|
|
1367 "ABORT" , "BUSY" , |
|
|
1368 "ABORT" , "NO CARRIER" , |
|
|
1369 "" , "ATZ" , |
|
|
1370 "OK" , "ATDT5551212" , |
|
|
1371 "CONNECT" , ... |
|
|
1372 |
|
|
1373 </programlisting> |
|
|
1374 |
|
|
1375 <para> |
|
|
1376 This sequence will expect nothing; and then send the string |
|
|
1377 ATZ. The expected response to this is the string OK. When it |
|
|
1378 receives OK, it sends the string ATDT5551212 to dial the |
|
|
1379 telephone. The expected string is CONNECT. If the string |
|
|
1380 CONNECT is received the remainder of the script is |
|
|
1381 executed. However, should the modem find a busy telephone, it |
|
|
1382 will send the string BUSY. This will cause the string to match |
|
|
1383 the abort character sequence. The script will then fail because |
|
|
1384 it found a match to the abort string. If it received the string |
|
|
1385 NO CARRIER, it will abort for the same reason. Either string |
|
|
1386 may be received. Either string will terminate the chat script. |
|
|
1387 </para> |
|
|
1388 |
|
|
1389 </sect1> |
|
|
1390 |
|
|
1391 <sect1 id="ppp-chat-timeout"> |
|
|
1392 <title>TIMEOUT</title> |
|
|
1393 <para> |
|
|
1394 The initial timeout value is 45 seconds. |
|
|
1395 To change the timeout value for the next expect string, |
|
|
1396 the following example may be used: |
|
|
1397 </para> |
|
|
1398 <programlisting width=72> |
|
|
1399 |
|
|
1400 "" , "ATZ" , |
|
|
1401 "OK" , "ATDT5551212" , |
|
|
1402 "CONNECT" , "\\c" , |
|
|
1403 "TIMEOUT" , "10" , |
|
|
1404 "ogin:--ogin:" , "ppp" , |
|
|
1405 "TIMEOUT" , "5" , |
|
|
1406 "assword:" , "hello2u2" , |
|
|
1407 0 |
|
|
1408 |
|
|
1409 </programlisting> |
|
|
1410 <para> |
|
|
1411 This will change the timeout to 10 seconds when it expects the |
|
|
1412 login: prompt. The timeout is then changed to 5 seconds when |
|
|
1413 it looks for the password prompt. |
|
|
1414 </para> |
|
|
1415 <para> |
|
|
1416 The timeout, once changed, remains in effect until it is |
|
|
1417 changed again. |
|
|
1418 </para> |
|
|
1419 |
|
|
1420 </sect1> |
|
|
1421 |
|
|
1422 <sect1 id="ppp-chat-eot"> |
|
|
1423 <title>Sending EOT</title> |
|
|
1424 <para> |
|
|
1425 The special reply string of EOT indicates that the chat |
|
|
1426 program should send an EOT character to the remote. This |
|
|
1427 is normally the End-of-file character sequence. A return |
|
|
1428 character is not sent following the EOT. The EOT sequence |
|
|
1429 may be embedded into the send string using the sequence |
|
|
1430 "\x04" (i.e. a Control-D character). |
|
|
1431 </para> |
|
|
1432 </sect1> |
|
|
1433 |
|
|
1434 <sect1 id="ppp-chat-escape"> |
|
|
1435 <title>Escape Sequences</title> |
|
|
1436 <para> |
|
|
1437 Most standard <command>chat</command> escape sequences can be replaced |
|
|
1438 with standard C string escapes such as '\r', '\n', '\t' |
|
|
1439 etc. Additional escape sequences may be embedded in the expect or |
|
|
1440 reply strings by introducing them with <emphasis>two</emphasis> |
|
|
1441 backslashes. |
|
|
1442 </para> |
|
|
1443 |
|
|
1444 <variablelist> |
|
|
1445 |
|
|
1446 <varlistentry> |
|
|
1447 <term>\\c</term> |
|
|
1448 <listitem> |
|
|
1449 <para> |
|
|
1450 Suppresses the newline at the end of the reply string. This is the |
|
|
1451 only method to send a string without a trailing return character. It |
|
|
1452 must be at the end of the send string. For example, the sequence |
|
|
1453 "hello\\c" will simply send the characters h, e, l, l, o. (not valid |
|
|
1454 in expect strings.) |
|
|
1455 </para> |
|
|
1456 </listitem> |
|
|
1457 </varlistentry> |
|
|
1458 |
|
|
1459 </variablelist> |
|
|
1460 |
|
|
1461 </sect1> |
|
|
1462 |
|
|
1463 </chapter> |
|
|
1464 |
|
|
1465 <!-- }}} --> |
|
|
1466 <!-- {{{ Drivers --> |
|
|
1467 |
|
|
1468 <chapter id="ppp-drivers"> |
|
|
1469 <title>PPP Enabled Device Drivers</title> |
|
|
1470 <para> |
|
|
1471 For PPP to function fully over a serial device, its driver must |
|
|
1472 implement certain features. At present not all |
|
|
1473 <productname>eCos</productname> serial drivers implement these |
|
|
1474 features. A driver indicates that it supports a certain feature by |
|
|
1475 including an <literal>"implements"</literal> line in its CDL for the |
|
|
1476 following interfaces: |
|
|
1477 </para> |
|
|
1478 |
|
|
1479 <variablelist> |
|
|
1480 |
|
|
1481 <varlistentry> |
|
|
1482 <term><literal>CYGINT_IO_SERIAL_FLOW_CONTROL_HW</literal></term> |
|
|
1483 <listitem> |
|
|
1484 <para> |
|
|
1485 This interface indicates that the driver implements hardware flow |
|
|
1486 control using the RTS and CTS lines. When data is being transferred |
|
|
1487 over high speed data lines, it is essential that flow control be used |
|
|
1488 to prevent buffer overrun. |
|
|
1489 </para> |
|
|
1490 <para> |
|
|
1491 The PPP subsystem functions best with hardware flow control. If this |
|
|
1492 is not available, then it can be configured to use software flow |
|
|
1493 control. Since software flow control is implemented by the device |
|
|
1494 independent part of the serial device infrastructure, it is available |
|
|
1495 for all serial devices. However, this will have an effect on the |
|
|
1496 performance and reliability of the PPP link. |
|
|
1497 </para> |
|
|
1498 </listitem> |
|
|
1499 </varlistentry> |
|
|
1500 |
|
|
1501 |
|
|
1502 <varlistentry> |
|
|
1503 <term><literal>CYGINT_IO_SERIAL_LINE_STATUS_HW</literal></term> |
|
|
1504 <listitem> |
|
|
1505 <para> |
|
|
1506 This interface indicates that the driver implements a callback |
|
|
1507 interface for indicating the status of various RS232 control lines. Of |
|
|
1508 particular interest here is the ability to detect changes in the |
|
|
1509 Carrier Detect (CD) line. Not all drivers that implement this |
|
|
1510 interface can indicate CD status. |
|
|
1511 </para> |
|
|
1512 <para> |
|
|
1513 This functionality is only needed if it is important that the link be |
|
|
1514 dropped immediately a telephone connection fails. Without it, a |
|
|
1515 connection will only be dropped after it times out. This may be |
|
|
1516 acceptable in many situations. |
|
|
1517 </para> |
|
|
1518 </listitem> |
|
|
1519 </varlistentry> |
|
|
1520 |
|
|
1521 </variablelist> |
|
|
1522 |
|
|
1523 <para> |
|
|
1524 At the time of writing, the serial device drivers for the following |
|
|
1525 platforms implement some or all of the required functionality: |
|
|
1526 </para> |
|
|
1527 |
|
|
1528 <itemizedlist> |
|
|
1529 |
|
|
1530 <listitem> |
|
|
1531 <para> |
|
|
1532 All drivers that use the generic 16x5x driver implement all functions: |
|
|
1533 </para> |
|
|
1534 <itemizedlist> |
|
|
1535 <listitem><para>ARM CerfPDA</para></listitem> |
|
|
1536 <listitem><para>ARM IQ80321</para></listitem> |
|
|
1537 <listitem><para>ARM PID</para></listitem> |
|
|
1538 <listitem><para>ARM IOP310</para></listitem> |
|
|
1539 <listitem><para>i386 PC</para></listitem> |
|
|
1540 <listitem><para>MIPS Atlas</para></listitem> |
|
|
1541 <listitem><para>MIPS Ref4955</para></listitem> |
|
|
1542 <listitem><para>SH3 SE77x9</para></listitem> |
|
|
1543 </itemizedlist> |
|
|
1544 </listitem> |
|
|
1545 |
|
|
1546 <listitem> |
|
|
1547 <para> |
|
|
1548 The following drivers implement flow control but either do not support |
|
|
1549 line status callbacks, or do not report CD changes: |
|
|
1550 </para> |
|
|
1551 <itemizedlist> |
|
|
1552 <listitem><para>SH4 SCIF</para></listitem> |
|
|
1553 <listitem><para>A&M AdderI</para></listitem> |
|
|
1554 <listitem><para>A&M AdderII</para></listitem> |
|
|
1555 </itemizedlist> |
|
|
1556 </listitem> |
|
|
1557 |
|
|
1558 <listitem> |
|
|
1559 <para> |
|
|
1560 All other drivers can support software flow control only. |
|
|
1561 </para> |
|
|
1562 </listitem> |
|
|
1563 |
|
|
1564 </itemizedlist> |
|
|
1565 |
|
|
1566 |
|
|
1567 </chapter> |
|
|
1568 |
|
|
1569 <!-- }}} --> |
|
|
1570 <!-- {{{ Tests --> |
|
|
1571 |
|
|
1572 <chapter id="ppp-tests"> |
|
|
1573 <title>Testing</title> |
|
|
1574 |
|
|
1575 |
|
|
1576 <sect1> |
|
|
1577 <title>Test Programs</title> |
|
|
1578 |
|
|
1579 <para> |
|
|
1580 There are a number of test programs supplied with the PPP |
|
|
1581 subsystem. By default all of these tests use the device configured by |
|
|
1582 <literal>CYGPKG_PPP_TEST_DEVICE</literal> as the PPP link device. |
|
|
1583 </para> |
|
|
1584 |
|
|
1585 <variablelist> |
|
|
1586 |
|
|
1587 <varlistentry> |
|
|
1588 <term><literal>ppp_up</literal></term> |
|
|
1589 <listitem> |
|
|
1590 <para> |
|
|
1591 This test just brings up the PPP link on |
|
|
1592 <literal>CYGPKG_PPP_TEST_DEVICE</literal> and waits until the remote end brings |
|
|
1593 it back down. No modem lines are used and the program expects a PPP |
|
|
1594 connection to be waiting on the other end of the line. Typically the |
|
|
1595 remote end will test the link using <command>ping</command> or access |
|
|
1596 the HTTP system monitor if it is present. |
|
|
1597 </para> |
|
|
1598 <para> |
|
|
1599 If <literal>CYGPKG_PPP_TESTS_AUTOMATE</literal> is set, then this test |
|
|
1600 attempts to bring PPP up at each of the baud rates specified in |
|
|
1601 <literal>CYGDAT_PPP_TEST_BAUD_RATES</literal>. If it is not set then |
|
|
1602 it will just bring the connection up at 115200 baud. |
|
|
1603 </para> |
|
|
1604 </listitem> |
|
|
1605 </varlistentry> |
|
|
1606 |
|
|
1607 <varlistentry> |
|
|
1608 <term><literal>ppp_updown</literal></term> |
|
|
1609 <listitem> |
|
|
1610 <para> |
|
|
1611 This test brings the PPP link up on |
|
|
1612 <literal>CYGPKG_PPP_TEST_DEVICE</literal> and attempts to |
|
|
1613 <command>ping</command> the remote end of the link. Once the pings |
|
|
1614 have finished, the link is then brought down. |
|
|
1615 </para> |
|
|
1616 <para> |
|
|
1617 If <literal>CYGPKG_PPP_TESTS_AUTOMATE</literal> is set, then this test |
|
|
1618 attempts to bring PPP up at each of the baud rates specified in |
|
|
1619 <literal>CYGDAT_PPP_TEST_BAUD_RATES</literal>. If it is not set then |
|
|
1620 it will just bring the connection up at 115200 baud. |
|
|
1621 </para> |
|
|
1622 </listitem> |
|
|
1623 </varlistentry> |
|
|
1624 |
|
|
1625 <varlistentry> |
|
|
1626 <term><literal>chat</literal></term> |
|
|
1627 <listitem> |
|
|
1628 <para> |
|
|
1629 This test does not bring the PPP link up but simply executes a chat |
|
|
1630 script. It expects a server at the remote end of the link to supply |
|
|
1631 the correct responses. |
|
|
1632 </para> |
|
|
1633 <para> |
|
|
1634 This program expects the <command>test_server.sh</command> script to |
|
|
1635 be running on the remote end and attempts several different tests, |
|
|
1636 expecting a variety of different responses for each. |
|
|
1637 </para> |
|
|
1638 </listitem> |
|
|
1639 </varlistentry> |
|
|
1640 |
|
|
1641 <varlistentry> |
|
|
1642 <term><literal>ppp_auth</literal></term> |
|
|
1643 <listitem> |
|
|
1644 <para> |
|
|
1645 This test attempts to bring up the PPP link under a variety of |
|
|
1646 different authentication conditions. This includes checking that both |
|
|
1647 PAP and CHAP authentication work, and that the connection is rejected |
|
|
1648 when the incorrect authentication protcol or secrets are used. |
|
|
1649 </para> |
|
|
1650 <para> |
|
|
1651 This test expects the <command>test_server.sh</command> script to be |
|
|
1652 running on the remote end. For this test to work the <filename>/etc/ppp/pap-secrets</filename> file on the remote |
|
|
1653 end should contain the following two lines: |
|
|
1654 </para> |
|
|
1655 <programlisting width=72> |
|
|
1656 eCos * secret * |
|
|
1657 eCosPAP * secretPAP * |
|
|
1658 </programlisting> |
|
|
1659 <para> |
|
|
1660 The <filename>/etc/ppp/chap-secrets</filename> file should contain: |
|
|
1661 </para> |
|
|
1662 <programlisting width=72> |
|
|
1663 eCos * secret * |
|
|
1664 eCosCHAP * secretCHAP * |
|
|
1665 </programlisting> |
|
|
1666 </listitem> |
|
|
1667 </varlistentry> |
|
|
1668 |
|
|
1669 <varlistentry> |
|
|
1670 <term><literal>isp</literal></term> |
|
|
1671 <listitem> |
|
|
1672 <para> |
|
|
1673 This test expects the serial test device to be connected to a Hayes |
|
|
1674 compatible modem. The test dials the telephone number given in |
|
|
1675 <literal>CYGPKG_PPP_DEFAULT_DIALUP_NUMBER</literal> and attempts to |
|
|
1676 log on to an ISP using the user name and password supplied in |
|
|
1677 <literal>CYGPKG_PPP_AUTH_DEFAULT_USER</literal> and |
|
|
1678 <literal>CYGPKG_PPP_AUTH_DEFAULT_PASSWD</literal>. Once the PPP |
|
|
1679 connection has been made, the program then attempts to ping a number |
|
|
1680 of well known addresses. |
|
|
1681 </para> |
|
|
1682 <para> |
|
|
1683 Since this test is designed to interact with an ISP, it does not run |
|
|
1684 within the automated testing system. |
|
|
1685 </para> |
|
|
1686 </listitem> |
|
|
1687 </varlistentry> |
|
|
1688 |
|
|
1689 <varlistentry> |
|
|
1690 <term><literal>tcp_echo</literal></term> |
|
|
1691 <listitem> |
|
|
1692 <para> |
|
|
1693 This is a version of the standard network <command>tcp_echo</command> |
|
|
1694 test that brings up the PPP connection before waiting for the |
|
|
1695 <command>tcp_sink</command> and <command>tcp_source</command> programs |
|
|
1696 to connect. It is expected that at least one of these programs will |
|
|
1697 connect via the PPP link. However, if another network interface is |
|
|
1698 present, such as an ethernet device, then one may connect via that |
|
|
1699 interface. |
|
|
1700 </para> |
|
|
1701 <para> |
|
|
1702 While this test is supported by the <command>test_server.sh</command> |
|
|
1703 script, it runs for such a long time that it should not normally be |
|
|
1704 used during automated testing. |
|
|
1705 </para> |
|
|
1706 </listitem> |
|
|
1707 </varlistentry> |
|
|
1708 |
|
|
1709 <varlistentry> |
|
|
1710 <term><literal>nc_test_slave</literal></term> |
|
|
1711 <listitem> |
|
|
1712 <para> |
|
|
1713 This is a version of the standard network |
|
|
1714 <command>nc_test_slave</command> test that brings up the PPP |
|
|
1715 connection before waiting for the <command>nc_test_master</command> |
|
|
1716 program to connect. It is expected that the master will connect via |
|
|
1717 the PPP link. |
|
|
1718 </para> |
|
|
1719 <para> |
|
|
1720 While this test is supported by the <command>test_server.sh</command> |
|
|
1721 script, it runs for such a long time that it should not normally be |
|
|
1722 used during automated testing. |
|
|
1723 </para> |
|
|
1724 </listitem> |
|
|
1725 </varlistentry> |
|
|
1726 |
|
|
1727 </variablelist> |
|
|
1728 |
|
|
1729 </sect1> |
|
|
1730 |
|
|
1731 <sect1 id="ppp-test-script"> |
|
|
1732 <title>Test Script</title> |
|
|
1733 |
|
|
1734 <para> |
|
|
1735 The PPP package additionally contains a shell script |
|
|
1736 (<command>test_server.sh</command>) that may be used to operate the |
|
|
1737 remote end of a PPP test link. |
|
|
1738 </para> |
|
|
1739 |
|
|
1740 <para> |
|
|
1741 The script may be invoked with the following arguments: |
|
|
1742 </para> |
|
|
1743 |
|
|
1744 <variablelist> |
|
|
1745 |
|
|
1746 <varlistentry> |
|
|
1747 <term><literal>--dev=<devname></literal></term> |
|
|
1748 <listitem> |
|
|
1749 <para> |
|
|
1750 This mandatory option gives the name of the device to be used for the |
|
|
1751 PPP link. Typically <literal>"/dev/ttyS0"</literal> or |
|
|
1752 <literal>"/dev/ttyS1"</literal>. |
|
|
1753 </para> |
|
|
1754 </listitem> |
|
|
1755 </varlistentry> |
|
|
1756 |
|
|
1757 <varlistentry> |
|
|
1758 <term><literal>--myip=<ipaddress></literal></term> |
|
|
1759 <listitem> |
|
|
1760 <para> |
|
|
1761 This mandatory option gives the IP address to be attached to this end |
|
|
1762 of the PPP link. |
|
|
1763 </para> |
|
|
1764 </listitem> |
|
|
1765 </varlistentry> |
|
|
1766 |
|
|
1767 <varlistentry> |
|
|
1768 <term><literal>--hisip=<ipaddress></literal></term> |
|
|
1769 <listitem> |
|
|
1770 <para> |
|
|
1771 This mandatory option gives the IP address to be attached to the |
|
|
1772 remote (test target) end of the PPP link. |
|
|
1773 </para> |
|
|
1774 </listitem> |
|
|
1775 </varlistentry> |
|
|
1776 |
|
|
1777 <varlistentry> |
|
|
1778 <term><literal>--baud=<baud_rate></literal></term> |
|
|
1779 <listitem> |
|
|
1780 <para> |
|
|
1781 This option gives the baud rate at which the PPP link is to be run. If |
|
|
1782 absent then the link will run at the value set for |
|
|
1783 <literal>--redboot-baud</literal>. |
|
|
1784 </para> |
|
|
1785 </listitem> |
|
|
1786 </varlistentry> |
|
|
1787 |
|
|
1788 <varlistentry> |
|
|
1789 <term><literal>--redboot</literal></term> |
|
|
1790 <listitem> |
|
|
1791 <para> |
|
|
1792 If this option is present then the script will look for a |
|
|
1793 <literal>"RedBoot>"</literal> prompt between test runs. This is |
|
|
1794 necessary if the serial device being used for testing is also used by |
|
|
1795 RedBoot. |
|
|
1796 </para> |
|
|
1797 </listitem> |
|
|
1798 </varlistentry> |
|
|
1799 |
|
|
1800 <varlistentry> |
|
|
1801 <term><literal>--redboot-baud=<baud_rate></literal></term> |
|
|
1802 <listitem> |
|
|
1803 <para> |
|
|
1804 This option gives the baud rate at which the search for the RedBoot |
|
|
1805 prompt will be made. If absent then the link will run at 38400 baud. |
|
|
1806 </para> |
|
|
1807 </listitem> |
|
|
1808 </varlistentry> |
|
|
1809 |
|
|
1810 <varlistentry> |
|
|
1811 <term><literal>--debug</literal></term> |
|
|
1812 <listitem> |
|
|
1813 <para> |
|
|
1814 If this option is present, then the script will print out some |
|
|
1815 additional debug messages while it runs. |
|
|
1816 </para> |
|
|
1817 </listitem> |
|
|
1818 </varlistentry> |
|
|
1819 |
|
|
1820 </variablelist> |
|
|
1821 |
|
|
1822 <para> |
|
|
1823 This script operates as follows: If the <literal>--redboot</literal> |
|
|
1824 option is set it sets the device baud rate to the RedBoot baud rate |
|
|
1825 and waits until a <literal>"RedBoot>"</literal> prompt is encountered. |
|
|
1826 It then sets the baud rate to the value given by the |
|
|
1827 <literal>--baud</literal> option and reads lines from the device until |
|
|
1828 a recognizable test announce string is read. It then executes an |
|
|
1829 appropriate set of commands to satisfy the test. This usually means |
|
|
1830 bringing up the PPP link by running <command>pppd</command> and maybe |
|
|
1831 executing various commands. It then either terminates the link itself, |
|
|
1832 or waits for the target to terminate it. It then goes back to looking |
|
|
1833 for another test announce string. If a string of the form |
|
|
1834 <literal>"BAUD:XXX"</literal> is received then the baud rate is |
|
|
1835 changed depending on the <literal>XXX</literal> value. If a |
|
|
1836 <literal>"FINISH"</literal> string is received it returns to waiting |
|
|
1837 for a <literal>"RedBoot>"</literal> prompt. The script repeats this |
|
|
1838 process until it is terminated with a signal. |
|
|
1839 </para> |
|
|
1840 |
|
|
1841 </sect1> |
|
|
1842 |
|
|
1843 </chapter> |
|
|
1844 |
|
|
1845 <!-- }}} --> |
|
|
1846 |
|
|
1847 |
|
|
1848 </part> |
