em_code.3X 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496
  1. .TH EM_CODE 3 "$Revision$"
  2. .ad
  3. .SH NAME
  4. emcode \- EM code interface for compilers
  5. .SH SYNOPSIS
  6. .nf
  7. .B #include <em.h>
  8. .PP
  9. .B void C_init(wsize, psize)
  10. .B arith wsize, psize;
  11. .PP
  12. .B int C_open(filename)
  13. .B void C_close()
  14. .B int C_busy()
  15. .B char *filename;
  16. .PP
  17. .B void C_magic()
  18. .PP
  19. .B void C_df_dlb(l)
  20. .B void C_df_dnam(s)
  21. .B void C_df_ilb(l)
  22. .B label l; char *s;
  23. .PP
  24. .B void C_pro(s, l)
  25. .B void C_pro_narg(s)
  26. .B void C_end(l)
  27. .B void C_end_narg()
  28. .B char *s; arith l;
  29. .PP
  30. .B void C_exa_dlb(l)
  31. .B void C_exa_dnam(s)
  32. .B void C_exp(s)
  33. .B void C_ina_dlb(l)
  34. .B void C_ina_dnam(s)
  35. .B void C_inp(s)
  36. .B char *s; label l;
  37. .PP
  38. .BI "void C_bss_" cstp ()
  39. .BI "void C_hol_" cstp ()
  40. .BI "void C_con_" cstp ()
  41. .BI "void C_rom_" cstp ()
  42. .PP
  43. .B #include <em_mes.h>
  44. .B void C_mes_begin(ms)
  45. .BI "void C_" cstp ()
  46. .B void C_mes_end()
  47. .B int ms;
  48. .PP
  49. .B void C_exc(c1, c2)
  50. .B arith c1, c2;
  51. .PP
  52. .BI "void C_" mnem ()
  53. .BI "void C_" mnem _dlb()
  54. .BI "void C_" mnem _dnam()
  55. .BI "void C_" mnem _narg()
  56. .PP
  57. .B void C_insertpart(id)
  58. .B int id;
  59. .PP
  60. .B void C_beginpart(id)
  61. .B int id;
  62. .PP
  63. .B void C_endpart(id)
  64. .B int id;
  65. .PP
  66. .B int C_getid()
  67. .PP
  68. .B char *C_tmpdir;
  69. .PP
  70. .B #include <em.h>
  71. .PP
  72. .B int C_out(p)
  73. .B struct e_instr *p;
  74. .PP
  75. .B char *C_error;
  76. .fi
  77. .SH DESCRIPTION
  78. This package provides a procedural EM code interface to be used in
  79. compilers and other EM code producing programs.
  80. The basic idea behind this package is to simplify the program writer's task
  81. of producing EM code in any form, either compact or human-readable
  82. EM assembly code or a sequence of procedure calls.
  83. .PP
  84. The named types
  85. .B arith
  86. and
  87. .B label
  88. refer to types on the local
  89. machine that are suitable for doing arithmetics and storing EM numeric labels
  90. respectively.
  91. Common definitions are
  92. .B long
  93. for
  94. .B arith
  95. and
  96. .B
  97. unsigned int
  98. for
  99. .BR label .
  100. .PP
  101. .B C_init()
  102. should be called to initialize the module.
  103. .I Wsize
  104. is the word size and
  105. .I psize
  106. the pointer size on the target machine.
  107. Checking implementations of this module use these values to check
  108. whether arguments of an instruction are legal.
  109. .PP
  110. .BI C_open( filename )
  111. should be invoked as initialiser for
  112. a sequence of calls that produce EM code on file
  113. .IR filename .
  114. When
  115. .I filename
  116. is a null pointer, the code is produced on standard output.
  117. Some implementations, such as fast back ends, may ignore the parameter.
  118. .B C_close
  119. causes some internal buffers to be flushed and the output file to be closed.
  120. All subsequent routines, except for
  121. .BR C_busy ,
  122. must be invoked between the calls to
  123. .B C_open
  124. and
  125. .BR C_close .
  126. .PP
  127. .B C_busy
  128. can be invoked in order
  129. to detect whether EM code is currently being generated, i.e. whether
  130. .B C_open
  131. is invoked without a corresponding
  132. .BR C_close .
  133. If this is the case,
  134. .B C_busy
  135. returns a 1.
  136. .PP
  137. .B C_magic()
  138. produces the EM magic word.
  139. .PP
  140. Two routines can be used to generate code for the definitions of global data
  141. labels:
  142. .BI C_df_dlb( l )
  143. for numeric labels
  144. .BI . l
  145. and
  146. .BI C_df_dnam( s )
  147. for alphanumeric labels
  148. .IR s .
  149. .PP
  150. .BI C_df_ilb( l )
  151. produces EM code for instruction label
  152. .IR l .
  153. .PP
  154. The routines for producing the EM procedure delimiters are:
  155. .PP
  156. .RS
  157. .TS
  158. box;
  159. l|l.
  160. routine EM pattern
  161. =
  162. \&\fBC_pro(\fP\fIs\fP\fB,\ \fP\fIl\fP\fB)\fP \fBpro\ \fP\fIs\fP\fB,\ \fP\fIl\fP
  163. _
  164. \&\fBC_pro_narg(\fP\fIs\fP\fB)\fP \fBpro\ \fP\fIs\fP\fB,\ ?\fP
  165. _
  166. \&\fBC_end(\fP\fIl\fP\fB)\fP \fBend\ \fP\fIl\fP
  167. _
  168. \&\fBC_end_narg()\fP \fBend\ ?\fP
  169. .TE
  170. .RE
  171. .PP
  172. A set of routines, concerning the scope definition pseudo instructions, is:
  173. .PP
  174. .RS
  175. .TS
  176. box;
  177. l|l.
  178. routine EM pattern
  179. =
  180. \&\fBC_exa_dnam(\fP\fIs\fP\fB)\fP \fBexa \fP\fIs\fP
  181. _
  182. \&\fBC_exa_dlb(\fP\fIl\fP\fB)\fP \fBexa .\fP\fIl\fP
  183. _
  184. \&\fBC_exp(\fP\fIs\fP\fB)\fP \fBexp $\fP\fIs\fP
  185. _
  186. \&\fBC_ina_dnam(\fP\fIs\fP\fB)\fP \fBina \fP\fIs\fP
  187. _
  188. \&\fBC_ina_dlb(\fP\fIl\fP\fB)\fP \fBina .\fP\fIl\fP
  189. _
  190. \&\fBC_inp(\fP\fIs\fP\fB)\fP \fBinp $\fP\fIs\fP
  191. .TE
  192. .RE
  193. .PP
  194. In the set of
  195. .B storage-declaration
  196. pseudo instructions, we can
  197. distinguish four groups, one for each type of storage declaration:
  198. .BR con ,
  199. .BR rom ,
  200. .B bss
  201. and
  202. .BR hol .
  203. .PP
  204. The
  205. .BR con / rom
  206. instructions are generated by
  207. .BI C_con_ cstp
  208. and
  209. .BI C_rom_ cstp ,
  210. respectively.
  211. The type of the initialization value and the number and type of the parameters
  212. are determined by
  213. .I cstp
  214. according to the following table:
  215. .PP
  216. .RS
  217. .TS
  218. box;
  219. l|l|l|l
  220. l|l|l|l
  221. l|n|l|l.
  222. \&\fIcstp\fP number of type of description
  223. parameters parameters
  224. =
  225. \&\fBcst\fP 1 \fBarith\fP word-sized integer of \fBarith\fP-type
  226. _
  227. \&\fBicon\fP 2 \fBchar *\fP integer in string representation
  228. \fBarith\fP number of bytes on target machine
  229. _
  230. \&\fBucon\fP 2 \fBchar *\fP unsigned integer in string representation
  231. \fBarith\fP number of bytes on target machine
  232. _
  233. \&\fBfcon\fP 2 \fBchar *\fP floating in string representation
  234. \fBarith\fP number of bytes on target machine
  235. _
  236. \&\fBscon\fP 2 \fBchar *\fP row of bytes
  237. \fBarith\fP length of the row of bytes
  238. _
  239. \&\fBdnam\fP 2 \fBchar *\fP alphanumeric global data label
  240. \fBarith\fP offset (possibly 0)
  241. _
  242. \&\fBdlb\fP 2 \fBlabel\fP numeric global data label
  243. \fBarith\fP offset (possibly 0)
  244. _
  245. \&\fBilb\fP 1 \fBlabel\fP instruction label
  246. _
  247. \&\fBpnam\fP 1 \fBchar *\fP procedure identifier
  248. .TE
  249. .RE
  250. .PP
  251. As an example of the use of the
  252. .BR con / rom
  253. routines, consider the
  254. following
  255. .B con
  256. instruction:
  257. .RS
  258. con 23I4, "hello world", .12, table + 12, *33
  259. .RE
  260. A sequence of calls to get this, is
  261. .RS
  262. .nf
  263. C_con_icon("23", (arith)4);
  264. C_con_scon("hello world", (arith) 11);
  265. C_con_dlb((label)12, (arith)0);
  266. C_con_dnam("table", (arith)12);
  267. C_con_ilb((label)33);
  268. .fi
  269. .RE
  270. .PP
  271. A
  272. .B bss
  273. or
  274. .B hol
  275. instruction is produced by invoking
  276. .BI C_bss_ cstp
  277. or
  278. .BI C_hol_ cstp
  279. where
  280. .I cstp
  281. indicates the type of value that is used at initialisation.
  282. The parameter list of
  283. .BI C_bss_ cstp
  284. and
  285. .BI C_hol_ cstp
  286. is similar to that of the corresponding
  287. .BI C_con_ cstp,
  288. except that it is preceeded by an
  289. .BR arith -typed
  290. operand
  291. .I nbytes,
  292. and followed by an
  293. .BR int -typed
  294. operand
  295. .IR init ;
  296. .I nbytes
  297. indicates the number of bytes to reserve for the data;
  298. .I init
  299. has value 1 if the initialization is strictly necessary and 0 if not.
  300. Note that, according to the EM definition, an initialisation type of
  301. .B scon
  302. is not allowed in the
  303. .BR bss / hol
  304. instruction.
  305. .PP
  306. Another set of routines is that of the EM
  307. .B mes
  308. pseudo instructions.
  309. As there is an undefined number of messages and each type of message has
  310. its own number of parameters and each parameter its own type,
  311. the user is responsible for building his own message lists.
  312. Such a list consists of a list of
  313. .BI C_ cstp
  314. routine calls enclosed
  315. by
  316. .BI C_mes_begin( ms )
  317. where
  318. .I ms
  319. is the message number,
  320. and
  321. .BR C_mes_end() .
  322. .PP
  323. .I C_exc
  324. produces the EM
  325. .B exc
  326. .IR c1 , c2
  327. instruction.
  328. The use of this function may cause trouble in some implementations of this
  329. module.
  330. A fast back end, for instance, may refuse to implement
  331. .IR C_exc .
  332. The use of this function is therefore not recommended.
  333. .PP
  334. The final class of routines is that of the EM machine-instruction generating
  335. routines
  336. .BI C_ mnem,
  337. .BI C_ mnem _dlb ,
  338. .BI C_ mnem _dnam
  339. and
  340. .BI C_ mnem _narg .
  341. The best way to describe them is according to section 11.3 of [EM].
  342. Depending on the class of the argument (as indicated by a letter), one
  343. or more routines are available for each machine instruction.
  344. The following table gives an overview of the available routines for
  345. the EM machine instruction
  346. .IR mnem :
  347. .PP
  348. .RS
  349. .TS
  350. box;
  351. l|l|l|l
  352. l|l|l|l
  353. l|l|n|l.
  354. class routine(s) number of type of
  355. parameters parameter(s)
  356. =
  357. [\fBcdflnorsz\fP] \fBC_\fP\fImnem\fP 1 \fBarith\fP
  358. _
  359. \&\fBw\fP \fBC_\fP\fImnem\fP 1 \fBarith\fP
  360. \fBC_\fP\fImnem\fP\fB_narg\fP 0
  361. _
  362. \&\fBg\fP \fBC_\fP\fImnem\fP 1 \fBarith\fP
  363. \fBC_\fP\fImnem\fP\fB_dnam\fP 2 \fBchar *\fP
  364. \fBarith\fP
  365. \fBC_\fP\fImnem\fP\fB_dlb\fP 2 \fBlabel\fP
  366. \fBarith\fP
  367. _
  368. \&\fBp\fP \fBC_\fP\fImnem\fP 1 \fBchar *\fP
  369. _
  370. \&\fBb\fP \fBC_\fP\fImnem\fP 1 \fBlabel\fP
  371. _
  372. \&\fB\-\fP \fBC_\fP\fImnem\fP 0
  373. .TE
  374. .RE
  375. .PP
  376. The available routines for, for example, the EM machine instruction
  377. .B adi
  378. (with argument class
  379. .BR w )
  380. are
  381. .BI C_adi( w )
  382. for
  383. .B adi
  384. with a given argument, and
  385. .B C_adi_narg()
  386. for
  387. .B adi
  388. with an argument on top of the stack.
  389. Likewise are the available routines for
  390. .BR loe
  391. (which instruction has argument class
  392. .BR g ):
  393. .BI C_loe( g )
  394. where
  395. .I g
  396. is a constant,
  397. .BI C_loe_dnam( g , o )
  398. where
  399. .I g
  400. is an alphanumeric label, and
  401. .BI C_loe_dlb( g , o )
  402. where
  403. .I g
  404. is a numeric label.
  405. The latter two routines have the (possibly zero) offset
  406. .I o
  407. as second parameter.
  408. .PP
  409. The
  410. .IR C_insertpart ,
  411. .IR C_beginpart ,
  412. and
  413. .I C_endpart
  414. routines together implement a mechanism for re-arranging the generated code.
  415. A call to
  416. .I C_insertpart
  417. indicates that part
  418. .I id
  419. is to be inserted at the current position.
  420. The routines
  421. .I C_beginpart
  422. and
  423. .I C_endpart
  424. indicate begin and end of part
  425. .IR id .
  426. The order in which the parts are defined is not significant.
  427. However, when
  428. .I C_close
  429. is called, all parts that have been inserted, must also be defined.
  430. Parts may themselves again have sub-parts.
  431. .PP
  432. The routine
  433. .I C_getid
  434. can be used to obtain a valid and unique part
  435. .IR id .
  436. .PP
  437. On implementations with limited memory, the mechanism is implemented with a
  438. temporary file.
  439. The directory in which this file resides is indicated by
  440. .IR C_tmpdir .
  441. The default is the #define TMP_DIR from ~em/h/em_path.h.
  442. The user can change this by just changing
  443. .I C_tmpdir
  444. before calling
  445. .IR C_open.
  446. .PP
  447. .I C_out
  448. accepts a structure as delivered by the
  449. .I read_em
  450. module, and produces code for it. It returns 1 if it succeeds, 0 if it fails
  451. for some reason. The reason can then be found in \fIC_error\fP. The
  452. .I C_out
  453. routine replaces the EM_mkcalls routine.
  454. .SH FILES
  455. .nf
  456. ~em/modules/h/em.h
  457. ~em/modules/lib/libemk.a: library for generating compact EM code
  458. ~em/modules/lib/libeme.a: library for generating human-readable EM code
  459. ~em/lib.bin/em_data.a: library needed when using libeme.a
  460. .fi
  461. .SH MODULES
  462. .nf
  463. libemk.a: alloc(3), system(3), string(3)
  464. libeme.a: alloc(3), print(3), system(3), string(3)
  465. .fi
  466. .SH SEE ALSO
  467. read_em(3), em_mes(3)
  468. .SH REFERENCES
  469. .IP [EM] 6
  470. Andrew S. Tanenbaum, Hans van Staveren, Ed G. Keizer, Johan W. Stevenson,
  471. .B
  472. "Description of a Machine Architecture for use with Block Structured Languages",
  473. Informatica Rapport IR-81, Vrije Universiteit, Amsterdam, 1983.
  474. .LP
  475. .SH DIAGNOSTICS
  476. .I C_open
  477. returns 1 if the open is successful and 0 if not.
  478. .PP
  479. When a read, write or open fails, the routine
  480. .I C_failed
  481. is called. The user can override its default definition by supplying his
  482. own. The default just gives an error message and quits.
  483. .PP
  484. When an error occurs with the
  485. .I C_insertpart
  486. mechanism, the routine
  487. .I C_internal_error
  488. is called. Again, the user can override its default definition by supplying his
  489. own. Such errors, however, are caused by a programming error of the user.
  490. .SH REMARKS
  491. Some of the routines in this module may be implemented as macros. So,
  492. do not try to take the address of these functions.
  493. .SH BUGS
  494. It is not possible to indicate that the argument of
  495. .B C_con_cst ()
  496. must be seen as an unsigned value.