ppp.sgml

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

          the serial cable and the latency of the communicating
          devices. Since it does not rely on any hardware support, this
          flow control mechanism is always available.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
    <para>
    Default value: CYG_PPP_FLOWCTL_HARDWARE
    </para>
  </listitem>
</varlistentry>

<varlistentry>
  <term>refuse_pap</term>
  <listitem>
    <para> If this option is set to 1, then the PPP subsystem will not
    agree to authenticate itself to the peer with PAP. When dialling
    in to a remote server it is normal to authenticate the
    client. There are three ways this can be done, using a
    straightforward login mechanism via the CHAT script, with the
    Password Authentication Protocol (PAP), or with the Challenge
    Handshake Authentication Protocol (CHAP). For PAP to work the
    <structfield>user</structfield> and
    <structfield>passwd</structfield> options must be set to the
    expected values. If they are not, then this option should be set
    to force CHAP authentication.
    </para>
    <para>
    Default value: 0
    </para>
  </listitem>
</varlistentry>

<varlistentry>
  <term>refuse_chap</term>
  <listitem>
    <para> If this option is set to 1, then the PPP subsystem will not
    agree to authenticate itself to the peer with CHAP. CHAP
    authentication will only work if the
    <structfield>passwd</structfield> option has been set to the
    required CHAP secret for the destination server. Otherwise this
    option should be disabled.
    </para>
    <para>
    If both <structfield>refuse_pap</structfield> and
    <structfield>refuse_chap</structfield> are set, then either no
    authentication will be carried out, or it is the responsibility of
    the <command>chat</command> script to do it. If the peer does not
    require any authentication, then the setting of these options is
    irrelevant.
    </para>
    <para>
    Default value: 0
    </para>
  </listitem>
</varlistentry>

<varlistentry>
  <term>baud</term>
  <listitem>
    <para> This option is set to the baud rate at which the serial
    connection should be run. The default value is the rate at which
    modems conventionally operate. This field is an instance of the
    <type>cyg_serial_baud_rate_t</type> enum defined in the
    <literal>serialio.h</literal> header and may only take one of the
    baud rate constants defined in there.
    </para>
    <para>
    Default value: <literal>CYGNUM_SERIAL_BAUD_115200</literal>
    </para>
  </listitem>
</varlistentry>

<varlistentry>
  <term>idle_time_limit</term>
  <listitem>
    <para> This is the number of seconds that the PPP connection may
    be idle before it is shut down automatically.
    </para>
    <para>
    Default value: 60
    </para>
  </listitem>
</varlistentry>

<varlistentry>
  <term>maxconnect</term>
  <listitem>
    <para> This causes the connection to terminate when it has been up
    for this number of seconds. The default value of zero means that
    the connection will stay up indefinitely, until either end
    explicitly brings it down, or the link is lost.
    </para>
    <para>
    Default value: 0
    </para>
  </listitem>
</varlistentry>

<varlistentry>
  <term>our_address</term>
  <listitem>
    <para> This is the IP address, in network byte order, to be
    attached to the local end of the PPP connection. The default value
    of <literal>INADDR_ANY</literal> causes the local address to be
    obtained from the peer.
    </para>
    <para>
    Default value: <literal>INADDR_ANY</literal>
    </para>
  </listitem>
</varlistentry>

<varlistentry>
  <term>his_address</term>
  <listitem>
    <para> This is the IP address, in network byte order, to be
    attached to the remote end of the PPP connection. The default
    value of <literal>INADDR_ANY</literal> causes the remote address
    to be obtained from the peer.
    </para>
    <para>
    Default value: <literal>INADDR_ANY</literal>
    </para>
  </listitem>
</varlistentry>

<varlistentry>
  <term>script</term>
  <listitem>
    <para> This is a pointer to a CHAT script suitable for passing to
    <function>cyg_ppp_chat()</function>. See <xref linkend="ppp-chat">
    for details of the format and contents of this script.
    </para>
    <para>
    Default value: <literal>NULL</literal>
    </para>
  </listitem>
</varlistentry>

<varlistentry>
  <term>user</term>
  <listitem>
    <para> This array contains the user name to be used for PAP
    authentication. This field is not used for CHAP authentication. By
    default the value of this option is set from the
    <literal>CYGPKG_PPP_AUTH_DEFAULT_USER</literal> configuration
    option.
    </para>
    <para>
    Default value: <literal>CYGPKG_PPP_AUTH_DEFAULT_USER</literal>
    </para>
  </listitem>
</varlistentry>

