GLMAC User's Guide
         



                                 INTRODUCTION

              This    document    describes    the    contents     of
         LB:[1,1]GLMAC.MLB.  GLMAC is a collection of frequently-used
         MACRO definitions, and is intended to be referenced  in  all
         CSG  MACRO-11  programs.  Also described are the contents of
         LB:[1,1]GLMAC.OLB, a similar collection  of  object  modules
         (subroutines).  



         1.  Format

              Each macro or subroutien in GLMAC  is  described  in  a
         chapter  of this document.  The description includes invoca-
         tion rules, actions, and usage notes.  



         2.  Adding Macros

              Users are encouraged to submit their favorite macros or
         subroutines for inclusion in GLMAC.  Entries in GLMAC should
         fit one of two criteria:  generality  or  uniqueness.   Most
         macros in GLMAC will be those of general use and appeal (the
         CALL and RETURN macros for  example).   However,  macros  of
         limited  generality which are complex, unusual, and so forth
         may also be included.  The same guidelines apply for subrou-
         tines included in GLMAC.OLB.  

              If a user wishes to submit a routine to GLMAC, the fol-
         lowing should be prepared:

              *  Source:  The source file should be commented (often,
                 though,  MACROs are lightly commented, which is OK).
                 Also, examine the source for generality and ease  of
                 use.   Try  to keep things simple -- several related
                 routines are often preferable to one  with  gobs  of
                 parameters.  Also, is the routine in its most gener-
                 al form?
              *  Document source:  A RNO source file should  be  pre-
                 pared  which  follows  the  format of this document.
                 Each routine (macro or  subroutine)  is  a  separate
                 chapter.   Be sure to mention dependencies - such as
                 upon other GLMAC modules.  
              *  Test Program A simple program illustrating the  rou-
                 tine should be prepared.  



         GLMAC User's Guide                                    Page 2
         



         3.  MACROS

              This section lists macros which exist.  Full documenta-
         tion is found in individual chapters.  
              *  CALL -- general subroutine call
              *  RETURN -- general return from subroutine
              *  PUSH -- push registers on stack
              *  POP -- pop registers from stack
         
         





                                  CHAPTER 1

                                     CALL



                            CALL -- Subroutine call
          
         CALL name, reg, args
          
                 name = name of entry point (ASCII)
                 reg = optional linkage register (Rn)
                 args = optional arguement list
          

              CALL performs a generalized subroutine call.  The  name
         parameter is required.  In the simplest form (CALL foo), a

              JSR PC, foo instruction is generated.  If the reg  par-
         ameter  is  specified, the specified register is used in the
         JSR instruction.  The args parameter specifies one  or  more
         arguements  which are converted into successive .WORD direc-
         tives immediately following the JSR instruction.  Note  that
         if  multiple  args are specified, the arguement list must be
         enclosed in brokets (i.e., <a,b,c>).  In its full form, CALL
         would expand as follows:
                    
                   CALL foo,r4,<able, baker,  3,<bits!24>>
                   JSR  R4, foo
                   .word  able
                   .word  baker
                   .word   3
                   .word  <bits!24>
                    
         
         





                                  CHAPTER 2

                                    RETURN



                 RETURN -- generalized return from subroutine
                    
                   RETURN reg
                    
                         reg = optional linkage register
                    
         RETURN translates into a simple RTS instruction.  If no  re-
         gister is specified, PC is used.  
         
         





                                  CHAPTER 3

                                     POP



                       POP -- Pop register(s) from stack
                   POP <regs>
                    
                         regs = register or <register list>
                    
         POP produces a 
                   MOV (sp)+, reg for  each  register  supplied.   If
         more  than  one  register  is supplied, the entire arguement
         list must be surrounded by brokets (i.e.,  POP  <r0,r1,r3>).
         The registers are popped in the order specified.  


                                  NOTE WELL

              When using PUSH and POP, the registers are used in
              the  order  specified  - you must normally specify
              registers to POP in reverse order used in PUSH for
              everything to come out right.  

                   PUSH <r0,r1,r2>

                   POP <r2,r1,r0>


              If only one register is specified, it need not  be  en-
         closed by brokets.  
         
         





                                  CHAPTER 4

                                    PUSH 



                      PUSH -- PUSH register(s) from stack
                   PUSH <regs>
                    
                         reg = register or <register list>
                    
         PUSH produces a 
                   MOV reg, -(sp) for  each  register  supplied.   If
         more  than  one  register  is supplied, the entire arguement
         list must be surrounded by brokets (i.e., PUSH  <r0,r1,r3>).
         The registers are pushed in the order specified.  


                                  NOTE WELL

              When using PUSH and POP, the registers are used in
              the  order  specified  - you must normally specify
              registers to POP in reverse order used in PUSH for
              everything to come out right.  

                   PUSH <r0,r1,r2>

                   POP <r2,r1,r0>


              If only one register is specified, it need not  be  en-
         closed by brokets.  
         
         





                                   CONTENTS



             1.  Format . . . . . . . . . . . . . . . . . . . . .   1
             2.  Adding Macros  . . . . . . . . . . . . . . . . .   1
             3.  MACROS . . . . . . . . . . . . . . . . . . . . .   2
         
         1.  CALL . . . . . . . . . . . . . . . . . . . . . . . . 1-1

         2.  RETURN . . . . . . . . . . . . . . . . . . . . . . . 2-1

         3.  POP  . . . . . . . . . . . . . . . . . . . . . . . . 3-1

         4.  PUSH   . . . . . . . . . . . . . . . . . . . . . . . 4-1