eicon.nr

早期freebsd实现

.sh 2 "X.25 Public Data Network Support"
.pp
This ARGO release includes support for an X.25 Public Data Network (PDN)
in the form of a device driver for the Eicon Technology
Network Adapter \**.
.(f
This adapter, its software, and its documentation are
available from Eicon Technology Corporation, 3452 Ashby Street, Montreal,
Quebec, Canada H4R 2C1.
.)f
The adapter and its software, together with
the ARGO \fIecn(4)\fR driver, implement
the X.25 packet layer protocol as required to support the OSI connection
oriented network service.
The remainder of this section of this manual
destribes the ARGO device driver (hereinafter called "the driver")
for the Eicon Technology Network Adapter (hereinafter called "the adapter"),
the interface between the driver
and the CONS software described above, and the interface
between the driver and the software on the adapter.
.sh 3 "Software Modules"
.lp
The modules relevant to the design of the driver are listed below.
.ip "\fICONS -\fR"
The Connection Oriented Network Service (CONS) provides the upper ISO layers
with an interface to the PDN. 
In this release,
the PDN is 1980 X.25, although support for 1984 X.25 is included.
CONS can receive requests
from the CLNP entity and
from the OSI transport entity.
In addition, the CONS module 
supports \fIioctl()\fR commands used by 
\fIifconfig(8)\fR to configure 
the X.25 network address and to
declare the adapter to be up or down. 
See \fIcons(4p)\fR.
.ip "\fIDriver -\fR"
The driver accepts commands from CONS, formats these commands 
for the adapter, and interprets error indications delivered by the adapter.  
This driver supports all the UNIX configuration device structures. 
See \fIecn(4)\fR.
.ip "\fIEcnconf -\fR"
\fIEcnconf\fR is a program that allows the privileged user to
reconfigure
the options offered by the software on the adapter. 
\fIEcnconf\fR can be run at any time. 
See \fIecnconf(8)\fR.
.ip "\fIEcnload -\fR"
\fIEcnload\fR is a program that downloads Eicon Technology software
to the adapter and passes the configuration changes made 
with the \fIecnconf\fR program to the driver. 
\fIEcnload must be run only when the X.25 link is considered down\fR.
See \fIecnload(8)\fR. 
.ip "\fIEcnstat -\fR"
\fIEcnstat\fR is a program that
prints the connection state information and counters kept by
the adapter and by the driver.
The statistics include the number of sends and receives,
active connections, and errors.
For more information, see \fI ecnstat(8)\fR.
.ip "\fIAdapter -\fR"
The adapter's interface to the driver is the Network Control
Block and Request Vector that exist within the adapter's shared memory (often
called the "Common Data Area").
This is described in detail below.
.sh 3 "Interactions Among the Modules"
.lp
The commands
passed between CONS and the driver can be any one of the \fIECN\fR
commands outlined in the
sections "ECN Requests" and "ECN Replies", below.
CONS uses the \fCecnrestart()\fR procedure for restart requests,
\fCecnshutdown()\fR procedure for shutdown requests, and 
\fCecnoutput()\fR procedure for all
normal data transfer requests. 
CONS uses the \fCecnioctl()\fR procedure call for
servicing adapter status requests from the X.25 statistics program \fIecnstat\fR.
.lp
Commands passed between the driver and the adapter can
be any one of the network control block (\fINCB\fR)
commands described in the section "NCB Commands", below.
All commands to and from the adapter are
communicated in the Network Control Block and Request Vector within
the adapter's Common Data Area.
.lp
\fIEcnload\fR starts the 
Eicon Technology Network Adapter software on the adapter
and downloads the validated configuration
to the driver.
.sh 3 "ECN Requests"
.lp
The \fIECN\fR request types that CONS can pass to the driver are listed below.
.ip "\fIECN_STOP - (by calling ecnshutdown())\fR"
This request instructs the driver to restart the network but not to listen for 
any incoming calls. 
CONS issues this request in response to an \fIioctl()\fR command
issued by the utility program \fIifconfig\fR, when
\fIifconfig\fR is used to bring down the adapter.
.ip "\fIECN_RESTART - (by calling ecnrestart())\fR"
This request instructs the driver to restart the network \fIand\fR to listen 
and accept any incoming calls. 
CONS issues this request in response to an \fIioctl()\fR command
issued by the utility program \fIifconfig\fR, when
\fIifconfig\fR is used to bring the adapter up.
.ip "\fIECN_CALL - 0x90\fR"
This request instructs the driver to place
a call request
to the specified DTE.
.ip "\fIECN_CLEAR - 0x92\fR"
This request instructs the driver to clear a given virtual circuit. 
All outbound data are acknowledged by the remote DTE
before the circuit is cleared.
.ip "\fIECN_SEND - 0x94\fR"
This request instructs the driver to transmit a data buffer across a given 
virtual circuit.
.ip "\fIECN_RESET - 0x04\fR"
This request instructs the driver to reset the given virtual circuit and
clear out all outstanding requests
associated with that virtual circuit.
.ip "\fIECN_STATUS - 0xb4 (exclusively through ecnioctl())\fR"
This requests instructs the driver to 
solicit the adapter's current connection state information and
counters.
.sh 3 "ECN Replies"
.lp
The \fIECN\fR responses
the driver can give
to CONS are listed below.
.ip "\fIECN_CONNECT - 0x01\fR"
This reply notifies CONS that the driver has established a virtual circuit
connection initiated by the remote DTE.
.ip "\fIECN_ACCEPT - 0x03\fR"
This reply notifies CONS that an ECN_CALL request has succeeded. The
reply contains a pointer to a protocol control block.
.ip "\fIECN_REFUSE - 0x02\fR"
This reply notifies CONS that a previous \fIECN_CALL\fR request has failed.
The reply contains a pointer to a protocol control block.
.ip "\fIECN_CLEAR - 0x92\fR"
This reply notifies CONS that a given virtual circuit has been cleared
either by the DCE or by the remote DTE.
.ip "\fIECN_RECEIVE - 0x95\fR"
This reply notifies CONS that the driver has received a data packet from
the remote DTE.
.ip "\fIECN_RESET - 0x04\fR"
This reply notifies CONS that the virtual circuit has been reset either
by the DCE or by the remote DTE.
.ip "\fIECN_ACK - 0x05\fR"
This reply tells CONS that the associated ECN_SEND request has been been
completed by the adapter.
.sh 3 "NCB Commands"
.lp
The driver hides from the CONS module
many of the idiosyncrasies of the adapter's 
software interface
by mapping many of the above \fIECN\fR requests into corresponding
\fINCB\fR commands. Below is a list of requests that the driver can place to
the adapter. For each request that the driver places to the adapter, the adapter
returns with a command completion.
.ip "\fINCB_CALL - 0x90\fR"
This command creates a virtual circuit. 
.ip "\fINCB_LISTEN - 0x91\fR"
This command tells the adapter that our host is
willing to accept incoming calls. 
.ip "\fINCB_CLEAR (and NCB_ABORT) - 0x92\fR"
This command clears a virtual circuit. An option exists to clear the circuit
immediately, without waiting first for outstanding acknowledgments.
.ip "\fINCB_SEND (and NCB_RESET) - 0x94\fR"
This command sends data to the remote DTE. An option is
available for resetting the
virtual circuit. This command can return a status indicating that the
circuit has been cleared by the DCE or the remote DTE.
.ip "\fINCB_RECEIVE - 0x95\fR"
This command tells the adapter that our host is
willing to receive data on a given virtual circuit. This command can return
received data, a reset circuit, M-, D-, and Q-bits, interrupt packets,
or a cleared circuit.
.ip "\fINCB_STATUS - 0xb4\fR"
This command queries the adapter about 
the status of a virtual circuit.
The driver uses this command to support the ECN_STATUS request.
.ip "\fINCB_RESTART - 0xb2\fR"
This command restarts the network. This command requires that a corresponding
configuration file be passed down to the adapter.
.bp
.sh 3 "ECN Request and Reply Structure"
.lp
Below is
the data structure used in CONS-driver 
communications.
This data structure is a parameter to the 
\fIecnoutput()\fR procedure.
\fC
.nf
/* Eicon Driver Request Structure -- used between CONS and the driver */

