Subversion Repositories openrisc

This package provides support for PPP (Point-to-Point Protocol) in the

eCos FreeBSD TCP/IP networking stack.

The eCos PPP implementation provides the

following features:

PPP line protocol including VJ compression.

LCP, IPCP and CCP control protocols.

PAP and CHAP authentication.

CHAT subset connection scripting.

Modem control line support.

Before going into detail, let's look at a simple example of how the

eCos PPP package is used. Consider the

following example:

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( &options );

    // Start up PPP

    ppp_handle = cyg_ppp_up( "/dev/ser0", &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 );

    }

}

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.

The first thing this code does is to call

init_all_network_interfaces() to bring up the

TCP/IP stack and initialize any other network interfaces. It then

calls cyg_ppp_options_init() 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 cyg_ppp_up(). The arguments to this

function give the name of the serial device to use, in this case

"/dev/ser0", and a pointer to the options.

When cyg_ppp_up() 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

cyg_ppp_wait_up(), which returns

zero if the link is up and running, or

-1 if it has gone down or failed to come up.

After a successful return from cyg_ppp_wait_up(),

the application may make use of the PPP connection. This is

represented here by the call to use_ppp() 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.

Once the application has finished with the PPP link, it can bring it

down by calling cyg_ppp_down(). 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

cyg_ppp_wait_down().

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:

static char *isp_script[] =

{

    "ABORT"             ,       "BUSY"                                  ,

    "ABORT"             ,       "NO CARRIER"                            ,

    "ABORT"             ,       "ERROR"                                 ,

    ""                  ,       "ATZ"                                   ,

    "OK"                ,       "AT S7=45 S0=0 L1 V1 X4 &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"                                   ,

};

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( &options );

    options.script = isp_script;

    options.modem  = 1;

    // Start up PPP

    ppp_handle = cyg_ppp_up( "/dev/ser0", &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 );

    }

}

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 cyg_ppp_up(). The

script option is set to point to a CHAT

script to manage the setup of the connection. The

modem option is set to cause the PPP system

to make use of the modem control lines.

During the PPP bring-up a call will be made to

cyg_ppp_chat() to run the CHAT script (see 

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 ). 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.

The modem option causes the PPP system to

make use of the modem control lines. In particular it waits for

Carrier Detect to be asserted, and will bring the

link down if it is lost. See 

for more details.

    cyg_ppp_options_init()

      cyg_ppp_options_init

      Initialize PPP link options

#include <cyg/ppp/ppp.h>

          cyg_int32 cyg_ppp_options_init

          cyg_ppp_options_t *options

This function initializes the PPP options, pointed to by the

options 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

cyg_ppp_options_t structure.

This function returns zero if the options were initialized

successfully. It returns -1 if the options

argument is NULL, or the options could not be initialized.

