home *** CD-ROM | disk | FTP | other *** search
/ CP/M / CPM_CDROM.iso / mbug / mbug175.arc / JRTMAN2.LBR / JRTMAN.1Z0 / JRTMAN.100
Text File  |  1979-12-31  |  18KB  |  595 lines
  1. .OP
  2.  
  3.       JRT Pascal  User's Guide     version 3.0         NOT FOR SALE   -120-
  4.  
  5.  
  6.  
  7.       10.   Assembler
  8.  
  9.  
  10.            The JRT Pascal system provides two methods of preparing external
  11.       procedures  and  functions  written  in assembly language.  A special
  12.       purpose assembler is provided which generates modules in the  correct
  13.       format.   The  second  method  may  be  used  if  a  Microsoft format
  14.       assembler is available, such as  RMAC  or  MACRO-80.   The   CONVERTM
  15.       utility  converts  the  '.REL' files produced by these two assemblers
  16.       into '.INT' format files which may be accessed as external procedures
  17.       (see section 10.7 of this manual).
  18.  
  19.            The JRT assembler translates 8080  assembly  language  into  JRT
  20.       relocatable  format  modules.   These  modules  can  be called from a
  21.       Pascal  program  as  if  they  were   Pascal   external   procedures.
  22.       Parameters  may  be  passed to them and function return values may be
  23.       received.
  24.  
  25.            The JRT  assembler  is  compatible  with  the  standard  ASM.COM
  26.       program  distributed with CP/M.  Input files must have a file type of
  27.       '.ASM'.  The assembler output is a file of type '.INT', which may  be
  28.       linked with the main program or automatically loaded at run-time.
  29.  
  30.  
  31.       10.1  Entry codes
  32.  
  33.            After  an  external  procedure is loaded into main storage, EXEC
  34.       transfers control to it.  A five byte code (95,6,0,92,0) is placed at
  35.       the start of the procedure to inform EXEC that this is  an  assembler
  36.       procedure  rather  than Pascal.  The procedure must end with a return
  37.       (RET) instruction.  Any registers EXCEPT the 8080 stack  pointer  may
  38.       be modified.
  39.  
  40.       Example of entry codes:
  41.  
  42.                   ;procedure entry
  43.                         db 95,6,0,92,0    ;required entry codes
  44.                   ;
  45.                   ;send a message to console
  46.                         mvi c,9           ;print buffer code
  47.                         lxi d,msg         ;address of message
  48.                         call 5            ;bdos entry point
  49.                   ;
  50.                         ret               ;end of procedure
  51.                   ;
  52.                   msg   db 'JRTASM sample procedure'
  53.                         db 0dh,0ah,'$'    ;carriage return/line feed
  54.       ;                  end
  55.       Copy compliments of Merle Schnick              SECTION 10:  Assembler
  56. .PAè
  57.       JRT Pascal  User's Guide     version 3.0         NOT FOR SALE   -121-
  58.  
  59.  
  60.  
  61.            If  this procedure were named SAMPLE.ASM then the declaration in
  62.       the Pascal program referencing it would be:
  63.  
  64.                   PROCEDURE SAMPLE; EXTERN;
  65.  
  66.  
  67.       10.2  Operating JRTASM
  68.  
  69.  
  70.            To assemble an external procedure, enter:
  71.  
  72.                   EXEC JRTASM
  73.  
  74.       You will be prompted at  the  console  for  the  input  filename  and
  75.       options.  The options are:
  76.  
  77.  
  78.           1  -  produce a listing on the console during pass 1 of the
  79.            assembly process, useful for debugging.
  80.  
  81.           C - produce an output  file  of  type  '.COM'  rather  than
  82.            '.INT'.  This  is not an external procedure but a directly
  83.            executable command file in standard CP/M format.  An   ORG
  84.            100H    directive  should  be  included  since the default
  85.            origin is 0.
  86.  
  87.  
  88.       10.3   Directives
  89.  
  90.            These assembler directives are supported:
  91.  
  92.                   directive         purpose
  93.                   ---------         ---------
  94.                   ORG               set location counter, not used
  95.                                      in external procedures
  96.                   SET               assign a value to a variable
  97.                   EQU               assign a value to a fixed symbol
  98.                   IF/ELSE/ENDIF     conditional assembly of code,
  99.                                      may be nested to 16 levels
  100.                   DB                define byte, multiple operands
  101.                   DW                define word
  102.                   DS                define storage
  103.                   READ              used to assign a new value to a
  104.                                      variable, like SET except that
  105.                                      value is obtained from console 
  106.                   WRITE             display strings or expressions 
  107.                                      on console
  108.  
  109.       Copy compliments of Merle Schnick              SECTION 10:  Assembler
  110. .PAè
  111.       JRT Pascal  User's Guide     version 3.0         NOT FOR SALE   -122-
  112.  
  113.  
  114.  
  115.       Examples of directives:
  116.  
  117.             1.         a     set 9
  118.                              if a = 9
  119.                              write 'a is equal to nine'
  120.                              else
  121.                              write 'a  is not equal to nine'
  122.                              endif
  123.  
  124.             2.         x     read        ;msg at console will ask for x 
  125.                              write 'x squared is ',(x * x)
  126.  
  127.             3.         a     set a + 1   ;increment a
  128.                              db 'string',a,255
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139.  
  140.  
  141.  
  142.  
  143.  
  144.  
  145.  
  146.  
  147.  
  148.  
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.       Copy compliments of Merle Schnick              SECTION 10:  Assembler
  164. .PAè
  165.       JRT Pascal  User's Guide     version 3.0         NOT FOR SALE   -123-
  166.  
  167.  
  168.  
  169.       10.4   Expressions
  170.  
  171.  
  172.            Integer expressions  can  be  used  in  assembler  instructions.
  173.       Expressions are either fixed or relocatable.  A symbol is relocatable
  174.       if  it refers to an address, otherwise it is fixed.  If any symbol in
  175.       an  expression  is  relocatable  then  the   entire   expression   is
  176.       relocatable.  Parenthesis may be nested to any level.
  177.  
  178.            These operators are supported:
  179.  
  180.                   *  /  +  -
  181.                   NOT  AND  OR  XOR
  182.                   MOD  HIGH  LOW
  183.                   EQ  NE  LT  LE  GT  GE
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205.  
  206.  
  207.  
  208.  
  209.  
  210.  
  211.  
  212.  
  213.  
  214.  
  215.  
  216.  
  217.       Copy compliments of Merle Schnick              SECTION 10:  Assembler
  218. .PAè
  219.       JRT Pascal  User's Guide     version 3.0         NOT FOR SALE   -124-
  220.  
  221.  
  222.  
  223.       10.5   Parameters and function return values
  224.  
  225.  
  226.            Parameters  of any data type may be passed to assembler external
  227.       procedures and functions.  The EXEC  maintains  a  data  stack  which
  228.       contains all static variables, parameters, function return values and
  229.       procedure linkage blocks.
  230.  
  231.            Three address pointers are used to access the data stack.  These
  232.       are  available  to  external procedures in the 8080 register pairs on
  233.       entry to the procedure.
  234.                   BASE  (HL) - address of the data stack
  235.                   CUR   (DE) - address of the linkage block for
  236.                                 currently active procedure
  237.                   TOS   (BC) - top of stack, points past last
  238.                                 allocated byte
  239.  
  240.  
  241.                         I                 I
  242.                         I                 I
  243.                   TOS-->I                 I
  244.                         I-----------------I
  245.                         I                 I
  246.                         I     6 bytes     I     linkage block for
  247.                         I                 I      current procedure
  248.                   CUR-->I                 I
  249.                         I-----------------I
  250.                         I     2 bytes     I     parameter length fld
  251.                         I-----------------I
  252.                         I                 I
  253.                         I     x bytes     I     parameters of 
  254.                         I                 I      current procedure
  255.                         I                 I
  256.                         I-----------------I
  257.                         I                 I
  258.  
  259.                         I                 I
  260.                         I                 I
  261.                         I                 I     global variables 
  262.                         I                 I      of main program 
  263.                         I-----------------I
  264.                         I                 I
  265.                         I     6 bytes     I     linkage block for
  266.                         I                 I      main program
  267.                         I                 I
  268.                  BASE-->I-----------------I
  269.  
  270.  
  271.       Copy compliments of Merle Schnick              SECTION 10:  Assembler
  272. .PAè
  273.       JRT Pascal  User's Guide     version 3.0         NOT FOR SALE   -125-
  274.  
  275.  
  276.  
  277.            With the three data stack pointers, the parameters passed to the
  278.       procedure can be accessed.  If it is a function, the return value can
  279.       be stored. Also, the global variables of  the  main  program  can  be
  280.       accessed.   For example, if the first global variable declared in the
  281.       main Pascal program which calls the external procedure is an  integer
  282.       named INT1, then just add 6 to the BASE pointer to get the address of
  283.       INT1.   The  BASE  pointer  is  in  register  pair HL on entry to the
  284.       procedure.
  285.  
  286.            Data stack after procedure call  DEMO( 'A',7 );
  287.  
  288.             'A'   7     length        linkage block
  289.             41    0700  0300        xx xx xx xx xx xx  yy
  290.                                     I                  I
  291.                                     CUR                TOS
  292.  
  293.  
  294.        The two byte integer fields are in 8080  byte-reverse  format.   The
  295.       parameter  length  field is equal to three.  The linkage block is six
  296.       bytes of unspecified data
  297.  
  298.            Parameters are accessed by decrementing the CUR pointer.  Pascal
  299.       value parameters  are  actually  present  in  the  data  stack.   For
  300.       reference  parameters,  the address of the variable is present in the
  301.       data stack.  If the procedure has no parameters, the parameter length
  302.       field is zero.
  303.  
  304.            Function return values must be stored just before the function's
  305.       first parameter in the data stack.
  306.  
  307.            Data stack after function call  X := TEST( 3,8 );
  308.       (The return value is of the type integer)
  309.  
  310.                   3     8     length        linkage block
  311.             rrrr  0300  0800  0400        xx xx xx xx xx xx  yy
  312.             I                             I                  I
  313.             return value                  CUR                TOS
  314.  
  315.  
  316.            If the return value is of type CHAR, a string, or  a  structured
  317.       variable  (entire  array,  entire  record)  then  there is a two byte
  318.       length field between the return value and the first parameter.   This
  319.       field  is  set by EXEC and MUST NOT be modified.  If the return value
  320.       is a dynamic string, the current length field is a two byte field  at
  321.       the  beginning  of the string. This must be set to the desired length
  322.       of the field.
  323.  
  324.  
  325.       Copy compliments of Merle Schnick              SECTION 10:  Assembler
  326. .PAè
  327.       JRT Pascal  User's Guide     version 3.0         NOT FOR SALE   -126-
  328.  
  329.  
  330.  
  331.            Data stack after function call  NAME := LOOKUP( 'X',1);
  332.       (The return value is of type ARRAY [1..4] OF CHAR;)
  333.  
  334.             return value  rv len    'X'   1     length   linkage block
  335.             rr rr rr rr   0400      58    0100  0300   xx xx xx xx xx xx  yy
  336.                                                        I                  I
  337.                                                        CUR                TOS
  338.  
  339.  
  340.  
  341.       10.6   Debugging assembler procedures
  342.  
  343.  
  344.            One effective  way  to  debug  external  procedures  written  in
  345.       assembler  uses  the  CP/M Dynamic Debugging Tool (DDT). If a user is
  346.       running a Pascal program under DDT, then a RST 7 instruction will  be
  347.       seen  as  a  breakpoint  and  allow  the  user  to access all the DDT
  348.       facilities.  To run under DDT, enter:
  349.  
  350.                   DDT EXEC.COM
  351.                   Iprogram_name
  352.                   G100
  353.  
  354.  
  355.            When the  RST  7  instruction  is  encountered,  DDT  will  gain
  356.       control.   The  display,  modify,  disassemble facilities then can be
  357.       used to examine the procedure data areas.  To resume  execution,  use
  358.       the XP command to set the instruction address ahead by 1, to get past
  359.       the RST 7 instruction.
  360.  
  361.  
  362.  
  363.  
  364.  
  365.  
  366.  
  367.  
  368.  
  369.  
  370.  
  371.  
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.       Copy compliments of Merle Schnick              SECTION 10:  Assembler
  380. .PAè
  381.       JRT Pascal  User's Guide     version 3.0         NOT FOR SALE   -127-
  382.  
  383.  
  384.  
  385.       10.7   Convertm program
  386.  
  387.  
  388.            The  Convertm  program  translates Microsoft format '.REL' files
  389.       into JRT format '.INT' files.  Only  '.REL'  files  may  be  input  -
  390.       '.HEX' files do not contain information about relocation addresses.
  391.  
  392.            To run the Convertm program, enter:
  393.  
  394.                   EXEC CONVERTM
  395.  
  396.  
  397.            The  program  will  inquire  at  the console for the name of the
  398.       module to be translated.  A file type  of  '.REL'  is  assumed.   The
  399.       output module '.INT' file is placed on the same disk.
  400.  
  401.  
  402.  
  403.       10.8   Sample assembly programs
  404.  
  405.  
  406.            Three  sample assembly programs are included here.  Two external
  407.       procedures (setbit, resetbit) and one external function (testbit) can
  408.       be called from any Pascal program or external function.  These  small
  409.       modules  provide  fast  and simple bit manipulation facilities.  They
  410.       also illustrate the passing and returning of parameters for  assembly
  411.       language external procedures.
  412.  
  413.  
  414.  
  415.  
  416.  
  417.  
  418.  
  419.  
  420.  
  421.  
  422.  
  423.  
  424.  
  425.  
  426.  
  427.  
  428.  
  429.  
  430.  
  431.  
  432.  
  433.       Copy compliments of Merle Schnick              SECTION 10:  Assembler
  434. .PAè
  435.       JRT Pascal  User's Guide     version 3.0         NOT FOR SALE   -128-
  436.  
  437.  
  438.  
  439.       Listing of setbit.asm:
  440.  
  441.  
  442.  
  443.       ;setbit.asm
  444.       ;external procedure which sets a bit on in a byte
  445.       ;
  446.       ; procedure setbit ( var x : char; bit : integer );
  447.       ;               extern;
  448.       ; bit# in range 0..7
  449.       ;
  450.       ;entry code
  451.               db 95,6,0       ;int vmcode
  452.               db 92           ;lpn vmcode
  453.               db 0            ;mode vmcode
  454.       ;on entry  bc=wtos  de=wb  hl=wbase
  455.       ;
  456.       ;get bit# in b_reg,  addr(x) in hl,  x into c_reg
  457.       setbit  xchg            ;hl=wb
  458.               dcx h! dcx h! dcx h! dcx h
  459.               mov b,m         ;bit#
  460.               dcx h! mov d,m! dcx h! mov e,m ;addr(x)
  461.               xchg            ;hl=addr(x)
  462.               mov c,m         ;c=x
  463.       ;create mask
  464.               inr b           ;incr loop count
  465.               mvi a,1
  466.       loop    rrc
  467.               dcr b
  468.               jnz loop
  469.       ;a=mask  c=byte
  470.               ora c
  471.               mov m,a         ;store byte
  472.               ret
  473.       ;
  474.               end
  475.  
  476.  
  477.  
  478.  
  479.  
  480.  
  481.  
  482.  
  483.  
  484.  
  485.  
  486.  
  487.       Copy compliments of Merle Schnick              SECTION 10:  Assembler
  488. .PAè
  489.       JRT Pascal  User's Guide     version 3.0         NOT FOR SALE   -129-
  490.  
  491.  
  492.  
  493.       Listing of resetbit.asm
  494.  
  495.  
  496.       ;resetbit.asm
  497.       ;external procedure which reset bit in a byte
  498.       ;
  499.       ; procedure resetbit ( var x : char; bit : integer );
  500.       ;               extern;
  501.       ; bit# in range 0..7
  502.       ;
  503.       ;entry code
  504.               db 95,6,0       ;int vmcode
  505.               db 92           ;lpn vmcode
  506.               db 0            ;mode vmcode
  507.       ;on entry  bc=wtos  de=wb  hl=wbase
  508.       ;
  509.       ;get bit# in b_reg,  addr(x) in hl,  x into c_reg
  510.       resetbit xchg           ;hl=wb
  511.               dcx h! dcx h! dcx h! dcx h
  512.               mov b,m         ;bit#
  513.               dcx h! mov d,m! dcx h! mov e,m ;addr(x)
  514.               xchg            ;hl=addr(x)
  515.               mov c,m         ;c=x
  516.       ;create mask
  517.               inr b           ;incr loop count
  518.               mvi a,0feh
  519.       loop    rrc
  520.               dcr b
  521.               jnz loop
  522.       ;a=mask  c=byte
  523.               ana c
  524.               mov m,a         ;store byte
  525.               ret
  526.       ;
  527.               end
  528.  
  529.  
  530.  
  531.  
  532.  
  533.  
  534.  
  535.  
  536.  
  537.  
  538.  
  539.  
  540.  
  541.       Copy compliments of Merle Schnick              SECTION 10:  Assembler
  542. .PAè
  543.       JRT Pascal  User's Guide     version 3.0         NOT FOR SALE   -130-
  544.  
  545.  
  546.  
  547.       Listing of testbit.asm
  548.  
  549.  
  550.  
  551.       ;testbit.asm
  552.       ;external function which returns bit value of a byte
  553.       ;
  554.       ; function testbit ( x : char; bit : integer ):
  555.       ;               boolean; extern;
  556.       ;
  557.       ; bit number is in range 0..7
  558.       ;
  559.       ;entry code
  560.               db 95,6,0       ;int vmcode
  561.               db 92           ;lpn vmcode
  562.               db 0            ;mode vmcode
  563.       ;on entry  bc=wtos  de=wb  hl=wbase
  564.       ;
  565.       ;get bit# into b_reg and x into a_reg
  566.       testbit xchg            ;hl=wb
  567.               dcx h! dcx h! dcx h! dcx h ;point to bit lownib
  568.               mov b,m         ;low byte of bit
  569.               dcx h! mov a,m  ;x
  570.               inr b
  571.       ;shift loop
  572.       loop    rlc
  573.               dcr b
  574.               jnz loop
  575.               jc true         ;bit is set
  576.       ;false : bit is zero
  577.               dcx h! mvi m,0! dcx h! mvi m,0
  578.               ret
  579.       ;true : bit is one
  580.       true    dcx h! mvi m,0! dcx h! mvi m,1
  581.               ret
  582.       ;
  583.               end
  584.  
  585.  
  586.  
  587.  
  588.  
  589.  
  590.  
  591.  
  592.  
  593.  
  594.       Copy compliments of Merle Schnick              SECTION 10:  Assembler
  595. .PAè