The World of Computer Software

home *** CD-ROM | disk | FTP | other *** search

/ The World of Computer Software / World_Of_Computer_Software-02-385-Vol-1of3.iso / p / pcrte224.zip / SRC.DOC < prev next >

Wrap

Text File | 1992-06-09 | 17KB | 348 lines

PCroute source code description Vance Morrison PCroute is distributed with source for essentially one reason, I would like to involve many people in the design and debugging of PCroute, and for them to do this, they need the source. Since I will not be the only one fixing bugs and adding enhancements, PCroute will continue to develop as long as there are people who think it is a worthwhile program to support. As creator of PCroute, however I request/demand the following 1) Please let me know about any bug fixes so that I can incorporate them into the 'official' release. 2) You may make local enhancements to PCroute and use them LOCALLY (that is within the same organization) but you may NOT distribute this code. The reason for the second demand (it is in the copywrite) is very simple, I don't want PCroute to fragment into many versions. That is my ONLY concern. Thus just tell me what you want to do, and I will give you an copy of the working source code, and you can be sure that the part that you are working on is not being worked on by anyone else, and when you are done it will be ready to integrate into the official release. I do reserve the right NOT to integrate features that I regard as counterproductive and code that simply is too poorly written or buggy to risk, but I do not see myself exercising that option. All of these conditions are simply to insure that PCroute has a long and productive life. I have no monetary interest in PCroute. I could like to thank David Johnson for his contribution of the first generation SLIP code to PCroute. Great work! Thanks for the excellent contribution. ============================================================================ DESIGN CRITERIA PCroute had to be designed to squeeze all the power it could out of an 8088 CPU. As such I had to make some rather drastic measures. These include 1) Programming the main packet routing loop in assembler 2) NO procedure call in the main packet routing loop Since assembler have very good macro expansion capabilities, the second decision is relatively painless. Simply use macros instead of procedure calls. This can make the code large, but memory has not been a problem yet. Once we are out of the main packet loop, these optimizations are not really necessary anymore. Thus if/when SNMP support is added to PCroute, it will be done in C, since all of this code is only executed when SNMP operations are being done. =========================================================================== CONVENTIONS Despite the use use of assembler, I have tried to make the code as modular as possible, and to adopt conventions that I have found quite useful in preventing common assembly code errors. Some of these conventions are 1) function prefixing - Macros are groups into modules that provide a set of related services. All function in this group are prefixed by the same short string. This improves readability and prevents name conflicts 2) Naming input, output and constant registers - The most common error in assembly code is calling a macro that changes registers that you believed where held constant. To prevent this type of error Macro names have the following form <NAME>_in_<REG LIST>_out_<REG_LIST>_const_<REG_LIST> For example WD_IF_COPY_in_CX_SI_DI_ES_out_SI_DI_const_BX_BP_ES name It is quite clear from the name that this macro has its parameters passed in CX,SI,DI,ES, it returns values in SI,DI and it holds the registers BX,BP,ES constant. While this may seem long-winded (it is) it is VERY useful and has prevented many bugs and I will DEMAND that any new assembly code follow these conventions. Note that since the CS,DS,SS registers are NEVER changed, you may assume that EVERY macro preserves these registers. 3) file naming - There are two type of files in the source code at present, INC files and ASM files. INC files contain ONLY macro definitions and admit NO code and are meant to be included in ASM files. INC file are thus the 'meat' of the code. The ASM files contain NO macro definitions, but do instantiate the macros to generate the actual code. Originally (an ideally), there was only one ASM file (namely PCROUTE.ASM) and assembling this file generated all code. As PCroute grew, however, the assembler could no longer compile it all in one piece, so I had to break the program into into many parts that are assembled separately and then linked together. All of these ASM file are generally quite boring because all they do is instantiate a few macros. The INC files is where the action is. =========================================================================== Overall structure The OSI model served as the basic 'backbone' of the PCroute structure, however, there were some problems with the model, and I had to make a few changes. The basic layering is 1) IF.INC (the interface (ethernet card) interface) 2) DL_IP.INC (the data link interface for IP) 3) IP.INC (the IP interface) 4) UDP.INC (the User datagram protocol (UDP) interface) Notice this is ROUGHLY analogous to the first 4 layers of the OSI stack, but the major difference is the realization that a interface is a separator BETWEEN two layers and as such must explicitly KNOW what is on at least one of the sides. For example there cannot be a generic interface for the DL (data link) layer that will interface ANY data link level code with ANY network level code. The interface must know about one layer or the other. In this case the interface KNOWS that the network layer is IP (hence DL_IP), and as long as the Data link layer below this conforms to this DL_IP interface IP can use it. In the case of IF interface, the interface KNOWS that the code above it will treat it like an ethernet. Conversely, the only thing the upper layer sees is the IF interface, thus any ethernet board board can be used as long as there is code that conforms to the IF interface for it. DL_IP.INC and IF.INC are also examples of an abstract interface. These modules to no real useful work themselves. Instead, they act as dispatchers, calling the proper code that will do the actual work. The advantage doing this is that it allows multiple interface types (in the case of DL_IP) or multiple ethernet cards (in the case of IF) without having to change any code. In the case of Ethernet, there is an additional layer between the IF and DL_IP layer. This layer (ETHER.INC) encapsulates the (old) Ethernet style of addressing (as opposed to 802.3). This layer was added to add easy addition of the 802.3 type addressing and to support other networking protocols (Decnet, XNS) if desired (conceivably all on the same cable!). The complete layering for ethernet is WD8003E.INC IF interface specific to the WD8003E card WD8003.INC A more generic IF interface that will work with WD8003E (ethernet) as well as WD8003S (starlan), the major difference is that this module has output queuing which is needed for starlan but not for ethernet. It is not recommended for ethernet since it will be slower than the WD8003E code. WD.INC Constant declarations needed by the above two modules to manipulate the WD8003 card. IF.INC Supplies a standard interface for all card specific code and dispatches the proper code when generic routines are called. ETHER.INC Describes the Ethernet header and packet dispatching on packet type. ARP.INC Provides a DL_IP interface for ethernet by using the standard Address Resolution Protocol (ARP) DL_IP.INC Supplies a standard interface for data link specific code and dispatches the proper code when generic routines are called. IP.INC Provides the routing service between the data link layers and a higher level interface for those packets directed to and from this program. It also supports fragmentation if necessary. This is the heart of the program. ICMP.INC Uses the IP services to provide the ICMP control datagrams need to fully support the IP protocol. UDP.INC Uses the IP services to provide the User datagram protocol needed for routing (RIP) and logging (syslogd). ========================================================================== For the packet driver support, only one module is needed. This module conforms to the IF interface. The file associated with this module is PACKET.INC An IF interface that then talks to the packet driver software though a software interrupt. ========================================================================== For the localtalk support, only one module is needed. This module conforms to the DL_IP interface. There are two files associated with this module. ATALK.INC A DL_IP interface that then talks to the localtalk driver to encapsulate the IP packets in localtalk. AT.INC A list of constant declarations needed to use the localtalk driver supplied with PC localtalk boards ========================================================================== For SLIP support, four modules are needed. They are I8250.INC Does all the stuff needed to get a single character on and off the PC. Interrupt code, and hardware specific code is all in here. SLIP.INC Defines the code that provides data transparency and packetizing. This is the code that places packets into a read queue. QIF.INC Implements the 'other side' of the read queue that SLIP.INC is filling. It looks like an IF interface to calling code. PP.INC Implements a DL_IP interface for point to point links give an point to point IF link (like the one QIF provides). ========================================================================== Additional functionality In addition to the basic networking layers, there are a variety of support functions that are needed to have a complete, functioning router. These include RIP.INC Provides a routing interface and implements the RIP protocol. This module has complete control over the routing table and IP calls though this interface to determine how to route a packet (thus another routing protocol could replace RIP by changing ONLY this module) BOOTP.INC Implements bootp forwarding by listening on the appropriate UDP port. LOG.INC Implements logging functions and the syslogd code needed to get these messages to the logging host. These routines violate convention in that they preserve ALL registers but do not have a CONST part in their name (for the practical reason that it simply would not fit on a line anymore) DLOG.INC Very similar to LOG, but the messages go to the disk instead of the syslogd host. These routines and only be used at boot up since disk access is slow. These routines violate convention in that they preserve ALL registers but do not have a CONST part in their name. CONFIG.INC This module is responsible for configuring all of other modules that need configuration time data. I am unhappy with this module, since it has to be change whenever ANY module needs different config info. I think instead of its present structure it should simply provide a standard interface for getting configuration data and let each module manage its configuration data itself. DECLARE.INC Contains actually hardware configuration of the router. It is this file that is changed (and ONLY this file) when new hardware is added to the router. =========================================================================== Support routines In addition to the major functional blocks, there are some modules that provide rather generic services that are used by the other functional blocks. These modules include DEBUG.INC Provides simple routines that print to screen routines. They should not be in production code (use log routines) These routines violate convention in that they preserve ALL registers but do not have a CONST part in their name. ARPTAB.INC Provides a simple table 'object' that is used to hold hardware-ip address translation data, used in ARP.INC and ATALK.INC. BUFFER.INC Provides simple buffer allocation routines used in output (and possibly input) queuing. Used in ATALK.INC and WD8003.INC QUEUE.INC Provides simple queuing routines used for packet queues. Used in ATALK.INC and WD8003.INC TASKS.INC Provides SIMPLE time slicing routines (they aren't even coroutines, but they are sufficient). TIMER.INC Provides the ability to schedule a routine to be executed some time in the future. Used in RIP.INC and other places. ========================================================================== Experimental Routines BRIDGE.INC This takes several WDE interfaces and returns several IF interfaces, but it also provides ethernet bridging between the interfaces. Incorporated into the rest of the code it implements a b-router. Used by itself (in BRIDGE.ASM) it implements just a bridge. ============================================================================== ASM files The ASM file frankly are not too interesting, nevertheless, for completeness their description follows. The only reason for most of these (with the exceptions of bridge.asm and pcroute.asm) is simply to get around the macro size limitation in TURBO ASSEMBLER. ATALK.ASM appletalk code declarations DLOG.ASM disk logging code declarations LOG.ASM syslog logging code declarations ETHER.ASM ethernet code declarations IP.ASM ip code declarations IP_DL#.ASM ip code associated with interface # RIP.ASM rip routing code declarations SLIP.ASM SLIP code declarations WD8003.ASM wd8003 card code declarations WD8003E.ASM wd8003e card code declarations I8250.ASM Serial line code declarations PP.ASM declarations for the point-to-point DL_IP code PACKET.ASM packet driver code declarations PCROUTE.ASM the main program!!!! BRIDGE.ASM an independent program implementing a two interface ethernet bridge. (Three or more interface are possible, but you will want a fast machine for this use)