cippd_protocol.c

<B>Digital的Unix操作系统VAX 4.2源码</B>

 * and duplication.   The reception of duplicate datagrams is easily detected
 * and handled.  Overcomming the loss of datagrams presents a greater
 * challenge.  It is solved by the following retry mechanism based upon the
 * re-transmission of datagrams on expiration of path associated timers:
 *
 *	1. The appropriate PB interval timer is activated each time a datagram
 *	   is transmitted on a formative CI PPD path.
 *	2. Reception of the response expected for the datagram transmitted
 *	   deactivates this timer.
 *	3. Expiration of a path associated timer triggers re-transmission of
 *	   the last datagram transmitted on the formative path and re-activates
 *	   the timer.
 *
 * The number of re-transmissions made( Step 3 ) is not infinite, but computed
 * based upon a whole set of CI PPD and local port specific parameters.
 * Reception of certain acceptable but NOT expected datagrams can force
 * re-computation of this number prior to datagram re-transmission and timer
 * re-activation.  Expiration of the number of retries remaining terminates
 * path establishment and forces clean of the formative CI PPD.
 *
 * Path associated interval timers are not activated for every datagram
 * transmitted by the CI PPD, but only for those datagram transmissions for
 * which specific responses are expected.  This includes START and STACK CI PPD
 * datagram transmissions and specific requests for remote port
 * identifications.  It does not include routine CI PPD polling or CI PPD ACK
 * datagram transmissions, neither of which expect specific responses.
 *
 * Path termination is done unilaterally by each CI PPD, unlike path
 * establishment.  It does not require the CI PPD to notify its counterparts.
 * There is no path termination CI PPD protocol sequence. 
 * 
 * The CI PPD is implemented as a finite state machine.  Associated with each
 * path is its path state.  When an asynchronous event occurs on a path its
 * state dictates what actions are taken.  It also represents the path's
 * current position within a CI PPD protocol sequence.  Therefore, certain
 * events trigger transitioning of paths into different path state.  The
 * following table illustrates for each possible path state - event combination
 * the actions which are taken and the concluding path state:
 *
 *  Path State	    EVENT		   ACTION		    Path State
 * ------------	  ----------	-----------------------------	   ------------
 * CLOSED	  ID_REC	Allocate and Initialize PB	   START_SNT
 *				Send START CI PPD Datagram
 *				Start CI PPD Timer
 *		  START_REC	Allocate and Initialize PB	   START_REC
 *				Allocate and Initialize SB
 *	 			Request Remote Identification
 *				Start CI PPD Timer
 *		  STACK_REC	Discard Datagram			-
 *		  ACK_REC	Discard Datagram			-
 *		  SCSMSG_REC	Disable CI PPD Path			-
 *		  ERROR_REC	Discard Datagram			-
 *		  STOP_REC	Discard Datagram			-
 *		  TIMEOUT	Invalid State-Event Combination		-
 *		  PATH_FAIL	Invalid State-Event Combination		-
 *		  PROC_ERROR	Discard Datagram		   PATH_FAILURE
 *				Send STOP CI PPD Datagram
 *				Schedule Asynchronous PB Clean Up
 *
 * START_SNT	  ID_REC	Discard Datagram			-
 *		  START_REC	Stop CI PPD Timer		   STACK_SNT
 *				Allocate and Initialize SB
 *				Update PB
 *				Enable CI PPD Path
 *				Send STACK CI PPD Datagram
 *				Start CI PPD Timer
 *		  STACK_REC	Stop CI PPD Timer		   OPEN
 *				Allocate and Initialize SB
 *				Update PB
 *				Enable CI PPD Path
 *				Enter PB and SB into Databases
 *				Send ACK CI PPD Datagram
 *		  ACK_REC	Stop CI PPD Timer		   PATH_FAILURE
 *				Abort CI PPD Path Establishment
 *		  SCSMSG_REC	Stop CI PPD Timer		   PATH_FAILURE
 *				Abort CI PPD Path Establishment
 *		  ERROR_REC	Event log ERROR CI PPD Datagram		-
 *				Discard Datagram
 *		  STOP_REC	Stop CI PPD Timer		   PATH_FAILURE
 *				Abort CI PPD Path Establishment
 *		  TIMEOUT	Send START CI PPD Datagram		-
 *				Start CI PPD Timer
 *		  PATH_FAIL	Stop CI PPD Timer		   PATH_FAILURE
 *				Send STOP CI PPD Datagram
 *				Schedule Asynchronous PB Clean Up
 *		  PROC_ERROR	Discard Optional Datagram	   PATH_FAILURE
 *				Disable CI PPD Path
 *				Send STOP CI PPD Datagram
 *				Schedule Asynchronous PB Clean Up
 *
 * START_REC	  ID_REC	Stop CI PPD Timer		   STACK_SNT
 *				Initialize and Update PB
 *				Enable CI PPD Path
 *				Send STACK CI PPD Datagram
 *				Start CI PPD Timer
 *		  START_REC	Stop CI PPD Timer			-
 *				Update SB
 *	 			Request Remote Identification
 *				Start CI PPD Timer
 *		  STACK_REC	Stop CI PPD Timer		   PATH_FAILURE
 *				Abort CI PPD Path Establishment
 *		  ACK_REC	Stop CI PPD Timer		   PATH_FAILURE
 *				Abort CI PPD Path Establishment
 *		  SCSMSG_REC	Stop CI PPD Timer		   PATH_FAILURE
 *				Disable CI PPD Path
 *				Abort CI PPD Path Establishment
 *		  ERROR_REC	Event log ERROR CI PPD Datagram		-
 *				Discard Datagram
 *		  STOP_REC	Stop CI PPD Timer		   PATH_FAILURE
 *				Abort CI PPD Path Establishment
 *		  TIMEOUT	Request Remote Identification		-
 *				Start CI PPD Timer
 *		  PATH_FAIL	Stop CI PPD Timer		   PATH_FAILURE
 *				Send STOP CI PPD Datagram
 *				Schedule Asynchronous PB Clean Up
 *		  PROC_ERROR	Discard Optional Datagram	   PATH_FAILURE
 *				Send STOP CI PPD Datagram
 *				Schedule Asynchronous PB Clean Up
 *
 * STACK_SNT	  ID_REC	Discard Datagram			-
 *		  START_REC	Stop CI PPD Timer			-
 *				Update SB
 *				Send STACK CI PPD Datagram
 *				Start CI PPD Timer
 *		  STACK_REC	Stop CI PPD Timer		   OPEN
 *				Update SB
 *				Enter PB and SB into Databases
 *				Send ACK CI PPD Datagram
 *		  ACK_REC	Stop CI PPD Timer		   OPEN
 *				Enter PB and SB into Databases
 *				Discard Datagram
 *		  SCSMSG_REC	Stop CI PPD Timer		   OPEN
 *				Enter PB and SB into Databases
 *		  ERROR_REC	Event log ERROR CI PPD Datagram		-
 *				Discard Datagram
 *		  STOP_REC	Stop CI PPD Timer		   PATH_FAILURE
 *				Abort CI PPD Path Establishment
 *		  TIMEOUT	Send STACK CI PPD Datagram		-
 *				Start CI PPD Timer
 *		  PATH_FAIL	Stop CI PPD Timer		   PATH_FAILURE
 *				Disable CI PPD Path
 *				Send STOP CI PPD Datagram
 *				Schedule Asynchronous PB Clean Up
 *		  PROC_ERROR	Discard Optional Datagram	   PATH_FAILURE
 *				Disable CI PPD Path		
 *				Send STOP CI PPD Datagram
 *				Schedule Asynchronous PB Clean Up
 *
 * OPEN		  ID_REC	Discard Datagram			-
 *		  START_REC	Crash CI PPD Path		   PATH_FAILURE
 *				Discard Datagram
 *		  STACK_REC	Update SB				-
 *				Send ACK CI PPD Datagram
 *		  ACK_REC	Discard Datagram			-
 *		  SCSMSG_REC		-				-
 *		  ERROR_REC	Event log ERROR CI PPD Datagram		-
 *				Discard Datagram
 *		  STOP_REC	Crash CI PPD Path		   PATH_FAILURE
 *				Discard Datagram
 *		  TIMEOUT	Invalid State-Event Combination		-
 *		  PATH_FAIL	Disable CI PPD Path		   PATH_FAILURE
 *				Send STOP CI PPD Datagram
 *				Invalidate Translation Cache
 *				Schedule Asynchronous PB Clean Up
 *		  PROC_ERROR	Invalid State-Event Combination		-
 *
 * PATH_FAILURE	  ID_REC	Discard Datagram			-
 *		  START_REC	Send STOP CI PPD Datagram		-
 *				Discard Datagram
 *		  STACK_REC	Send STOP CI PPD Datagram		-
 *				Discard Datagram
 *		  ACK_REC	Send STOP CI PPD Datagram		-
 *				Discard Datagram
 *		  SCSMSG_REC	Send STOP CI PPD Datagram		-
 *		  ERROR_REC	Event log ERROR CI PPD Datagram		-
 *				Discard Datagram
 *		  STOP_REC	Discard Datagram			-
 *		  TIMEOUT	Invalid State-Event Combination		-
 *		  PATH_FAIL		-				-
 *		  PROC_ERROR	Invalid State-Event Combination		-
 *
 * This table is presented to give an overall picture of the finite state
 * machine.  It is by no means complete.  Some of the excluded actions are
 * just unimportant as is the case with certain ancillary ones.  Others
 * include tests which exist only to potentially divert the flow of control
 * into secondary error paths if various criteria are not met.  Only those
 * actions which illustrate the primary flow of control and whose presence
 * contributes to the overall picture were included within the table.
 *
 * Official documentation of the CI PPD protocol is included within the
 * corporate SCA architectural specification.  A comparison between this
 * specification and the table documented above would reveal several marked
 * discrepancies, the most important of which is the lack of a START_REC state
 * in the latter.  This state was added to the Ultrix implementation of the
 * CI PPD protocol to both increase the protocol's robustness and reduce the
 * amount of time required for synchronizing local and remote CI PPDs during
 * path establishment.  Its presence does not violate the official protocol
 * as it is a purely local CI PPD convention.  Its benignity also has been
 * firmly established by co-existence of Ultrix, VMS, and HSC implementations
 * on the same CI.
 *
 * Many of the actions executed by the finite state machine in its processing
 * of events have no resultant status and can not affect the flow of control
 * within the machine.  Others do have a resultant status including both
 * actions represented in the table above and some that are not.  These actions
 * can affect the flow of control within the finite state machine by
 * prematurely terminating processing of the current event whenever their
 * outcome is not successful.
 *
 * Premature termination of event processing has one major designed side
 * effect: it also terminates the path on which the event originally occurred.
 * One consequence of this outcome is that event processing on established or
 * failed paths may never be terminated.  Failed paths have already been
 * terminated and established paths may only be terminated by explicit crashing
 * of the path.  Only event processing on formative paths can be terminated.
 * In fact, premature termination of event processing represents the only
 * supported mechanism for crashing formative paths and aborting their
 * establishment from within the finite state machine itself.  Formative paths
 * may be explicitly crashed external to the finite state machine, but they
 * may never be explicitly crashed from within it.  This insures that formative
 * paths are correctly aborted.
 *
 * All actions responsible for prematurely terminating event processing and
 * aborting establishment of the formative path are also responsible for
 * logging the reason for such termination.  Only the very first occurrence of
 * a specific reason for aborting establishment of a specific formative path is
 * logged.  Logging of subsequent failures is bypassed until such time as the
 * condition responsible has been satisfactorily resolved for the specific
 * path.
 *
 * Once an action returns a failure status, actual termination of event
 * processing and abortion of path establishment is relatively straightforward.
 * The finite state machine declares a special event( event == CNFE_PROC_ERROR)
 * on the path to be aborted by iteratively invoking itself.  The path state
 * remains the same because processing of the previous event was prematurely
 * terminated before the path could be transitioned to its new state.  It is
 * during processing of this special event that establishment of the formative
 * path is aborted by disabling the path, scheduling its asynchronously clean
 * up, and transitioning its state to PS_PATH_FAILURE.
 *
 * A number of general rules exist which are quite helpful in understanding the
 * overall design of the CI PPD finite state machine and the machine's
 * implementation of the CI PPD protocol.  These rules are listed below:
 *
 *  1. Entry to the CI PPD finite state machine is by means of the function
 *     cippd_dispatch() and only this function.
 *  2. Each action in the table above is represented by its own finite state
 *     machine action function/routine.  Functions return status while routines
 *     do not.  All action functions/routines have the exact same interface.  
 *  3. The CI PPD finite state machine executes in turn all actions associated
 *     with the current path state - event pairing.  On successful invocation
 *     of all actions the path is transitioned into its new state.  Failure of
 *     any action terminates processing of the current event and iteratively
 *     invokes the finite state machine( event == CNFE_PROC_ERROR ) to abort
 *     establishment of the path.
 *  4. Action functions executed while processing established CI PPD paths must
 *     never return failure.  This would trigger iterative invocation of the
 *     finite state machine( event == CNFE_PROC_ERROR ) for the purpose of
 *     aborting the path.  This is not allowed.  Established paths can only be
 *     terminated through explicit invocation of cippd_crash_pb().  This
 *     insures that they are terminated correctly.
 *  5. Action functions executed while processing failed paths( path state ==
 *     PS_PATH_FAILURE ) or either process error( event == CNFE_PROC_ERROR ) or
 *     path failure( event == CNFE_PATH_FAIL ) events must never return
 *     failure.  This would trigger termination of paths that are already in
 *     the process of being terminated.
 *  6. The functions cippd_pcreason, cippd_disb_path, and cippd_path_sched may
 *     not be included among the action functions executed while processing
 *     failed paths( path state == PS_PATH_FAILURE ).  Such functions may only
 *     be executed once per path incarnation and were invoked during processing
 *     of the path failure event itself( event == CNFE_PATH_FAIL ).  In
 *     addition, the function cippd_pcreason() may only be executed on
 *     established paths.  Only the path crash reasons associated with such
 *     paths require mapping.
 *  7. The status returned by certain action functions may be ignored when the
 *     function is invoked during processing of certain path state - event
 *     combinations.  It may be ignored either when the status is guaranteed to
 *     be successful under the current circumstances or must be successful
 *     because of the current event or path state( See Rules 4 and 5 ).
 *  8. Datagrams are optional in all calls to the finite state machine.  For