The option fields, their functions and default values are as follows:

  debug

     If set to 1 this enables the reporting of debug messages

    from the PPP system. These will be generated using

    diag_printf() and will appear on the standard

    debug channel. Note that diag_printf()

    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.

    Default value: 0

  kdebugflag

     This five bit field enables low level debugging messages from

    the PPP device layer in the TCP/IP stack. As with the

    debug option, this may result in missed

    characters and cause errors. The bits of the field have the

    following meanings:

            0x01

            SC_DEBUG

            Enable debug messages

            0x02

            SC_LOG_INPKT

            Log contents of good packets received

            0x04

            SC_LOG_OUTPKT

            Log contents of packets sent

            0x08

            SC_LOG_RAWIN

            Log all characters received

            0x10

            SC_LOG_FLUSH

            Log all characters flushed

    Default value: 0

  default_route

     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.

    Default value: 1

  modem

     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 carrier detect signal is

    asserted before bringing up the PPP link, and will take the PPP

    link down if this signal is de-asserted.

    Default value: 0

  flowctl

     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:

        CYG_PPP_FLOWCTL_DEFAULT

          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.

        CYG_PPP_FLOWCTL_NONE

          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.

        CYG_PPP_FLOWCTL_HARDWARE

          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.

        CYG_PPP_FLOWCTL_SOFTWARE

          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

          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.

    Default value: CYG_PPP_FLOWCTL_HARDWARE

  refuse_pap

     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

    user and

    passwd options must be set to the

    expected values. If they are not, then this option should be set

    to force CHAP authentication.

    Default value: 0

  refuse_chap

     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

    passwd option has been set to the

    required CHAP secret for the destination server. Otherwise this

    option should be disabled.

    If both refuse_pap and

    refuse_chap are set, then either no

    authentication will be carried out, or it is the responsibility of

    the chat script to do it. If the peer does not

    require any authentication, then the setting of these options is

    irrelevant.

    Default value: 0

  baud

     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

    cyg_serial_baud_rate_t enum defined in the

    serialio.h header and may only take one of the

    baud rate constants defined in there.

    Default value: CYGNUM_SERIAL_BAUD_115200

  idle_time_limit

     This is the number of seconds that the PPP connection may

    be idle before it is shut down automatically.

    Default value: 60

  maxconnect

     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.

    Default value: 0

  our_address

     This is the IP address, in network byte order, to be

    attached to the local end of the PPP connection. The default value

    of INADDR_ANY causes the local address to be

    obtained from the peer.

    Default value: INADDR_ANY

  his_address

     This is the IP address, in network byte order, to be

    attached to the remote end of the PPP connection. The default

    value of INADDR_ANY causes the remote address

    to be obtained from the peer.

    Default value: INADDR_ANY

  script

     This is a pointer to a CHAT script suitable for passing to

    cyg_ppp_chat(). See 

    for details of the format and contents of this script.

    Default value: NULL

  user

     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

    CYGPKG_PPP_AUTH_DEFAULT_USER configuration

    option.

    Default value: CYGPKG_PPP_AUTH_DEFAULT_USER

  passwd

     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 CYGPKG_PPP_AUTH_DEFAULT_PASSWD

    configuration option.

    Default value: CYGPKG_PPP_AUTH_DEFAULT_PASSWD

    cyg_ppp_up()

      cyg_ppp_up

      Bring PPP connection up

#include <cyg/ppp/ppp.h>

          cyg_ppp_handle_t cyg_ppp_up

          char *devnam

          const cyg_ppp_options_t *options

This function starts up a PPP connection. The

devnam argument is the name of the device to be

used for the connection, typically "/dev/ser0" or

"/dev/ser1". The options

argument should point to an initialized

cyg_ppp_options_t object.

The return value will either be zero, indicating a failure, or a

cyg_ppp_handle_t object that may be used as an argument

to other PPP functions.

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.

    cyg_ppp_down()

      cyg_ppp_down

      Bring PPP connection down

#include <cyg/ppp/ppp.h>

          cyg_int32 cyg_ppp_down

          cyg_ppp_handle_t handle

This function brings the PPP connection down. The

handle argument is the result of a successful

call to cyg_ppp_up(). 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

cyg_ppp_wait_down() after calling

cyg_ppp_down().

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.

    cyg_ppp_wait_up()

      cyg_ppp_wait_up

      Wait for PPP connection to come up

#include <cyg/ppp/ppp.h>

          cyg_int32 cyg_ppp_wait_up

          cyg_ppp_handle_t handle

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 cyg_ppp_up()

returns, and may take some time to complete, especially if dialling a

remote server.

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.

    cyg_ppp_wait_down()

      cyg_ppp_wait_down

      Wait for PPP connection to terminate

#include <cyg/ppp/ppp.h>

          void cyg_ppp_wait_down

          cyg_ppp_handle_t handle

This function waits for the PPP connection to terminate. The link may

be terminated with a call to cyg_ppp_down(), by

the remote end, or by the telephone line being dropped or lost.

This function has no return value. If the PPP connection is not

running, or has terminated, it will return. Applications should use

cyg_ppp_wait_up() to test the link state.

    cyg_ppp_chat()

      cyg_ppp_chat

      Execute chat script

#include <cyg/ppp/ppp.h>

          cyg_int32 cyg_ppp_chat

          const char *devname

          const char *script[]

This function implements a subset of the automated conversational

scripting as defined by the chat program. The first

argument is the name of the serial device to be used, typically

"/dev/ser0" or "/dev/ser1". The

script argument is a pointer to a zero

terminated array of strings that comprise the chat script. See 

linkend="ppp-using"> for an example script, and 

linkend="ppp-chat"> for full detail of the script used.

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.

Under normal use this function is called from the PPP subsystem if the

cyg_ppp_options_t

script field is set to a

non-NULL value. This function should only be used