| blob | a1281ac1fc7d64f888cb3732380c3dcb24ab8b93 |
1 .\" $NetBSD$
2 .\"
3 .sh 2 "X.25 Public Data Network Support"
4 .pp
5 This ARGO release includes support for an X.25 Public Data Network (PDN)
6 in the form of a device driver for the Eicon Technology
7 Network Adapter \**.
8 .(f
9 This adapter, its software, and its documentation are
10 available from Eicon Technology Corporation, 3452 Ashby Street, Montreal,
11 Quebec, Canada H4R 2C1.
12 .)f
13 The adapter and its software, together with
14 the ARGO \fIecn(4)\fR driver, implement
15 the X.25 packet layer protocol as required to support the OSI connection
16 oriented network service.
17 The remainder of this section of this manual
18 destribes the ARGO device driver (hereinafter called "the driver")
19 for the Eicon Technology Network Adapter (hereinafter called "the adapter"),
20 the interface between the driver
21 and the CONS software described above, and the interface
22 between the driver and the software on the adapter.
23 .sh 3 "Software Modules"
24 .lp
25 The modules relevant to the design of the driver are listed below.
26 .ip "\fICONS -\fR"
27 The Connection Oriented Network Service (CONS) provides the upper ISO layers
28 with an interface to the PDN.
29 In this release,
30 the PDN is 1980 X.25, although support for 1984 X.25 is included.
31 CONS can receive requests
32 from the CLNP entity and
33 from the OSI transport entity.
34 In addition, the CONS module
35 supports \fIioctl()\fR commands used by
36 \fIifconfig(8)\fR to configure
37 the X.25 network address and to
38 declare the adapter to be up or down.
39 See \fIcons(4p)\fR.
40 .ip "\fIDriver -\fR"
41 The driver accepts commands from CONS, formats these commands
42 for the adapter, and interprets error indications delivered by the adapter.
43 This driver supports all the UNIX configuration device structures.
44 See \fIecn(4)\fR.
45 .ip "\fIEcnconf -\fR"
46 \fIEcnconf\fR is a program that allows the privileged user to
47 reconfigure
48 the options offered by the software on the adapter.
49 \fIEcnconf\fR can be run at any time.
50 See \fIecnconf(8)\fR.
51 .ip "\fIEcnload -\fR"
52 \fIEcnload\fR is a program that downloads Eicon Technology software
53 to the adapter and passes the configuration changes made
54 with the \fIecnconf\fR program to the driver.
55 \fIEcnload must be run only when the X.25 link is considered down\fR.
56 See \fIecnload(8)\fR.
57 .ip "\fIEcnstat -\fR"
58 \fIEcnstat\fR is a program that
59 prints the connection state information and counters kept by
60 the adapter and by the driver.
61 The statistics include the number of sends and receives,
62 active connections, and errors.
63 For more information, see \fI ecnstat(8)\fR.
64 .ip "\fIAdapter -\fR"
65 The adapter's interface to the driver is the Network Control
66 Block and Request Vector that exist within the adapter's shared memory (often
67 called the "Common Data Area").
68 This is described in detail below.
69 .sh 3 "Interactions Among the Modules"
70 .lp
71 The commands
72 passed between CONS and the driver can be any one of the \fIECN\fR
73 commands outlined in the
74 sections "ECN Requests" and "ECN Replies", below.
75 CONS uses the \fCecnrestart()\fR procedure for restart requests,
76 \fCecnshutdown()\fR procedure for shutdown requests, and
77 \fCecnoutput()\fR procedure for all
78 normal data transfer requests.
79 CONS uses the \fCecnioctl()\fR procedure call for
80 servicing adapter status requests from the X.25 statistics program \fIecnstat\fR.
81 .lp
82 Commands passed between the driver and the adapter can
83 be any one of the network control block (\fINCB\fR)
84 commands described in the section "NCB Commands", below.
85 All commands to and from the adapter are
86 communicated in the Network Control Block and Request Vector within
87 the adapter's Common Data Area.
88 .lp
89 \fIEcnload\fR starts the
90 Eicon Technology Network Adapter software on the adapter
91 and downloads the validated configuration
92 to the driver.
93 .sh 3 "ECN Requests"
94 .lp
95 The \fIECN\fR request types that CONS can pass to the driver are listed below.
96 .ip "\fIECN_STOP - (by calling ecnshutdown())\fR"
97 This request instructs the driver to restart the network but not to listen for
98 any incoming calls.
99 CONS issues this request in response to an \fIioctl()\fR command
100 issued by the utility program \fIifconfig\fR, when
101 \fIifconfig\fR is used to bring down the adapter.
102 .ip "\fIECN_RESTART - (by calling ecnrestart())\fR"
103 This request instructs the driver to restart the network \fIand\fR to listen
104 and accept any incoming calls.
105 CONS issues this request in response to an \fIioctl()\fR command
106 issued by the utility program \fIifconfig\fR, when
107 \fIifconfig\fR is used to bring the adapter up.
108 .ip "\fIECN_CALL - 0x90\fR"
109 This request instructs the driver to place
110 a call request
111 to the specified DTE.
112 .ip "\fIECN_CLEAR - 0x92\fR"
113 This request instructs the driver to clear a given virtual circuit.
114 All outbound data are acknowledged by the remote DTE
115 before the circuit is cleared.
116 .ip "\fIECN_SEND - 0x94\fR"
117 This request instructs the driver to transmit a data buffer across a given
118 virtual circuit.
119 .ip "\fIECN_RESET - 0x04\fR"
120 This request instructs the driver to reset the given virtual circuit and
121 clear out all outstanding requests
122 associated with that virtual circuit.
123 .ip "\fIECN_STATUS - 0xb4 (exclusively through ecnioctl())\fR"
124 This requests instructs the driver to
125 solicit the adapter's current connection state information and
126 counters.
127 .sh 3 "ECN Replies"
128 .lp
129 The \fIECN\fR responses
130 the driver can give
131 to CONS are listed below.
132 .ip "\fIECN_CONNECT - 0x01\fR"
133 This reply notifies CONS that the driver has established a virtual circuit
134 connection initiated by the remote DTE.
135 .ip "\fIECN_ACCEPT - 0x03\fR"
136 This reply notifies CONS that an ECN_CALL request has succeeded. The
137 reply contains a pointer to a protocol control block.
138 .ip "\fIECN_REFUSE - 0x02\fR"
139 This reply notifies CONS that a previous \fIECN_CALL\fR request has failed.
140 The reply contains a pointer to a protocol control block.
141 .ip "\fIECN_CLEAR - 0x92\fR"
142 This reply notifies CONS that a given virtual circuit has been cleared
143 either by the DCE or by the remote DTE.
144 .ip "\fIECN_RECEIVE - 0x95\fR"
145 This reply notifies CONS that the driver has received a data packet from
146 the remote DTE.
147 .ip "\fIECN_RESET - 0x04\fR"
148 This reply notifies CONS that the virtual circuit has been reset either
149 by the DCE or by the remote DTE.
150 .ip "\fIECN_ACK - 0x05\fR"
151 This reply tells CONS that the associated ECN_SEND request has been been
152 completed by the adapter.
153 .sh 3 "NCB Commands"
154 .lp
155 The driver hides from the CONS module
156 many of the idiosyncrasies of the adapter's
157 software interface
158 by mapping many of the above \fIECN\fR requests into corresponding
159 \fINCB\fR commands. Below is a list of requests that the driver can place to
160 the adapter. For each request that the driver places to the adapter, the adapter
161 returns with a command completion.
162 .ip "\fINCB_CALL - 0x90\fR"
163 This command creates a virtual circuit.
164 .ip "\fINCB_LISTEN - 0x91\fR"
165 This command tells the adapter that our host is
166 willing to accept incoming calls.
167 .ip "\fINCB_CLEAR (and NCB_ABORT) - 0x92\fR"
168 This command clears a virtual circuit. An option exists to clear the circuit
169 immediately, without waiting first for outstanding acknowledgments.
170 .ip "\fINCB_SEND (and NCB_RESET) - 0x94\fR"
171 This command sends data to the remote DTE. An option is
172 available for resetting the
173 virtual circuit. This command can return a status indicating that the
174 circuit has been cleared by the DCE or the remote DTE.
175 .ip "\fINCB_RECEIVE - 0x95\fR"
176 This command tells the adapter that our host is
177 willing to receive data on a given virtual circuit. This command can return
178 received data, a reset circuit, M-, D-, and Q-bits, interrupt packets,
179 or a cleared circuit.
180 .ip "\fINCB_STATUS - 0xb4\fR"
181 This command queries the adapter about
182 the status of a virtual circuit.
183 The driver uses this command to support the ECN_STATUS request.
184 .ip "\fINCB_RESTART - 0xb2\fR"
185 This command restarts the network. This command requires that a corresponding
186 configuration file be passed down to the adapter.
187 .bp
188 .sh 3 "ECN Request and Reply Structure"
189 .lp
190 Below is
191 the data structure used in CONS-driver
192 communications.
193 This data structure is a parameter to the
194 \fIecnoutput()\fR procedure.
195 \fC
196 .nf
197 /* Eicon Driver Request Structure -- used between CONS and the driver */
199 struct eicon_request {
200 struct ecn_ncb eicon_req_ncb; /* the network control block */
201 caddr_t eicon_req_pcb; /* CONS pcb used on CALL requests */
202 int eicon_req_state; /* used internally by the driver */
203 int eicon_retry_cnt; /* used internally by the driver */
204 int eicon_more; /* used internally by the driver */
205 u_char eicon_reason; /* source of CLEAR requests */
206 };
207 \fR
208 .lp
209 The \fCeicon_req_ncb\fR field in the eicon request structure is of
210 type \fCecn_ncb\fR, defined in the following section. This structure stores
211 the command block
212 that the driver uses in communicating with the adapter.
213 The command block contains a \fIlogical session number\fR (LSN),
214 which identifies a virtual circuit.
215 Requests such as ECN_CALL are made without an LSN to identify
216 a circuit.
217 When an LSN is not available, the request is identified by
218 the field
219 \fCeicon_req_pcb\fR, which is a pointer to a CONS protocol control block.
220 The \fCeicon_req_state\fR field is used by the driver to keep track
221 of the status of the given request.
222 The following list defines the various values for this field:
223 .ip "\fIREQ_NEW\fR"
224 The driver recognizes a new request, has placed the request into the driver's
225 own request queue, but has yet to interrupt the
226 adapter. (The driver maintains a pointer \fCecn_pending_req\fR that indicates
227 whether an interrupt to the adapter is outstanding. If one is outstanding, the
228 driver places any new requests in this \fIREQ_NEW\fR state. If an interrupt
229 is not
230 outstanding, the driver places the request immediately in the
231 \fIREQ_INTERRUPT\fR state defined below.)
232 .ip "\fIREQ_INTERRUPT\fR"
233 The driver has dequeued the CONS request, assigned \fCecn_pending_req\fR to
234 point to the request, and
235 interrupted the adapter for a chance to post this request.
236 .ip "\fIREQ_POSTED\fR"
237 The driver has sent the request to the adapter.
238 .ip "\fIREQ_COMPLETE\fR"
239 The driver has just completed the request, and if necessary, is now posting
240 it to CONS.
241 .lp
242 The \fCeicon_retry_cnt\fR field in the eicon request structure keeps track
243 of how many times the driver has tried posting this command to the adapter.
244 After the second retry, the driver gives up and performs the appropriate
245 error routine.
246 The \fCeicon_more\fR field defines a \fIRECEIVE\fR request that
247 has been re-posted to the adapter to take care of m-bit transfers.
248 The \fCeicon_reason\fR field quantifies the reason for a connection being
249 cleared. These reasons are defined in the include file \fCiso_errno.h\fR.
250 .lp
251 Any data associated with the request are linked to the request through the
252 request mbuf's \fCm_next\fR field.
253 This is done so that when
254 the driver calls the \fIMFREE_M\fR deallocation routine, both the request
255 and the data are freed together.
256 .lp
257 The following chart defines those fields within the eicon request structure
258 that are relevant in any CONS request
259 to the driver via the \fIecnoutput()\fR call.
260 .sp
261 .sz 8
262 .TS
263 center,box,tab(:);
264 c s s s s
265 c||c s s s
266 c||c|c|c|c
267 l||l|l|l|l.
268 \fBField Definitions for CONS \(-> Driver Requests\fR
269 _
270 \fI:Request Types (CONS \(-> Driver)\fR
271 \fIField:ECN_CALL:ECN_CLEAR:ECN_SEND:ECN_RESET\fR
272 =
273 \fIncb\(->command\fR:0x90:0x92:0x94:0x04
274 _
275 \fIncb\(->loc_ses_num\fR:T{
276 .na
277 leave as zero
278 T}:VC #:VC #:VC #
279 _
280 \fIncb\(->info\fR:0x0:0x0:0x0:0x2
281 _
282 \fIeicon_req_pcb\fR:T{
283 .na
284 address of CONS' protocol control block
285 T}:NULL:NULL:NULL
286 _
287 \fIeicon_req_data\fR:T{
288 .na
289 address of mbuf containing contents of Call Request packet (including DTE address, facilities, and call user data)
290 T}:T{
291 .na
292 NULL or address of mbuf containing contents of Clear Request packet
293 T}:T{
294 .na
295 address of mbuf containing contents of user data
296 T}:T{
297 .na
298 NULL or the address of mbuf containing a one byte Reset Diagnostic code
299 T}
300 .TE
301 .sz 10
302 .sh 3 "Structure of the Network Control Block (NCB)"
303 .lp
304 The \fCecn_ncb\fR structure is used by the driver to
305 make requests of the adapter.
306 \fC
307 .nf
308 /* Network Control Block -- used between the driver and the Eicon adapter */
310 struct ecn_ncb {
311 u_char command; /* command field */
312 u_char retcode; /* return code field */
313 u_char lsn; /* local session number */
314 u_char info; /* additional information */
315 caddr_t buffer; /* pointer to data buffer's mbuf */
316 u_short length; /* buffer length */
317 u_char callname[16]; /* module name on NA "X25" */
318 u_char appl_name[16]; /* application name */
319 u_char rxto; /* receive timeout in secs */
320 u_char txto; /* send(tx) timeout in secs */
321 caddr_t post; /* NULL */
322 u_char lana_num; /* specifies Eicon Tech NA */
323 u_char cmd_cplt; /* command status */
324 u_char reserve[14]; /* reserved area */
325 };
326 \fR
327 .sp
328 .lp
329 The chart below defines those fields that are relevant in any
330 reply passed by the driver back up to CONS.
331 .sp
332 .sz 7
333 .TS
334 center,box,tab(:);
335 c s s s s s s
336 c||c s s s s s
337 c||c|c|c|c|c|c
338 l||l|l|l|l|l|l.
339 \fBField Definitions for Driver \(-> CONS Replies\fR
340 _
341 \fI:Reply Types (Driver \(-> CONS)\fR
342 \fIField:ECN_CONNECT:ECN_ACCEPT:ECN_REFUSE:ECN_CLEAR:ECN_RECEIVE:ECN_RESET\fR
343 =
344 \fIncb\(->command\fR:0x01:0x03:0x02:0x92:0x95:0x04
345 _
346 \fIncb\(->loc_ses_num\fR:VC #:VC #:ignore:VC #:VC #:VC #
347 _
348 \fIncb\(->info\fR:ignore:ignore:ignore:ignore:T{
349 .na
350 Interrupt received (bit 0), D-bit set (bit 6), and/or Q-bit set (bit 7). Zero
351 info field implies a normal receive.
352 T}:ignore
353 _
354 \fIeicon_req_pcb\fR:NULL:T{
355 .na
356 address of CONS's protocol control block
357 T}:T{
358 .na
359 address of CONS's protocol control block
360 T}:ignore:ignore:ignore
361 _
362 \fIeicon_req_data\fR:T{
363 .na
364 NULL or address of mbuf containing contents of Call Indication packet
365 T}:T{
366 .na
367 NULL or address of mbuf containing contents of Call Connected data
368 T}:T{
369 .na
370 NULL or address of mbuf containing contents of Call Cleared data
371 T}:T{
372 .na
373 NULL or address of mbuf containing contents of Call Cleared data
374 T}:T{
375 .na
376 address of mbuf containing contents of user data
377 T}:T{
378 .na
379 NULL or address of mbuf containing one byte Reset Diagnostic code
380 T}
381 _
382 \fIeicon_reason\fR:ignore:ignore:T{
383 .na
384 reason for refusal
385 T}:T{
386 .na
387 reason for clear
388 .T}:ignore:T{
389 .na
390 reason for reset
391 T}
392 .TE
393 .sz 10
394 .bp
395 .sh 3 "Internal Driver Data Sructures"
396 .lp
397 The main driver data structure
398 is the \fIecn_softc\fR structure.
399 This structure keeps track of the interface request queue
400 (\fCecn_if\fR and \fCecn_pending_req\fR),
401 magic addresses on the adapter (\fCecn_iom_base, ecn_mem_base,\fR and
402 \fCecn_data_base\fR),
403 error statistics (\fCecn_errors\fR), the state
404 of each virtual circuit (\fCecn_vc_state\fR), the state of the \fILISTEN\fR
405 request (\fCecn_listen_pending\fR), and the current caller (\fCecn_cause\fR).
406 \fC
407 .nf
408 struct ecn_softc {
409 int ecn_errors[NCB_MAX][ST_MAX];
410 int ecn_cause[CAUSE_MAX]; /* ecn_work() causes */
411 struct mbuf *ecn_pending_req; /* waiting for command req */
412 char ecn_listen_pending; /* boolean = listen req pending? */
413 char ecn_vc_state[LSN_MAX]; /* the current state of each vc */
414 struct ecn_device
415 *ecn_iom_base; /* base address of io map */
416 struct ecn_request_vector
417 *ecn_mem_base; /* base address of memory map */
418 caddr_t ecn_data_base; /* base address for data area */
419 struct ifnet ecn_if; /* queue of new requests */
420 }
421 \fR
422 .so figs/ecn_queue.nr
423 .sh 2 "Queueing in the Driver"
424 .lp
425 .CF
426 illustrates the queueing mechanism used by the driver.
427 .lp
428 CONS queues its data transfer requests at the end of the queue managed by
429 \fCecn_if\fR field in the \fCecn_softc\fR structure.
430 At this point, each request has the state value of
431 \fIREQ_NEW\fR.
432 Once the driver notifies the adapter that it has a command to post,
433 the driver dequeues the first request from the \fCecn_if\fR queue
434 and sets the pointer
435 \fCecn_pending_req\fR to point to the request.
436 At this point, the request is in the \fIREQ_INTERRUPT\fR state.
437 .lp
438 Once the driver posts the request to the adapter, it
439 dequeues the next request in the \fCecn_if\fR queue, reassigns the
440 \fCecn_pending_req\fR pointer, and then indicates to the adapter
441 that it is ready to post another request.
442 The driver no longer has to keep track of the previous request,
443 because for every reply, the adapter includes the associated
444 mbuf pointer.
445 While the request is outstanding, the request is in the \fIREQ_POSTED\fR state.
446 .so figs/ecn_vc.nr
447 .lp
448 After the adapter completes the command, the driver may want to reply to CONS.
449 It does this by placing its reply in CONS's \fCconsintrq\fR queue, defined as
450 an external \fCifqueue\fR in the driver code.
451 .sh 2 "Virtual Circuit States"
452 .lp
453 The \fCecn_vc_state\fR array in the \fCecn_softc\fR structure above keeps track
454 of the state of each virtual circuit (VC).
455 This is necessary to avoid handing
456 the adapter any commands that may not apply during a given state.
457 This mechanism
458 is especially useful in dealing with unexpected aborts or clears where there
459 is the potential for all outstanding commands to complete with errors.
460 By changing
461 states, the driver can prevent redundant commands (like clears and aborts)
462 from being passed either to the adapter or to CONS.
463 .lp
464 The driver only keeps track of four different states, as illustrated in
465 .CF
466 .
467 These states are:
468 .ip "\fIVC_NO_CONNECTION\fR"
469 When a virtual circuit is in this state, the virtual circuit does not exits.
470 Only \fICALL\fR and \fILISTEN\fR commands are valid.
471 .ip "\fIVC_DATA_XFER\fR"
472 All commands, except \fICALL\fR and \fILISTEN\fR commands are valid once the
473 connection exists.
474 .ip "\fIVC_RESET_IN_PROGRESS\fR"
475 In this state, either the driver has issued an \fINCB_RESET\fR or it has
476 received a reset error code on the completion of a command.
477 Only reissued \fIRESET\fR commands and \fIRECEIVE\fRs are
478 valid.
479 \fIRECEIVE\fR is valid in this state because the adapter uses the
480 completion of this command to hand back the cause of the reset (the RESET
481 INDICATION packet).
482 .ip "\fIVC_CLEAR_IN_PROGRESS\fR"
483 The driver has either issued an \fINCB_CLEAR\fR command or has just
484 received a clear error code on the completion of a command.
485 Within this state, only reissued
486 \fICLEAR\fR and \fIABORT\fR commands are valid.
487 .sh 2 "Error Statistics"
488 .lp
489 With the \fCecn_errors\fR field in the \fCecn_softc\fR structure,
490 the driver maintains a two dimensional array of counters
491 if the frequencies of errors.
492 In order to inspect this array easily with
493 the kernel debugger, the first index to every command ( <command, 0> ) is
494 reserved for a four character ASCII command identifier.
495 .bp
496 .sh 3 "The Driver State Machine"
497 .sh 2 "Handling of Normal Command Completions"
498 .lp
499 The chart below lists
500 all the available adapter request types, at what level each of
501 these requests can be used, options, and the driver's action after a normal
502 completion of the command.
503 .sp
504 .sz 7
505 .TS
506 center,box,tab(:);
507 c s s s
508 c|c s|c
509 c|c|c|c
510 l|l|l|l.
511 \fBNormal Completion Handling\fR
512 _
513 \fINCB:Options:Action Based on Normal Competion of\fR
514 \fICommand:To Adapter:From Adapter:Driver\(->Adapter Command\fR
515 =
516 \fINCB_RESTART\fR:none:none:T{
517 .na
518 dequeue the request, and issue an NCB_LISTEN request to the adapter.
519 T}
520 _
521 \fINCB_CALL\fR:none:connected:T{
522 .na
523 dequeue the request, pass an ECN_ACCEPT reply to CONS, and issue a RECEIVE to
524 the adapter.
525 T}
526 _
527 \fINCB_LISTEN\fR:T{
528 .na
529 use zero-length Call User Data and a zero-length Calling DTE address
530 T}:none:T{
531 .na
532 dequeue the request, pass an ECN_CONNECT to CONS, and issue a RECEIVE to the
533 adapter. Re-issue another NCB_LISTEN
534 for another possible virtual circuit connection.
535 T}
536 _
537 \fINCB_CLEAR\fR:T{
538 .na
539 normal clearing with all outstanding ACKs returned
540 T}:none:T{
541 .na
542 dequeue the request.
543 T}
544 :_:_:_
545 :T{
546 .na
547 immediate clearing
548 T}:none:T{
549 .na
550 dequeue the request.
551 T}
552 _
553 \fINCB_SEND\fR:T{
554 .na
555 normal send
556 T}:none:T{
557 .na
558 dequeue the request and reply to CONS with an ECN_ACK.
559 T}
560 :_:_:_
561 :T{
562 .na
563 reset the virtual circuit
564 T}:none:T{
565 dequeue the request.
566 T}
567 _
568 \fINCB_RECEIVE\fR:none:T{
569 .na
570 normal, uncomplicated receive
571 T}:T{
572 .na
573 dequeue the request and bcopy the data into the request's associated mbuf. Ship to CONS. Re-issue another NCB_RECEIVE.
574 T}
575 :_:_:_
576 :none:T{
577 .na
578 m-bit set
579 T}:T{
580 .na
581 same as above (adapter does the resegmentation automatically).
582 T}
583 :_:_:_
584 :none:T{
585 .na
586 d-bit set
587 T}:T{
588 .na
589 same as above.
590 T}
591 :_:_:_
592 :none:T{
593 .na
594 q-bit set
595 T}:T{
596 .na
597 same as above.
598 T}
599 :_:_:_
600 :none:T{
601 .na
602 interrupt received
603 T}:T{
604 .na
605 same as above.
606 T}
607 :_:_:_
608 :none:T{
609 .na
610 reset received
611 T}:T{
612 dequeue the request, send an ECN_RESET back up to CONS, and issue another
613 receive.
614 T}
615 .TE
616 .sz 10
617 .sp
618 .uh "CONS \(-> Driver"
619 .lp
620 All entries in this column indicate that the CONS module can send this request
621 down to the driver. Command names in parenthesis define the mapping between
622 the \fIECN\fR and \fINCB\fR commands.
623 .uh "Driver \(-> Adapter"
624 .lp
625 All checks in this column indicate that the driver can send this request
626 to the adapter. The last column in the above table defines what the driver must
627 do upon normal completion of the command from the adapter.
628 Note that not all driver-to-adapter
629 commands have a CONS-to-driver equivalent.
630 This shows that this
631 command request is generated within the driver, rather than originating from
632 the CONS driver.
633 .uh "Driver \(-> CONS"
634 .lp
635 All entries in this column indicate that the driver can send this reply
636 back to CONS. Command names in parenthesis define the mapping between
637 the \fIECN\fR and \fINCB\fR commands.
638 .bp
639 .sh 3 "Handling of Errors upon Command Completion"
640 .lp
641 Below is listed all the driver request and pseudo request types, along with the
642 actions the driver must perform given a command completion error delivered by
643 the Eicon Network Adapter.
644 .sp
645 .sz 7
646 .TS
647 center,box,tab(:);
648 c s s s s s s s
649 c||c s s s s s s
650 c||c|c|c|c|c|c|c
651 c||c|c|c|c|c|c|c
652 l||l|l|l|l|l|l|l.
653 \fBError Completion Handling\fR
654 _
655 :\fIAction Based on Error Completion of Driver \(-> Adapter Command\fR
656 \fIError Returned\fR:_:_:_:_:_:_:_
657 \fI:NCB_CALL:NCB_LISTEN:NCB_CLEAR:NCB_ABORT:NCB_RESET:NCB_SEND:NCB_RECEIVE\fR
658 =
659 \fIST_BAD_LEN\fR:<soft-error>:<soft-error>:<soft-error>:<soft-error>:<soft-error>:<soft-error>:<soft-error>
660 _
661 \fIST_INVALID\fR:<soft-error>:<soft-error>:<dequeue>:<dequeue>:<dequeue>:<dequeue>:<dequeue>
662 _
663 \fIST_COMMAND_TO\fR:<retry>:<retry>:<retry>:<retry>:<abort>:<abort>:<retry>
664 _
665 \fIST_ISSUE_ANOTHER_RCV\fR:<refuse>:<retry>:<retry>:<retry>:<abort>:<abort>:T{
666 .na
667 requeue request and increment "more" count
668 T}
669 _
670 \fIST_BAD_LSN\fR:<soft-error>:<soft-error>:<dequeue>:<dequeue>:<dequeue>:<dequeue>:<dequeue>
671 _
672 \fIST_NO_RESOURCES\fR:<retry>:<retry>:<retry>:<retry>:<abort>:<abort>:<retry>
673 _
674 \fIST_CALL_CLEARED\fR:<refuse>:<retry>:<retry>:<retry>:<clear>:<clear>:<clear>
675 _
676 \fIST_COMMAND_CANCELLED\fR:<refuse>:<retry>:<retry>:<retry>:<abort>:<abort>:<abort>:
677 _
678 \fIST_NO_CIRCUITS\fR:<refuse>:<retry>:<retry>:<retry>:<abort>:<abort>:<abort>
679 _
680 \fIST_CALL_UNSUCCESSFUL\fR:<refuse>:<retry>:<retry>:<retry>:<abort>:<abort>:<abort>
681 _
682 \fIST_INCORRECT_CALLNAME\fR:<soft-error>:<soft-error>:<soft-error>:<soft-error>:<soft-error>:<soft-error>:<soft-error>
683 _
684 \fIST_X25_RESET\fR:<refuse>:<retry>:<retry>:<retry>:<dequeue>:<dequeue>:<retry>
685 _
686 \fIST_TOO_MANY_COMMANDS\fR:<retry>:<retry>:<retry>:<retry>:<abort>:<abort>:<retry>
687 _
688 \fIST_L1_NO_DATA_SET_READY\fR:<refuse>:<retry>:<retry>:<retry>:<abort>:<abort>:<abort>
689 _
690 \fIST_L1_NO_CLEAR_TO_SEND\fR:<refuse>:<retry>:<retry>:<retry>:<abort>:<abort>:<abort>
691 _
692 \fIST_L1_NO_CLOCK\fR:<refuse>:<retry>:<retry>:<retry>:<abort>:<abort>:<abort>
693 .TE
694 .sz 10
695 .sp
696 .lp
697 Each of the actions from the above chart are defined as follows.
698 .ip "\fI<abort>\fR -"
699 The driver should clear the connection by issuing an \fINCB_ABORT\fR
700 to the adapter and sending an \fIECN_CLEAR\fR to CONS.
701 .ip "\fI<refuse>\fR -"
702 The driver should send an \fIECN_REFUSE\fR back to CONS.
703 .ip "\fI<dequeue>\fR -"
704 The driver should simply dequeue the request. Usually these errors occur when a
705 reset or clear occurs on the adapter while the driver is in the midst of
706 issuing the command which subsequently completes with an error status.
707 .ip "\fI<clear>\fR -"
708 The driver should send an \fIECN_CLEAR\fR back up to CONS.
709 .ip "\fI<retry>\fR -"
710 The driver should requeue the request if and only if the
711 \fCecn_retry_cnt\fR field in the request structure does not exceed the
712 retry maximum.
713 .ip "\fI<soft-error>\fR -"
714 This action only takes place when a software error has occurred. The driver
715 should
716 print the error to the console in big bold letters and then panic.
717 .bp
718 .sh 3 "The IFP Flags"
719 .lp
720 The IFP flags in the standard \fCifnet\fR structure
721 should be used in the following way.
722 .ip "\fIIFF_UP on -\fR"
723 This flag is set by the driver only after the procedure \fIecnrestart()\fR
724 successfully completes.
725 .ip "\fIIFF_UP off -\fR"
726 This flag is set immediately upon entry into the procedure \fIecnshutdown()\fR.
727 .ip "\fIIFF_RUNNING on -\fR"
728 This flag is set on whenever the \fIecnwork()\fR procedure is active, eg. the
729 driver is actually doing something.
730 .ip "\fIIFF_RUNNING off -\fR"
731 This flag is turned off upon exit from the \fIecnwork()\fR procedure.