3 <!-- =============================================================== -->
9 <!-- =============================================================== -->
10 <!-- ####COPYRIGHTBEGIN#### -->
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 <!-- =============================================================== -->
20 <!-- ####COPYRIGHTEND#### -->
21 <!-- =============================================================== -->
22 <!-- #####DESCRIPTIONBEGIN#### -->
24 <!-- ####DESCRIPTIONEND#### -->
25 <!-- =============================================================== -->
31 <title><productname>eCos</productname> PPP User Guide</title>
35 This package provides support for PPP (Point-to-Point Protocol) in the
36 <productname>eCos</productname> FreeBSD TCP/IP networking stack.
42 <chapter id="ppp-features">
43 <title>Features</title>
45 The <productname>eCos</productname> PPP implementation provides the
52 PPP line protocol including VJ compression.
58 LCP, IPCP and CCP control protocols.
64 PAP and CHAP authentication.
70 CHAT subset connection scripting.
76 Modem control line support.
86 <chapter id="ppp-using">
87 <title>Using PPP</title>
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
94 <programlisting width=72>
95 static void ppp_up(void)
97 cyg_ppp_options_t options;
98 cyg_ppp_handle_t ppp_handle;
100 // Bring up the TCP/IP network
101 init_all_network_interfaces();
103 // Initialize the options
104 cyg_ppp_options_init( &options );
107 ppp_handle = cyg_ppp_up( "/dev/ser0", &options );
109 // Wait for it to get running
110 if( cyg_ppp_wait_up( ppp_handle ) == 0 )
115 // Bring PPP link down
116 cyg_ppp_down( ppp_handle );
118 // Wait for connection to go down.
119 cyg_ppp_wait_down( ppp_handle );
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
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.
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.
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.
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>.
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:
180 <programlisting width=72>
182 static char *isp_script[] =
185 "ABORT" , "NO CARRIER" ,
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 ,
197 static void ppp_up(void)
199 cyg_ppp_options_t options;
200 cyg_ppp_handle_t ppp_handle;
202 // Bring up the TCP/IP network
203 init_all_network_interfaces();
205 // Initialize the options
206 cyg_ppp_options_init( &options );
208 options.script = isp_script;
212 ppp_handle = cyg_ppp_up( "/dev/ser0", &options );
214 // Wait for it to get running
215 if( cyg_ppp_wait_up( ppp_handle ) == 0 )
220 // Bring PPP link down
221 cyg_ppp_down( ppp_handle );
223 // Wait for connection to go down.
224 cyg_ppp_wait_down( ppp_handle );
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.
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.
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">
262 <!-- {{{ Interface -->
264 <chapter id="ppp-interface">
265 <title>PPP Interface</title>
267 <!-- {{{ cyg_ppp_options_init -->
269 <refentry id="ppp-options-init">
272 <refentrytitle>cyg_ppp_options_init()</refentrytitle>
276 <refname>cyg_ppp_options_init</refname>
277 <refpurpose>Initialize PPP link options</refpurpose>
283 #include <cyg/ppp/ppp.h>
286 <funcdef>cyg_int32 <function>cyg_ppp_options_init</function></funcdef>
287 <paramdef>cyg_ppp_options_t <parameter>*options</parameter></paramdef>
292 <refsect1><title id="ppp-options-init-description">Description</title>
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.
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.
308 The option fields, their functions and default values are as follows:
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.
332 <term>kdebugflag</term>
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
340 <informaltable frame="all">
341 <tgroup cols="3" colsep="1" rowsep="1" align="left">
345 <entry>BSD Name</entry>
346 <entry>Description</entry>
352 <entry>SC_DEBUG</entry>
353 <entry>Enable debug messages</entry>
357 <entry>SC_LOG_INPKT</entry>
358 <entry>Log contents of good packets received</entry>
362 <entry>SC_LOG_OUTPKT</entry>
363 <entry>Log contents of packets sent</entry>
367 <entry>SC_LOG_RAWIN</entry>
368 <entry>Log all characters received</entry>
372 <entry>SC_LOG_FLUSH</entry>
373 <entry>Log all characters flushed</entry>
385 <term>default_route</term>
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
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.
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
425 <term><literal>CYG_PPP_FLOWCTL_DEFAULT</literal></term>
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.
436 <term><literal>CYG_PPP_FLOWCTL_NONE</literal></term>
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.
446 <term><literal>CYG_PPP_FLOWCTL_HARDWARE</literal></term>
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.
459 <term><literal>CYG_PPP_FLOWCTL_SOFTWARE</literal></term>
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.
473 Default value: CYG_PPP_FLOWCTL_HARDWARE
479 <term>refuse_pap</term>
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.
500 <term>refuse_chap</term>
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.
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
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.
534 Default value: <literal>CYGNUM_SERIAL_BAUD_115200</literal>
540 <term>idle_time_limit</term>
542 <para> This is the number of seconds that the PPP connection may
543 be idle before it is shut down automatically.
552 <term>maxconnect</term>
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.
566 <term>our_address</term>
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.
574 Default value: <literal>INADDR_ANY</literal>
580 <term>his_address</term>
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.
588 Default value: <literal>INADDR_ANY</literal>
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.
601 Default value: <literal>NULL</literal>
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
616 Default value: <literal>CYGPKG_PPP_AUTH_DEFAULT_USER</literal>
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.
631 Default value: <literal>CYGPKG_PPP_AUTH_DEFAULT_PASSWD</literal>
643 <!-- {{{ cyg_ppp_up -->
645 <refentry id="ppp-up">
648 <refentrytitle>cyg_ppp_up()</refentrytitle>
652 <refname>cyg_ppp_up</refname>
653 <refpurpose>Bring PPP connection up</refpurpose>
659 #include <cyg/ppp/ppp.h>
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>
669 <refsect1><title id="ppp-up-description">Description</title>
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.
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.
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.
699 <!-- {{{ cyg_ppp_down -->
701 <refentry id="ppp-down">
704 <refentrytitle>cyg_ppp_down()</refentrytitle>
708 <refname>cyg_ppp_down</refname>
709 <refpurpose>Bring PPP connection down</refpurpose>
715 #include <cyg/ppp/ppp.h>
718 <funcdef>cyg_int32 <function>cyg_ppp_down</function></funcdef>
719 <paramdef>cyg_ppp_handle_t <parameter>handle</parameter></paramdef>
724 <refsect1><title id="ppp-down-description">Description</title>
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>.
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.
747 <!-- {{{ cyg_ppp_wait_up -->
749 <refentry id="ppp-wait-up">
752 <refentrytitle>cyg_ppp_wait_up()</refentrytitle>
756 <refname>cyg_ppp_wait_up</refname>
757 <refpurpose>Wait for PPP connection to come up</refpurpose>
763 #include <cyg/ppp/ppp.h>
766 <funcdef>cyg_int32 <function>cyg_ppp_wait_up</function></funcdef>
767 <paramdef>cyg_ppp_handle_t <parameter>handle</parameter></paramdef>
772 <refsect1><title id="ppp-wait-up-description">Description</title>
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
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.
796 <!-- {{{ cyg_ppp_wait_down -->
798 <refentry id="ppp-wait-down">
801 <refentrytitle>cyg_ppp_wait_down()</refentrytitle>
805 <refname>cyg_ppp_wait_down</refname>
806 <refpurpose>Wait for PPP connection to terminate</refpurpose>
812 #include <cyg/ppp/ppp.h>
815 <funcdef>void <function>cyg_ppp_wait_down</function></funcdef>
816 <paramdef>cyg_ppp_handle_t <parameter>handle</parameter></paramdef>
821 <refsect1><title id="ppp-wait-down-description">Description</title>
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.
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.
839 <!-- {{{ cyg_ppp_chat -->
841 <refentry id="ppp-chat-fn">
844 <refentrytitle>cyg_ppp_chat()</refentrytitle>
848 <refname>cyg_ppp_chat</refname>
849 <refpurpose>Execute chat script</refpurpose>
855 #include <cyg/ppp/ppp.h>
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>
865 <refsect1><title id="ppp-chat-description">Description</title>
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.
878 The return value of this function will be zero if the chat script
879 fails for any reason, such as an ABORT or a timeout. If the end of the
880 script is reached, then the return value will be non-zero.
884 Under normal use this function is called from the PPP subsystem if the
885 <structname>cyg_ppp_options_t</structname>
886 <structfield>script</structfield> field is set to a
887 non-<literal>NULL</literal> value. This function should only be used
888 directly if the application needs to undertake special processing
889 between running the chat script, and bringing up the PPP connections.
904 <!-- {{{ Install and Config -->
906 <chapter id="ppp-config">
907 <title>Installing and Configuring PPP</title>
909 <sect1 id="ppp-config-include">
910 <title>Including PPP in a Configuration</title>
913 PPP is contained entirely within a single
914 <productname>eCos</productname> package. So to include PPP in a
915 configuration all you need to do is add that package.
919 In the GUI configuration tool use the
920 <command>Build->Packages</command> menu item, find the "PPP Support"
921 package in the left-hand pane and use the <command>Add</command> button
922 to add it to the list of packages in use in the right-hand pane.
926 In the command-line tool <command>ecosconfig</command>, you can use the
927 following command during the configuration phase to add the PPP package:
930 <programlisting width=72>
937 In addition to the PPP package you will also need to have the
938 <literal>"Network"</literal> package and the <literal>"Serial Device
939 Drivers"</literal> package in the configuration. The dependencies and
940 requirements of the networking package are such that it is strongly
941 recommended that you start with the <literal>net</literal> template.
945 See the <productname>eCos</productname> User Guide for full details on
946 how to configure and build <productname>eCos</productname>.
952 <sect1 id="ppp-config-config">
953 <title>Configuring PPP</title>
955 The PPP package contains a number of configuration options that may be
956 changed to affect its behaviour.
961 <term>CYGNUM_PPP_PPPD_THREAD_PRIORITY</term>
964 The PPP system contains two threads, One is used for receiving
965 data from the link and processing control packets. The other is
966 used to transmit data asynchronously to the link when it cannot be
967 completed synchronously. The receive thread runs at the priority
968 given here, and the transmit thread runs at the next lower
969 priority. The exact priority needed here depends on the
970 importance of the PPP subsystem relative to the rest of the
971 system. The default is to put it in the middle of the priority
972 range to provide reasonable response without impacting genuine
973 high priority threads.
976 Default value: <literal>CYGNUM_KERNEL_SCHED_PRIORITIES/2</literal>
982 <term>CYGPKG_PPP_DEBUG_WARN_ONLY</term>
985 The runtime <varname>debug</varname> option enables logging of
986 high level debug messages. Too many of these can interfere with
987 the PPP device and may result in missed messages. This is because
988 these messages are emitted via the diag_printf() mechanism, which
989 disables interrupts while it prints. By default, therefore, we
990 only report errors and warnings, and not all events. Setting this
991 option to zero will enable the logging of all events.
994 Default value: <literal>1</literal>
1000 <term>CYGPKG_PPP_AUTH_DEFAULT_USER</term>
1003 This option gives the default value for the user name used to
1004 initialize the <structfield>user</structfield> field in the PPP
1008 Default value: <literal>"eCos"</literal>
1014 <term>CYGPKG_PPP_AUTH_DEFAULT_PASSWD</term>
1017 This option gives the default value for the password used to
1018 initialize the <structfield>passwd</structfield> field in the PPP
1022 Default value: <literal>"secret"</literal>
1028 <term>CYGPKG_PPP_DEFAULT_DIALUP_NUMBER</term>
1031 This option provides a default dialup number for use in
1032 <command>chat</command> scripts. This value is not used anywhere
1033 in the PPP package, but is provided to complete the information
1034 needed, alongside the user name and password, for accessing a
1035 typical dialup server.
1038 Default value: <literal>"5551234"</literal>
1044 <term>CYGPKG_PPP_PAP</term>
1047 This component enables the inclusion of PAP authentication
1057 <term>CYGPKG_PPP_CHAP</term>
1060 This component enables the inclusion of CHAT authentication
1070 <term>CYGPKG_PPP_COMPRESSION</term>
1073 This component provides control over PPP compression
1074 features. WARNING: at present there are problems with this option,
1075 and and in any case the compression code needs to allocate large
1076 amounts of memory. Hence this option is currently disabled and
1086 <term>PPP_BSDCOMP</term>
1089 This option enables inclusion of BSD compression into the PPP
1099 <term>PPP_DEFLATE</term>
1102 This option enables inclusion of ZLIB compression into the PPP
1112 <term>CYGPKG_PPP_CHAT</term>
1115 This component enables the inclusion of a simple scripting system
1116 to bring up PPP connections. It implements a subset of the
1117 <command>chat</command> scripting language.
1126 <term>CYGNUM_PPP_CHAT_ABORTS_MAX</term>
1129 This option defines the maximum number of <literal>ABORT</literal>
1130 strings that the CHAT system will store.
1139 <term>CYGNUM_PPP_CHAT_ABORTS_SIZE</term>
1142 This option defines the maximum size of each
1143 <literal>ABORT</literal> strings that the <command>chat</command>
1153 <term>CYGNUM_PPP_CHAT_STRING_LENGTH</term>
1156 This option defines the maximum size of any expect or reply
1157 strings that the <command>chat</command> system will be given.
1166 <term>CYGPKG_PPP_TEST_DEVICE</term>
1169 This option defines the serial device to be used for PPP test
1173 Default value: <literal>"/dev/ser0"</literal>
1179 <term>CYGPKG_PPP_TESTS_AUTOMATE</term>
1182 This option enables automated testing features in certain test
1183 programs. These programs will interact with a test server at the
1184 remote end of the serial link to run a variety of tests in
1185 different conditions. Without this option most tests default to
1186 running a single test instance and are suitable for being run by
1187 hand for debugging purposes.
1196 <term>CYGDAT_PPP_TEST_BAUD_RATES</term>
1199 This option supplies a list of baud rates at which certain tests
1200 will run if the <literal>CYGPKG_PPP_TESTS_AUTOMATE</literal>
1204 Default value: <literal>"CYGNUM_SERIAL_BAUD_19200,CYGNUM_SERIAL_BAUD_38400,CYGNUM_SERIAL_BAUD_57600,CYGNUM_SERIAL_BAUD_115200"</literal>
1222 <chapter id="ppp-chat">
1223 <title>CHAT Scripts</title>
1225 The automated conversational scripting supported by the
1226 <productname>eCos</productname> PPP package is a subset of the
1227 scripting language provided by the <command>chat</command> command
1228 found on most UNIX and Linux systems.
1232 Unlike the <command>chat</command> command, the
1233 <productname>eCos</productname> <function>cyg_ppp_chat()</function>
1234 function takes as a parameter a zero-terminated array of pointers to
1235 strings. In most programs this will be defined by means of an
1236 initializer for a static array, although there is nothing to stop the
1237 application constructing it at runtime. A simple script would be
1241 <programlisting width=72>
1243 static char *chat_script[] =
1246 "ABORT" , "NO CARRIER" ,
1248 "ogin:--ogin:" , "ppp" ,
1249 "ssword:" , "hithere" ,
1256 The following sections have been abstracted from the public domain
1257 documentation for the <command>chat</command> command.
1261 <sect1 id="ppp-chat-script">
1262 <title>Chat Script</title>
1264 A script consists of one or more "expect-send" pairs of
1265 strings, separated by spaces, with an optional "subexpect-
1266 subsend" string pair, separated by a dash as in the following
1270 <programlisting width=72>
1272 "ogin:--ogin:" , "ppp" ,
1273 "ssword:" , "hello2u2" ,
1279 This script fragment indicates that the
1280 <function>cyg_ppp_chat()</function> function should expect the
1281 string "ogin:". If it fails to receive a login prompt within
1282 the time interval allotted, it is to send a carriage return
1283 to the remote and then expect the string "ogin:" again. If
1284 the first "ogin:" is received then the carriage return is not
1288 Once it received the login prompt the
1289 <function>cyg_ppp_chat()</function> function will send the
1290 string "ppp" and then expect the prompt "ssword:". When it
1291 receives the prompt for the password, it will send the password
1295 A carriage return is normally sent following the reply string.
1296 It is not expected in the "expect" string unless it is
1297 specifically requested by using the "\r" character sequence.
1300 The expect sequence should contain only what is needed to
1301 identify the string. It should not contain variable
1302 information. It is generally not acceptable to look for time
1303 strings, network identification strings, or other variable
1304 pieces of data as an expect string.
1307 To help correct for characters which may be corrupted during
1308 the initial sequence, look for the string "ogin:" rather than
1309 "login:". It is possible that the leading "l" character may be
1310 received in error and you may never find the string even though
1311 it was sent by the system. For this reason, scripts look for
1312 "ogin:" rather than "login:" and "ssword:" rather than
1316 A very simple script might look like this:
1318 <programlisting width=72>
1321 "ssword:" , " hello2u2" ,
1327 In other words, expect "....ogin:", send "ppp", expect "...ssword:",
1331 In actual practice, simple scripts are rare. At the very least,
1332 you should include sub-expect sequences should the original
1333 string not be received. For example, consider the following
1336 <programlisting width=72>
1338 "ogin:--ogin:" , "ppp" ,
1339 "ssword:" , "hello2u2",
1344 This would be a better script than the simple one used earlier.
1345 This would look for the same "login:" prompt, however, if one
1346 was not received, a single return sequence is sent and then it
1347 will look for "login:" again. Should line noise obscure the
1348 first login prompt then sending the empty line will usually
1349 generate a login prompt again.
1354 <sect1 id="ppp-chat-abort">
1355 <title>ABORT Strings</title>
1358 Many modems will report the status of the call as a
1359 string. These strings may be CONNECTED or NO CARRIER or
1360 BUSY. It is often desirable to terminate the script should the
1361 modem fail to connect to the remote. The difficulty is that a
1362 script would not know exactly which modem string it may
1363 receive. On one attempt, it may receive BUSY while the next
1364 time it may receive NO CARRIER.
1367 These "abort" strings may be specified in the script using
1368 the ABORT sequence. It is written in the script as in the
1371 <programlisting width=72>
1374 "ABORT" , "NO CARRIER" ,
1376 "OK" , "ATDT5551212" ,
1382 This sequence will expect nothing; and then send the string
1383 ATZ. The expected response to this is the string OK. When it
1384 receives OK, it sends the string ATDT5551212 to dial the
1385 telephone. The expected string is CONNECT. If the string
1386 CONNECT is received the remainder of the script is
1387 executed. However, should the modem find a busy telephone, it
1388 will send the string BUSY. This will cause the string to match
1389 the abort character sequence. The script will then fail because
1390 it found a match to the abort string. If it received the string
1391 NO CARRIER, it will abort for the same reason. Either string
1392 may be received. Either string will terminate the chat script.
1397 <sect1 id="ppp-chat-timeout">
1398 <title>TIMEOUT</title>
1400 The initial timeout value is 45 seconds.
1401 To change the timeout value for the next expect string,
1402 the following example may be used:
1404 <programlisting width=72>
1407 "OK" , "ATDT5551212" ,
1410 "ogin:--ogin:" , "ppp" ,
1412 "assword:" , "hello2u2" ,
1417 This will change the timeout to 10 seconds when it expects the
1418 login: prompt. The timeout is then changed to 5 seconds when
1419 it looks for the password prompt.
1422 The timeout, once changed, remains in effect until it is
1428 <sect1 id="ppp-chat-eot">
1429 <title>Sending EOT</title>
1431 The special reply string of EOT indicates that the chat
1432 program should send an EOT character to the remote. This
1433 is normally the End-of-file character sequence. A return
1434 character is not sent following the EOT. The EOT sequence
1435 may be embedded into the send string using the sequence
1436 "\x04" (i.e. a Control-D character).
1440 <sect1 id="ppp-chat-escape">
1441 <title>Escape Sequences</title>
1443 Most standard <command>chat</command> escape sequences can be replaced
1444 with standard C string escapes such as '\r', '\n', '\t'
1445 etc. Additional escape sequences may be embedded in the expect or
1446 reply strings by introducing them with <emphasis>two</emphasis>
1456 Suppresses the newline at the end of the reply string. This is the
1457 only method to send a string without a trailing return character. It
1458 must be at the end of the send string. For example, the sequence
1459 "hello\\c" will simply send the characters h, e, l, l, o. (not valid
1472 <!-- {{{ Drivers -->
1474 <chapter id="ppp-drivers">
1475 <title>PPP Enabled Device Drivers</title>
1477 For PPP to function fully over a serial device, its driver must
1478 implement certain features. At present not all
1479 <productname>eCos</productname> serial drivers implement these
1480 features. A driver indicates that it supports a certain feature by
1481 including an <literal>"implements"</literal> line in its CDL for the
1482 following interfaces:
1488 <term><literal>CYGINT_IO_SERIAL_FLOW_CONTROL_HW</literal></term>
1491 This interface indicates that the driver implements hardware flow
1492 control using the RTS and CTS lines. When data is being transferred
1493 over high speed data lines, it is essential that flow control be used
1494 to prevent buffer overrun.
1497 The PPP subsystem functions best with hardware flow control. If this
1498 is not available, then it can be configured to use software flow
1499 control. Since software flow control is implemented by the device
1500 independent part of the serial device infrastructure, it is available
1501 for all serial devices. However, this will have an effect on the
1502 performance and reliability of the PPP link.
1509 <term><literal>CYGINT_IO_SERIAL_LINE_STATUS_HW</literal></term>
1512 This interface indicates that the driver implements a callback
1513 interface for indicating the status of various RS232 control lines. Of
1514 particular interest here is the ability to detect changes in the
1515 Carrier Detect (CD) line. Not all drivers that implement this
1516 interface can indicate CD status.
1519 This functionality is only needed if it is important that the link be
1520 dropped immediately a telephone connection fails. Without it, a
1521 connection will only be dropped after it times out. This may be
1522 acceptable in many situations.
1530 At the time of writing, the serial device drivers for the following
1531 platforms implement some or all of the required functionality:
1538 All drivers that use the generic 16x5x driver implement all functions:
1541 <listitem><para>ARM CerfPDA</para></listitem>
1542 <listitem><para>ARM IQ80321</para></listitem>
1543 <listitem><para>ARM PID</para></listitem>
1544 <listitem><para>ARM IOP310</para></listitem>
1545 <listitem><para>i386 PC</para></listitem>
1546 <listitem><para>MIPS Atlas</para></listitem>
1547 <listitem><para>MIPS Ref4955</para></listitem>
1548 <listitem><para>SH3 SE77x9</para></listitem>
1554 The following drivers implement flow control but either do not support
1555 line status callbacks, or do not report CD changes:
1558 <listitem><para>SH4 SCIF</para></listitem>
1559 <listitem><para>A&M AdderI</para></listitem>
1560 <listitem><para>A&M AdderII</para></listitem>
1566 All other drivers can support software flow control only.
1578 <chapter id="ppp-tests">
1579 <title>Testing</title>
1583 <title>Test Programs</title>
1586 There are a number of test programs supplied with the PPP
1587 subsystem. By default all of these tests use the device configured by
1588 <literal>CYGPKG_PPP_TEST_DEVICE</literal> as the PPP link device.
1594 <term><literal>ppp_up</literal></term>
1597 This test just brings up the PPP link on
1598 <literal>CYGPKG_PPP_TEST_DEVICE</literal> and waits until the remote end brings
1599 it back down. No modem lines are used and the program expects a PPP
1600 connection to be waiting on the other end of the line. Typically the
1601 remote end will test the link using <command>ping</command> or access
1602 the HTTP system monitor if it is present.
1605 If <literal>CYGPKG_PPP_TESTS_AUTOMATE</literal> is set, then this test
1606 attempts to bring PPP up at each of the baud rates specified in
1607 <literal>CYGDAT_PPP_TEST_BAUD_RATES</literal>. If it is not set then
1608 it will just bring the connection up at 115200 baud.
1614 <term><literal>ppp_updown</literal></term>
1617 This test brings the PPP link up on
1618 <literal>CYGPKG_PPP_TEST_DEVICE</literal> and attempts to
1619 <command>ping</command> the remote end of the link. Once the pings
1620 have finished, the link is then brought down.
1623 If <literal>CYGPKG_PPP_TESTS_AUTOMATE</literal> is set, then this test
1624 attempts to bring PPP up at each of the baud rates specified in
1625 <literal>CYGDAT_PPP_TEST_BAUD_RATES</literal>. If it is not set then
1626 it will just bring the connection up at 115200 baud.
1632 <term><literal>chat</literal></term>
1635 This test does not bring the PPP link up but simply executes a chat
1636 script. It expects a server at the remote end of the link to supply
1637 the correct responses.
1640 This program expects the <command>test_server.sh</command> script to
1641 be running on the remote end and attempts several different tests,
1642 expecting a variety of different responses for each.
1648 <term><literal>ppp_auth</literal></term>
1651 This test attempts to bring up the PPP link under a variety of
1652 different authentication conditions. This includes checking that both
1653 PAP and CHAP authentication work, and that the connection is rejected
1654 when the incorrect authentication protcol or secrets are used.
1657 This test expects the <command>test_server.sh</command> script to be
1658 running on the remote end. For this test to work the <filename>/etc/ppp/pap-secrets</filename> file on the remote
1659 end should contain the following two lines:
1661 <programlisting width=72>
1663 eCosPAP * secretPAP *
1666 The <filename>/etc/ppp/chap-secrets</filename> file should contain:
1668 <programlisting width=72>
1670 eCosCHAP * secretCHAP *
1676 <term><literal>isp</literal></term>
1679 This test expects the serial test device to be connected to a Hayes
1680 compatible modem. The test dials the telephone number given in
1681 <literal>CYGPKG_PPP_DEFAULT_DIALUP_NUMBER</literal> and attempts to
1682 log on to an ISP using the user name and password supplied in
1683 <literal>CYGPKG_PPP_AUTH_DEFAULT_USER</literal> and
1684 <literal>CYGPKG_PPP_AUTH_DEFAULT_PASSWD</literal>. Once the PPP
1685 connection has been made, the program then attempts to ping a number
1686 of well known addresses.
1689 Since this test is designed to interact with an ISP, it does not run
1690 within the automated testing system.
1696 <term><literal>tcp_echo</literal></term>
1699 This is a version of the standard network <command>tcp_echo</command>
1700 test that brings up the PPP connection before waiting for the
1701 <command>tcp_sink</command> and <command>tcp_source</command> programs
1702 to connect. It is expected that at least one of these programs will
1703 connect via the PPP link. However, if another network interface is
1704 present, such as an ethernet device, then one may connect via that
1708 While this test is supported by the <command>test_server.sh</command>
1709 script, it runs for such a long time that it should not normally be
1710 used during automated testing.
1716 <term><literal>nc_test_slave</literal></term>
1719 This is a version of the standard network
1720 <command>nc_test_slave</command> test that brings up the PPP
1721 connection before waiting for the <command>nc_test_master</command>
1722 program to connect. It is expected that the master will connect via
1726 While this test is supported by the <command>test_server.sh</command>
1727 script, it runs for such a long time that it should not normally be
1728 used during automated testing.
1737 <sect1 id="ppp-test-script">
1738 <title>Test Script</title>
1741 The PPP package additionally contains a shell script
1742 (<command>test_server.sh</command>) that may be used to operate the
1743 remote end of a PPP test link.
1747 The script may be invoked with the following arguments:
1753 <term><literal>--dev=<devname></literal></term>
1756 This mandatory option gives the name of the device to be used for the
1757 PPP link. Typically <literal>"/dev/ttyS0"</literal> or
1758 <literal>"/dev/ttyS1"</literal>.
1764 <term><literal>--myip=<ipaddress></literal></term>
1767 This mandatory option gives the IP address to be attached to this end
1774 <term><literal>--hisip=<ipaddress></literal></term>
1777 This mandatory option gives the IP address to be attached to the
1778 remote (test target) end of the PPP link.
1784 <term><literal>--baud=<baud_rate></literal></term>
1787 This option gives the baud rate at which the PPP link is to be run. If
1788 absent then the link will run at the value set for
1789 <literal>--redboot-baud</literal>.
1795 <term><literal>--redboot</literal></term>
1798 If this option is present then the script will look for a
1799 <literal>"RedBoot>"</literal> prompt between test runs. This is
1800 necessary if the serial device being used for testing is also used by
1807 <term><literal>--redboot-baud=<baud_rate></literal></term>
1810 This option gives the baud rate at which the search for the RedBoot
1811 prompt will be made. If absent then the link will run at 38400 baud.
1817 <term><literal>--debug</literal></term>
1820 If this option is present, then the script will print out some
1821 additional debug messages while it runs.
1829 This script operates as follows: If the <literal>--redboot</literal>
1830 option is set it sets the device baud rate to the RedBoot baud rate
1831 and waits until a <literal>"RedBoot>"</literal> prompt is encountered.
1832 It then sets the baud rate to the value given by the
1833 <literal>--baud</literal> option and reads lines from the device until
1834 a recognizable test announce string is read. It then executes an
1835 appropriate set of commands to satisfy the test. This usually means
1836 bringing up the PPP link by running <command>pppd</command> and maybe
1837 executing various commands. It then either terminates the link itself,
1838 or waits for the target to terminate it. It then goes back to looking
1839 for another test announce string. If a string of the form
1840 <literal>"BAUD:XXX"</literal> is received then the baud rate is
1841 changed depending on the <literal>XXX</literal> value. If a
1842 <literal>"FINISH"</literal> string is received it returns to waiting
1843 for a <literal>"RedBoot>"</literal> prompt. The script repeats this
1844 process until it is terminated with a signal.