read_em.3 9.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328
  1. .TH READ_EM 3 "$Revision$"
  2. .ad
  3. .SH NAME
  4. EM_open, EM_getinstr, EM_close,
  5. EM_mkcalls\ \-\ a module to read EM assembly code
  6. .SH SYNOPSIS
  7. .B #include <em_spec.h>
  8. .br
  9. .B #include <em_mnem.h>
  10. .br
  11. .B #include <em_pseu.h>
  12. .br
  13. .B #include <em_flag.h>
  14. .br
  15. .B #include <em_ptyp.h>
  16. .br
  17. .B #include <em.h>
  18. .br
  19. .B #include <em_comp.h>
  20. .PP
  21. .B int EM_open(filename)
  22. .br
  23. .B EM_close()
  24. .br
  25. .B char *filename;
  26. .PP
  27. .B int EM_getinstr(instr)
  28. .B struct e_instr *instr;
  29. .PP
  30. .B int EM_mkcalls(instr)
  31. .br
  32. .B struct e_instr *instr;
  33. .PP
  34. .B char *EM_error;
  35. .PP
  36. .B unsigned int EM_lineno;
  37. .PP
  38. .B char *EM_filename;
  39. .PP
  40. .B int EM_wordsize, EM_pointersize;
  41. .SH DESCRIPTION
  42. This package provides routines to read EM assembly code.
  43. The object is to simplify the program
  44. writer's task of reading EM assembly code,
  45. either in compact or human-readable form.
  46. .PP
  47. \fIEM_open\fR must be called as initializer of the package.
  48. If \fIfilename\fR is a null pointer, reading is done from standard input,
  49. otherwise it is done from the file \fIfilename\fR.
  50. \fIEM_open\fR returns 1 on success and 0 on failure
  51. with an error message in \fIEM_error\fR.
  52. \fIEM_close\fR must be called after all other calls to this package.
  53. .PP
  54. \fIEM_getinstr\fR reads an EM instruction, and
  55. returns it in the structure pointed to by \fIinstr\fR.
  56. This structure has the following layout:
  57. .br
  58. .PP
  59. .ta \w'struct\ \ \ 'u +\w'struct e_instr *\ \ \ \ \ \ 'u +\w'em_opcode\ \ \ 'u +\w'*emu_string\ \ \ 'u
  60. .nf
  61. /*
  62. * (c) copyright 1987 by the Vrije Universiteit, Amsterdam, The Netherlands.
  63. * See the copyright notice in the ACK home directory, in the file "Copyright".
  64. */
  65. /* $Header$ */
  66. struct e_arg {
  67. int ema_argtype; /* type of this argument */
  68. union e_simple_arg {
  69. arith emu_cst; /* a cst */
  70. label emu_dlb; /* a numeric data label */
  71. label emu_ilb; /* an instruction label */
  72. char *emu_dnam; /* a data label */
  73. char *emu_pnam; /* a procedure name */
  74. char *emu_string; /* a string (fcon,icon,ucon,scon) */
  75. } ema_arg;
  76. arith ema_szoroff;
  77. };
  78. #define ema_cst ema_arg.emu_cst
  79. #define ema_dlb ema_arg.emu_dlb
  80. #define ema_ilb ema_arg.emu_ilb
  81. #define ema_dnam ema_arg.emu_dnam
  82. #define ema_pnam ema_arg.emu_pnam
  83. #define ema_nlocals ema_szoroff
  84. #define ema_string ema_arg.emu_string
  85. struct e_instr {
  86. int em_type; /* Type of this instr */
  87. #define EM_MNEM 256 /* A machine instruction */
  88. #define EM_PSEU 257 /* A pseudo */
  89. #define EM_STARTMES 258 /* Start of a MES pseudo */
  90. #define EM_MESARG 259 /* A member in a MES list */
  91. #define EM_ENDMES 260 /* End of a MES pseudo */
  92. #define EM_DEFILB 261 /* An instruction label definition */
  93. #define EM_DEFDLB 262 /* A numeric data label definition */
  94. #define EM_DEFDNAM 263 /* A non-numeric data label def */
  95. #define EM_ERROR 264 /* Recoverable error */
  96. #define EM_FATAL 265 /* Unrecoverable error */
  97. #define EM_EOF 266 /* End of file */
  98. int em_opcode;
  99. struct e_arg em_arg;
  100. };
  101. extern arith
  102. EM_holsize, EM_bsssize;
  103. extern int
  104. EM_holinit, EM_bssinit;
  105. #define em_ilb em_arg.ema_ilb
  106. #define em_dlb em_arg.ema_dlb
  107. #define em_dnam em_arg.ema_dnam
  108. #define em_argtype em_arg.ema_argtype
  109. #define em_cst em_arg.ema_cst
  110. #define em_pnam em_arg.ema_pnam
  111. #define em_nlocals em_arg.ema_nlocals
  112. #define em_string em_arg.ema_string
  113. #define em_off em_arg.ema_szoroff
  114. #define em_size em_arg.ema_szoroff
  115. /* arguments for EXC pseudo: */
  116. #define em_exc1 em_arg.ema_cst
  117. #define em_exc2 em_arg.ema_szoroff
  118. extern char
  119. *EM_error, *EM_filename;
  120. extern unsigned int
  121. EM_lineno;
  122. extern int
  123. EM_wordsize, EM_pointersize;
  124. .fi
  125. .PP
  126. The named types \fBarith\fR and \fBlabel\fR refer to types on the local machine
  127. that are suitable for doing arithmetic and storing EM numeric labels
  128. respectively.
  129. Common definitions are \fBlong\fR for \fBarith\fR and \fBunsigned int\fR for
  130. \fBlabel\fR.
  131. .PP
  132. The \fIe_instr\fR structure consists of the fields
  133. \fIem_type\fR, containing the type of this \fIe_instr\fR,
  134. \fIem_opcode\fR, containing the opcode of an instruction,
  135. and \fIem_arg\fR, containing a possible argument.
  136. .PP
  137. The possible values of
  138. \fIem_type\fR, defined in <em_comp.h>, are summarized below:
  139. .br
  140. .ta \w'EM_STARTMES\ \ \ 'u +\w'em_defdnam\ \ \ 'u
  141. .di xx
  142. \ka
  143. .br
  144. .di
  145. .IP "Value Selector" \nau
  146. Meaning
  147. .IP "EM_MNEM em_opcode" \nau
  148. an EM machine instruction.
  149. .br
  150. .PD 0
  151. .IP " em_arg" \nau
  152. The \fIem_opcode\fR field
  153. contains the opcode of the instruction, and \fIem_arg\fR may contain an
  154. argument. If \fIem_argtype\fR indicates that there is no argument,
  155. \fIem_cst\fR is set to 0.
  156. .IP "EM_PSEU em_opcode" \nau
  157. an EM pseudo instruction.
  158. .IP " em_arg" \nau
  159. The \fIem_opcode\fR field
  160. contains the opcode, and \fIem_arg\fR may contain an argument.
  161. As consecutive CON-pseudos are allocated consecutively, a CON delivered by
  162. \fIEM_getinstr\fR has exactly one argument.
  163. If the CON-pseudo read has more, they are delivered as separate CON's.
  164. The same holds for ROM-pseudos.
  165. Also, if the length of a string constant exceeds 256 characters, it will be
  166. delivered as several CON's or ROM's.
  167. There are two "special" pseudo's, that use other variables, HOL and BSS.
  168. They use EM_holsize, EM_holinit, EM_bsssize, and EM_bssinit, because those
  169. arguments do not fit in the \fIe_arg\fR structure, and we want to keep the
  170. \fIe_arg\fR structure as small as possible.
  171. The EXC pseudo has its arguments encoded as indicated in the #defines.
  172. The PRO pseudo has its second argument in \fIem_nlocals\fR. If it is
  173. -1, it was omitted.
  174. .IP "EM_STARTMES em_arg" \nau
  175. the start of a MES pseudo.
  176. .br
  177. There is one argument: the message number.
  178. The other arguments, if any, are delivered as separate EM_MESARG's.
  179. .IP "EM_MESARG em_arg" \nau
  180. an argument of a MES pseudo.
  181. .IP "EM_ENDMES none" \nau
  182. the end of a MES pseudo.
  183. .IP "EM_DEFILB em_ilb" \nau
  184. an instruction label definition.
  185. .br
  186. The field \fIem_ilb\fR contains the label (instruction labels are always
  187. numeric).
  188. .IP "EM_DEFDLB em_dlb" \nau
  189. a numeric data label definition.
  190. .br
  191. The field \fIem_dlb\fR contains the label.
  192. .IP "EM_DEFDNAM em_dnam" \nau
  193. a non-numeric data label definition.
  194. .br
  195. The field \fIem_dnam\fR contains the label.
  196. .IP "EM_ERROR none" \nau
  197. an error in the input that makes the rest of the data in the structure
  198. meaningless.
  199. .br
  200. \fIEM_error\fR
  201. contains an error message.
  202. .IP "EM_FATAL none" \nau
  203. a fatal error.
  204. .br
  205. \fIEM_error\fR contains an
  206. error message.
  207. .IP "EM_EOF none" \nau
  208. end of file
  209. .PD
  210. .PP
  211. The \fIe_arg\fR structure consists of the fields
  212. the field \fIema_argtype\fR, containing the type of this argument or 0
  213. if absent,
  214. the field \fIema_arg\fR, containing the value of the argument,
  215. and \fIema_szoroff\fR, containing an optional offset or size.
  216. The possible values of \fIema_argtype\fR, defined in <em_ptyp.h>,
  217. are summarized below:
  218. .br
  219. .ta \w'dlb_ptyp\ \ \ \ 'u +\w'em_opcode\ \ \ 'u
  220. .di xx
  221. \ka
  222. .br
  223. .di
  224. .IP "Value Selector" \nau
  225. Meaning
  226. .IP "0 none" \nau
  227. no argument.
  228. .IP "ilb_ptyp em_ilb" \nau
  229. an instruction label.
  230. .PD 0
  231. .IP "nof_ptyp em_dlb" \nau
  232. an offset from a numeric data label.
  233. .IP " em_off" \nau
  234. The
  235. \fIem_off\fR field contains the offset and the
  236. \fIem_dlb\fR field contains the label.
  237. .IP "sof_ptyp em_dnam" \nau
  238. an offset from a non-numeric data label.
  239. .IP " em_off" \nau
  240. The \fIem_off\fR field contains the offset and the \fIem_dnam\fR field
  241. contains the label, represented as a string.
  242. .IP "cst_ptyp em_cst" \nau
  243. a numeric constant.
  244. .IP "pro_ptyp em_pnam" \nau
  245. a procedure name, not including the '$',
  246. represented as a string.
  247. .IP "str_ptyp em_string" \nau
  248. a string constant.
  249. .IP " em_size" \nau
  250. The string is found in \fIem_string\fR, represented as a row of bytes, of
  251. length \fIem_size\fR.
  252. .IP "ico_ptyp em_string" \nau
  253. an integer constant.
  254. .IP " em_size" \nau
  255. A string representation of the constant is found in \fIem_string\fR.
  256. It has size \fIem_size\fR bytes on the target machine.
  257. .IP "uco_ptyp em_string" \nau
  258. an unsigned constant.
  259. .IP " em_size" \nau
  260. A string representation of the constant is found in \fIem_string\fR.
  261. It has size \fIem_size\fR bytes on the target machine.
  262. .IP "fco_ptyp em_string" \nau
  263. a floating constant.
  264. .IP " em_size" \nau
  265. A string representation of the constant is found in \fIem_string\fR.
  266. It has size \fIem_size\fR bytes on the target machine.
  267. .PD
  268. .PP
  269. When an error occurs, \fIEM_error\fR is set to indicate the reason.
  270. \fIEM_getinstr\fR returns 1 if all goes well, 0 if it does not.
  271. The EM_ERROR described above is only set when the error
  272. is serious enough.
  273. .PP
  274. The routine \fIEM_mkcalls\fR "translates" the EM instruction indicated
  275. by \fIinstr\fR
  276. into calls of the procedural interface defined in \fIem_code\fR(3L).
  277. It returns 1 if it succeeds, 0 if it fails for some reason. The
  278. reason can then be found in \fIEM_error\fR.
  279. The \fIEM_mkcalls\fP routine is obsolete. It is being replaced by the
  280. .I C_out
  281. routine of the
  282. .I em_code
  283. module.
  284. .PP
  285. \fIEM_lineno\fR contains the line number of the last line read by
  286. \fIEM_getinstr\fR.
  287. .PP
  288. \fIEM_filename\fR contains a filename. It usually contains the value
  289. given as parameter to \fIEM_open\fR, but may have a different value, when
  290. the input was the result of some preprocessing.
  291. .PP
  292. .I EM_wordsize
  293. and
  294. .I EM_pointersize
  295. contain the wordsize and pointersize, but only after the first
  296. (pseudo-)instruction has successfully been read.
  297. .SH FILES
  298. .nf
  299. ~em/modules/h/em.h
  300. ~em/h/em_ptyp.h
  301. ~em/modules/h/em_comp.h
  302. ~em/modules/lib/libread_emk.a: non-checking library for reading compact EM code
  303. ~em/modules/lib/libread_emkV.a: checking library for reading compact EM code
  304. ~em/modules/lib/libread_emeV.a: checking library for reading human-readable EM code
  305. .fi
  306. .SH MODULES
  307. em_code(3), string(3), system(3), ~em/lib/em_data.a
  308. .SH "SEE ALSO"
  309. em_code(3)
  310. .br
  311. A.S. Tanenbaum, H. v Staveren, E.G. Keizer, J.W. Stevenson, "\fBDescription
  312. of a Machine Architecture for use with Block Structured Languages\fR",
  313. Informatica Rapport IR-81, Vrije Universiteit, Amsterdam, 1983.
  314. .SH REMARKS
  315. All strings must be considered to be contained in a static area, so
  316. must be copied to be saved.
  317. .SH BUGS
  318. As CON's and ROM's may be delivered in several parts, the count fields in
  319. a static exchange may be wrong.
  320. .PP
  321. Please report bugs to the author.