struct eicon_request {
    struct ecn_ncb  eicon_req_ncb;   /* the network control block       */
    caddr_t         eicon_req_pcb;   /* CONS pcb used on CALL requests  */
    int             eicon_req_state; /* used internally by the driver   */
    int             eicon_retry_cnt; /* used internally by the driver   */
    int             eicon_more;      /* used internally by the driver   */
    u_char          eicon_reason;    /* source of CLEAR requests        */
};
\fR
.lp
The \fCeicon_req_ncb\fR field in the eicon request structure is of
type \fCecn_ncb\fR, defined in the following section. This structure stores 
the command block
that the driver uses in communicating with the adapter. 
The command block contains a \fIlogical session number\fR (LSN),
which identifies a virtual circuit.
Requests such as ECN_CALL are made without an LSN to identify
a circuit.
When an LSN is not available, the request is identified by
the field
\fCeicon_req_pcb\fR, which is a pointer to a CONS protocol control block. 
The \fCeicon_req_state\fR field is used by the driver to keep track 
of the status of the given request. 
The following list defines the various values for this field:
.ip "\fIREQ_NEW\fR"
The driver recognizes a new request, has placed the request into the driver's 
own request queue, but has yet to interrupt the
adapter. (The driver maintains a pointer \fCecn_pending_req\fR that indicates
whether an interrupt to the adapter is outstanding. If one is outstanding, the
driver places any new requests in this \fIREQ_NEW\fR state. If an interrupt 
is not
outstanding, the driver places the request immediately in the 
\fIREQ_INTERRUPT\fR state defined below.)
.ip "\fIREQ_INTERRUPT\fR"
The driver has dequeued the CONS request, assigned \fCecn_pending_req\fR to
point to the request, and
interrupted the adapter for a chance to post this request.
.ip "\fIREQ_POSTED\fR"
The driver has sent the request to the adapter.
.ip "\fIREQ_COMPLETE\fR"
The driver has just completed the request, and if necessary, is now posting 
it to CONS.
.lp
The \fCeicon_retry_cnt\fR field in the eicon request structure keeps track
of how many times the driver has tried posting this command to the adapter.
After the second retry, the driver gives up and performs the appropriate
error routine. 
The \fCeicon_more\fR field defines a \fIRECEIVE\fR request that
has been re-posted to the adapter to take care of m-bit transfers.
The \fCeicon_reason\fR field quantifies the reason for a connection being
cleared. These reasons are defined in the include file \fCiso_errno.h\fR.
.lp
Any data associated with the request are linked to the request through the
request mbuf's \fCm_next\fR field. 
This is done so that when
the driver calls the \fIMFREE_M\fR deallocation routine, both the request 
and the data are freed together.
.lp
The following chart defines those fields within the eicon request structure
that are relevant in any CONS request
to the driver via the \fIecnoutput()\fR call. 
.sp
.sz 8
.TS
center,box,tab(:);
c s s s s
c||c s s s
c||c|c|c|c
l||l|l|l|l.
\fBField Definitions for CONS \(-> Driver Requests\fR
_
\fI:Request Types (CONS \(-> Driver)\fR
\fIField:ECN_CALL:ECN_CLEAR:ECN_SEND:ECN_RESET\fR
=
\fIncb\(->command\fR:0x90:0x92:0x94:0x04 
_
\fIncb\(->loc_ses_num\fR:T{
.na
leave as zero
T}:VC #:VC #:VC #
_
\fIncb\(->info\fR:0x0:0x0:0x0:0x2
_
\fIeicon_req_pcb\fR:T{
.na
address of CONS' protocol control block
T}:NULL:NULL:NULL
_
\fIeicon_req_data\fR:T{
.na
address of mbuf containing contents of Call Request packet (including DTE address, facilities, and call user data)
T}:T{
.na
NULL or address of mbuf containing contents of Clear Request packet
T}:T{
.na
address of mbuf containing contents of user data
T}:T{
.na
NULL or the address of mbuf containing a one byte Reset Diagnostic code
T}
.TE
.sz 10
.sh 3 "Structure of the Network Control Block (NCB)"
.lp
The \fCecn_ncb\fR structure is used by the driver to
make requests of the adapter. 
\fC
.nf
/* Network Control Block -- used between the driver and the Eicon adapter */

struct ecn_ncb {
    u_char      command;        /* command field                         */
    u_char      retcode;        /* return code field                     */
    u_char      lsn;            /* local session number                  */
    u_char      info;           /* additional information                */
    caddr_t     buffer;         /* pointer to data buffer's mbuf         */
    u_short     length;         /* buffer length                         */
    u_char      callname[16];   /* module name on NA "X25"               */
    u_char      appl_name[16];  /* application name                      */
    u_char      rxto;           /* receive timeout in secs               */
    u_char      txto;           /* send(tx) timeout in secs              */
    caddr_t     post;           /* NULL                                  */
    u_char      lana_num;       /* specifies Eicon Tech NA               */
    u_char      cmd_cplt;       /* command status                        */
    u_char      reserve[14];    /* reserved area                         */
};
\fR
.sp
.lp
The chart below defines those fields that are relevant in any
reply passed by the driver back up to CONS.
.sp
.sz 7
.TS
center,box,tab(:);
c s s s s s s
c||c s s s s s 
c||c|c|c|c|c|c
l||l|l|l|l|l|l.
\fBField Definitions for Driver \(-> CONS Replies\fR
_
\fI:Reply Types (Driver \(-> CONS)\fR
\fIField:ECN_CONNECT:ECN_ACCEPT:ECN_REFUSE:ECN_CLEAR:ECN_RECEIVE:ECN_RESET\fR
=
\fIncb\(->command\fR:0x01:0x03:0x02:0x92:0x95:0x04
_
\fIncb\(->loc_ses_num\fR:VC #:VC #:ignore:VC #:VC #:VC #
_
\fIncb\(->info\fR:ignore:ignore:ignore:ignore:T{
.na
Interrupt received (bit 0), D-bit set (bit 6), and/or Q-bit set (bit 7). Zero
info field implies a normal receive.
T}:ignore
_
\fIeicon_req_pcb\fR:NULL:T{
.na
address of CONS's protocol control block
T}:T{
.na
address of CONS's protocol control block
T}:ignore:ignore:ignore
_
\fIeicon_req_data\fR:T{
.na
NULL or address of mbuf containing contents of Call Indication packet 
T}:T{
.na
NULL or address of mbuf containing contents of Call Connected data