<varlistentry>
  <term>passwd</term>
  <listitem>
    <para> This array contains the password to be used for PAP
    authentication, or the secret to be used during CHAP
    authentication. By default the value of this option is set from
    the <literal>CYGPKG_PPP_AUTH_DEFAULT_PASSWD</literal>
    configuration option.
    </para>
    <para>
    Default value: <literal>CYGPKG_PPP_AUTH_DEFAULT_PASSWD</literal>
    </para>
  </listitem>
</varlistentry>

</variablelist>

    </refsect1>

</refentry>

<!-- }}} -->
<!-- {{{ cyg_ppp_up                       -->

<refentry id="ppp-up">

    <refmeta>
    <refentrytitle>cyg_ppp_up()</refentrytitle>
    </refmeta>

    <refnamediv>
      <refname>cyg_ppp_up</refname>
      <refpurpose>Bring PPP connection up</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
      <funcsynopsis>
        <funcsynopsisinfo>
#include &lt;cyg/ppp/ppp.h&gt;
        </funcsynopsisinfo>
        <funcprototype>
          <funcdef>cyg_ppp_handle_t <function>cyg_ppp_up</function></funcdef>
          <paramdef>char <parameter>*devnam</parameter></paramdef>
          <paramdef>const cyg_ppp_options_t <parameter>*options</parameter></paramdef>
        </funcprototype>
      </funcsynopsis>
    </refsynopsisdiv>

    <refsect1><title id="ppp-up-description">Description</title>
<para>
This function starts up a PPP connection. The
<parameter>devnam</parameter> argument is the name of the device to be
used for the connection, typically <literal>"/dev/ser0"</literal> or
<literal>"/dev/ser1"</literal>. The <structfield>options</structfield>
argument should point to an initialized
<structname>cyg_ppp_options_t</structname> object.
</para>

<para>
The return value will either be zero, indicating a failure, or a
<type>cyg_ppp_handle_t</type> object that may be used as an argument
to other PPP functions.
</para>

<note>
<para>
Although the PPP API is designed to permit several simultaneous
connections to co-exist, at present only one PPP connection is
actually implemented. Any attempt to create a second connection while
there is already one open will fail.
</para>
</note>

</refsect1>

</refentry>

<!-- }}} -->
<!-- {{{ cyg_ppp_down                     -->

<refentry id="ppp-down">

    <refmeta>
    <refentrytitle>cyg_ppp_down()</refentrytitle>
    </refmeta>

    <refnamediv>
      <refname>cyg_ppp_down</refname>
      <refpurpose>Bring PPP connection down</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
      <funcsynopsis>
        <funcsynopsisinfo>
#include &lt;cyg/ppp/ppp.h&gt;
        </funcsynopsisinfo>
        <funcprototype>
          <funcdef>cyg_int32 <function>cyg_ppp_down</function></funcdef>
          <paramdef>cyg_ppp_handle_t <parameter>handle</parameter></paramdef>
        </funcprototype>
      </funcsynopsis>
    </refsynopsisdiv>

    <refsect1><title id="ppp-down-description">Description</title>
<para>
This function brings the PPP connection down. The
<parameter>handle</parameter> argument is the result of a successful
call to <function>cyg_ppp_up()</function>. This function only signals
to the PPP subsystem that the link should be brought down. The link
will be terminated asynchronously. If the application needs to wait
for the link to terminate, then it should call
<function>cyg_ppp_wait_down()</function> after calling
<function>cyg_ppp_down()</function>.
</para>

<para>
The function returns zero if it was able to start the termination of
the PPP connection successfully. It will return -1 if the connection
is not running, or if it could not otherwise start the termination.
</para>

    </refsect1>

</refentry>

<!-- }}} -->  
<!-- {{{ cyg_ppp_wait_up                  -->

<refentry id="ppp-wait-up">

    <refmeta>
    <refentrytitle>cyg_ppp_wait_up()</refentrytitle>
    </refmeta>

    <refnamediv>
      <refname>cyg_ppp_wait_up</refname>
      <refpurpose>Wait for PPP connection to come up</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
      <funcsynopsis>
        <funcsynopsisinfo>
#include &lt;cyg/ppp/ppp.h&gt;
        </funcsynopsisinfo>
        <funcprototype>
          <funcdef>cyg_int32 <function>cyg_ppp_wait_up</function></funcdef>
          <paramdef>cyg_ppp_handle_t <parameter>handle</parameter></paramdef>
        </funcprototype>
      </funcsynopsis>
    </refsynopsisdiv>

    <refsect1><title id="ppp-wait-up-description">Description</title>
<para>
This function waits until the PPP connection is running and then
returns. This is needed because the actual bring up of the connection
happens mostly after the call to <function>cyg_ppp_up()</function>
returns, and may take some time to complete, especially if dialling a
remote server.
</para>

<para>
The result of this call will be zero when the connection is running,
or -1 if the connection failed to start for some reason. If the
connection is already running when this call is made it will return
immediately with a zero result. If the connection is not in the
process of coming up, or has failed, or has terminated, then a result
of -1 will be returned immediately. Thus this function may also be
used to test that the connection is still running at any point.
</para>

    </refsect1>

</refentry>

<!-- }}} -->  
<!-- {{{ cyg_ppp_wait_down                -->

<refentry id="ppp-wait-down">

    <refmeta>
    <refentrytitle>cyg_ppp_wait_down()</refentrytitle>
    </refmeta>

    <refnamediv>
      <refname>cyg_ppp_wait_down</refname>
      <refpurpose>Wait for PPP connection to terminate</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
      <funcsynopsis>
        <funcsynopsisinfo>
#include &lt;cyg/ppp/ppp.h&gt;
        </funcsynopsisinfo>
        <funcprototype>
          <funcdef>void <function>cyg_ppp_wait_down</function></funcdef>
          <paramdef>cyg_ppp_handle_t <parameter>handle</parameter></paramdef>
        </funcprototype>
      </funcsynopsis>
    </refsynopsisdiv>

    <refsect1><title id="ppp-wait-down-description">Description</title>
<para>
This function waits for the PPP connection to terminate. The link may
be terminated with a call to <function>cyg_ppp_down()</function>, by
the remote end, or by the telephone line being dropped or lost. 
</para>

<para>
This function has no return value. If the PPP connection is not
running, or has terminated, it will return. Applications should use
<function>cyg_ppp_wait_up()</function> to test the link state.
</para>

    </refsect1>

</refentry>

<!-- }}} -->  
<!-- {{{ cyg_ppp_chat                     -->

<refentry id="ppp-chat-fn">

    <refmeta>
    <refentrytitle>cyg_ppp_chat()</refentrytitle>
    </refmeta>

    <refnamediv>
      <refname>cyg_ppp_chat</refname>
      <refpurpose>Execute chat script</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
      <funcsynopsis>
        <funcsynopsisinfo>
#include &lt;cyg/ppp/ppp.h&gt;
        </funcsynopsisinfo>
        <funcprototype>
          <funcdef>cyg_int32 <function>cyg_ppp_chat</function></funcdef>
          <paramdef>const char <parameter>*devname</parameter></paramdef>
          <paramdef>const char <parameter>*script[]</parameter></paramdef>
        </funcprototype>
      </funcsynopsis>
    </refsynopsisdiv>

    <refsect1><title id="ppp-chat-description">Description</title>
<para>
This function implements a subset of the automated conversational
scripting as defined by the <command>chat</command> program. The first
argument is the name of the serial device to be used, typically
<literal>"/dev/ser0"</literal> or <literal>"/dev/ser1"</literal>. The
<parameter>script</parameter> argument is a pointer to a zero
terminated array of strings that comprise the chat script. See <xref
linkend="ppp-using"> for an example script, and <xref
linkend="ppp-chat"> for full detail of the script used.
</para>

<para>
The return value of this function will be zero if the chat script
fails for any reason, such as an ABORT or a timeout. If the end of the
script is reached, then the return value will be non-zero.
</para>

<para>
Under normal use this function is called from the PPP subsystem if the
<structname>cyg_ppp_options_t</structname>
<structfield>script</structfield> field is set to a
non-<literal>NULL</literal> value. This function should only be used
directly if the application needs to undertake special processing
between running the chat script, and bringing up the PPP connections.
</para>

    </refsect1>

</refentry>

<!-- }}} -->  


<!--IOCTLs???? -->

</chapter>

<!-- }}} -->
<!-- {{{ Install and Config               -->

<chapter id="ppp-config">
<title>Installing and Configuring PPP</title>

<sect1 id="ppp-config-include">
<title>Including PPP in a Configuration</title>

<para>
PPP is contained entirely within a single
<productname>eCos</productname> package. So to include PPP in a
configuration all you need to do is add that package.
</para>

<para>
In the GUI configuration tool use the
<command>Build->Packages</command> menu item, find the "PPP Support"
package in the left-hand pane and use the <command>Add</command> button
to add it to the list of packages in use in the right-hand pane.
</para>

<para>
In the command-line tool <command>ecosconfig</command>, you can use the
following command during the configuration phase to add the PPP package:
</para>