ppp.sgml

eCos/RedBoot for勤研ARM AnywhereII(4510) 含全部源代码

<!-- {{{ Banner                         -->

<!-- =============================================================== -->
<!--                                                                 -->
<!--     ppp.sgml                                                    -->
<!--                                                                 -->
<!--     eCos PPP code                                               -->
<!--                                                                 -->
<!-- =============================================================== -->
<!-- ####COPYRIGHTBEGIN####                                          -->
<!--                                                                 -->
<!-- =============================================================== -->
<!-- Copyright (C) 2003, 2004 eCosCentric Ltd.                             -->
<!-- This material may be distributed only subject to the terms      -->
<!-- and conditions set forth in the Open Publication License, v1.0  -->
<!-- or later (the latest version is presently available at          -->
<!-- http://www.opencontent.org/openpub/)                            -->
<!-- =============================================================== -->
<!--                                                                 -->      
<!-- ####COPYRIGHTEND####                                            -->
<!-- =============================================================== -->
<!-- #####DESCRIPTIONBEGIN####                                       -->
<!--                                                                 -->
<!-- ####DESCRIPTIONEND####                                          -->
<!-- =============================================================== -->

<!-- }}} -->


<part id="ppp">
<title><productname>eCos</productname> PPP User Guide</title>

<partintro>
<para>
This package provides support for PPP (Point-to-Point Protocol) in the
<productname>eCos</productname> FreeBSD TCP/IP networking stack.
</para>
</partintro>

<!-- {{{ Features                         -->

<chapter id="ppp-features">
<title>Features</title>
<para>
The <productname>eCos</productname> PPP implementation provides the
following features:
</para>
<itemizedlist>

<listitem>
<para>
PPP line protocol including VJ compression.
</para>
</listitem>

<listitem>
<para>
LCP, IPCP and CCP control protocols.
</para>
</listitem>

<listitem>
<para>
PAP and CHAP authentication.
</para>
</listitem>

<listitem>
<para>
CHAT subset connection scripting.
</para>
</listitem>

<listitem>
<para>
Modem control line support.
</para>
</listitem>

</itemizedlist>
</chapter>

<!-- }}} -->
<!-- {{{ Using                            -->

<chapter id="ppp-using">
<title>Using PPP</title>
<para>
Before going into detail, let's look at a simple example of how the
<productname>eCos</productname> PPP package is used. Consider the
following example:
</para>

<programlisting width=72>
static void ppp_up(void)
{
    cyg_ppp_options_t options;
    cyg_ppp_handle_t ppp_handle;

    // Bring up the TCP/IP network
    init_all_network_interfaces();

    // Initialize the options
    cyg_ppp_options_init( &amp;options );

    // Start up PPP
    ppp_handle = cyg_ppp_up( "/dev/ser0", &amp;options );

    // Wait for it to get running
    if( cyg_ppp_wait_up( ppp_handle ) == 0 )
    {
        // Make use of PPP
        use_ppp();

        // Bring PPP link down
        cyg_ppp_down( ppp_handle );

        // Wait for connection to go down.
        cyg_ppp_wait_down( ppp_handle );
    }
}
</programlisting>

<para>
This is a simple example of how to bring up a simple PPP connection to
another computer over a directly connected serial line. The other end
is assumed to already be running PPP on the line and waiting for a
connection.
</para>

<para>
The first thing this code does is to call
<function>init_all_network_interfaces()</function> to bring up the
TCP/IP stack and initialize any other network interfaces. It then
calls <function>cyg_ppp_options_init()</function> to initialize the
PPP options structure to the defaults. As it happens, the default
options are exactly what we want for this example, so we don't need to
make any further changes. We go straight on to bring the PPP interface
up by calling <function>cyg_ppp_up()</function>. The arguments to this
function give the name of the serial device to use, in this case
<literal>"/dev/ser0"</literal>, and a pointer to the options.
</para>

<para>
When <function>cyg_ppp_up()</function> returns, it passes back a
handle to the PPP connection which is to be used in other calls.  The
PPP link will not necessarily have been fully initialized at this
time. There is a certain amount of negotiation that goes on between
the ends of a PPP link before it is ready to pass packets. An
application can wait until the link is ready by calling
<function>cyg_ppp_wait_up()</function>, which returns
zero if the link is up and running, or
<literal>-1</literal> if it has gone down or failed to come up.
</para>

<para>
After a successful return from <function>cyg_ppp_wait_up()</function>,
the application may make use of the PPP connection. This is
represented here by the call to <function>use_ppp()</function> but
it may, of course, be accessed by any thread. While the connection is
up the application may use the standard socket calls to make or accept
network connections and transfer data in the normal way.
</para>

<para>
Once the application has finished with the PPP link, it can bring it
down by calling <function>cyg_ppp_down()</function>. As with bringing
the connection up, this call is asynchronous, it simply informs the
PPP subsystem to start bringing the link down. The application can
wait for the link to go down fully by calling
<function>cyg_ppp_wait_down()</function>.
</para>

<para>
That example showed how to use PPP to connect to a local peer. PPP is
more often used to connect via a modem to a remote server, such as an
ISP. The following example shows how this works:
</para>

<programlisting width=72>

static char *isp_script[] =
{
    "ABORT"             ,       "BUSY"                                  ,
    "ABORT"             ,       "NO CARRIER"                            ,
    "ABORT"             ,       "ERROR"                                 ,
    ""                  ,       "ATZ"                                   ,
    "OK"                ,       "AT S7=45 S0=0 L1 V1 X4 &amp;C1 E1 Q0"      ,
    "OK"                ,       "ATD" CYGPKG_PPP_DEFAULT_DIALUP_NUMBER  ,
    "ogin:--ogin:"      ,       CYGPKG_PPP_AUTH_DEFAULT_USER            ,
    "assword:"          ,       CYGPKG_PPP_AUTH_DEFAULT_PASSWD          ,
    "otocol:"           ,       "ppp"                                   ,
    "HELLO"             ,       "\\c"                                   ,
    0
};

static void ppp_up(void)
{
    cyg_ppp_options_t options;
    cyg_ppp_handle_t ppp_handle;

    // Bring up the TCP/IP network
    init_all_network_interfaces();

    // Initialize the options
    cyg_ppp_options_init( &amp;options );

    options.script = isp_script;
    options.modem  = 1;

    // Start up PPP
    ppp_handle = cyg_ppp_up( "/dev/ser0", &amp;options );

    // Wait for it to get running
    if( cyg_ppp_wait_up( ppp_handle ) == 0 )
    {
        // Make use of PPP
        use_ppp();

        // Bring PPP link down
        cyg_ppp_down( ppp_handle );

        // Wait for connection to go down.
        cyg_ppp_wait_down( ppp_handle );
    }
}
</programlisting>

<para>
The majority of this code is exactly the same as the previous
example. The main difference is in the setting of a couple of options
before calling <function>cyg_ppp_up()</function>. The
<structfield>script</structfield> option is set to point to a CHAT
script to manage the setup of the connection. The
<structfield>modem</structfield> option is set to cause the PPP system
to make use of the modem control lines.
</para>

<para>
During the PPP bring-up a call will be made to
<function>cyg_ppp_chat()</function> to run the CHAT script (see <xref
linkend="ppp-chat">). In the example this script sets up various modem
options and then dials a number supplied as part of the PPP package
configuration (see <xref linkend="ppp-config">). When the connection
has been established, the script log on to the server, using a name
and password also supplied by the configuration, and then starts PPP
on the remote end. If this script succeeds the PPP connection will be
brought up and will then function as expected.
</para>

<para>
The <structfield>modem</structfield> option causes the PPP system to
make use of the modem control lines. In particular it waits for
<literal>Carrier Detect</literal> to be asserted, and will bring the
link down if it is lost. See <xref linkend="ppp-options-init">
for more details.
</para>

</chapter>

<!-- }}} -->
<!-- {{{ Interface                        -->

<chapter id="ppp-interface">
<title>PPP Interface</title>

<!-- {{{ cyg_ppp_options_init             -->

<refentry id="ppp-options-init">

    <refmeta>
    <refentrytitle>cyg_ppp_options_init()</refentrytitle>
    </refmeta>

    <refnamediv>
      <refname>cyg_ppp_options_init</refname>
      <refpurpose>Initialize PPP link options</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
      <funcsynopsis>
        <funcsynopsisinfo>
#include &lt;cyg/ppp/ppp.h&gt;
        </funcsynopsisinfo>
        <funcprototype>
          <funcdef>cyg_int32 <function>cyg_ppp_options_init</function></funcdef>
          <paramdef>cyg_ppp_options_t <parameter>*options</parameter></paramdef>
        </funcprototype>
      </funcsynopsis>
    </refsynopsisdiv>

    <refsect1><title id="ppp-options-init-description">Description</title>
<para>
This function initializes the PPP options, pointed to by the
<parameter>options</parameter> parameter, to the default state. Once
the defaults have been initialized, application code may adjust them
by assigning new values to the the fields of the
<structname>cyg_ppp_options_t</structname> structure.
</para>

<para>
This function returns zero if the options were initialized
successfully. It returns -1 if the <parameter>options</parameter>
argument is NULL, or the options could not be initialized.
</para>

<para>
The option fields, their functions and default values are as follows:
</para>

<variablelist>

<varlistentry>
  <term>debug</term>
  <listitem>
    <para> If set to 1 this enables the reporting of debug messages
    from the PPP system. These will be generated using
    <function>diag_printf()</function> and will appear on the standard
    debug channel. Note that <function>diag_printf()</function>
    disables interrupts during output: this may cause the PPP link
    device to overrun and miss characters. It is quite possible for
    this option to cause errors and even make the PPP link fail
    completely. Consequently, this option should be used with care.
    </para>
    <para>
    Default value: 0
    </para>
  </listitem>
</varlistentry>

<varlistentry>
  <term>kdebugflag</term>
  <listitem>
    <para> This five bit field enables low level debugging messages from
    the PPP device layer in the TCP/IP stack. As with the
    <structfield>debug</structfield> option, this may result in missed
    characters and cause errors. The bits of the field have the
    following meanings:
    </para>
    <informaltable frame="all">
      <tgroup cols="3" colsep="1" rowsep="1" align="left">
        <thead>
          <row>
            <entry>Bit</entry>
            <entry>BSD Name</entry>
            <entry>Description</entry>
          </row>
        </thead>
        <tbody>
          <row>
            <entry>0x01</entry>
            <entry>SC_DEBUG</entry>
            <entry>Enable debug messages</entry>
          </row>
          <row>
            <entry>0x02</entry>
            <entry>SC_LOG_INPKT</entry>
            <entry>Log contents of good packets received</entry>
          </row>
          <row>
            <entry>0x04</entry>
            <entry>SC_LOG_OUTPKT</entry>
            <entry>Log contents of packets sent</entry>
          </row>
          <row>
            <entry>0x08</entry>
            <entry>SC_LOG_RAWIN</entry>
            <entry>Log all characters received</entry>
          </row>
          <row>
            <entry>0x10</entry>
            <entry>SC_LOG_FLUSH</entry>
            <entry>Log all characters flushed</entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>
    <para>
    Default value: 0
    </para>
  </listitem>
</varlistentry>

<varlistentry>
  <term>default_route</term>
  <listitem>
    <para> If set to 1 this option causes the PPP subsystem to install
    a default route in the TCP/IP stack's routing tables using the
    peer as the gateway. This entry will be removed when the PPP link
    is broken. If there is already an existing working network
    connection, such as an ethernet device, then there may already be
    a default route established. If this is the case, then this option
    will have no effect.
    </para>
    <para>
    Default value: 1
    </para>
  </listitem>
</varlistentry>

<varlistentry>
  <term>modem</term>
  <listitem>
    <para> If this option is set to 1, then the modem lines will be
    used during the connection. Specifically, the PPP subsystem will
    wait until the <literal>carrier detect</literal> signal is
    asserted before bringing up the PPP link, and will take the PPP
    link down if this signal is de-asserted.
    </para>
    <para>
    Default value: 0
    </para>
  </listitem>
</varlistentry>

<varlistentry>
  <term>flowctl</term>
  <listitem>
    <para> This option is used to specify the mechanism used to
    control data flow across the serial line. It can take one of the
    following values:
    </para>
    <variablelist>
      <varlistentry>
        <term><literal>CYG_PPP_FLOWCTL_DEFAULT</literal></term>
        <listitem>
          <para>
          The flow control mechanism is not changed and is left at
          whatever value was set before bringing PPP up. This allows
          a non-standard flow control mechanism to be used, or for it to
          be chosen and set by some other means.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><literal>CYG_PPP_FLOWCTL_NONE</literal></term>
        <listitem>
          <para>
          Flow control is turned off. It is not recommended that this
          option be used unless the baud rate is set low or the two
          communicating machines are particularly fast.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><literal>CYG_PPP_FLOWCTL_HARDWARE</literal></term>
        <listitem>
          <para>
          Use hardware flow control via the RTS/CTS lines. This is the
          most effective flow control mechanism and should always be
          used if available. Availability of this mechanism depends on
          whether the serial device hardware has the ability to control
          these lines, whether they have been connected to the socket
          pins and whether the device driver has the necessary support.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><literal>CYG_PPP_FLOWCTL_SOFTWARE</literal></term>
        <listitem>
          <para>
          Use software flow control by embedding XON/XOFF characters in
          the data stream. This is somewhat less effective that hardware
          flow control since it is subject to the propagation time of