iotrap.nr 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376
  1. .SN 8
  2. .VS 1 0
  3. .BP
  4. .S1 "ENVIRONMENT INTERACTIONS"
  5. EM programs can interact with their environment in three ways.
  6. Two, starting/stopping and monitor calls, are dealt with in this chapter.
  7. The remaining way to interact, interrupts, will be treated
  8. together with traps in chapter 9.
  9. .S2 "Program starting and stopping"
  10. EM user programs start with a call to a procedure called
  11. m_a_i_n.
  12. The assembler and backends look for the definition of a procedure
  13. with this name in their input.
  14. The call passes three parameters to the procedure.
  15. The parameters are similar to the parameters supplied by the
  16. UNIX
  17. .FS
  18. UNIX is a Trademark of Bell Laboratories.
  19. .FE
  20. operating system to C programs.
  21. These parameters are often called
  22. .BW argc ,
  23. .B argv
  24. and
  25. .BW envp .
  26. Argc is the parameter nearest to LB and is a wordsized integer.
  27. The other two are pointers to the first element of an array of
  28. string pointers.
  29. .N
  30. The
  31. .B argv
  32. array contains
  33. .B argc
  34. strings, the first of which contains the program call name.
  35. The other strings in the
  36. .B argv
  37. array are the program parameters.
  38. .P
  39. The
  40. .B envp
  41. array contains strings in the form "name=string", where 'name'
  42. is the name of an environment variable and string its value.
  43. The
  44. .B envp
  45. is terminated by a zero pointer.
  46. .P
  47. An EM user program stops if the program returns from the first
  48. invocation of m_a_i_n.
  49. The contents of the function return area are used to procure a
  50. wordsized program return code.
  51. EM programs also stop when traps and interrupts occur that are
  52. not caught and when the exit monitor call is executed.
  53. .S2 "Input/Output and other monitor calls"
  54. EM differs from most conventional machines in that it has high level i/o
  55. instructions.
  56. Typical instructions are OPEN FILE and READ FROM FILE instead
  57. of low level instructions such as setting and clearing
  58. bits in device registers.
  59. By providing such high level i/o primitives, the task of implementing
  60. EM on various non EM machines is made considerably easier.
  61. .P
  62. I/O is initiated by the MON instruction, which expects an iocode on top
  63. of the stack.
  64. Often there are also parameters which are pushed on the
  65. stack in reverse order, that is: last
  66. parameter first.
  67. Some i/o functions also provide results, which are returned on the stack.
  68. In the list of monitor calls we use several types of parameters and results,
  69. these types consist of integers and unsigneds of varying sizes, but never
  70. smaller than the wordsize, and the two pointer types.
  71. .N 1
  72. The names of the types used are:
  73. .IS 4
  74. .PS - 10
  75. .PT int
  76. an integer of wordsize
  77. .PT int2
  78. an integer whose size is the maximum of the wordsize and 2
  79. bytes
  80. .PT int4
  81. an integer whose size is the maximum of the wordsize and 4
  82. bytes
  83. .PT intp
  84. an integer with the size of a pointer
  85. .PT uns2
  86. an unsigned integer whose size is the maximum of the wordsize and 2
  87. .PT unsp
  88. an unsigned integer with the size of a pointer
  89. .PT ptr
  90. a pointer into data space
  91. .PE 1
  92. .IE 0
  93. The table below lists the i/o codes with their results and
  94. parameters.
  95. This list is similar to the system calls of the UNIX Version 7
  96. operating system.
  97. .BP
  98. .A
  99. To execute a monitor call, proceed as follows:
  100. .IS 2
  101. .N 1
  102. .PS a 4 "" )
  103. .PT
  104. Stack the parameters, in reverse order, last parameter first.
  105. .PT
  106. Push the monitor call number (iocode) onto the stack.
  107. .PT
  108. Execute the MON instruction.
  109. .PE 1
  110. .IE
  111. An error code is present on the top of the stack after
  112. execution of most monitor calls.
  113. If this error code is zero, the call performed the action
  114. requested and the results are available on top of the stack.
  115. Non-zero error codes indicate a failure, in this case no
  116. results are available and the error code has been pushed twice.
  117. This construction enables programs to test for failure with a
  118. single instruction (~TEQ or TNE~) and still find out the cause of
  119. the failure.
  120. The result name 'e' is reserved for the error code.
  121. .N 1
  122. List of monitor calls.
  123. .DS B
  124. number name parameters results function
  125. 1 Exit status:int Terminate this process
  126. 2 Fork e,flag,pid:int Spawn new process
  127. 3 Read fildes:int;buf:ptr;nbytes:unsp
  128. e:int;rbytes:unsp Read from file
  129. 4 Write fildes:int;buf:ptr;nbytes:unsp
  130. e:int;wbytes:unsp Write on a file
  131. 5 Open string:ptr;flag:int
  132. e,fildes:int Open file for read and/or write
  133. 6 Close fildes:int e:int Close a file
  134. 7 Wait e:int;status,pid:int2
  135. Wait for child
  136. 8 Creat string:ptr;mode:int
  137. e,fildes:int Create a new file
  138. 9 Link string1,string2:ptr
  139. e:int Link to a file
  140. 10 Unlink string:ptr e:int Remove directory entry
  141. 12 Chdir string:ptr e:int Change default directory
  142. 14 Mknod string:ptr;mode,addr:int2
  143. e:int Make a special file
  144. 15 Chmod string:ptr;mode:int2
  145. e:int Change mode of file
  146. 16 Chown string:ptr;owner,group:int2
  147. e:int Change owner/group of a file
  148. 18 Stat string,statbuf:ptr
  149. e:int Get file status
  150. 19 Lseek fildes:int;off:int4;whence:int
  151. e:int;oldoff:int4 Move read/write pointer
  152. 20 Getpid pid:int2 Get process identification
  153. 21 Mount special,string:ptr;rwflag:int
  154. e:int Mount file system
  155. 22 Umount special:ptr e:int Unmount file system
  156. 23 Setuid userid:int2 e:int Set user ID
  157. 24 Getuid e_uid,r_uid:int2 Get user ID
  158. 25 Stime time:int4 e:int Set time and date
  159. 26 Ptrace request:int;pid:int2;addr:ptr;data:int
  160. e,value:int Process trace
  161. 27 Alarm seconds:uns2 previous:uns2 Schedule signal
  162. 28 Fstat fildes:int;statbuf:ptr
  163. e:int Get file status
  164. 29 Pause Stop until signal
  165. 30 Utime string,timep:ptr
  166. e:int Set file times
  167. 33 Access string,mode:int e:int Determine file accessibility
  168. 34 Nice incr:int Set program priority
  169. 35 Ftime bufp:ptr e:int Get date and time
  170. 36 Sync Update filesystem
  171. 37 Kill pid:int2;sig:int
  172. e:int Send signal to a process
  173. 41 Dup fildes,newfildes:int
  174. e,fildes:int Duplicate a file descriptor
  175. 42 Pipe e,w_des,r_des:int Create a pipe
  176. 43 Times buffer:ptr Get process times
  177. 44 Profil buff:ptr;bufsiz,offset,scale:intp Execution time profile
  178. 46 Setgid gid:int2 e:int Set group ID
  179. 47 Getgid e_gid,r_gid:int Get group ID
  180. 48 Sigtrp trapno,signo:int
  181. e,prevtrap:int See below
  182. 51 Acct file:ptr e:int Turn accounting on or off
  183. 53 Lock flag:int e:int Lock a process
  184. 54 Ioctl fildes,request:int;argp:ptr
  185. e:int Control device
  186. 56 Mpxcall cmd:int;vec:ptr e:int Multiplexed file handling
  187. 59 Exece name,argv,envp:ptr
  188. e:int Execute a file
  189. 60 Umask complmode:int2 oldmask:int2 Set file creation mode mask
  190. 61 Chroot string:ptr e:int Change root directory
  191. .DE 1
  192. Codes 0, 11, 13, 17, 31, 32, 38, 39, 40, 45, 49, 50, 52,
  193. 55, 57, 58, 62, and 63 are
  194. not used.
  195. .P
  196. All monitor calls, except fork and sigtrp
  197. are the same as the UNIX version 7 system calls.
  198. .P
  199. The sigtrp entry maps UNIX signals onto EM interrupts.
  200. Normally, trapno is in the range 0 to 252.
  201. In that case it requests that signal signo
  202. will cause trap trapno to occur.
  203. When given trap number -2, default signal handling is reset, and when given
  204. trap number -3, the signal is ignored.
  205. .P
  206. The flag returned by fork is 1 in the child process and 0 in
  207. the parent.
  208. The pid returned is the process-id of the other process.
  209. .BP
  210. .S1 "TRAPS AND INTERRUPTS"
  211. EM provides a means for the user program to catch all traps
  212. generated by the program itself, the hardware, or external conditions.
  213. This mechanism uses five instructions: LIM, SIM, SIG, TRP and RTT.
  214. This section of the manual may be omitted on the first reading since it
  215. presupposes knowledge of the EM instruction set.
  216. .P
  217. The action taken when a trap occures is determined by the value
  218. of an internal EM trap register.
  219. This register contains a pointer to a procedure.
  220. Initially the pointer used is zero and all traps halt the
  221. program with, hopefully, a useful message to the outside world.
  222. The SIG instruction can be used to alter the trap register,
  223. it pops a procedure pointer from the
  224. stack into the trap register.
  225. When a trap occurs after storing a nonzero value in the trap
  226. register, the procedure pointed to by the trap register
  227. is called with the trap number
  228. as the only parameter (see below).
  229. SIG returns the previous value of the trap register on the
  230. stack.
  231. Two consecutive SIGs are a no-op.
  232. When a trap occurs, the trap register is reset to its initial
  233. condition, to prevent recursive traps from hanging the machine up,
  234. e.g. stack overflow in the stack overflow handling procedure.
  235. .P
  236. The runtime systems for some languages need to ignore some EM
  237. traps.
  238. EM offers a feature called the ignore mask.
  239. It contains one bit for each of the lowest 16 trap numbers.
  240. The bits are numbered 0 to 15, with the least significant bit
  241. having number 0.
  242. If a certain bit is 1 the corresponding trap never
  243. occurs and processing simply continues.
  244. The actions performed by the offending instruction are
  245. described by the Pascal program in appendix A.
  246. .N
  247. If the bit is 0, traps are not ignored.
  248. The instructions LIM and SIM allow copying and replacement of
  249. the ignore mask.~
  250. .P
  251. The TRP instruction generates a trap, the trap number being found on the
  252. stack.
  253. This is, among other things,
  254. useful for library procedures and runtime systems.
  255. It can also be used by a low level trap procedure to pass the trap to a
  256. higher level one (see example below).
  257. .P
  258. The RTT instruction returns from the trap procedure and continues after the
  259. trap.
  260. In the list below all traps marked with an asterisk ('*') are
  261. considered to be fatal and it is explicitly undefined what happens if
  262. you try to restart after the trap.
  263. .P
  264. The way a trap procedure is called is completely compatible
  265. with normal calling conventions. The only way a trap procedure
  266. differs from normal procedures is the return. It has to use RTT instead
  267. of RET. This is necessary because the complete runtime status is saved on the
  268. stack before calling the procedure and all this status has to be reloaded.
  269. Error numbers are in the range 0 to 252.
  270. The trap numbers are divided into three categories:
  271. .IS 4
  272. .N 1
  273. .PS - 10
  274. .PT ~~0-~63
  275. EM machine errors, e.g. illegal instruction.
  276. .PS - 8
  277. .PT ~0-15
  278. maskable
  279. .PT 16-63
  280. not maskable
  281. .PE
  282. .PT ~64-127
  283. Reserved for use by compilers, run time systems, etc.
  284. .PT 128-252
  285. Available for user programs.
  286. .PE 1
  287. .IE
  288. EM machine errors are numbered as follows:
  289. .DS I 5
  290. .TS
  291. tab(@);
  292. n l l.
  293. 0@EARRAY@Array bound error
  294. 1@ERANGE@Range bound error
  295. 2@ESET@Set bound error
  296. 3@EIOVFL@Integer overflow
  297. 4@EFOVFL@Floating overflow
  298. 5@EFUNFL@Floating underflow
  299. 6@EIDIVZ@Divide by 0
  300. 7@EFDIVZ@Divide by 0.0
  301. 8@EIUND@Undefined integer
  302. 9@EFUND@Undefined float
  303. 10@ECONV@Conversion error
  304. 16*@ESTACK@Stack overflow
  305. 17*@EHEAP@Heap overflow
  306. 18*@EILLINS@Illegal instruction
  307. 19*@EODDZ@Illegal size argument
  308. 20*@ECASE@Case error
  309. 21*@EMEMFLT@Addressing non existent memory
  310. 22*@EBADPTR@Bad pointer used
  311. 23*@EBADPC@Program counter out of range
  312. 24@EBADLAE@Bad argument of LAE
  313. 25@EBADMON@Bad monitor call
  314. 26@EBADLIN@Argument of LIN too high
  315. 27@EBADGTO@GTO descriptor error
  316. .TE
  317. .DE 0
  318. .P
  319. As an example,
  320. suppose a subprocedure has to be written to do a numeric
  321. calculation.
  322. When an overflow occurs the computation has to be stopped and
  323. the higher level procedure must be resumed.
  324. This can be programmed as follows using the mechanism described above:
  325. .DS B
  326. mes 2,2,2 ; set sizes
  327. ersave
  328. bss 2,0,0 ; Room to save previous value of trap procedure
  329. msave
  330. bss 2,0,0 ; Room to save previous value of trap mask
  331. pro calcule,0 ; entry point
  332. lxl 0 ; fill in non-local goto descriptor with LB
  333. ste jmpbuf+4
  334. lor 1 ; and SP
  335. ste jmpbuf+2
  336. lim ; get current ignore mask
  337. ste msave ; save it
  338. lim
  339. loc 16 ; bit for EFOVFL
  340. ior 2 ; set in mask
  341. sim ; ignore EFOVFL from now on
  342. lpi $catch ; load procedure identifier
  343. sig ; catch wil get all traps now
  344. ste ersave ; save previous trap procedure identifier
  345. ; perform calculation now, possibly generating overflow
  346. 1 ; label jumped to by catch procedure
  347. loe ersave ; get old trap procedure
  348. sig ; refer all following trap to old procedure
  349. asp 2 ; remove result of sig
  350. loe msave ; restore previous mask
  351. sim ; done now
  352. ; load result of calculation
  353. ret 2 ; return result
  354. jmpbuf
  355. con *1,0,0
  356. end
  357. .DE 0
  358. .VS 1 1
  359. .DS
  360. Example of catch procedure
  361. pro catch,0 ; Local procedure that must catch the overflow trap
  362. lol 2 ; Load trap number
  363. loc 4 ; check for overflow
  364. bne *1 ; if other trap, call higher trap procedure
  365. gto jmpbuf ; return to procedure calcule
  366. 1 ; other trap has occurred
  367. loe ersave ; previous trap procedure
  368. sig ; other procedure will get the traps now
  369. asp 2 ; remove the result of sig
  370. lol 2 ; stack trap number
  371. trp ; call other trap procedure
  372. rtt ; if other procedure returns, do the same
  373. end
  374. .DE