============================================================================= TermiteIP module SWI list ============================================================================= TermiteIP_Initialise TermiteIP_Finalise TermiteIP_Register TermiteIP_DeRegister TermiteIP_Poll *obsolete* TermiteIP_SendIPPacket TermiteIP_AllocatePort TermiteIP_CreateSocket TermiteIP_ClosePort TermiteIP_SendTCPData TermiteIP_SendUDPData TermiteIP_IPProtocolNumberToName TermiteIP_ReadIPProtocolEnable TermiteIP_ReadLinkStatus TermiteIP_ChecksumData TermiteIP_ReadPacket TermiteIP_ReadInformation TermiteIP_ReadTCPData TermiteIP_SendICMPMessage TermiteIP_ChecksumDataAndHeader TermiteIP_IPAddressToNumber TermiteIP_NumberToIPAddress TermiteIP_ReadNextEvent TermiteIP_NetToArcTime TermiteIP_PortInformation TermiteIP_DeleteSocket TermiteIP_TCPStateToText TermiteIP_DecodeICMPErrorMessage TermiteIP_StartTCPConnection TermiteIP_ReadTCPStatus TermiteIP_ConfigureTCP TermiteIP_ConvertPortNumber TermiteIP_ResolveAddToCache TermiteIP_ResolveReadCacheEntry TermiteIP_ResolveFindEntryInCache TermiteIP_ExamineTCPData TermiteIP_SetTCPSocketWindow TermiteIP_KickTCPSocket TermiteIP_CheckSocket TermiteIP_TelnetOp TermiteIP_ResolveOp TermiteIP_CloseTCPConnection TermiteIP_ReadTCPPointers TermiteIP_SetTCPSocketToListen TermiteIP_ResolveChangeCacheEntry TermiteIP_ResolveDeleteCacheEntry TermiteIP_EnumerateOp TermiteIP_ClientInformation TermiteIP_SocketInformation TermiteIP_ResolveFindIPAddressForName TermiteIP_ReadDomainName TermiteIP_ClosePortsSockets TermiteIP_ProtocolOp TermiteIP_MiscOp TermiteIP_SendEvent TermiteIP_TCPBufferInfo TermiteIP_RemoveTCPData The byte order used when transmiting these packets is in fact Most-Significant-Byte first (MSB first) so when sending multi-byte numbers always send the MSB first. The IP address encoder and decoder automatically give you a MSB byte first result - i.e. the actual word you get contains the MSB in the first byte of the word, not the last as standard on the Arc.! All SWIs will return with the flags preserved unless there is an error, then the V flag is set and R0 points to an error block (all other processor flags will be undefined if V is set.) Possible module errors: &80D900 : Bad IP protocol number &80D901 : Too many tasks have been registered with the TermiteIP support &80D902 : Bad packet length passed to TermiteIP &80D903 : Unknown port number &80D904 : Unknown client &80D905 : Too many options passed to IP send &80D906 : TermiteIP module cannot be killed - link in operation &80D907 : Illegal access - port is in use by another client &80D908 : This connection already exists &80D909 : This connection does not exist &80D90A : This connection is closing &80D90B : Invalid IP address &80D90C : Options passed to TermiteIP are too long &80D90D : Insufficient space in buffer &80D90E : No free ports available &80D90F : Bad socket pointer &80D910 : Bad port pointer &80D911 : I do not know how to decode this ICMP error &80D912 : No such name in resolve cache &80D913 : Bad TelnetOp reason code &80D914 : Bad ResolveOp reason code &80D915 : Bad list of resolve servers, must be less than 16 servers &80D916 : Connection is still active - cannot delete socket &80D917 : I do not know about this port &80D918 : There is no resolve cache loaded to use &80D919 : Bad R2 passed to ResolveCacheChangeEntry &80D91A : No name resolvers currently defined &80D91B : Bad R0 passed to EnumerateOp &80D91C : TCP connection is already going &80D91D : The specified link driver could not be loaded &80D91E : Bad buffer length passed to TCP &80D91F : Bad data length passed to ResolveAddToCache &80D920 : Bad buffer pointer/length passed to TermiteIP &80D921 : Bad ReverseResolveOp reason code &80D922 : Bad ProtocolOp reason code &80D923 : This Internet protocol is already claimed by someone else &80D924 : Bad ProtocolOp free call - protocol is not claimed &80D925 : Bad ProtocolOp free call - protocol is not claimed by caller &80D926 : Your client does not own this socket &80D927 : There is no link driver loaded &80D928 : Bad reason code passed to TermiteIP_MiscOp ============================================================================= ** TermiteIP link ** ----------------------------------------------------------------------------- TermiteIP_Initialise ----------------------------------------------------------------------------- R1 = flags : none defined yet, should all be 0 R2-> block-driver to use, already initialised R3 = port number to pass to block driver R4-> protocol driver or 0 for SLIP R5 = our IP address (a word) R6 = maximum transmision unit in bytes Exit: R0 = 0 for sucessful initialise = 1 if the module has allready been set-up by someone else > 1 then the V flag will be set and r0 points to an error This sets up the TermiteIP module to start up with the specified block driver and protocol to use. If the module has already been initialised by someone else then this call will not change any of the settings. The block driver must be accessible under interupts, and must be able to be called in SVC mode (this means you must have release 9 or above of SerialDev) TermiteIP_Finalise ----------------------------------------------------------------------------- r0 = 0 (for future compatibility) Terminates current link. If there is no current link this will return without error. TermiteIP_Register ----------------------------------------------------------------------------- R2 = 0 R3 = task handle of the task, or 0 if not a WIMP task R4-> name of registeree, eg "Termite Ping", max 31 bytes Exit: R0 = unique ID for your task the unique ID is used to identify the client with TermiteIP. It is used to protect sockets, return event data on ports/sockets and so on. TermiteIP_DeRegister ----------------------------------------------------------------------------- R0 = unique ID for your task De-registers your task from TermiteIP, removing all sockets and declaiming all ports. TermiteIP_ReadLinkStatus ----------------------------------------------------------------------------- Exit: R0 = our IP address R2-> name of driver text R3-> type of driver text (either Acorn DCI / Blockdriver) R4-> name of author R5-> version R6-> additional text V flag set if no link setup, and r0-> error block This gives some general information about the current link TermiteIP_MiscOp ----------------------------------------------------------------------------- registers dependant on r0 miscop 0: read link status -------------------------- r0 = 0 Exit: r0 = 0 for no link 1 for link miscop 1: call linkdriver miscop entry -------------------------------------- r0 = 1 r8 = r0 to pass to link driver Exit: resultant registers from linkdriver miscop miscop 2: read IP address ------------------------- r0 = 2 Exit: r0 = IP address NB... this may not be valid if there is no link currently running miscop 3: find client identity ------------------------------ r0 = 3 r2 = client ID Exit: r0 = name passed to Th‰ à°r r2 = number of pending events r3 = task handle given to TermiteIP_Register miscop 4: read TermiteIP support taskhandle ------------------------------------------- r0 = 4 Exit: r0 = task handle This can be used if you want to send messages directly to TermiteIP miscop 5: read IP configurations -------------------------------- r0 = 5 Exit: r0 = maximum transmision unit r2 = size of buffer to hold packet identities for error lookup (this has one byte per packet transmitted, and will loop around if the buffer is filled up.) r3 = time-to-live field inserted into IP packets on transmission r4 = expiry time for partly received packets (in centiseconds) miscop 6: decode event number ----------------------------- r0 = 6 r2 = event number Exit: r0-> text string naming event. miscop 7: free transmit buffers ------------------------------- r0 = 7 This frees all the transmit blocks from the transmit list miscop 8: free receive buffers ------------------------------ R0 = 8 This frees all the current receive blocks miscop 9: set maximum transmit data size ---------------------------------------- r0 = 9 r2 = number of bytes allowed in the TX queue, or negative/zero to read Exit: r2 = current number of bytes allowed in the TX queue This feature allows you to regulate the amount of data put in the transmit packet queue by TCP. Please note that ack packets may still be sent, and no garuntee the queue will always be kept below the specified length - this is just to regulate the amount of TCP data transmited, and has no effect on direct calls to things like TermiteIP_SendIPPacket, TermiteIP_SendICMPPacket and TermiteIP_SendUDPData... miscop 10: read amount of data in TX queue ------------------------------------------ r0 = 10 Exit: r0 = number of bytes in TX queue miscop 11: read amount of data in the RX queue ---------------------------------------------- r0 = 11 Exit: r0 = number of bytes in the RX queue This reads the number of bytes in the RX queue. This means the number of bytes currently still awaiting part of a split packet to be received to make the packet complete (once the packet is completeted, the packet is passed to the relevant handler and TermiteIP loses track of it) miscop 12: set machine&domain name --------------------------- r0 = 12 r2-> machine & domain name (i.e. doggysft.demon.co.uk) r3 = offset into string to use for domain name, or -1 to work out the offset of the first '.' in the string miscop 13: read machine and domain name --------------------------------------- r0 = 13 Exit: r2-> machine & domain name (control terminated) r3-> domain name r4 = offset into r2 where the domain name starts r0 = 14 : control receive time ------------------------------ r0 = 14 r2 = number of centiseconds before abadoning receive, or -1 to read Exit: r2 = current value in centiseconds This allows you to stop TermiteIP from taking total control of tbe machine by making sure the receive routines do not take more than x centi-seconds each poll. r0 = 15 : control Wimp_Poll or Ticker usage ------------------------------------------- r0 = 15 r2 = 0 : use Wimp_Poll 1 : use ticker vector -1 : read current state Exit: r2 = current state This allows you to make TermiteIP run in the background of the ticker vector instead of using Wimp_PollIdle. r0 = 16 : poll time ------------------- r0 = 16 r2 = time in centi-seconds between each poll, or negative to read Exit: r2 = current time in centi-seconds between each poll This allows you to control how often TermiteIP polls the transmit and receive buffers as well as doing TCP transmision and timeout processing. Any value that is over 50 centiseconds or under 1 centisecond will be rejected by the module. r0 = 17 : control transmit time ------------------------------- r0 = 17 r2 = number of centiseconds before abadoning transmit, or -1 to read Exit: r2 = current time in centi-seconds. This stops TermiteIP taking too much time over processing of transmit buffers and will make it stop after x centi-seconds... r0 = 18 : set checksum control ------------------------------ r0 = 18 r2 = EOR flag r3 = BIC flag bit 0 - receive IP checksum control bit 1 - receive UDP checksum control bit 2 - receive TCP checksum control bit 3 - recieve ICMP checksum control bit 4 - transmit IP checksum control bit 5 - transmit UDP checksum control bit 6 - transmit TCP checksum control bit 7 - transmit ICMP checksum control Exit: r2 = current state This allows you to control checksum checking on IP packets, TCP packets and UDP packets. If the coresponding bit in the wptf is set then all checksum fields will be ignored, or not sent on transmision. r0 = 19 : poll receive and transmit routine ------------------------------------------- r0 = 19 This causes all the transmit and receive routines (as well as poll) routines for all the linkdrivers to be serviced. The call also serivces the current resolve and tcp buffer checks. TermiteIP_ReadInformation ----------------------------------------------------------------------------- r0 = variable number, or if >255 a pointer to a list of variable numbers r1-> buffer to receive the result if r0>255 Exit: r0 = value, or pointer to end of buffer passed in r1 the variable numbers are: 0 - bytes received by the link 1 - 0 if not threaded, 1 if the interupt routines are threaded 2 - packets received ok. 3 - packets received with missing data 4 - packets received with bad CRCs 5 - packets received and lost due to memory problems 6 - packets received with no known protocol ============================================================================= ** Maintaining connections ** ----------------------------------------------------------------------------- To start a connection you must have a port number and a socket within the port. Each port can only have ONE outgoing socket to the same destination, so it is usual to have one port per outgoing connection to allow for two connections to the same destination. The reason behind this is that to identify packets you only know the source/destination ipaddress and port. If you want two connections to the same ipaddress and port (which is quite common) then you must have a different port (since you can't change your ipaddress). However, for a 'listening' port (a port that accepts incoming connections) since the remote computers will follow the above to make sure they can have more than one connection to the same address, an infinite number of people can connect into such a port that is listening. So a socket is a connection identified by the sender and receiver IP addresses and port numbers. If you create a socket you can also set this socket so that it is a 'listening' socket (TermiteIP_SetTCPSocketToListen), see bit 0 in TermiteIP_AllocatePort flags. To very abruptly close a port and all sockets do: SWI "TermiteIP_ClosePortSockets" SWI "TermiteIP_ClosePort" To very abruptly close a socket do: SWI "TermiteIP_DropTCPConnection" TermiteIP_AllocatePort ----------------------------------------------------------------------------- R0 = unique ID R2 = port number, or -1 to allocate first free port R3 = flags: bit 0 - if unset this is a listening port, and will accept incoming connections (you will be sent an event through ReadNextEvent) and create a new socket - this does not apply to any sockets you have already created and made listening sockets with SetTCPSocketToListen. bit 1 - unprotected port (anyone can create sockets) bits 8-11: bits 4-7 passed to CreateSocket for creating TCP sockets bits 12-15: bits 4-7 passed to CreateSocket for creating UDP sockets bit 16 - set this bit to disable incoming UDP access to this port bit 17 - set this bit to disable incoming TCP access to this port Exit: R2 = port number, if r2=-1 then you have already claimed this port This call creates the specified port and creates the necessary port block TermiteIP_ClosePort ----------------------------------------------------------------------------- R2 = port number This removes the specified port from the list of claimed ports, NOTE this SWI does not close any open sockets, this must be done yourself TermiteIP_ChangePortFlags ----------------------------------------------------------------------------- R2 = port number R3 = BIC word R4 = EOR word new_flags = (old flags BIC R3) EOR R4 This allows you to change the flags of the specified socket. TermiteIP_CreateSocket ----------------------------------------------------------------------------- R0 = unique ID R2 = port number of source port R3 = port number of destination port R4 = destination IP address R5 = bits 0 - 3 : 0 = UDP : 1 = TCP bit 4 : 0 automatically delete socket 1 leave socket in closed state bit 5 : 1 allow creation if an associated port doesn't exist 0 error if port has not been allocated bit 8 : 0 return socket pointer if socket already exists and belongs to you 1 return error if socket exists Exit: R0-> socket pointer R2 = actual port number of source port R3 = actual port number of destination port This creates the specified socket, for either UDP or a TCP connection - note that TCP data can only be sent from a TCP socket, wheras UDP data can be sent from both kinds of socket. If the socket already exists, and bit8 is clear then the call will return that socket pointer. TermiteIP_DeleteSocket ----------------------------------------------------------------------------- R0-> socket pointer This deletes the specified socket, removing any memory claimed for the socket Make sure you call TermiteIP_CloseTCPConnection before this and the socket has reached a time-wait or closed state. If you want to abruptly remove the socket then call TermiteIP_DropTCPConnection instead. This SWI also removes any outstanding events for the socket. TermiteIP_ClosePortSockets ----------------------------------------------------------------------------- R2 = port number This will close *ALL* open sockets on a specified port, useful if you want to completely break all comunications on a port - also calls TermiteIP_ DropTCPConnection so that all open sockets are reset too. TermiteIP_SendEvent ----------------------------------------------------------------------------- R0 = unique ID R1 = event code (see TermiteIP_ReadNextEvent) R2 = R2 to pass back from TermiteIP_ReadNextEvent R3 = R3 to pass back from TermiteIP_ReadNextEvent (this will only be passed for the necessary events.) This sends the specified event to a client. An error will occur if the client does not exist. TermiteIP_ReadNextEvent ----------------------------------------------------------------------------- R0 = unique ID and R2 = -1 - for next event, but only non-socket events or R2 = 0 - for next event or R2-> socket pointer - only socket events Exit: R0 = type of data R2 = dependent on value of r0 R3 = dependent on value of r0, or preserved This reports back on various miscellaneous events 0 : null reason code, no messages left no other registers, r2 may have been corrupted 1 : recieved ICMP message r2 = IP packet identifer that holds the ICMP message 2 : new socket starting up r2-> socket pointer of the newly created socket 3 : notification of ping arival - for ping servers r2 = IP packet identifier that holds the ICMP ping message 4 : data arrived at socket (UDP) r2 = IP packet identifier r3-> socket pointer 5 : Remote has finished (FIN received) r2-> socket pointer This event is issued when the other side has no more data to send (i.e. it has finished its data transmission) and if you have not closed your end of the connection with TermiteIP_CloseTCPConnection you should transmit the remaining data and call TermiteIP_CloseTCPConnection to shut your end of the connection down. This will then cause the connection to fully close (see closing scenarios below). 6 : ICMP error message arrived r2 = IP packet identifer that holds the ICMP message r3-> socket pointer destined for, or 0 for no socket 7 : TCP socket has been RESET r2-> socket pointer Call TermiteIP_DeleteSocket to delete the socket. 8 : Urgent data arriving on TCP socket r2-> socket pointer r3 = sequence number of start of urgent data (note this is not supported by TermiteIP at the moment.) 9 : Connection closed r2-> socket pointer - You should now use TermiteIP_DeleteSocket to delete the socket. This occurs after timewait or after an immediate non-timewait close. * Only occurs if auto-deletion is off. 10: TCP connection changing state r2-> socket pointer r3 = new state code Do *not* use the state change codes to perform certain closedown actions, use the events 5, 9 and 11. You can wait for this event with R3 = 4 (established) to know when the connection has been made. 11: TCP connection finished r2-> socket pointer This is issued on the successful closing of the connection. If you have created the socket with auto-deletion then the socket will be deleted automatically after this, and no more events should come from this socket. 12: Resolve packet received r2 = IP packet identified r3 = resolve job id This is received if a resolve packet comes in for a specific resolve job if you've enabled it with ResolveOp 13 Connections can close like so: a) Receive close request (event 5) call CloseTCPConnection, wait for event 11 (both ends finished), end. b) Send close request (CloseTCPConnection), receive event 5, either: i) call CloseTCPConnection, wait for event 11 (both ends finished), end. [ie. goto a)] ii) call CloseTCPConnection, wait for event 9 (time wait finished), call DeleteSocket. c) Receive reset, receive event 7, call DeleteSocket, end. d) Send reset (DropTCPConnection), end. Note that in b)i) it does CloseTCPConnection even although we have already called CloseTCPConnection - this is so that you can have the same exit routines for a) and b)i), since you will notice they are identical. You must call TermiteIP_ReadNextEvent to look for events. ReadNextEvent can be used in two ways, Termite application does it by calling ReadNextEvent with 0 for general information, and then each of the protocols that are active call ReadNextEvent with their socket pointer to find out information on that socket only, without interfering with the more general events. Alternatively you can call ReadNextEvent with -1 and you will get all events given back. The follow are the state codes: 0 = closed 1 = listening 2 = syn-sent 3 = syn-received 4 = established 5 = fin-wait1 6 = fin-wait2 7 = close-wait 8 = closing 9 = last-ack 10 = time-wait ============================================================================= ** ICMP/UDP ** ----------------------------------------------------------------------------- ICMP - Internet control message protocol. Usually error messages or general information, there is no retransmission policy. UDP - User Datagram Protocol. Usually data services, eg. name resolving, there is no retransmission policy. TermiteIP_DecodeICMPErrorMessage ----------------------------------------------------------------------------- R0 -> result buffer (no length checking so at least 32 bytes, and should not reach over 256 bytes) R2 -> header from IP packet carrying ICMP data R3 -> pointer to the ICMP data Exit: buffer in r0 updated TermiteIP_SendICMPMessage ----------------------------------------------------------------------------- R0 = client ID R1 = bits 0 - 7 :type bits 8 -15 :code R2-> start of data to send R3 = length of data to send R4 = destination address R5 = IP options, or 0 for no options R6 = type of service and time-to-live (see SendIPPacket). protocol number is automatically filled in, and should be 0 R7 = pointer field (for some codes it will be options/ID/seq no) this is stored at ICMP header+4 This SWI builds and then sends an ICMP message to the specified address, this can be to complain about various defects and to request an echo. If you are sending an echo, the ID of the echo packet should be filled in with your unique ID (LSB first) and then the reply will get back to you - otherwise it will be sent to someone else - please note that although the ID is specified as LSB first, the SEQ is a MSB byte first TermiteIP_SendUDPData ----------------------------------------------------------------------------- R0-> socket pointer R2 = data R3 = length of data R5 = pointer to options data or 0 for no options to be included the first word is the length of options data to be included, this must be a multiple of 4 bytes R6 = bits 0-2 : precedence value (normally 0) bit 3 : delay - 0= normal, 1= low bit 4 : throughput - 0= normal, 1= high bit 5 : reliability - 0= normal, 1= high bits 6-7 : reserved - should be 0 protocol number is filled in for you bits16-23: time-to-live value, 0 for standard setting. To read UDP packets you get told about the data as it comes, from ReadNextEvent. The way you receive UDP is by event 4 from ReadNextEvent. When you receive the event, you should read the data given using TermiteIP_ReadPacket, and then decode the packet. The data is at packet+8... example for echoing data:
   .process_event_4
     MOV     r0,r2
     MOV     r2,#0
     MOV     r3,#0
     MOV     r4,#0
     MOV     r5,#1
     SWI     TermiteIP_ReadPacket       ; find length of data needed
     ;; claim memory from result of r4.
     ;; assumes that r3 is pointer to memory
     MOV     r2,#0
     MOV     r5,#0
     SWI     TermiteIP_ReadPacket       ; read data into buffer
     ADD     r2,r3,#8                   ; r2-> data
     SUB     r3,r4,#8                   ; r3 = length of data
     MOV     r5,#0
     MOV     r6,#0
     SWI     TermiteIP_SendUDPData
     SWI     TermiteIP_DeleteSocket     ; delete socket if necessary
============================================================================= ** TCP ** ----------------------------------------------------------------------------- TermiteIP_SetTCPSocketToListen ----------------------------------------------------------------------------- R0-> socket pointer This sets the specified socket to listen for a connection (this is not the same as listening on a port, see TermiteIP_AllocatePort bit 0) TermiteIP_StartTCPConnection ----------------------------------------------------------------------------- R0-> socket pointer This initiates a connection by sending the SYN, and setting up connection details Creating a socket doesn't actually start the connection, you must call this SWI and then wait for it to become 'established' before you can send and receive data. TermiteIP_CloseTCPConnection ----------------------------------------------------------------------------- R0-> socket pointer This closes the connection at both ends, going through the proper procedures You will be notified when the connection has been fully closed by an event, you should not delete the socket (call TermiteIP_DeleteSocket) until this event (time-wait or closed) has been received through TermiteIP_ ReadNextEvent. TermiteIP_DropTCPConnection ----------------------------------------------------------------------------- R0-> socket pointer This immediately drops the connection to the remote host, sending a RESET to the remote host and discarding any buffers. This is not the recommended way of shutting a connection, and is used by the TermiteIP_DeRegister SWI to drop any connections left open by your task, if you cannot or do not want to allow connections from certain remote hosts, then you should shut the connection properly, or send an ICMP message with port unreachable or host unreachable code. It also deletes the socket for you. TermiteIP_SetTCPSocketWindow -----------------------------------------------------------------------------
R0-> socket pointer
R2 = new size of window
This sets the current receive window, and sends an current ACK to the destination if the window has changed. The current receive window controls how much incoming data the socket is willing to buffer at this end of the connection TermiteIP_TCPStateToText ----------------------------------------------------------------------------- R0 = state code (0 to 10) Exit: R0-> text string, i.e. SYN received TermiteIP_KickTCPSocket ----------------------------------------------------------------------------- R0-> socket pointer This preforms a KICK to the relevant socket TermiteIP_ReadTCPData ----------------------------------------------------------------------------- R0-> socket pointer R2-> buffer to receive data R3 = length of receive buffer Exit: R3 = length of data placed in buffer This SWI will read as much data as possible into the buffer supplied, thus removing it from the rx buffer. The data can be examined with TermiteIP_ExamineTCPData. TermiteIP_ExamineTCPData ----------------------------------------------------------------------------- R0-> socket pointer R2-> buffer to receive data R3 = length of receive buffer Exit: R3 = length of data placed in buffer This does the same job as TermiteIP_ReadTCPData, but does not remove the data from the rx buffer. TermiteIP_RemoveTCPData ----------------------------------------------------------------------------- R0-> socket pointer R3 = length of data to remove from buffer (start of buffer) Exit: R3 = length of data removed from buffer This removes the specified amount of data from the tcp rx buffer, and will discards it. TermiteIP_SendTCPData ----------------------------------------------------------------------------- R0-> socket pointer R2-> buffer to transmit R3 = length of buffer This transmits the specified data. The data is copied to a tx buffer to await transmission and acknowledgement of receipt at the destination. To send urgent data from this socket you should call TermiteIP_SocketOp 3, and any you can find out if any urgent data has arrived on the port by using TermiteIP_SocketOp 4. Before you poll any socket to read data, you should first check for any urgent data on it. TermiteIP_ConfigureTCP ----------------------------------------------------------------------------- r2 = maximum transmit segment size, or 0 to read r3 = initial round-trip-time in centiseconds, or 0 to read r4 = initial receive window size in bytes, or 0 to read Exit: r2 = last value of r2 r3 = last value of r3 r4 = last value of r4 This allows a few miscellaneous configurations to be read from the module or set. r2 sets how many bytes the tcp handlers will transmit in one packet. r3 controls the timeout wait on un-acknowledged packets. r4 is the value given to the receive window when a socket is created. TermiteIP_ReadTCPPointers ----------------------------------------------------------------------------- R0-> socket pointer Exit: R0 = Fisrt unacknowledged TX sequence number R1 = Initial send sequence number R2 = Current send sequence number R3 = Next send sequence number R4 = Size of TX window R5 = Initial receive sequence number R6 = Next expected sequence number R7 = Size of RX window bytes transmited = (R2-R1)-1 bytes received = (R6-R5)-1 This SWI returns the current TCP pointers for the socket so you can calculate the current bytes transmited and received. It does not have to be your socket and therefore you can inspect other peoples sockets. TermiteIP_ReadTCPStatus -----------------------------------------------------------------------------
R0 = socket pointer
Exit:
R2 = state code of socket (see SWI TermiteIP_TCPStateToText)
R3 = size of data in receive buffer
R4 = size of data in transmit buffer
This SWI gets the data on the given socket. It does not have to be your socket for you to do this, and therefore you can obtain data on any socket you wish to use. TermiteIP_TCPBufferInfo ----------------------------------------------------------------------------- R0 = socket pointer Exit: R2 = start sequence of RX buffer R3 = length of RX buffer R4 = start sequence of TX buffer R5 = length of TX buffer ============================================================================= ** IP ** ----------------------------------------------------------------------------- If you want to use another protocol other than TCP, ICMP or UDP then you can do it yourself by using TermiteIP_SendIPPacket to send, and registering a protcol handler with TermiteIP. TermiteIP_ProtocolOp ----------------------------------------------------------------------------- R0 = reason code other registers dependent on reason code Exit: registers dependent on reason code This SWI allows you to claim unknown Internet protocols (i.e. other than TCP, ICMP and UDP) and allow any other program to use other interntet protocols R0 = 0 : register protocol -------------------------- R0 = 0 R2 = ip protocol number (0-255) R3 = value of R12 to call routine with R4-> routine to call This registers the specified protocol with TermiteIP module. The routine is called with these registers: R0 -> IP data (data in IP packet) R1 = IP protocol number R2 -> IP header of first packet in sequence R4 = length of IP data R5 = length of IP header R8 -> IP packet (for calls to ReadPacket and so on) R12 = R4 passed to ProtocolOp_0 R13 = full descending stack R14 = return address The routine should preserve R8-R11, and must free the IP packet in question at the end of processing otherwise the memory containing this packet will not be freed up. The routine must return using the given return address, so the X form of all SWIs should be used. If it doesn't then there will be a chance that the TermiteIP module will stop working. The word at the routine-4 should be an offset from routine to a zero terminated text-string naming the protocol handler in r0 IE... MOV r0,#0 MOV r2,#30 MOV r3,r12 ADR r4,packet_handler SWI "XTermiteIP_ProtocolOp" ...etc... EQUD handler_name-packet_handler .packet_handler STMFD (sp)!,{r0-r6,lk} ...code to handle protocol 30... MOV r0,r8 MOV r2,#0 MOV r3,#0 MOV r4,#0 MOV r5,#0 SWI "XTermiteIP_ReadPacket" LDMFD (sp)!,{r0-r6,pc}^ .handler_name EQUS "NETBLT handler, (c) 1995 DoggySoft"+CHR$0 ALIGN Only one handler may be registered for any given protocol and TCP, UDP and ICMP are handled by TermiteIP itself. If the protocol is already claimed then an error will be returned. R0 = 1 : deregister protocol ---------------------------- R0 = 1 R2 = ip protocol number (0-255) R3 = value of R3 given to claim call R4-> routine given to claim R0 = 2 : read protocol state ---------------------------- R0 = 2 R2 = protocol number Exit: R0-> name of handler R3 = value of R3 given to the claim call R4-> routine handling this protocol TermiteIP_SendIPPacket ----------------------------------------------------------------------------- R1 = local ip address (if bit 24 of r3 set) R2-> start of data (word aligned) R3 = length of data bits 24-31: flags bit 24 = 1 for source IP address, otherwise work out source address from destination address R4 = IP address to send to R5-> options data or 0 for no options to be included the first word is the length of options data to be included, this must be a multiple of 4 bytes (i.e. pad out with zeros) R6 = bits 0-2 : precedence value (normaly 0) bit 3 : delay - 0= normal, 1= low bit 4 : throughput - 0= normal, 1= high bit 5 : reliability - 0= normal, 1= high bits 6-7 : reserved - should be 0 bits 8-15: protocol number (see list of protocols supported by IP) bits16-23: time-to-live value, 0 for standard setting. Errors: Bad options length IP packet too long to send This builds and then sends the specified IP packet accross the link. The top byte of r3 is used to communicate flags. This is not a problem as the size of a packet is limited to 64K anyway (the error 'Bad packet length passed to TermiteIP' (&80D902) will be returned if this limit is exceeded) If you want to specify the source address for this packet, then you can either set bit 24 of r3 and set r1 = source address. The alternative is to put a strict- TermiteIP_ReadPacket ----------------------------------------------------------------------------- R0 = IP packet identifier R2-> buffer to receive IP header (or 0 for none) - max 64bytes R3-> buffer to receive IP data (or 0 for none) R4 = length of buffer R5 = flags: bit 0 clear : Destroy IP packet after reading bit 0 set : Preserve IP packet Exit: R4 = length of data in buffer This reads and deletes if bit 0 of r5 is clear the specified IP packet. If you want to find the length of the buffer to read the packet into then you should call the SWI with r2,r3 and r4=0 and r5 with bit 1 set; The result will be returned in r4. The header is that of a standard IP packet, and is so: r2+00 = version and header length bits 0-4: length of header, in words bits 5-7: version, currently 4 r2+01 = type of service r2+02 = length of total data (this is the total inc. any other fragmented packets) NB MSB bytes first... r2+04 = unique(ish) 16bit identifier field r2+08 = time to live value r2+09 = protocol number (1=ICMP, 6=TCP, 17=UDP, etc.) r2+10 = header checksum r2+12 = source IP address r2+16 = destination IP address TermiteIP_ReadIPProtocolEnable ----------------------------------------------------------------------------- R0 = protocol number Exit: R2 = 0 if protocol disabled, or 1 if enabled ============================================================================= ** Telnet ** ----------------------------------------------------------------------------- TermiteIP_TelnetOp ----------------------------------------------------------------------------- R0 = reason code other registers dependent on reason code Exit: registers dependent on reason code This allows you to have a telnet implementation with the minimum of hassle. The SWI process any incoming data, and sends out the necessary command/text strings. The module keeps track of the telnet status in a telnet control block, which the user must allocate. The block may be put in a WimpExt_Heap block or RMA, but must NOT be put in a WimpExt_CDA block. You must pass the current address of the block to any TelnetOp which needs it. R0 = 0 : read size of telnet control block needed ------------------------------------------------- Exit: R2 = size in bytes for telnet block R0 = 1 : initiailise telnet control block ----------------------------------------- R2-> telnet control block R3 = socket identifier for telnet socket R4 = flags: bit 0 : don't allow echo bit 1 : allow centi-second output buffer flushing - uses r5 R5 = centi-second count for flushing non-empty telnet buffers Exit: telnet control block set-up R0 = 2 : finalise telnet control block -------------------------------------- R2-> telnet control block Exit: telnet control block finalised R0 = 3 : poll telnet -------------------- R0 = 3 R2-> telnet control block R3-> character output routine R4 = r12 to pass to character output routine Character output routine R0 = reason code: 0 = NoOp 1 = write charachter in R4 to cursor 2 = erase line 3 = erase last byte R11-> telnet control block R12 = R4 passed to TelnetOp 3 R0 = 4 : send byte ------------------ R2-> telnet control block R3 = byte to send R0 = 5 : send bytes ------------------- R2-> telnet control block R3-> buffer R4 = length of buffer R0 = 6 : send bytes with CR expansion ------------------------------------- R2-> telnet control block R3-> buffer R4 = length of buffer This is the same as r0=4, except that if a CR is encountered, a CR-LF sequence is sent. R0 = 7 : flush output buffer ---------------------------- R2-> telnet control block This makes sure that there is no data left in the output buffer r0 = 8 : set terminal-type data ------------------------------- R2-> telnet control block R3-> zero terminated telnet type string, IE DEC-VT100 This call allows you to set the Terminal-type sent to the remote host R0 = 9,10 : set data log filehandles ------------------------------------ 9 for indata log, 10 for outdata log R2-> telnet control block R3 = filehandle, or 0 to cancel file logging This allows the raw telnet data to be sent to the file of your choice. This feature is entirely under your control, and it is your responsibilty to keep track of any filehandles... and shut them yourself. The data includes any commands. The outdata is only written when a flush of the output buffers happens (when a command is issued or when a line is completed) ============================================================================= ** Resolving ** ----------------------------------------------------------------------------- TermiteIP uses a resolve cache to keep used entries, and when asked to resolve an address it will, unless otherwise specified check the resolve cache for that address first. If the address cannot be found in the cache then a resolve request is sent to the default server set by the user and the resolve will carry on until it either times out, fails or acquires the answer required. TermiteIP_ResolveOp ----------------------------------------------------------------------------- R0 = reason code other registers dependent on reason code Exit: registers dependent on reason code This SWI allows the use of a central name resolving system which uses a list of Domain name servers to lookup the given name. R0 = 0 : initialise ------------------- R2-> name of host, zero terminated Exit: R0 = 0 then started resolve, r2 = job id R0 = 1 then r2 = IP address R0 = 1 : close resolve ---------------------- R2 = job id R0 = 2 : job status/poll ------------------------ R2 = job id Exit: R0 = code: 0 = asking servers 1 = completed, R2 = address (if it was a reverse resolve op, then r2-> hostname) 2 = failed to locate name, r2-> explanation string If the job is completed, your job will be deleted for you - do not access this job again! If it was a reverse resolve operationn and it completed successfully (r0=1) then r2 is an RMA block containing the host name and after you've read the name from it you should call OS_Module 7 to free the block R0 = 3 : list current servers ----------------------------- Exit: R0-> list of servers R2 = number of current servers R0 = 4 : set list of servers ---------------------------- R2-> list of servers, terminated by 0 R0 = 5 : configure ------------------ R0 = 5 R2 = BIC flags bit 0 - cache all useable results R3 = EOR flags R4 = pointer to RMA block contatining the domain name suffix, or 0 to keep Exit: R2 = new flag state R4 = pointer to domain name R0 = 6 : current state of resolve cache --------------------------------------- R0 = 6 R2 = job id Exit: R3 = current resolve socket pointer R4 = resolve count (counts down) R0 = 7 : save resolve cache --------------------------- R0 = 7 This saves the current state of the resolve cache R0 = 8 : flush resolve op ------------------------- R0 = 8 This clears the entriity of the resolve cache R0 = 9 : initialise reverse resolve ----------------------------------- R0 = 9 R2 = IP address Exit: R0 = result code: 0 - job id is in r2 1 - name is pointed to by r2 R2 = dependant on R0 You call TermiteIP_ResolveOp 2 in the same was as for a standard resolve and you get the hostname back in a RMA block from that call. See the entry for TermiteIP_ResolveOp 2 for more information. Due to cache movement, you should not rely on this call working. Please use TermiteIP_ResolveOp 16 instead R0 = 10 : check cache for IP address ------------------------------------ R0 = 10 R2 = IP address Exit: R0 = 0 if not found, otherwise pointer to string This checks the cache for a record for the IP address and gives you the string which relates to it. Please note this call only checks the cache Due to cache movement, you should not rely on this call working. Please use TermiteIP_ResolveOp 17 instead R0 = 11 : decode resolve type to simple text -------------------------------------------- R0 = 11 R2 = resolve type Exit: R0-> text string. IE, call with R0 = 12 amd R2=&01000100 then R0 points to the string 'IP' R0 = 12 : decode resolve type to text ------------------------------------- R0 = 12 R2 = resolve type Exit: R0-> text string. IE, call with R0 = 13 amd R2=&01000100 then R0 points to the string 'Internet Address' R0 = 13 : set packet monitoring ------------------------------- R0 = 13 R2 = job id R3 = client id, or -1 for no packet logging This allows all the packets received by the resolver to be passed onto the specified client instead of being automatically discarded. If you set this option then you will be notified by event 12 R0 = 14 : get address of record comparison routine -------------------------------------------------- R0 = 14 R2 = resolve type Exit: R0-> comparison routine, called with: r0-> record 1 r1-> record 2 r2 = length r13-> stack, full descending. Exit: all registers preserved. EQ if records the same NE if records are different The routine assumes that the record types/class are identical and that the length of both records is the same. R0 = 15 : find IP address from cache ------------------------------------ R0 = 15 R2-> name Exit: R0 = IP address if found, V flag set if not round and R0-> error block R0 = 16 : initialise reverse resolve ----------------------------------- R0 = 9 R2 = IP address R3-> buffer R4 = length of buffer Exit: R0 = result code: 0 - job id is in r2 1 - name is in buffer R2 = dependant on R0 R3 preserved R4 = bytes left in buffer You call TermiteIP_ResolveOp 2 in the same was as for a standard resolve and you get the hostname back in a RMA block from that call. See the entry for TermiteIP_ResolveOp 2 for more information. This replaces TermiteIP_ResolveOp 9 R0 = 17 : check cache for IP address ------------------------------------ R0 = 17 R2 = IP address R3-> buffer R4 = length of buffer Exit: R0 = 0 if not found, otherwise string placed in buffer R2,R3 preserved R4 = bytes left in the buffer This checks the cache for a record for the IP address and gives you the string which relates to it. Please note this call only checks the cache This replaces TermiteIP_ResolveOp 10. TermiteIP_ResolveReadCacheEntry ----------------------------------------------------------------------------- R0 = offset into resolve cache (0 for initial read) Exit: R0 = updated, -1 if no-entry R2-> name (copy away if you want to use this) the name is zero terminated and the additional data is after this for the type of entry. Eg. the IP address. the additional data is not guaranteed to be word aligned. R3 = usage count R4 = resolve flags R5 = class and type fields R6 = time out delay TermiteIP_ResolveFindEntryInCache ----------------------------------------------------------------------------- R0-> string R4 = type Exit: R2 = usage count R3 = resolve flags R4 = type R5 = time out delay R6-> name in cache with additional data after it. R7 = length of add. data TermiteIP_ResolveAddToCache ----------------------------------------------------------------------------- R0-> string R2 = usage count R3 = resolve flags R4 = class and type fields R5 = time out delay R6-> additional data R7 = length of additional data This adds the specified item to the TermiteIP resolve cache. The string specifies what the name of the item is, the usage count can be optionally updated to show access to that address. The class and type fields specify the class of the item (IE Internet, etc.) and type (IE, IP address, Malibox, Canonical name). The time-out delay is the delay in seconds before the entry becomes invalid and will be flushed from the resolve cache. The additional data pointed to by r6, with length = r7 is the data associated with this entry. If the type is IP then r6 points to 4 bytes of internet address and r7=4. If it is say, a CNAME then r6 points to another name and r7 is the length. TermiteIP_ResolveDeleteCacheEntry ----------------------------------------------------------------------------- R0-> string R4 = class and type fields R6-> additional data R7 = length of additional data This deletes the specified entry ============================================================================= ** Miscellaneous information ** ----------------------------------------------------------------------------- TermiteIP_EnumerateOp ----------------------------------------------------------------------------- R0 = reason code R3 = 0 (to start) Exit: R0 preserved R2 = enumeration result (see below) R3 incremented, or -1 for no more items - r2 is meaningless R0 = 0 : EnumerateClients Exit: R2 = client unique id R0 = 1 : EnumeratePorts Exit: R2 = allocated port R0 = 2 : EnumerateSockets Exit: R2 = allocated socket R0 = 3 : EnumerateInterfaces Exit: R2 = ICB TermiteIP_CheckSocket ----------------------------------------------------------------------------- R0-> socket pointer Exit: R0 = type of socket, 1=TCP, 0=UDP or -1 if not a valid socket TermiteIP_PortInformation ----------------------------------------------------------------------------- R2 = port number Exit: R0 = client ID of owner of this port R2 = port flags This allows you to find out information about a port TermiteIP_SocketInformation ----------------------------------------------------------------------------- R0-> socket pointer Exit: R2 = port socket came from R3 = destination port R4 = destination address R5 = type of socket - 0=UDP, 1=TCP TermiteIP_ClientInformation ----------------------------------------------------------------------------- R0 = client unique id Exit: R2 = taskhandle R3-> name R4,R5 corrupted TermiteIP_ReadDomainName ----------------------------------------------------------------------------- Exit R0-> domain name string (ie. doggysft.demon.co.uk) ============================================================================= ** Miscellaneous conversions ** ----------------------------------------------------------------------------- TermiteIP_NumberToIPAddress ----------------------------------------------------------------------------- R0 = ip address, a MSB byte first word as from an IP packet R1-> buffer to receive data R2 = size of buffer Exit: R0 = buffer from R1 R1 = end of buffer R2 = bytes left TermiteIP_IPAddressToNumber ----------------------------------------------------------------------------- R1-> string Exit: R1 = terminator R2 = IP address This SWI tries to evaluate the number, then it checks the resolve cache for the given string and will return an error if both fail. TermiteIP_IPProtocolNumberToName ----------------------------------------------------------------------------- R0 = IP protocol number (0-255) Exit: R0-> name of IP protocol. R0 is the protocol number, eg 16 is TCP. TermiteIP_NetToArcTime ----------------------------------------------------------------------------- R0 = 32-bit word containing the net-time (this is the number of seconds since 00:00:00 1 January 1900) R2 -> 5 byte block to place the Arc format time (this block does not need to be word-aligned) Exit: 5 bytes at r2 are LSB-MSB of the time (as used by OS_Word 14,3 and OS_ConvertDateAndTime) TermiteIP_ConvertPortNumber ----------------------------------------------------------------------------- R0 = port number - set bit 16 if you want portname (portnumber) R1-> buffer R2 = size of buffer Exit: R0 = R1 on entry R1-> end of buffer R2 = bytes remaining in buffer TermiteIP_ChecksumData ----------------------------------------------------------------------------- R2-> start of data R3 = length of data Exit: R0 = checksum value (16 bit) TermiteIP_ChecksumDataAndHeader ----------------------------------------------------------------------------- R2-> start of data R3 = length of data R4 = address of IP header Exit: R0 = checksum value (16 bit) ============================================================================= ** Service calls and Wimp messages ** ----------------------------------------------------------------------------- Service &4AE44 : TermiteIP_Initialise This is broadcast when the module is first initialised. It is intended to allow any modules which rely on TermiteIP to register their interest with TermiteIP (register client and their IP protocol handlers) Service &4AE45 : TermiteIP_Finalise This is broadcast when the module is being killed. You can de-register you IP protocol handlers and any other information they are holding Service &4AE47 : TermiteIP_LinkClosing This is broadcast when the SWI TermiteIP_Finalise is called to warn you that the link is being closed. Message &4AE44 : TermiteIP_Initialising This is broadcast on the initialisation of the TermiteIP support task. Message &4AE45 : TermiteIP_Finalise This is broadcast when the module is being killed Message &4AE47 : TermiteIP_LinkClosing This is broadcast when the SWI TermiteIP_Finalise is called to warn you that the link is being closed. ============================================================================= (c) DoggySoft 1995. Documentation by Ben Dooks (ben@fluff.demon.co.uk)