Copyright (c) 1999 Massachusetts Institute of Technology This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. ------------------------------ Warning- don't believe everything in this file! ITS NCP INTERFACE CALL: .OPEN FUNCTION: OPEN channel to Network ARGUMENT TEMPLATE: 1. Channel number in AC field of .OPEN instruction 2. 4 word block addressed by @ E (X) field of .OPEN instruction 4 word block has this form: _________________________________________________ | | | | MODE BITS | SIXBIT /NET/ | |_______________________|_______________________| | | | LOCAL SOCKET | |_______________________________________________| | | | FOREIGN SOCKET | |_______________________________________________| | | | FOREIGN HOST | |_______________________________________________| MODE BITS |--------- don't buffer more | output than allocation | | |----- 0-200 words | | 1-2000 words | | ____________________________________________________________________________ | | | | | |out|big|by- lis gen|im- | | | SIZE OF BYTE | | |ctl|buf| te ten sok|age blk out| |___________|___________|___________|___|___|___|___|___|___|_#_|___|___|___| | | | | |_____| BYTE SIZE IF | 0-"NORMAL" | | | | MODE=44 __| 1-8 BIT BYTE SIZE _______| | | (BYTE & IMAGE) IF ASCII | | STANDARD USE BYTE FIELD | | ITS IF IMAGE | | MODES | | ______________ 0-"NORMAL" | | | | 1-LISTEN ON ___________| | | 0XX ASCII | LOCAL SOCKET | | 1XX IMAGE | | | X0X UNIT | 0-USE LOCAL | | X1X BLOCK | SOCKET FIELD | | XX0 INPUT | 1-GENERATE _______________| | XX1 OUTPUT | "UNIQUE" SOCKET |____________| # (USE .RCHST TO FIND OUT RESULT) LOCAL SOCKET 32 bit socket # for local identification FOREIGN SOCKET 32 bit socket # determined by foreign host system FOREIGN HOST 8 bit socket # specifying computer system with which to contact RETURNS: None SKIPS: No Skip If Fails FAILURE RETURNS: Indicated in LH of .STATUS value (low order 6 bits in LH) i.e. .STATUS ch, ac LDB ac, [220600,,ac] CODE____ 2 "WRONG DIRECTION" (gender of socket wrong for mode) 6 "DEVICE FULL" (socket table full) 7 "DEVICE NOT READY" (NCP not up, or IMP not up) 13 "FILE ALREADY EXISTS" (socket already open by you on another channel) 22 "CONTRADICTORY OPEN" (byte size mismatched) 23 "FILE LOCKED" (socket number not part of your allocated "unique" group of 8 allocated to your job) 41 "OTHER END OF PIPELINE GONE OR NOT OPEN" (HOST dead or non-existant see NETHST call) SIDE EFFECTS: EXAMPLES: ;to listen .OPEN ch, listen JRST fail . . Listen: 20,,'NET 1 ;waiting socket 0 ;socket determined when matching RFC received 0 ;host determined when matching RFC received :to get "unique socket" .OPEN ch, unique JRST fail :Unique 10,,'NET 0 ;determined by system 1305 ;foreign socket 6 ;foreign host Equivalent: .CALL OPEN arg 1 mode,,channel number arg 2 SIXBIT/NET/ arg 3 local socket arg 4 foreign socket arg 5 host number CALL: .RCHST FUNCTION: Read extended STatus of network CHannel ARGUMENT TEMPLATE: AC/ channel,, RETURNS: WORD _________________________________ | | | 0 | | 'NET | |_______________|_______________| | | 1 | LOCAL SOCKET | |_______________________________| | | 2 | FOREIGN SOCKET | |_______________________________| | | | BYTE | | 3 | I | (reserved)| SIZE | HOST | |___|___________|_______|_______| | | | 4 | IMP DOWN | STATE | |_______________|_______________| | | | 5 | (reserved) | CLS | |_______________|_______________| | | | 6 | (reserved) | #BITS | |_______________|_______________| INTERRUPT 4.9 bit of word 3 set by receipt over network of INR/INS control message (see protocol) cleared by .RESET causes interrupt on channel BYTE SIZE 9 bit field byte size of connection (bits 2.9 - 2.1) HOST 9 bit field (8 used by Network foreign host #) IMP DOWN time in 1/30 sec. until IMP going down (if planned) -1 not going down 0 down +n planned to go down in n/30 sec. (see also NETIMP call) STATE %NSCLS 0 connection closed %NSLSN 1 listening for RFC %NSRFC 2 RFC in to listen %NSRCL 3 CLS received after RFC %NSRFS 4 RFC sent %NSOPN 5 open %NSRFN 6 RFNM wait on output %NSCLW 7 CLS sent, waiting for matching CLS %NSCLI 10 CLS received data available to input %NSINP 11 input available REASON FOR CLS (state 0) %NCNTO 0 never opened connection (not .OPEN) %NCUSR 1 CLS by user (.CLOSE) %NCFRN 2 CLS by foreign host %NCRST 3 RST (reset) from foreign host (dead) %NCDED 4 host dead (see also NETHST call) %NCINC 5 incomplete transmission (see NETHST) %NCBYT 6 byte size mismatch %NCNCP 7 local NCP went down, breaking connection %NCRFS 10 connection refused by foreign host SKIPS: No skip FAILURE RETURNS: None SIDE EFFECTS: None EXAMPLE: MOVE ac, [ch,,blk] .RCHST ac, . . BLK: BLOCK 7 Equivalent: .CALL RCHST arg 1 network channel number val 1 'NET,,0 val 2 local socket number val 3 foreign socket number val 4 4.9 interrupt received 2.1-2.9 byte size 1.1-1.9 host number val 5 LH IMP Down time/reason RH Socket state (%NSxxx) val 6 Open mode val 7 RH Close reason (%NCxxx) val 8 RH Number of bits____ available (input data available or output buffer room) .CALL WHYINT arg 1 network channel number val 1 %WYNET val 2 Socket state (%NSxxx) val 3 Number of bytes_____ available (input data available or output buffer room) val 4 Close reason (%NSxxx) This call is usually used to respond to a second-word interrupt from a network channel. CALL: .STATUS FUNCTION: Reads status of Network channel ARGUMENT TEMPLATE: Channel number in AC field of .STATUS instruction RETURNS: Status of word in location addressed by @ E (X) fields of .STATUS instruction SKIPS: No skip FAILURE RETURNS: None SIDE EFFECTS: None EXAMPLE: .STATUS ch, statwd Statwd: BLOCK 1 FORMAT OF STATUS WORD _________________________________ | | | | ERROR CODE | SS0026 | |_______________|_______________| ERROR CODE if IOC (I/O channel error) or OPEN failure, codes will be stored here. SS state (byte 140600), same as that given for .RCHST -- see list of states 26 code for Network device Equivalent: .CALL STATUS arg 1 channel number val 1 status word as above CALL: .NETACC FUNCTION: NETwork ACcepts Connection (after LISTEN type .OPEN) (to REJECT, do a .CLOSE) ARGUMENT TEMPLATE: Channel number in AC field of .NETACC instruction RETURNS: Nothing SKIPS: Skips on success FAILURE RETURNS: Not skip --not in state 2 (RFC received to LISTEN) SIDE EFFECTS: Sends matching RFC (and "allocate" if input) EXAMPLE: .NETACC ch, JRST error CALL: .NETS FUNCTION: NET Send buffer now (Buffer is normally sent when "full" or after 1/2 second of first activity) ARGUMENT TEMPLATE: Channel number in AC field .NETS of instruction RETURNS: Nothing SKIPS: No skip FAILURE RETURNS: IOC (I/O channel error) Code 1, if not SEND (write) channel SIDE EFFECTS: Buffer is queued to be sent immediately EXAMPLE: .NETS ch, CALL: .CALL FORCE arg 1 channel number Equivalent to .NETS (see above) CALL: .CALL FLUSH arg 1 channel number Does FORCE then waits for all buffered data to be sent and for the final RFNM to come back. CALL: .CLOSE FUNCTION: CLOSEs channel and returns immediately ARGUMENT TEMPLATE: Channel number in AC field of .CLOSE instruction RETURNS: None SKIPS: No skip FAILURE RETURNS: None EXAMPLE: .CLOSE ch, Equivalent: .CALL CLOSE arg 1 channel number CALL: .CALL NETBLK FUNCTION: Hang until connection is not in specified state or until time out ARGUMENT TEMPLATE: Standard .CALL arguments 1. channel number 2. state -- returns when not in this state 3. (optional) time -- number of 30ths of second to wait or -- (time since system up) in 30ths of second RETURNS: 1. (optional) state -- new state 2. (optional) time -- time left after state change SKIPS: Skips on success FAILURE RETURNS: Not skip and OPEN code 14 -- channel number not <20 -- channel not Network device SIDE EFFECTS: None EXAMPLE: .CALL netblk JRST error . . Netblk: SETZ SIXBIT /NETBLK/ channel state time 2000,,newstate 402000,,timeleft Channel: ch State: <-wait for this state to be left>- Time: <-30ths of second to wait>- Newstate: BLOCK 1 Timeleft: BLOCK 1 The time argument is clobbered in the same way that .SLEEP clobbers its AC; unless it is immediate. In that case, the time out will be restarted if the job is pclsred. CALL: .RESET FUNCTION: Used to RESET interrupt bit (INR/INS from Network) ARGUMENT TEMPLATE: Channel number in AC field of .RESET instruction RETURNS: Nothing SKIPS: No skip FAILURE RETURNS: None SIDE EFFECTS: Clears the Network interrupt bit (see .RCHST, bit 4.9 of word 3) EXAMPLE: .RESET ch, Equivalent: .CALL RESET arg 1 channel number CALL: .NETINT FUNCTION: Sends Network INR/INS control message for link corresponding to channel. (TELNET protocol also demands a "data mark" to be inserted in the stream) ARGUMENT TEMPLATE: Channel number in AC field of .NETINT instruction RETURNS: Nothing SKIPS: Skip if success No skip if Network down or not a Network channel FAILURE RETURNS: I/O Channel error Interrupt, NET went down Code 1 SIDE EFFECTS: Sends NET INR/INS control message EXAMPLE: .NETINT ch, JRST fail CALL: .GETSYS areas NCPHTB NCPPQ NCPSM FUNCTION: Get socket map host table pending queue ARGUMENT TEMPLATE: Name of first of 2 consecutive accumulators in AC field of .GETSYS instruction ac/ -<-length>-,,<-address>- ;CPTR to block to store ac+1/ SIXBIT/<-name>-/ ;sixbit name of area desired RETURNS: Block of desired information SKIPS: Skips on success FAILURE RETURNS: No skip -- area name not known in system -- not enough memory (ac+1 zeroes) (ac gets <-lng,,> for number of words needed) SIDE EFFECTS: None EXAMPLE 1: ;This can be used to find out how much storage is needed for a .GETSYS block HRROI ac,temp MOVE ac+1, [SIXBIT/NCPSM/] .GETSYS ac, HLRES ac ;here ac contains lng,,temp MOVNS ac ;now ac contains number of words needed CALL FREE (ac) EXAMPLE 2: MOVE ac, [-lng,,blk] MOVE ac+1 [SIXBIT /NCPSM/] or NCPHTB or NCPPQ .GETSYS ac, JRST error . . BLK: BLOCK lng NCPHTB area Length -- 400 (8) words (256(10)) Format -- one word per host number (word(i) is data for host.number (i)) Each word has info packed -- |1| | 2 | 9 | 18 ______________________________________________ |R| | | | | | |F| | | | | | |N|unused|RST| CTL TIME|00| HOST DEAD STATUS | |M| | | | | | |_|______|___|_________|__|__________________| RFNM 0-control link open 1-waiting for RFNM on control link RST 0-host down or not tried 1-sent RST to see if up 2-got RRP, connections may be opened CTL TIME 9 Last time (1/30 sec module 2 ) message sent to this host on control link (0) HOST DEAD STATUS Last HOST DEAD STATUS from this host's IMP (See RFC 611) (If data for a single host is desired, use the NETHST call) HOST DEAD STATUS in right half Bits 20-31 (byte pointer [041400,,x]) give the time of the Host's coming back up, bit-coded as follows: Bits 20-22 (byte pointer [150300,,x] the day of the week the Host is coming back up Monday is day 0 and Sunday is day 6 Bits 23-27 (byte pointer [100500,,x]) the hour of the day, from hour 0 to hour 23, that the Host is coming back up Bits 28-31 (byte pointer [040400,,x]) the five minute interval, from 0 to 11, in the hour that the Host is coming back up All three of the above are specified in Universal Time (i.e., G.M.T.). The Host may indicate that it will be coming back up more than a week away by setting bits 20-31 all to ones (7777). Setting all bits 20-30 to one and bit 31 to zero (20-31 = 7776) means it is unknown when the Host is coming back up. Bits 32-35 have the follwing meanings: Value Meaning ----- ------- 0 The destination Host is not communicating with the network -- the destination IMP has no information about the cause. Note that this is the message most likely to occur if the destination IMP has gone down since the destination Host went down. 1 The destination Host is not communicating with the network -- it took its ready-line down without saying why. 2 The destination Host is not communicating with the network -- the Host was tardy in taking traffic from the network and the network had to declare the Host down. 3 The destination Host does not exist to the knowledge of the NCC. 4 Currently unused. 5 The destination Host is down for scheduled P.M. 6 The destination Host is down for scheduled hardware work. 7 The destination Host is down for scheduled software work. 8 The destination Host is down for emergency restart. 9 The destination Host is down because of power outage. 10 The destination Host is stopped at a software breakpoint. 11 The destination Host is down because of a hardware failure. 12-15 Currently Unused. When the value of this 4-bit field is 0,1,2, or 3, bits 20-31 will have the "unknown" indication. NCPPQ area -- pending queue of RFC's Length -- variable 3+4*n where n is currently 40 (8) but may change Format -- word 0 -- relocation word, tells location in system core where first slot begins word 1 -- pointer to first queue entry word 2 thru 4*n+1 -- 4 word slot for queue or -1 if last one on queue (0) -- pointer to next one (must un-relocate, using word 0 (1) -- local socket number (2) -- foreign socket number (3) -- sign bit 0 = STR 1 = RTS low order 8 bits (byte pointer [001000,,X]) link number if RTS byte size if STR next 8 bits (byte pointer [101000,,x]) foreign Host number Example of unrelocating for the NCPPQ area. ;Let ac,ac+1 and b be accumulators MOVE ac, [-lng,,blk] MOVE ac+1, [SIXBIT /NCPPQ/] GETSYS ac, JRST error MOVEI ac, blk MOVN b,(ac) ;-system address loop: ADD ac,b ;ac now points to ;first queue entry ;0(ac) is next pointer word ;1(ac) is local socket word ;2(ac) is foreign socket word ;3(ac) is Host -- lind/byte word MOVE ac,0(ac) ;get next JUMPGE ac,loop ;loop if not last one NCPSM area Length -- 1+13.*20. = 261(10) or 405(8) there are 13 (or more) blocks each of length IMPSTL (an assebly parameter, currintly 20(n)) Format -- word 0 -- contains IMPSTL, the number of words in each block word 1 -- begins first block -- the blocks are: IMSOC1: REPEAT IMPSTL,0 ; 0 => FREE ; 4.9 = 1 => SOCKET IN USE ; 4.8 = 1 => CHNL TRYING TO BE CLOSED ; 3.1-4.7 MASK FOR INTERRUPT BIT (LSH 1 CHNL#) ; RH = USER INDEX IMSOC2: BLOCK IMPSTL ; 1.1-4.5 = LOCAL SOCKET NUMBER ; 4.6-4.9 0 (MAKES COMPARISONS EASIER) IMSOC3: BLOCK IMPSTL ; 1.1-4.5 = FOREIGN SOCKET NUMBER ; 4.6-4.9 = 0 IMSOC4: BLOCK IMPSTL ; RH = SOCKET STATE ; 3.1-3.8 = LINK NUMBER ; 3.9-4.7 = FOREIGN HOST NUMBER ; 4.8 = SET BY RCV CLS - MAKES MATCH USING IMSCHD FAIL ; 4.9 = SEND THIS BUFFER NOW IMSOC5: BLOCK IMPSTL ; 1.1-1.8 = CONNECTION BYTE SIZE ; 2.1-2.9 = CLOSE REASON ; 3.1-3.8 = USER BYTE SIZE ; 3.9 => ASCII MODE - 7 BIT ; 4.1 => ASCII MODE - 8 BIT ; 4.2 => 1 BIT BYTES ; 4.3 => NET INTERRUPT (INR/INS) RECEIVED ; 4.4 => HAVE BEGUN CLOSE TIMEOUT ; 4.5 => CLOSED WHILE IN RFNM WAIT, EXPECT ANOTHER RFNM ; 4.9 => TRANSFER IN 32 BIT MODE IMSOC6: BLOCK IMPSTL ; RH => BUFFER ADDRESS ; 4.9 => LOCKED BY CORE JOB ; 4.8 => ACTIVE AT PI LEVEL ; 4.7 => INPUT OCCURRED WHILE BUFFER LOCKED ; 3.1-3.8 => IOBFT INDEX, OR 377 IF BIG BUFFER IMSOC7: BLOCK IMPSTL ; BIT ALLOCATION IMSOC8: BLOCK IMPSTL ; MESSAGE ALLOCATION IMSC7I: BLOCK IMPSTL ; AMOUNT TO INCREASE BIT ALLOCATION BY IN NEXT ALL MSG IMSC8I: BLOCK IMPSTL ; AMOUNT TO INCREASE MESSAGE ALLOCATION BY " " " " IMSOCT: BLOCK IMPSTL ; TIME WHEN FIRST MESS PUT INTO BUF ; (DURING INPUT HAS NUMBER OF DATA BYTES LEFT IN MSG) ; (DURING CLOSE HAS TIME TIMEOUT STARTED) IMSMPP: BLOCK IMPSTL ; MAIN PROGRAM POINTER, ILDB OR IDPB FOR NEXT BYTE IMSMPC: BLOCK IMPSTL ; MAIN PROGRAM COUNTER, FOR OUTPUT HAS ROOM LEFT ; IN BUFFER IN BYTES. FOR INPUT HAS TOTAL NUMBER ; OF DATA BYTES IN THE BUFFER. IMSPIP: BLOCK IMPSTL ; INTERRUPT LEVEL POINTER. FOR OUTPUT ILDB GETS ; FIRST BYTE OF NEXT MESSAGE OUT. FOR INPUT RH ; HAS ADDRESS OF HEADER WORD OF NEXT MESSAGE IN. IMSBFE: BLOCK IMPSTL ; BYTE POINTER TO LAST BYTE IN BUFFER. CALL: .IOT FUNCTION: Transfer data in or out over Network ARGUMENT TEMPLATE: Channel number in AC field of .IOT in struction <-word>- or pointer to block RETURNS: None (unit output mode) Datum (unit input mode) Updated pointer (block mode) SKIPS: No skip FAILURE RETURNS: I/O Channel error INTERRUPT Code 1 -- Network went down Code 8 -- Attempted output mode IOT when not in State 5 (open) or State 6 (RFNM wait) Or attempted input IOT when in bad state or when closed other than by foreign host. End of file is sensed when input is done from a socket closed by the foreign host. In unit image mode this gives I/O channel error code 2. SIDE EFFECTS: Output -- data buffered to be sent Input -- data copied from buffer ALLOCATE sent if buffer empty (enough) EXAMPLE: .IOT ch, foo In image block mode, one byte per word is transferred, right-justified. In ascii block mode, five bytes per word are transferred, or four bytes per word (8-bit) if mode bit 1.6 was on in the OPEN.