home *** CD-ROM | disk | FTP | other *** search
/ ftp.barnyard.co.uk / 2015.02.ftp.barnyard.co.uk.tar / ftp.barnyard.co.uk / cpm / walnut-creek-CDROM / CPM / LANGUAGS / PASCAL-P / PP319DOC.LBR / RBMFILES.MZN / RBMFILES.MAN
Text File  |  2000-06-30  |  11KB  |  218 lines
  1. .macro chttl = RBM#files#and#HEX#files
  2. .ch .chttl
  3. .hl 1 General
  4. The fundamental relocatable binary modules are known as RBM files.  They have
  5. been designed to be compatible with the INTEL hex standard, and to be
  6. machine independant,  in that the only assumption made is
  7. that  the host machine addresses in units of bytes.   Modules  cannot  exceed
  8. 32768 bytes in length,  but no restriction on final code size is made, except
  9. that  external  values must be expressable in two bytes for arithmetic to  be
  10. performed.   Limitations on name length have been expressly avoided, although
  11. present software truncates all names to 8 characters.
  12.  
  13. The structure of RBM files is best explained by first explaining HEX files.
  14.  
  15. A HEX file is made up entirely of printing characters,  and can be tranmitted
  16. and manipulated as a text file.  A record, in a HEX file, begins with the ":"
  17. character,  has several fields containing only the hexadecimal characters '0'
  18. through '9' and 'A' through 'F'.  The fields are as follows:
  19. .rem end itemize area with .res
  20. .macro itemize = .sav .tabs 5 15 .p -10 1 5 .lm 15 .rm $$rm-5;
  21. .itemize
  22.  
  23. .pp     colon .t    The character ":", beginning a record.
  24. .pp     length .t   2 hex characters,  describing a value in the  range
  25. 0  to  255 only.   This value specifies the  length
  26. of the remainder of the record.
  27. .pp     address .t  4  hex  characters,  describing an address  in  the
  28. range  0  to 65535 (under some  circumstances  this
  29. is  considered  a  signed integer in  the  range  -
  30. 32768 to 32767).
  31. .pp     type .t     2 hex characters,  describing a value in the  range
  32. 0  to 255 only.   The interpretation of this  value
  33. is central to the use of RBM files.
  34. .pp     data   .t   (2  times length) hex  characters.   Interpretation
  35. varies with use.
  36. .pp     checksum .t  2  hex  characters,  such that when each  character
  37. pair since the ":" is considered as a number in the
  38. range (0..255), the sum MODULO 256 will be zero.
  39. .pp     anything .t  except  a ":" may follow the checksum,  and may  be
  40. used for formatting,  comments,  etc.  It is always
  41. ignored.
  42. .res
  43.  
  44. Note that every data item, after the initial colon, can be expressed as a one
  45. byte value, thus reducing storage requirements, transmission time, etc. by at
  46. least a factor of 2.
  47.  
  48. The  original  INTEL  standard defined record types 0 and 1.  Type  0  is  an
  49. absolute load code record,  in which "address" describes the machine  address
  50. to be loaded with the first byte in the data field.  Type 1 is an end-of-file
  51. record,  with length always zero,  and address describing an address to which
  52. execution  control is to be transferred.   Type 0,  when length is  zero,  is
  53. treated  in the same manner.   By convention,  a transfer address of zero  in
  54. these end-of-file records signifies that no control transfer is to be made.
  55.  
  56. .hl 1 RBM files
  57. RBM  records are exact images of HEX records,  except that the leading  colon
  58. and  trailing  checksum  have been discarded,  and that  the  information  is
  59. presented  as  8 bit bytes in place of pairs of hexadecimal  characters.   No
  60. trailing "anything" field is permitted,  and a new record begins  immediately
  61. after  the previous record ends.   Verification of storage is left up to  the
  62. storage  system  on which the files reside (typically CRC checksums over  the
  63. storage blocks).  Thus RBM records can be discussed in exactly the same terms
  64. as HEX records, and conversion between the systems is easy.
  65.  
  66. .tp 10
  67. .hl 2 RBM record types
  68. To  preserve compatibility RBM files retain the original INTEL  definitions
  69. of  record types 0 and 1,  and add further types starting at type 128  (080
  70. hex).   In  all cases the length byte describes the number of bytes in  the
  71. data field, which may be zero.  Additional types are:
  72.  
  73. .itemize
  74.  
  75. .pp  128 .t  Relocatable  data  record.    Exactly  analogous  to  the 
  76. absolute data record (0), but the address field describes the 
  77. location with respect to the base of the current module.
  78. .pp  129 .t  End module record.  Address and length are zero.
  79. .pp  130 .t Relocatable Code Module Header.   The relocatable records 
  80. which  follow are to be placed in a  code  segment.   The
  81. address field describes the total length of the following
  82. code.   The  data field,  (which may be empty) may hold a
  83. name for the segment of up to 60 characters.
  84. .pp  131 .t  Entrypoint  descriptor.   Address is a value relative  to
  85. the base of the current segment.   Data holds the name of
  86. the entrypoint, in Ascii characters.
  87. .pp  132 .t  Absolute entry.   Address is an absolute value,  which is
  88. to  be used to resolve any referances to the name in  the
  89. data field (again in Ascii characters).
  90. .pp  133 .t External  referance.   Address is an index value used  by
  91. the linkage records which follow.  The data field holds a
  92. name,  in Ascii,  whose actual value is described in some
  93. other module.   Note that the index in the address  field
  94. will  never be less than 2,  because indices 0 and 1  are
  95. reserved  to  describe  code  and  data  module  relative
  96. relocation.
  97. .pp  134 .t  Data  module  header.   As  type  130,  except  that  the
  98. following  data  records  are to be placed  in  the  data
  99. segment.
  100. .pp  135 .t  Alignment  Record.   Must only occur immediately after  a
  101. module  header record.   Causes the module to adjust  its
  102. location  so  that  the  absolute  location,  modulo  the
  103. address field, is zero.  The data field is unused.
  104. .pp  136 .t  Pcd  module entry point.  At linkage time this value must
  105. have  the high order 8 bits set to the module  number  in
  106. which  it  occured,  in  the range 1 to 127 (only  31  at
  107. present).  The data field contains the entry name.  These
  108. records  are  used to describe PCD linkages in  terms  of
  109. segment/entry_number  pairs.   The  occurance of such  an
  110. entry point causes LINKER to assume that the output is to
  111. be a PCD program.
  112. .pp  137 .t  Equate names.   Not presently implemented.  Address field
  113. is  unused.   The  data field contains  two  Ascii  names
  114. separated  by  the "=" character,  as  in  "name1=name2".
  115. Causes   all  referances  to  name1  to  be  resolved  as
  116. referances to name2.  The data field should not exceed 60
  117. characters,  thus effectively limiting names to less than
  118. 30 characters.
  119. .pp  138
  120. .pp  thru .t Reserved, not presently assigned.
  121. .pp  143
  122. .res
  123.  
  124. Types  144 through 159 are reserved as linkage records,  in which the  type
  125. modulo 16 is used as an operator.   The address field (except for types 152
  126. through 154 below) contains an index, which refers to an external referance
  127. record active within this module (or 0 or 1 to specify the current code  or
  128. data  segment  bases),  and  the  data  field contains a  list  of  16  bit
  129. addresses, in high byte first format, specifying a location relative to the
  130. current  module beginning which is to be adjusted.   All operators  discard
  131. any  carrys and borrows,  and thus never cause arithmetic  overflows.   The
  132. operators currently assigned are:
  133.  
  134. .itemize
  135. .pp  144 .t  Add  lobytefirst words.   The value of external referance
  136. is added to the two bytes of the module.
  137. .pp  145 .t  Subtract lobytefirst.  The value of external referance is
  138. subtracted from the two bytes of the module.
  139. .pp  146 .t  Add byte.   The value of external referance,  low order 8
  140. bits only, is added to the byte of the module.
  141. .pp  147 .t  Subtract  byte.   The value of  external  referance,  low
  142. order  8  bits only,  is subtracted from the byte of  the
  143. module.
  144. .pp  148 .t  Add  high byte.   The value of external  referance,  high
  145. order 8 bits only, is added to the byte of the module.
  146. .pp  149  .t Subtract  high byte.   The value of  external  referance,
  147. high  order  8 bits,  is subtracted from the byte of  the
  148. module.
  149. .pp  150 .t Add  hibytefirst words.   Similar to type  144,  but  the
  150. module  contents is treated as a high byte first integer.
  151. Note that this does not affect the value of the external.
  152. .pp  151 .t Subtract  hibytefirst  words.    As  150,   but  external
  153. referance is subtracted from the module content.
  154.  
  155. .res
  156. Types 152 through 154 are anonymous linkage records.   Address contains the
  157. value of the "external",  rather than an index to it's entry record.  These
  158. records permit construction of one pass assemblers and  codegenerators,  by
  159. postponing "fixup" operations to linkage time.   Since modules are in their
  160. most compact form at linkage time, and since general code generation always
  161. requires  a two pass algorithm at some point,  the linkage step is the most
  162. efficient point at which to implement the second pass.
  163.  
  164. .itemize
  165. .pp  152 .t Add lowbytefirst fixup linkage.
  166. .pp  153 .t Add hibytefirst fixup linkage.
  167. .pp  154 .t Add byte (8 bits only) fixup linkage.
  168.  
  169. .pp  155
  170. .pp thru .t Unassigned operators.
  171. .pp  159
  172.  
  173. .pp  160
  174. .pp  thru .t Reserved for future use.
  175. .pp  191
  176.  
  177. .pp  192 up .t Available for system dependant  special operations  which
  178. cannot be handled by the existing types.   No reliance on
  179. portablity should be made when these types are used.
  180.  
  181. .res
  182. .hl 1 Utility Programs
  183. The  utility programs HEXTORBM and RBMTOHEX perform conversions  between  RBM
  184. and  HEX  files,  and  are  principally  used  to  transfer  RBM  files  over
  185. transmission  links  (e.g.   RS232  lines).    RBM  files  are  generated  by
  186. assemblers,  compilers,  etc,  and linked into executable programs by LINKER.
  187. LINKER operation is documented separately.   RBMLOAD converts RBM files which
  188. contain  only absolute loader records,  into program files.   HEXLOAD is  the
  189. equivalent  for  HEX files,  and similar to the CPM standard  program  LOAD.
  190. However  HEXLOAD and RBMLOAD use the file redirection systems,  and are  thus
  191. much  more flexible.   RBMTOHEX also has provisions for co-operation with the
  192. PIP [b] option.  See the manual on FILTERS.
  193.  
  194. The typical execution command is
  195.  
  196. .i 10          B>runpcd hextorbm(hexfile, rbmfile) .b
  197. or .b
  198. .i 10          B>runpcd rbmtohex(rbmfile, hexfile); [parm]
  199.  
  200. For example, to transfer a rbm file named MYFILE.RBM over an RS232 link, such
  201. as a modem,  on the PUN device,  with 10 second delays for buffer flushing by
  202. the receiver, enter:
  203.  
  204. .i 10          B>runpcd rbmtohex(myfile.rbm, pun); [10]
  205.  
  206. If  no  files  can  be found for the input files  (hexfile  or  rbmfile)  the
  207. programs will prompt for their names, and request confirmation before purging
  208. any  previous versions of the destination file.   RBMLOAD and HEXLOAD act  in
  209. the identical manner.
  210.  
  211. BINHEX (binfile, hexfile) can be used to convert binary files to absolute load
  212. hex files.  By default the origin is set at 0100h.  The output may be converted
  213. back to a binary file by HEXLOAD.  [parm] may be used to co-operate with PIP
  214. operating with the [b] option.  See "FILTERS".
  215.  
  216.  
  217. See the separate documentation on LINKER and its companion SCANRBMS.
  218. ╒_