home *** CD-ROM | disk | FTP | other *** search
/ The World of Computer Software / World_Of_Computer_Software-02-385-Vol-1of3.iso / p / pcrte224.zip / COMPILE.DOC < prev    next >
Text File  |  1992-06-09  |  14KB  |  265 lines
  1.  
  2.                         Compiling New PCroute code
  3.  
  4.     
  5.     The PCroute distribution comes with a compiled PCROUTE.EXE file that is
  6. configured for two Ethernet (WD8003E) interfaces.  If you want a different
  7. interface configuration (say three ethernets, or an ethernet and a localtalk)
  8. you will need to make some small changes to the source code and recompile
  9. it.  This document describes how to do this.
  10.  
  11.  
  12. WHAT YOU WILL NEED.
  13.  
  14.     The original source code was written using TURBO ASSEMBLER 1.0.  I have 
  15. made no attempt to check if the code will assemble with other assemblers, 
  16. but you are welcome to try.  Here I will assume that you have the TASM and 
  17. TLINK utilities that come with TURBO ASSEMBLER.   In addition, the
  18. compilation needs a FULL 640K of memory in order to compile.  Thus you
  19. need a PC with at least this much memory and you will probably have to
  20. remove any TSR programs so that TURBO ASSEMBLER has as much space as possible.
  21.  
  22.  
  23. CONFIGURING PCroute.
  24.  
  25.     In order to change the interface configuration of PCroute it is only 
  26. necessary to change one file, DECLARE.INC.  This file contains a description 
  27. of each card in the router and it is this description that needs to be changed.  
  28. ------------------------------------------------------------------------------
  29.     Western Digital Ethernet Cards: for every WD card there are lines like
  30.        
  31.         ; this is a wd8013EBT entry
  32.     WDE_DECLARE %cur_dl, 280H, 0D000H, 0,0,64,1  ;;<name>, <I/O>, <seg>, <off>
  33.  ;      ; this is a wd8003EBT entry
  34.  ;  WDE_DECLARE %cur_dl, 280H, 0D000H, 0,0,128,0 ;;<name>, <I/O>, <seg>, <off>
  35.  ;      ; this is a wd8003E entry
  36.  ;  WDE_DECLARE %cur_dl, 280H, 0D000H, 0,0,32,0  ;;<name>, <I/O>, <seg>, <off>
  37.  ;      ; this is a starlan entry
  38.  ;  WD_DECLARE %cur_dl, 2A0H, 0D000H, 0,10,16 ;;<name>, <I/O>, <seg>, <off>
  39.     IF_DECLARE %cur_dl, %cur_dl, WDE        ;; <if name>, <real if>, <prefix>
  40.     ETH_DECLARE %cur_dl, %cur_dl, %cur_dl   ;; <eth name>, <if>, <task>
  41.     ARP_DECLARE %cur_dl, %cur_dl            ;; <arp name>, <ether>
  42.     DL_IP_DECLARE %cur_dl, %cur_dl, ARP     ;; <dlip name>, <real dlip> <prefix>
  43.     cur_dl = cur_dl + 1
  44.  
  45.     This particular declaration is for a WD8013 card.   The first
  46.     line declares that this card will be called 'cur_dl' and that
  47.     the card has its I/O address set to 280H, and its shared memory
  48.     address to D000:0000 (seg:offset).  The fifth parameter (0) is a
  49.     flag that indicates that we DON'T want promiscuous mode (where
  50.     the card returns every packet off the network.   The 6th parameter
  51.     tells how many 256byte pages of shared memory the card has, and the
  52.     final number is a flag that indicates if the card is a 16 bit card.
  53.  
  54.     The next two WDE_DECLARES are commented out.  These correspond to
  55.     the correct parameters for a WD8003EBT and WD8003E card.   Simply
  56.     comment out the first declaration and comment in the correct one
  57.     to change the type of card PCroute will expect.
  58.  
  59.     Note that for starlan cards a significant change was made.  Since
  60.     starlan cards are much slower than ethernet, starlan cards allocate
  61.     much of their memory to a write queue (instead of the input queue).
  62.     These changes are significant enough that different code is used
  63.     (not just different parameters).    That is why WD_DECLARE (instead
  64.     of WDE_DECLARE) is called.  The first four parameters to WD_DECLARE
  65.     are the same as WDE_DECLARE and the last two should probably always
  66.     be 10 and 16 (see WD8003.INC for details).  The bottom line, however
  67.     is the same if you want to compile for a starlan card, simply comment 
  68.     in this declaration.
  69.  
  70.     The rest of the declarations describe how this card is interacts 
  71.     with the rest to PCroute software.
  72.     In particular
  73.             1) IF_DECLARE declares that the WDE card is an ethernet card
  74.             2) ETH_DECLARE declares that this IF will use ethernet addressing
  75.                (as opposed to say 802.3 addressing)
  76.             3) ARP_DECLARE declares that the ARP protocol is to be used to 
  77.                map ethernet addresses to IP addresses
  78.             4) DL_IP declares that the card is to be used by a an IP code
  79.  
  80.     By and large these details are only of concern to a PCrouter programmer.
  81.     The only thing you need to know for configuration is that if you
  82.     are not using WD cards at all, all of these lines need to be
  83.     commented out.
  84.  
  85.     In addition to choosing the type of card, the first two parameters
  86.     determine the I/O address and shared memory segment for the card.
  87.     These numbers are arbitrary, but they must not conflict with any
  88.     other hardware.   The example declarations in DECLARE.INC use values
  89.     that I have found to work well.  You may have to change them however,
  90.     if you have unusual hardware.
  91.  
  92. -------------------------------------------------------------------------
  93.      Packet Driver:  For every card using the packet driver there is an entry
  94.  
  95.  
  96.     PKT_DECLARE %cur_dl, 60H, 01        ;; <name>, <Int Num> <Class (Eth=1)>
  97.     IF_DECLARE %cur_dl, %cur_dl, PKT        ;; <if name>, <real if>, <prefix>
  98.     ETH_DECLARE %cur_dl, %cur_dl, %cur_dl   ;; <eth name>, <if>, <task> 
  99.     ARP_DECLARE %cur_dl, %cur_dl            ;; <arp name>, <ether>
  100.     DL_IP_DECLARE %cur_dl, %cur_dl, ARP     ;; <dlip name>, <real dlip> <prefix>
  101.     cur_dl = cur_dl + 1
  102.  
  103.  
  104.     Like the WD case, only the first line in 'interesting'.   It simply
  105.     declares that it is an IF interface called 'cur_dl', that it should
  106.     communicate with the packet driver through software interrupt 60H,
  107.     and that the card has packet driver class 1.    
  108.     
  109.     Really only the second parameter is interesting.  When you load a
  110.     packet driver you also specify which software interrupt it will use.
  111.     This number should be the same as the one declared to PCroute here.
  112.     If you are using multiple cards using packet drivers, simply load
  113.     the packet drivers at different software interrupts (60H, 61H, ...)
  114.     and have several declarations like the one above (differing only
  115.     in the second arg of the PKT_DECLARE line).
  116.  
  117. -------------------------------------------------------------------------
  118.  
  119.     Localtalk:  For every localtalk entry there lines of the form
  120.  
  121.     ATP_DECLARE %cur_dl, 60H, %cur_dl, 10, 2000H;; <name> <int> <task> <wqueue>
  122.     DL_IP_DECLARE %cur_dl, %cur_dl, ATP     ;; <dlip name>, <real dlip> <prefix>
  123.     cur_dl = cur_dl + 1
  124.  
  125.     The ATP_DECLARE declares that this card will be called 'cur_dl' and 
  126.     that it can access the Appletalk software driver that comes with
  127.     the card though interrupt 60H.  (this is the correct number for Apple's
  128.     version of the localtalk driver).  The next parameter is the task
  129.     number needed by ATP and should ALWAYS be %cur_dl.  The next two
  130.     parameters is the number of entries in the write queue (in this case 10)
  131.     and the total space to allocate to the write queue (in this case 2000H
  132.     bytes).  These are tunable, but in general should not be changed.
  133.  
  134.     Also, if the line 'include atalk.inc' has been commented out, you
  135.     should comment it back in and comment out code for some other interface
  136.     you are not using (wd8003.inc for starlan, slip.inc for slip)
  137.  
  138.     At present, only ONE such localtalk entry is allowed.  The reason is
  139.     the appletalk driver that comes with the card can only support one
  140.     card.  It should be possible to install two cards (with different
  141.     I/O addresses), and install two drivers at different interrupts and
  142.     thus allow two localtalk cards.  I have tried this quickly to see
  143.     if it worked, and was unsuccessful, so for now, we only support one 
  144.     localtalk card. (:-(
  145.  
  146. -------------------------------------------------------------------------
  147.  
  148.     Slip:  For every Slip entry there are lines of the form
  149.  
  150.      I8250_DECLARE %cur_dl, SLIP, %cur_dl, IBM_COM1_PORT, IBM_COM1_IRQ, 0
  151.      tmp = cur_dl*100                                 ;; generate temp names
  152.      BUFF_DECLARE %(tmp+1), 3200                      ;; the read buffer
  153.      QUEUE_DECLARE %(tmp+2), 5, %(size qif_entry)     ;; the read queue
  154.      BUFF_DECLARE %(tmp+3), 10240                     ;; the write buffer
  155.      QUEUE_DECLARE %(tmp+4), 16, %(size qif_entry) ;; the write queue
  156.      SLIP_DECLARE %cur_dl,%cur_dl,%(tmp+1),%(tmp+2),%(tmp+3),%(tmp+4)
  157.      Q_IF_DECLARE %cur_dl,%(tmp+1),%(tmp+2),%(tmp+3),%(tmp+4),SLIP,%cur_dl
  158.      IF_DECLARE %cur_dl, %cur_dl, Q
  159.      PP_DECLARE %cur_dl, %cur_dl, %cur_dl
  160.      DL_IP_DECLARE %cur_dl, %cur_dl, PP   ;; <dlip name>, <real dlip> <prefix>
  161.      cur_dl = cur_dl + 1
  162.  
  163.      This declaration looks pretty daunting.  Luckily, only the first
  164.      line is of interest to us, and on that line only the 5th-7th 
  165.      parameters are interesting.  These parameters are the I/O address
  166.      of the COM port, the IRQ interrupt line for the port, and a flag
  167.      that will turn on CTS-RTS hardware flow control.    As you can
  168.      see from this example, the I/O port and IRQ number for the 'standard'
  169.      ports COM1 and COM2 have been given symbolic names.   Note that
  170.      COM3 and COM4 do NOT have a standard IRQ, so no symbolic names were
  171.      given for these.
  172.  
  173.      Note that you should make sure that no other hardware conflicts
  174.      with the IRQs used by the com ports.  In particular, WD cards have
  175.      use a default IRQ of 3, which is the same as that used by COM2.
  176.      Even though we don't use the WD interrupts, the fact that they are set
  177.      on the card will cause a conflict.   In addition every COM port
  178.      needs its own IRQ line.  Thus to use more that 2 serial ports you
  179.      must have COM cards that allow you to set to IRQs other than 4
  180.      and 3 (the IRQs for com1 and com2).  
  181.  
  182.      If you are following my good advice and are using a card with
  183.      a 16550AF chip in it for your COM board, you follow the same
  184.      instructions as above.  The I8250 code automatically determines
  185.      that it is a 16550 and turns on the FIFOs.  
  186.  
  187.      On a IBM XT, IRQ 2,3,4,(and 5 if you don't have a hard drive controller)
  188.          are usually available.
  189.  
  190.      On a IBM AT, IRQ 3,4,5,10,11,12,(and 13 if you don't have a coprocessor)
  191.          are usually available.
  192.  
  193.      Note that you CAN set all the WD cards to the SAME irq so you don't
  194.      waist more than one.  You may also be able to simply leave the IRQ
  195.      jumper off completely.  This may disable the IRQ lines so that they
  196.      will not conflict with anything.  I have not tried this, however,
  197.      so I simply don't know for sure that it will work.
  198.  
  199. =============================================================================
  200.  
  201.  
  202. The basic procedure now is to edit DECLARE.INC to make sure that it has
  203. all the proper declarations for the cards you want to use.  I have made
  204. this easy by including declarations for many common card configurations
  205. and commenting out all but the ones pertaining to the two ethernet card
  206. router.  So under almost all situations all you need to do is uncomment
  207. the proper declarations.  
  208.  
  209. Due to limitations in turbo assembler, the amount of actual code given
  210. to the assembler must be kept to a minimum.  To achieve this, at the top 
  211. of DECLARE.INC are a bunch of 'include' statements and any code that
  212. is not necessary is excluded by simply commenting out the proper line.
  213. Now, if you have changed, configurations, it is possible that you will
  214. also have comment in some include stmts and comment out others.  Basically
  215. you should comment out all files that have 'hardware like' names of 
  216. hardware you are not using.   Which ones are necessary should and which
  217. ones are not should be obvious.   
  218.  
  219. If you comment out too much, the compilation will abort saying that
  220. something is undefined.  If you leave in too much, you are likely to
  221. get a 'macro expansion size exceeded' or 'out of string space' message.
  222.  
  223. Once you have edited DECLARE.INC, the rest is easy.  Simply type
  224.  
  225.         tasm /ks170 *.asm                       
  226.         tlink pcroute ip rip log dlog ether atalk wd8003 wde8003 pp packet
  227.               ip_dl1 ip_dl2 ip_dl3 ip_dl4 ip_dl5 ip_dl6
  228.  
  229. (that is link all the object files create with the tasm command, the
  230. file link.bat should contain this command and will save you some typing)
  231. This will create a pcroute.exe file.  You can then copy this file
  232. to where config.exe lives and configure the router by following the
  233. in instructions in the installation document.  
  234.  
  235. The most common problem with the assembly procedure is the error message
  236. 'out of string space' or 'maximum macro expansion size exceeded'.  These
  237. error messages occur when TURBO ASSEMBLER runs out of memory.  Be sure
  238. you have a full 640K of memory and no TSR programs running if you get
  239. this message.  If this does not fix the problem, and you modified DECLARE.INC
  240. it is possible that you are compiling a configuration that is simply too 
  241. large for TURBO ASSEMBLER to handle.
  242.  
  243.  
  244. =============================================================================
  245.  
  246. Debugging:
  247.  
  248. For those of you that are modifying the code and wish to print out 
  249. debugging statements this is possible.  The file DEBUG.INC contains
  250. routines for doing just that.  The main routines are PRINT, PRINT_REG
  251. and DUMP_in_SI_CX.  PRINT simply prints a string.  PRINT_REG prints
  252. a string and the contents of any 16 bit register (in hex).  DUMP_in_SI_CX
  253. prints CX memory locations starting at SI using the named segment 
  254. register.  All of these routines modify NO registers so they can be
  255. used anywhere (except between a cmp and its jump instr).
  256.  
  257. Here is an example of how these macro look when they are called
  258.  
  259.     print <Starting program>
  260.     print_reg <SI = >, SI
  261.     print_reg <CX = >, CX
  262.     print <Dumping at SI for CX bytes>
  263.     dump_in_SI_CX DS
  264.  
  265.