.; SY42:[10,1]GLMAC.RNO -- GLMAC.MLB Documentation .; Author: Jim Bostwick .; Last Edit:JMB 12-FEB-1985 17:05:30 .ap .hy .title GLMAC User's Guide .c; 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). .hl 1 Format Each macro or subroutien in GLMAC is described in a chapter of this document. The description includes invocation rules, actions, and usage notes. .hl 1 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 subroutines included in GLMAC.OLB. If a user wishes to submit a routine to GLMAC, the following should be prepared: .sk .list 0,* .le 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 general form? .le Document source: A RNO source file should be prepared 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. .le Test Program A simple program illustrating the routine should be prepared. .els .hl 1 MACROS This section lists macros which exist. Full documentation is found in individual chapters. .list 0,* .le CALL -- general subroutine call .le RETURN -- general return from subroutine .le PUSH -- push registers on stack .le POP -- pop registers from stack .els .ch CALL .nf .c; CALL -- Subroutine call CALL name, reg, args name = name of entry point (ASCII) reg = optional linkage register (Rn) args = optional arguement list .F CALL performs a generalized subroutine call. The name parameter is required. In the simplest form (CALL foo), a .i 10; JSR PC, foo .bk instruction is generated. If the reg parameter 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 directives immediately following the JSR instruction. Note that if multiple args are specified, the arguement list must be enclosed in brokets (i.e., ). In its full form, CALL would expand as follows: .lm +10 .nf CALL foo,r4,> JSR R4, foo _.word able _.word baker _.word #3 _.word .f .lm -10 .ch RETURN .c; RETURN -- generalized return from subroutine .nf .lm +10 RETURN reg reg = optional linkage register .f .lm -10 RETURN translates into a simple RTS instruction. If no register is specified, PC is used. .ch POP .c; POP -- Pop register(s) from stack .nf .lm +10 POP regs = register or .f .lm -10 POP produces a .i 10;MOV (sp)+, reg .bk for each register supplied. If more than one register is supplied, the entire arguement list must be surrounded by brokets (i.e., POP ). The registers are popped in the order specified. .note 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. .i 10; PUSH .i 10; POP .end note If only one register is specified, it need not be enclosed by brokets. .ch PUSH .c; PUSH -- PUSH register(s) from stack .nf .lm +10 PUSH reg = register or .f .lm -10 PUSH produces a .i 10;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 ). The registers are pushed in the order specified. .note 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. .i 10; PUSH .i 10; POP .end note If only one register is specified, it need not be enclosed by brokets.