eicon.nr

早期freebsd实现

T}:T{
.na
NULL or address of mbuf containing contents of Call Cleared data
T}:T{
.na
NULL or address of mbuf containing contents of Call Cleared data
T}:T{
.na
address of mbuf containing contents of user data
T}:T{
.na
NULL or address of mbuf containing one byte Reset Diagnostic code
T}
_
\fIeicon_reason\fR:ignore:ignore:T{
.na
reason for refusal
T}:T{
.na
reason for clear
.T}:ignore:T{
.na
reason for reset
T}
.TE
.sz 10
.bp
.sh 3 "Internal Driver Data Sructures"
.lp
The main driver data structure
is the \fIecn_softc\fR structure.
This structure keeps track of the interface request queue 
(\fCecn_if\fR and \fCecn_pending_req\fR), 
magic addresses on the adapter (\fCecn_iom_base, ecn_mem_base,\fR and 
\fCecn_data_base\fR), 
error statistics (\fCecn_errors\fR), the state
of each virtual circuit (\fCecn_vc_state\fR), the state of the \fILISTEN\fR
request (\fCecn_listen_pending\fR), and the current caller (\fCecn_cause\fR).
\fC
.nf
struct ecn_softc {
    int             ecn_errors[NCB_MAX][ST_MAX]; 
    int             ecn_cause[CAUSE_MAX];  /* ecn_work() causes              */
    struct mbuf     *ecn_pending_req;      /* waiting for command req        */
    char            ecn_listen_pending;    /* boolean = listen req pending?  */
    char            ecn_vc_state[LSN_MAX]; /* the current state of each vc   */
    struct ecn_device      
                    *ecn_iom_base;         /* base address of io map         */
    struct ecn_request_vector
                    *ecn_mem_base;         /* base address of memory map     */
    caddr_t         ecn_data_base;         /* base address for data area     */
    struct ifnet    ecn_if;                /* queue of new requests          */
}
\fR
.so figs/ecn_queue.nr
.sh 2 "Queueing in the Driver"
.lp
.CF
illustrates the queueing mechanism used by the driver.
.lp
CONS queues its data transfer requests at the end of the queue managed by
\fCecn_if\fR field in the \fCecn_softc\fR structure. 
At this point, each request has the state value of 
\fIREQ_NEW\fR. 
Once the driver notifies the adapter that it has a command to post,
the driver dequeues the first request from the \fCecn_if\fR queue 
and sets the pointer
\fCecn_pending_req\fR to point to the request. 
At this point, the request is in the \fIREQ_INTERRUPT\fR state.
.lp
Once the driver posts the request to the adapter, it 
dequeues the next request in the \fCecn_if\fR queue, reassigns the 
\fCecn_pending_req\fR pointer, and then indicates to the adapter 
that it is ready to post another request. 
The driver no longer has to keep track of the previous request, 
because for every reply, the adapter includes the associated 
mbuf pointer. 
While the request is outstanding, the request is in the \fIREQ_POSTED\fR state.
.so figs/ecn_vc.nr
.lp
After the adapter completes the command, the driver may want to reply to CONS.
It does this by placing its reply in CONS's \fCconsintrq\fR queue, defined as
an external \fCifqueue\fR in the driver code.
.sh 2 "Virtual Circuit States"
.lp
The \fCecn_vc_state\fR array in the \fCecn_softc\fR structure above keeps track
of the state of each virtual circuit (VC).
This is necessary to avoid handing
the adapter any commands that may not apply during a given state. 
This mechanism
is especially useful in dealing with unexpected aborts or clears where there
is the potential for all outstanding commands to complete with errors. 
By changing
states, the driver can prevent redundant commands (like clears and aborts)
from being passed either to the adapter or to CONS. 
.lp
The driver only keeps track of four different states, as illustrated in 
.CF
.
These states are:
.ip "\fIVC_NO_CONNECTION\fR"
When a virtual circuit is in this state, the virtual circuit does not exits.
Only \fICALL\fR and \fILISTEN\fR commands are valid.
.ip "\fIVC_DATA_XFER\fR"
All commands, except \fICALL\fR and \fILISTEN\fR commands are valid once the
connection exists.
.ip "\fIVC_RESET_IN_PROGRESS\fR"
In this state, either the driver has issued an \fINCB_RESET\fR or it has 
received a reset error code on the completion of a command. 
Only reissued \fIRESET\fR commands and \fIRECEIVE\fRs are
valid. 
\fIRECEIVE\fR is valid in this state because the adapter uses the
completion of this command to hand back the cause of the reset (the RESET
INDICATION packet).
.ip "\fIVC_CLEAR_IN_PROGRESS\fR"
The driver has either issued an \fINCB_CLEAR\fR command or has just
received a clear error code on the completion of a command. 
Within this state, only reissued
\fICLEAR\fR and \fIABORT\fR commands are valid.
.sh 2 "Error Statistics"
.lp
With the \fCecn_errors\fR field in the \fCecn_softc\fR structure,
the driver maintains a two dimensional array of counters
if the frequencies of errors.
In order to inspect this array easily with
the kernel debugger, the first index to every command ( <command, 0> ) is
reserved for a four character ASCII command identifier.
.bp
.sh 3 "The Driver State Machine"
.sh 2 "Handling of Normal Command Completions"
.lp
The chart below lists
all the available adapter request types, at what level each of
these requests can be used, options, and the driver's action after a normal
completion of the command.
.sp
.sz 7
.TS
center,box,tab(:);
c s s s
c|c s|c
c|c|c|c
l|l|l|l.
\fBNormal Completion Handling\fR
_
\fINCB:Options:Action Based on Normal Competion of\fR
\fICommand:To Adapter:From Adapter:Driver\(->Adapter Command\fR
=
\fINCB_RESTART\fR:none:none:T{
.na
dequeue the request, and issue an NCB_LISTEN request to the adapter.
T}
_
\fINCB_CALL\fR:none:connected:T{
.na
dequeue the request, pass an ECN_ACCEPT reply to CONS, and issue a RECEIVE to
the adapter.
T}
_
\fINCB_LISTEN\fR:T{
.na
use zero-length Call User Data and a zero-length Calling DTE address
T}:none:T{
.na
dequeue the request, pass an ECN_CONNECT to CONS, and issue a RECEIVE to the
adapter. Re-issue another NCB_LISTEN
for another possible virtual circuit connection.
T}
_
\fINCB_CLEAR\fR:T{
.na
normal clearing with all outstanding ACKs returned 
T}:none:T{
.na
dequeue the request.
T}
:_:_:_
:T{
.na
immediate clearing 
T}:none:T{
.na
dequeue the request.
T}
_
\fINCB_SEND\fR:T{
.na
normal send
T}:none:T{
.na
dequeue the request and reply to CONS with an ECN_ACK.
T}
:_:_:_
:T{
.na
reset the virtual circuit
T}:none:T{
dequeue the request.
T}
_
\fINCB_RECEIVE\fR:none:T{
.na
normal, uncomplicated receive
T}:T{
.na
dequeue the request and bcopy the data into the request's associated mbuf. Ship to CONS. Re-issue another NCB_RECEIVE.
T}
:_:_:_
:none:T{
.na
m-bit set
T}:T{
.na
same as above (adapter does the resegmentation automatically).
T}
:_:_:_
:none:T{
.na
d-bit set
T}:T{
.na
same as above.
T}
:_:_:_
:none:T{
.na
q-bit set
T}:T{
.na
same as above.
T}
:_:_:_
:none:T{
.na
interrupt received
T}:T{
.na
same as above.
T}
:_:_:_
:none:T{
.na
reset received
T}:T{
dequeue the request, send an ECN_RESET back up to CONS, and issue another 
receive.
T}
.TE
.sz 10
.sp
.uh "CONS \(-> Driver"
.lp
All entries in this column indicate that the CONS module can send this request 
down to the driver.  Command names in parenthesis define the mapping between
the \fIECN\fR and \fINCB\fR commands.
.uh "Driver \(-> Adapter"
.lp
All checks in this column indicate that the driver can send this request
to the adapter. The last column in the above table defines what the driver must
do upon normal completion of the command from the adapter. 
Note that not all driver-to-adapter
commands have a CONS-to-driver equivalent. 
This shows that this 
command request is generated within the driver, rather than originating from
the CONS driver.
.uh "Driver \(-> CONS"
.lp
All entries in this column indicate that the driver can send this reply  
back to CONS. Command names in parenthesis define  the mapping between 
the \fIECN\fR and \fINCB\fR commands.
.bp
.sh 3 "Handling of Errors upon Command Completion"
.lp
Below is listed all the driver request and pseudo request types, along with the
actions the driver must perform given a command completion error delivered by
the Eicon Network Adapter.
.sp
.sz 7
.TS
center,box,tab(:);
c  s s s s s s s
c||c s s s s s s
c||c|c|c|c|c|c|c
c||c|c|c|c|c|c|c
l||l|l|l|l|l|l|l.
\fBError Completion Handling\fR
_
:\fIAction Based on Error Completion of Driver \(-> Adapter Command\fR
\fIError Returned\fR:_:_:_:_:_:_:_
\fI:NCB_CALL:NCB_LISTEN:NCB_CLEAR:NCB_ABORT:NCB_RESET:NCB_SEND:NCB_RECEIVE\fR
=
\fIST_BAD_LEN\fR:<soft-error>:<soft-error>:<soft-error>:<soft-error>:<soft-error>:<soft-error>:<soft-error>
_
\fIST_INVALID\fR:<soft-error>:<soft-error>:<dequeue>:<dequeue>:<dequeue>:<dequeue>:<dequeue>
_
\fIST_COMMAND_TO\fR:<retry>:<retry>:<retry>:<retry>:<abort>:<abort>:<retry>
_
\fIST_ISSUE_ANOTHER_RCV\fR:<refuse>:<retry>:<retry>:<retry>:<abort>:<abort>:T{
.na
requeue request and increment "more" count
T}
_
\fIST_BAD_LSN\fR:<soft-error>:<soft-error>:<dequeue>:<dequeue>:<dequeue>:<dequeue>:<dequeue>
_
\fIST_NO_RESOURCES\fR:<retry>:<retry>:<retry>:<retry>:<abort>:<abort>:<retry>
_
\fIST_CALL_CLEARED\fR:<refuse>:<retry>:<retry>:<retry>:<clear>:<clear>:<clear>
_
\fIST_COMMAND_CANCELLED\fR:<refuse>:<retry>:<retry>:<retry>:<abort>:<abort>:<abort>:
_
\fIST_NO_CIRCUITS\fR:<refuse>:<retry>:<retry>:<retry>:<abort>:<abort>:<abort>
_
\fIST_CALL_UNSUCCESSFUL\fR:<refuse>:<retry>:<retry>:<retry>:<abort>:<abort>:<abort>
_
\fIST_INCORRECT_CALLNAME\fR:<soft-error>:<soft-error>:<soft-error>:<soft-error>:<soft-error>:<soft-error>:<soft-error>
_
\fIST_X25_RESET\fR:<refuse>:<retry>:<retry>:<retry>:<dequeue>:<dequeue>:<retry>
_
\fIST_TOO_MANY_COMMANDS\fR:<retry>:<retry>:<retry>:<retry>:<abort>:<abort>:<retry>
_
\fIST_L1_NO_DATA_SET_READY\fR:<refuse>:<retry>:<retry>:<retry>:<abort>:<abort>:<abort>
_
\fIST_L1_NO_CLEAR_TO_SEND\fR:<refuse>:<retry>:<retry>:<retry>:<abort>:<abort>:<abort>
_
\fIST_L1_NO_CLOCK\fR:<refuse>:<retry>:<retry>:<retry>:<abort>:<abort>:<abort>
.TE
.sz 10
.sp
.lp
Each of the actions from the above chart are defined as follows.
.ip "\fI<abort>\fR -"
The driver should clear the connection by issuing an \fINCB_ABORT\fR 
to the adapter and sending an \fIECN_CLEAR\fR to CONS.
.ip "\fI<refuse>\fR -"
The driver should send an \fIECN_REFUSE\fR back to CONS.
.ip "\fI<dequeue>\fR -"
The driver should simply dequeue the request. Usually these errors occur when a
reset or clear occurs on the adapter while the driver is in the midst of
issuing the command which subsequently completes with an error status.
.ip "\fI<clear>\fR -"
The driver should send an \fIECN_CLEAR\fR back up to CONS.
.ip "\fI<retry>\fR -"
The driver should requeue the request if and only if the 
\fCecn_retry_cnt\fR field in the request structure does not exceed the
retry maximum. 
.ip "\fI<soft-error>\fR -"
This action only takes place when a software error has occurred. The driver 
should
print the error to the console in big bold letters and then panic.
.bp
.sh 3 "The IFP Flags"
.lp
The IFP flags in the standard \fCifnet\fR structure
should be used in the following way.
.ip "\fIIFF_UP on -\fR"
This flag is set by the driver only after the procedure \fIecnrestart()\fR
successfully completes.
.ip "\fIIFF_UP off -\fR"
This flag is set immediately upon entry into the procedure \fIecnshutdown()\fR.
.ip "\fIIFF_RUNNING on -\fR"
This flag is set on whenever the \fIecnwork()\fR procedure is active, eg. the
driver is actually doing something.
.ip "\fIIFF_RUNNING off -\fR"
This flag is turned off upon exit from the \fIecnwork()\fR procedure.