Modifications to the PPP module
*******************************

--------------------------------------------------------------------------------

	Distribution:	Company Confidential.
	Document ref:	aaaa
	Project:	bbbb
	Revision:	1.00
	Date:		12-04-1997
	Author:		Ben Laughton

--------------------------------------------------------------------------------

Contents
========

	1.0 	Overview.
	2.0 	Outstanding issues.
	3.0	Technical background.
	4.0	User interface.
	5.0	Programmer interface.
	6.0	Data interchange.
	7.0 	Data formats.
	8.0	External dependencies.
	9.0	Acceptance test.
	10.0	Non compliances.
	11.0	Development test strategy.
	12.0	Product organisation.
	13.0	Future enhancements.
	14.0	References.
	15.0	History.


--------------------------------------------------------------------------------

1.0 Overview
============

This document describes recent changes to the PPP module.  Two main 'batches'
of changes have been made, one for ART and one for ANC, which both provide
similar functionality.

Changes common to ART and ANC
	* Dual-serial support

ART changes:
	* Dialler support (timeouts, dual serial file handle arbitration).
	* Autodialling capability

ANC changes:
	* SWI interface to modify line drop idle time
	* SWI interface to read PPP status (idle time, connection status)

--------------------------------------------------------------------------------

2.0 Outstanding issues
======================

--------------------------------------------------------------------------------

3.0 Technical background
========================

3.1 Autodialling
----------------

The autodialling facility is only available if the ART Dialler module is in
use (ie. the dialler option was used in the pppconnect command).

To enable autodialling the PPP interface needs to remain ifconfig'd up even
when the line is really down.  The default route that PPP usually adds must
not be deleted otherwise Internet will not let any data through to PPP.
[In the sifdown routine the IFF_UP flag in ifr.ifr_flags is not altered.  The
behaviour of the DCI4 st_link_status flag in the Dib structure and the
moreflags flag in the ppp_softc structure are not changed].

When PPP receives a packet it checks whether the interface is really up or
down.  If it is down then it calls SWI Dialler_Dial, telling the dialler to
use the previous parameters.  PPP then returns ENETUNREACH and the packet is
discarded.
[This is done at the start of the pppoutput function.]

When it is time to bring the interface back up PPP checks to see if it has
already added a default route.  It it has then it changes the existing
default route (in case the gateway has changed); if not then it adds a
default route.

[The changes to the routing behaviour are implemented in the ipcp_down and
ipcp_up functions.  There is a new function in the sys-riscos file to change
a route].


--------------------------------------------------------------------------------

4.0 User interface
==================

Four options have been added to the pppconnect *command:
	1. dialler. PPP should use the Dialler for timeouts and access to the
serial port
	2. nodialler. PPP should not use the dialler
	4. autodial. PPP should attempt to autodial (dialler option must also
be enabled)
	5. noautodial. PPP should not attempt to autodial

--------------------------------------------------------------------------------

5.0 Programmer interface
========================

5.1 SWIs
--------

Two new SWIs have been added to the PPP module

5.1.1 PPP_AlterSettings (&4B620)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

On entry
	R0 = reason code, see below
	R1 = unit number
	If R0 = 0
		R2 = new line-drop idle time in seconds
	If R0 = 1
		R2 = new default and current line-drop idle time in seconds

On exit
	All registers preserved

Interrupts
	Interrupts are disabled
	Fast interrupts status is unaltered

Processor Mode
	Processor is in SVC mode

Re-entrancy
	Not defined

Use
	This SWI will have no effect if the dialler option was used when
	pppconnect was called. The SWI allows certain PPP settings to be
	changed depending on the reason word in R0:
	
	Reason Code	Meaning
	0		change current line-drop idle time
	1		change default and current line-drop idle time
	
	All other reason codes are reserved for future use.

Related SWIs
	PPP_Status
	Dialler_Timeout

Related vectors
	None


5.1.2 PPP_Status (SWI &4B621)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

On entry
	R0 = reason code, see below
	R1 = unit number

On exit
	R0, R1 are preserved
	If R0 = 0
		R2 = default line-idle drop time
		R3 = current line-idle drop time
	If R0 = 1
		R2 = Physical line state
			0: off line
			1: on line
		R3 = PPP connection phase (see below)

Interrupts
	Interrupts may be disabled
	Fast interrupts status is unaltered

Processor Mode
	Processor is in SVC mode

Re-entrancy
	Not defined

Use
	This call returns information on the status of the PPP module.
Different information is returned according to the reason code in R0:

	Reason Code	Meaning
	0		Return timeout information
	1		Return connection state information
	
	All other reason codes are reserved for future use.
	
	
	If the dialler option was used in the pppconnect command was called
then the results of calling this SWI with R0 = 0 are undefined.  If the modem
option was not used in the pppconnect command then the physical line state is
undefined when calling this SWI with R0 = 1. Calling this SWI with R0 > 1
will result in an error; additional reason codes amy be added in the future
to obtain more status information.

	The PPP connection phases are:
	Number	Phase		Meaning
	0	Dead		No link
	1       Establish       Connection being established
	2	Authenticate	Authenticating
	3	Network		Network layer protocols being configured
	4	Terminate	Link going down

	Refer to RFC 1661 for more information on PPP connection phases.

Related SWIs
	PPP_AlterSettings
	Dialler_Status

Related vectors
	None

5.2 Service Calls
-----------------

5.2.1 Service_PPPTimingOut (Service Call &C0)	
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Connection is about to timeout	

On entry
	R1 = (reason code)

On exit
	R1 = 0 to claim, else preserved to pass on
	All other registers preserved

Use
	PPP issues this service call when the line has been idle for the
	currently set line-drop idle time, and PPP is about to drop the line. 
	If the service call is claimed then PPP reset the line-idle timer and
	will not drop the line; if the service call is not claimed then the
	line will be dropped.

--------------------------------------------------------------------------------

6.0 Data interchange 
====================

--------------------------------------------------------------------------------

7.0 Data formats 
================

--------------------------------------------------------------------------------

8.0 External dependencies 
=========================

The Dual Serial version of the PPP module requires DeviceFS 0.35 or later. 
The Dual Serial module itself requires BufferManager 0.25 or greater and
FileSwitch 2.34 or later.

--------------------------------------------------------------------------------

9.0 Acceptance test 
===================

--------------------------------------------------------------------------------

10.0 Non compliances 
====================

--------------------------------------------------------------------------------

11.0 Development test strategy 
==============================

--------------------------------------------------------------------------------

12.0 Product organisation 
=========================

--------------------------------------------------------------------------------

13.0 Future enhancements 
========================

--------------------------------------------------------------------------------

14.0 References 
===============

--------------------------------------------------------------------------------

15.0 History 
============

	Revision	Who	Rev Date	Comment
	0.01		BAL	12-04-1997	Started.
	0.02		SJM	21-05-1999	Added AlterSettings,1
	
	
--------------------------------------------------------------------------------
