Mercurial > hg > Members > kono > nitros9-code
changeset 1085:a1464c5aedcb
Added cross references
| author | roug |
|---|---|
| date | Thu, 03 Apr 2003 19:25:16 +0000 |
| parents | 01e088e15051 |
| children | 8391bf11ab31 |
| files | docs/os9sysprog/errorcodes.appendix docs/os9sysprog/os9sysprog.docbook |
| diffstat | 2 files changed, 620 insertions(+), 565 deletions(-) [+] |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/os9sysprog/errorcodes.appendix Thu Apr 03 19:25:16 2003 +0000 @@ -0,0 +1,329 @@ +<appendix> +<title>Error Codes</title> +<section> +<title>OS-9 Error Codes</title> + +<para>The error codes are shown both in hexadecimal (first column) and +decimal (second column). Error codes other than those listed are +generated by programming languages or user programs.</para> + +<informaltable frame="none"> +<tgroup cols="3"> +<colspec colwidth="0.6in"/> +<colspec colwidth="0.6in"/> +<colspec colwidth="3.8in"/> +<thead> +<row> +<entry rowsep="1">HEX</entry> +<entry rowsep="1">DEC</entry> +<entry rowsep="0"></entry> +</row> +</thead> +<tbody> +<row> + <entry>$C8</entry> + <entry>200</entry> + <entry><errorname>PATH TABLE FULL</errorname> + - The file cannot be opened because + the system path table is currently full.</entry></row> +<row> + <entry>$C9</entry> + <entry>201</entry> + <entry><errorname>ILLEGAL PATH NUMBER</errorname> + - Number too large or for non-existant path.</entry></row> +<row> + <entry>$CA</entry> + <entry>202</entry> + <entry><errorname>INTERRUPT POLLING TABLE FULL</errorname></entry></row> +<row> + <entry>$CB</entry> + <entry>203</entry> + <entry><errorname>ILLEGAL MODE</errorname> + - attempt to perform I/O function of which the device or file is incapable.</entry></row> +<row> + <entry>$CC</entry> + <entry>204</entry> + <entry><errorname>DEVICE TABLE FULL</errorname> + - Can't add another device</entry></row> +<row> + <entry>$CD</entry> + <entry>205</entry> + <entry><errorname>ILLEGAL MODULE HEADER</errorname> + - module not loaded because its + sync code, header parity, or CRC is incorrect.</entry></row> +<row> + <entry>$CE</entry> + <entry>206</entry> + <entry><errorname>MODULE DIRECTORY FULL</errorname> + - Can't add another module</entry></row> +<row> + <entry>$CF</entry> + <entry>207</entry> + <entry><errorname>MEMORY FULL</errorname> + - Level One: not enough contiquous RAM free. + Level Two: process address space full</entry></row> +<row> + <entry>$D0</entry> + <entry>208</entry> + <entry><errorname>ILLEGAL SERVICE REQUEST</errorname> + - System call had an illegal code number</entry></row> +<row> + <entry>$D1</entry> + <entry>209</entry> + <entry><errorname>MODULE BUSY</errorname> + - non-sharable module is in use by another process.</entry></row> +<row> + <entry>$D2</entry> + <entry>210</entry> + <entry><errorname>BOUNDARY ERROR</errorname> + - Memory allocation or deallocation request not on a page boundary.</entry></row> +<row> + <entry>$D3</entry> + <entry>211</entry> + <entry><errorname>END OF FILE</errorname> + - End of file encountered on read.</entry></row> +<row> + <entry>$D4</entry> + <entry>212</entry> + <entry><errorname>RETURNING NON-ALLOCATED MEMORY</errorname> + - (NOT YOUR MEMORY) + attempted to deallocate memory not previously assigned.</entry></row> +<row> + <entry>$D5</entry> + <entry>213</entry> + <entry><errorname>NON-EXISTING SEGMENT</errorname> + - device has damaged file structure.</entry></row> +<row> + <entry>$D6</entry> + <entry>214</entry> + <entry><errorname>NO PERMISSION</errorname> + - file attributes do not permit access requested.</entry></row> +<row> + <entry>$D7</entry> + <entry>215</entry> + <entry><errorname>BAD PATH NAME</errorname> + - syntax error in pathlist (illegal character, etc.).</entry></row> +<row> + <entry>$D8</entry> + <entry>216</entry> + <entry><errorname>PATH NAME NOT FOUND</errorname> + - can't find pathlist specified.</entry></row> +<row> + <entry>$D9</entry> + <entry>217</entry> + <entry><errorname>SEGMENT LIST FULL</errorname> + - file is too fragmented to be expanded further.</entry></row> +<row> + <entry>$DA</entry> + <entry>218</entry> + <entry><errorname>FILE ALREADY EXISTS</errorname> + - file name already appears in current directory.</entry></row> +<row> + <entry>$DB</entry> + <entry>219</entry> + <entry><errorname>ILLEGAL BLOCK ADDRESS</errorname> + - device's file structure has been damaged.</entry></row> +<row> + <entry>$DC</entry> + <entry>220</entry> + <entry><errorname>ILLEGAL BLOCK SIZE</errorname> + - device's file structure has been damaged.</entry></row> +<row> + <entry>$DD</entry> + <entry>221</entry> + <entry><errorname>MODULE NOT FOUND</errorname> + - request for link to module not found in directory.</entry></row> + <row> + <entry>$DE</entry> + <entry>222</entry> + <entry><errorname>SECTOR OUT OF RANGE</errorname> + - device file structure damaged or +incorrectly formatted.</entry></row> +<row> + <entry>$DF</entry> + <entry>223</entry> + <entry><errorname>SUICIDE ATTEMPT</errorname> + - request to return memory where your stack is located.</entry></row> +<row> + <entry>$E0</entry> + <entry>224</entry> + <entry><errorname>ILLEGAL PROCESS NUMBER</errorname> + - no such process exists.</entry></row> +<row> + <entry>$E2</entry> + <entry>226</entry> + <entry><errorname>NO CHILDREN</errorname> + - can't wait because process has no children.</entry></row> +<row> + <entry>$E3</entry> + <entry>227</entry> + <entry><errorname>ILLEGAL SWI CODE</errorname> + - must be 1 to 3.</entry></row> +<row> + <entry>$E4</entry> + <entry>228</entry> + <entry><errorname>PROCESS ABORTED</errorname> + - process aborted by signal code 2.</entry></row> +<row> + <entry>$E5</entry> + <entry>229</entry> + <entry><errorname>PROCESS TABLE FULL</errorname> + - can't fork now.</entry></row> +<row> + <entry>$E6</entry> + <entry>230</entry> + <entry><errorname>ILLEGAL PARAMETER AREA</errorname> + - high and low bounds passed in fork call are incorrect.</entry></row> +<row> + <entry>$E7</entry> + <entry>231</entry> + <entry><errorname>KNOWN MODULE</errorname> + - for internal use only.</entry></row> +<row> + <entry>$E8</entry> + <entry>232</entry> + <entry><errorname>INCORRECT MODULE CRC</errorname> + - module has bad CRC value.</entry></row> +<row> + <entry>$E9</entry> + <entry>233</entry> + <entry><errorname>SIGNAL ERROR</errorname> + - receiving process has previous + unprocessed signal pending.</entry></row> +<row> + <entry>$EA</entry> + <entry>234</entry> + <entry><errorname>NON-EXISTENT MODULE</errorname> + - unable to locate module.</entry></row> +<row> + <entry>$EB</entry> + <entry>235</entry> + <entry><errorname>BAD NAME</errorname> + - illegal name syntax.</entry></row> +<row> + <entry>$EC</entry> + <entry>236</entry> + <entry><errorname>BAD HEADER</errorname> + - module header parity incorrect</entry></row> +<row> + <entry>$ED</entry> + <entry>237</entry> + <entry><errorname>RAM FULL</errorname> + - no free system RAM available at this time</entry></row> +<row> + <entry>$EE</entry> + <entry>238</entry> + <entry><errorname>UNKNOWN PROCESS ID</errorname> + - incorrect process ID number</entry></row> +<row> + <entry>$EF</entry> + <entry>239</entry> + <entry><errorname>NO TASK NUMBER AVAILABLE</errorname> + - all task numbers in use</entry></row> +</tbody> +</tgroup> +</informaltable> +</section> + +<section> +<title>Device Driver/Hardware Errors</title> + +<para>The following error codes are generated by I/O device drivers, and +are somewhat hardware dependent. Consult manufacturer's hardware +manual for more details.</para> + +<informaltable frame="none"> +<tgroup cols="3"> +<colspec colwidth="0.6in"/> +<colspec colwidth="0.6in"/> +<colspec colwidth="3.8in"/> +<thead> +<row> +<entry rowsep="1">HEX</entry> +<entry rowsep="1">DEC</entry> +<entry rowsep="0"></entry> +</row> +</thead> +<tbody> +<row> + <entry>$F0</entry> + <entry>240</entry> + <entry><errorname>UNIT ERROR</errorname> + - device unit does not exist</entry></row> +<row> + <entry>$F1</entry> + <entry>241</entry> + <entry><errorname>SECTOR ERROR</errorname> + - sector number is out of range.</entry></row> +<row> + <entry>$F2</entry> + <entry>242</entry> + <entry><errorname>WRITE PROTECT</errorname> + - device is write protected.</entry></row> +<row> + <entry>$F3</entry> + <entry>243</entry> + <entry><errorname>CRC ERROR</errorname> + - CRC error on read or write verify</entry></row> +<row> + <entry>$F4</entry> + <entry>244</entry> + <entry><errorname>READ ERROR</errorname> + - Data transfer error during disk read + operation, or SCF (terminal) input buffer overrun.</entry></row> +<row> + <entry>$F5</entry> + <entry>245</entry> + <entry><errorname>WRITE ERROR</errorname> + - hardware error during disk write operation.</entry></row> +<row> + <entry>$F6</entry> + <entry>246</entry> + <entry><errorname>NOT READY</errorname> + - device has "not ready" status.</entry></row> +<row> + <entry>$F7</entry> + <entry>247</entry> + <entry><errorname>SEEK ERROR</errorname> + - physical seek to non-existant sector.</entry></row> +<row> + <entry>$F8</entry> + <entry>248</entry> + <entry><errorname>MEDIA FULL</errorname> + - insufficient free space on media.</entry></row> +<row> + <entry>$F9</entry> + <entry>249</entry> + <entry><errorname>WRONG TYPE</errorname> + - attempt to read incompatible media (i.e. + attempt to read double-side disk on single-side drive)</entry></row> +<row> + <entry>$FA</entry> + <entry>250</entry> + <entry><errorname>DEVICE BUSY</errorname> + - non-sharable device is in use</entry></row> +<row> + <entry>$FB</entry> + <entry>251</entry> + <entry><errorname>DISK ID CHANGE</errorname> + - Media was changed with files open</entry></row> +<row> + <entry>$FC</entry> + <entry>252</entry> + <entry><errorname>RECORD IS LOCKED-OUT</errorname> + - Another process is accessing the requested record.</entry></row> +<row> + <entry>$FD</entry> + <entry>253</entry> + <entry><errorname>NON-SHARABLE FILE BUSY</errorname> + - Another process is accessing the requested file.</entry></row> +<row> + <entry>$FE</entry> + <entry>254</entry> + <entry><errorname>I/O DEADLOCK ERROR</errorname> + - Two processes are attempting to use the same two disk areas simultaneously.</entry></row> +</tbody> +</tgroup> +</informaltable> +</section> +</appendix>
--- a/docs/os9sysprog/os9sysprog.docbook Wed Apr 02 14:48:58 2003 +0000 +++ b/docs/os9sysprog/os9sysprog.docbook Thu Apr 03 19:25:16 2003 +0000 @@ -1,6 +1,8 @@ <?xml version="1.0" ?> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ + <!ENTITY errorcodesapp SYSTEM "errorcodes.appendix"> + ]> <!-- $Id$ --> <book id="os9sysprog" lang="en"> <bookinfo> @@ -274,7 +276,7 @@ for each specific type of I/O controller regardless of how many controllers the system uses.</para> -<para>One important component not shown is the Shell., which is the +<para>One important component not shown is the <command>shell</command>, which is the command interpreter. It is technically a program and not part of the operating system itself, and is described fully in the OS-9 Users Manual.</para> @@ -329,7 +331,7 @@ other service request functions including interprocess control and timekeeping.</para> -<para>A system-wide assembly languaqe equate file called "OS9Defs" defines +<para>A system-wide assembly languaqe equate file called <filename>OS9Defs</filename> defines symbolic names for all service requests. This file is included when assembling hand-written or compiler-generated code. The OS-9 Assembler has a built-in macro to generate system calls, for example:</para> @@ -353,7 +355,7 @@ <para>I/O REQUESTS perform various input/output functions. Requests of this type are passed by the kernel to IOMAN for processing. The symbolic names for this category have a "I$" prefix, for example, -the "read" service request is called "I$Read".</para> +the "read" service request is called <xref linkend="i.read"/>.</para> <para>FUNCTION REQUESTS perform memory management, multiprogramming, and miscellaneous functions. Most are processed by the kernel. The @@ -491,7 +493,8 @@ <sect1> <title>Process Creation</title> -<para>New processes are created when an existing process executes a "fork" +<para>New processes are created when an existing process executes a +<xref linkend="f.fork"/> service request. Its main argument is the name of the program module (called the "primary module") that the new process is to initially execute. OS-9 first attempts to find the module in the @@ -510,13 +513,15 @@ <para>The next step in the creation of a new process is allocation of data storage (RAM) memory for the process. The primary module's -header contains a storage size value that is used unless the "fork" +header contains a storage size value that is used unless the +<xref linkend="f.fork"/> system call requested an optionally larger size. OS-9 then attempts to allocate a CONTIGUOUS memory area of this size from the free memory space.</para> <para>If any of the previous steps cannot be performed, creation of the -new process is aborted, and the process that originated the "fork" +new process is aborted, and the process that originated the +<xref linkend="f.fork"/> is informed of the error. Otherwise, the new process is added to the active process queue for execution scheduling.</para> @@ -527,7 +532,7 @@ is used to identify all processes and files belonging to a particular user. The user ID is inherited from the parent process.</para> -<para>Processes terminate when they execute an "EXIT" system service +<para>Processes terminate when they execute an <xref linkend="f.exit"/> system service request, or when they receive fatal signals. The process termination closes any open paths, deallocates its memory, and unlinks its primary module.</para> @@ -567,7 +572,7 @@ <sect2> <title>The Wait State</title> -<para>This state is entered when a process executes a WAIT system +<para>This state is entered when a process executes a <xref linkend="f.wait"/> system service request. The process remains suspended until the death of any of its descendant processes, or, until it receives a signal.</para> </sect2> @@ -575,7 +580,7 @@ <sect2> <title>The Sleeping State</title> -<para>This state is entered when a process executes a SLEEP service +<para>This state is entered when a process executes a <xref linkend="f.sleep"/> service request, which specifies a time interval. (a specific number of ticks) for which the process is to remain suspended. The process remains asleep until the specified time has elapsed, or until a @@ -655,13 +660,13 @@ <para>What happens next depends on whether or not the process had previously set up a "signal trap" (signal service routine) by -executing an INTERCEPT service request. If it had not, the process is +executing an <xref linkend="f.icpt"/> service request. If it had not, the process is immediately aborted. It is also aborted if the signal code is zero. The abort will be deferred if the process is in system mode: the process dies upon its return to user state.</para> <para>If a signal intercept trap has been set up, the process resumes -execution at the address given in the INTERCEPT service request. The +execution at the address given in the <xref linkend="f.icpt"/> service request. The signal code is passed to this routine, which should terminate with an RTI instruction to resume normal execution of the process.</para> @@ -745,7 +750,7 @@ specific service routine in the kernel. The SWI, SWI2, and SWI3 vectors point to specific routines which in turn read the corresponding pseudo vector from the process' process descriptor and -dispatch to it. This is why the F$SSWI service request to be local to +dispatch to it. This is why the <xref linkend="f.sswi"/> service request to be local to a process since it only changes a pseudo vector in the process descriptor. The IRQ routine points directly to the IRQ polling system, or to it indirectly via the real-time clock device service @@ -917,17 +922,19 @@ <para>The device's static storage address and service routine address is read from the table and executed.</para> -<para>--> NOTE: The interrupt service routine should terminate with -an an <emphasis>RTS</emphasis>, not an RTI instruction.</para> +<note> +<para>The interrupt service routine should terminate with +an an <emphasis>RTS</emphasis>, not an RTI instruction.</para></note> <para>Entries can be made to the IRQ polling table by use of a special -OS-9 service request called "F$IRQ". This is a priviledged +OS-9 service request called <xref linkend="f.irq"/>. This is a priviledged service request that can be executed only when OS-9 is in System Mode (which is the case when device drivers are executed).</para> -<para>--> NOTE: The actual code for the interrupt polling system is +<note> +<para>The actual code for the interrupt polling system is located in the IOMAN module. The kernel P1 and P2 modules contain -the physical interrupt processing routines.</para> +the physical interrupt processing routines.</para></note> </sect2> </sect1> </chapter> @@ -1147,8 +1154,10 @@ <entry>$B,$C =</entry> <entry><para>Permanent Storage Requirement. This is the minimum number of bytes of data storage required to run. This is the number used by - FORK and CHAIN to allocate a process' data area.</para><para> - If the module will not be directly executed by a CHAIN or FORK + <xref linkend="f.fork"/> and <xref linkend="f.chain"/> + to allocate a process' data area.</para><para> + If the module will not be directly executed by a <xref linkend="f.chain"/> + or <xref linkend="f.fork"/> service request (for instance a subroutine package), this entry is not used by OS-9. It is commonly used to specify the maximum stack size required by reentrant subroutine modules. The calling @@ -1310,7 +1319,7 @@ having the device name given (or implied) in the pathlist. This module is the device's descriptor, which contains the names of the device driver and file manager for the device. This information is -saved by IOMAN so subsequent system call can be routed to these +saved by IOMAN so subsequent system calls can be routed to these modules.</para> </sect1> @@ -1435,7 +1444,8 @@ <para>The initialization table is copied into the "option section" of the path descriptor when a path to the device is opened. The values in this table may be used to define the operating parameters -that are changeable by the OS9 I$GetStt and I$SetStt service requests. +that are changeable by the OS9 <xref linkend="i.getstt"/> +and <xref linkend="i.setstt"/> service requests. For example, a terminal's initialization parameters define which control characters are used for backspace, delete, etc. The maximum size of initialization table which may be used is 32 bytes. If the @@ -1588,10 +1598,12 @@ parameters for the file or device. These variables are initialized at the time the path is opened by copying the initialization table contained in the device descriptor module, and can be altered later -by user programs by means of the GETSTAT and SETSTAT system calls.</para> +by user programs by means of the <xref linkend="i.getstt"/> +and <xref linkend="i.setstt"/> system calls.</para> <para>These two sections are defined each file manager's in the assembly -language equate file (SCFDefs for SCFMAN and RBFDefs for RBFMAN).</para> +language equate file (<filename>SCFDefs</filename> for SCFMAN and +<filename>RBFDefs</filename> for RBFMAN).</para> </sect1> </chapter> @@ -1652,7 +1664,7 @@ <para>Logical sector number zero contains a description of the physical and logical characteristics of the volume. These are established by -the "format" command program when the media is initialized, the +the <command>format</command> command program when the media is initialized, the table below gives the OS-9 mnemonic name, byte address, size, and description of each value stored in this sector. </para> @@ -1772,7 +1784,7 @@ </informaltable> </sect2> -<sect2> +<sect2 id="lsn1"> <title>Disk Allocation Map Sector</title> <para>One sector (usually LSN 1) of the disk is used for the "disk @@ -1791,7 +1803,7 @@ Each bit is cleared if the corresponding cluster is available for allocation, or set if the sector is already allocated, non-existent, or physically defective. The bitmap is initially created by the -"format" utility program.</para> +<command>format</command> utility program.</para> </sect2> <sect2> @@ -1887,7 +1899,7 @@ each of which can bold the name and LSN of a single regular or directory file.</para> -<para>Each directory entry is 32 b,ytes long, consisting of 29 bytes for +<para>Each directory entry is 32 bytes long, consisting of 29 bytes for the file name followed by a three byte logical sector number of the file's descriptor sector. The file name is left-justified in the field with the sign bit of the last character set. Unused entries @@ -2019,7 +2031,7 @@ <entry>Address of drive table</entry> </row> <row> - <entry spanname="all">RBFMAN Option Section Definitions (Copied from dev descriptor)</entry> + <entry spanname="all">RBFMAN Option Section Definitions (Copied from device descriptor)</entry> </row> <row> <entry></entry> @@ -2143,7 +2155,8 @@ managers, the second and third sections are defined by RBFMAN and RBFMAN-type device drivers. The option section of the path descriptor contains many device operating parameters which may be read and/or -written by the OS9 I$GetStt and I$SetStt service requests. This section +written by the OS9 <xref linkend="i.getstt"/> +and <xref linkend="i.setstt"/> service requests. This section is initialized by IOMAN which copies the initialization table of the device descriptor into the option section of the path descriptor when a path to a device is opened. Any values not determined by this table @@ -2390,8 +2403,10 @@ </tgroup> </table> -<para>NOTE: V.PAGE through V.USER are predefined in the OS9DEFS file. -V.NDRV, DRVBEG, DRVMEM are predefined in the RBFDEFS file.</para> +<para>NOTE: V.PAGE through V.USER are predefined in the +<filename>OS9Defs</filename> file. +V.NDRV, DRVBEG, DRVMEM are predefined in the <filename>RBFDefs</filename> +file.</para> <para>V.PAGE, V.PORT These three bytes are defined by IOMAN as the 24-bit device address.</para> @@ -2684,7 +2699,8 @@ </informaltable> <orderedlist numeration="arabic"> - <listitem><para>If disk writes are verified, use the F$SRqMem service, request + <listitem><para>If disk writes are verified, use the + <xref linkend="f.srqmem"/> service request to allocate a 256 byte buffer area where a sector may be read back and verified after a write.</para></listitem> <listitem><para>Initialize the device permanent storage. For floppy disk @@ -2694,7 +2710,7 @@ may be read or written to, and initializing V.TRAK to $FF so that the first seek will find track zero.</para></listitem> <listitem><para>Place the IRQ service routine on the IRQ polling list by - using the OS9 F$IRQ service request.</para></listitem> + using the OS9 <xref linkend="f.irq"/> service request.</para></listitem> <listitem><para>Initialize the device control registers (enable interrupts if necessary).</para></listitem> </orderedlist> @@ -2884,12 +2900,14 @@ </informaltable> <para>These routines are wild card calls used to get (set) the device's -operating parameters as specified for the OS9 I$GetStt and I$SetStt +operating parameters as specified for the OS9 <xref linkend="i.getstt"/> +and <xref linkend="i.setstt"/> service requests.</para> <para>It may be necessary to examine or change the register stack which -contains the values of MPU registers at the time of the I$GetStt or -I$SetStt service request. The address of the register stack may be +contains the values of MPU registers at the time of the +<xref linkend="i.getstt"/> or +<xref linkend="i.setstt"/> service request. The address of the register stack may be found in PD.RGS, which is located in the path descriptor, . The following offsets may be used to access any particular value in the register stack:</para> @@ -3019,7 +3037,7 @@ <para>3. Remove the device from the IRQ polling list.</para> <para>4. If the INIT routine reserved a 256 byte buffer for verifying -disk writes, return the memory with the F$Mem service request.</para> +disk writes, return the memory with the <xref linkend="f.mem"/> service request.</para> </sect2> <sect2> @@ -3102,7 +3120,8 @@ (code $C). The execution offset in the module header contains the offset to the entry point of this subroutine.</para> -<para>It obtains the starting sector number and size of the "OS9Boot" +<para>It obtains the starting sector number and size of the +<filename>OS9Boot</filename> file from the identification sector (LSN 0). OS-9 is called to allocate a memory area large enough for the boot file, and then it loads the boot file into this memory area.</para> @@ -3112,7 +3131,7 @@ contains the values for DD.BT (the 24 bit logical sector number of the bootstrap file), and DD.BSZ (the size of the bootstrap file in bytes). For a full description of the identification sector. -See 6.1.1.</para> +See <xref linkend="lsn1"/>.</para> <para>2. After reading the identification sector into the buffer, get the 24 bit logical sector number of the bootstrap file from DD.BT.</para> @@ -3122,8 +3141,8 @@ logical sector specified in DD.BT and extending for (DD.BSZ/256+1) sectors.</para> -<para>4. Use the OS9 F$SRqMem service request to request the memory area -where the boot file will be loaded into.</para> +<para>4. Use the OS9 <xref linkend="f.srqmem"/> service request to +request the memory area where the boot file will be loaded into.</para> <para>5. Read the boot file into this memory area.</para> @@ -3153,7 +3172,7 @@ <sect1> <title>SCFMAN Line Editing Functions</title> -<para>I$Read and I$Write service requests (which correspond to Basic09 +<para><xref linkend="i.read"/> and <xref linkend="i.write"/> service requests (which correspond to Basic09 GET and PUT statements) to SCFMAN-type devices pass data to/from the device without any modification, except that keyboard interrupt, keyboard abort, and pause character are filtered out of the input @@ -3162,14 +3181,15 @@ automatically followed by line feeds or nulls, and the high order bits are passed as sent/received.</para> -<para>I$ReadLn and I$WritLn service requests (which correspond to Basic09 +<para><xref linkend="i.readln"/> and <xref linkend="i.writln"/> service requests (which correspond to Basic09 INPUT, PRINT, READ and WRITE statements) to SCFMAN-type devices perform full line editing of all functions enabled for the particular device. These functions are initialized when the device is first used by copying the option table from the device descriptor table associated with the specific device. They may be altered anytime -afterwards from assembly language programs using the I$SetStt and -I$GetStt service requests, or from the keyboard using the TMODE +afterwards from assembly language programs using the <xref linkend="i.setstt"/> and +<xref linkend="i.getstt"/> service requests, +or from the keyboard using the <command>tmode</command> command. Also, all bytes transfered in this mode will have the high order bit cleared.</para> @@ -3202,26 +3222,26 @@ line if PD.DLO = 0, or echo CR/LF if PD.DLO <> 0.</para> <para>PD.EOR defines the end of record character. This is the last -character an each line entered (I$ReadLn), and terminates the output -(I$WritLn) when this character is sent. Normally PD.EOR will be set -to $0D. If it is set to zero, SCF's READLN will NEVER terminate, +character an each line entered (<xref linkend="i.readln"/>), and terminates the output +(<xref linkend="i.writln"/>) when this character is sent. Normally PD.EOR will be set +to $0D. If it is set to zero, SCF's <xref linkend="i.readln"/> will NEVER terminate, unless an EOF occurs.</para> <para>If PD.EOF <> 0, it defines the end of file character. SCFMAN -will return an end-of-file error on I$Read or I$ReadLn if this is the +will return an end-of-file error on <xref linkend="i.read"/> or <xref linkend="i.readln"/> if this is the first (and only) character input. It can be disabled by setting its value to zero.</para> -<para>If PD.RPR <> 0, SCF (I$ReadLn) will, upon receipt of this +<para>If PD.RPR <> 0, SCF (<xref linkend="i.readln"/>) will, upon receipt of this character, echo a carriage return [optional line feed], and then reprint the current line.</para> -<para>If PD.DUP <> 0, SCF (I$ReadLn) will duplicate whatever is in +<para>If PD.DUP <> 0, SCF (<xref linkend="i.readln"/>) will duplicate whatever is in the input buffer through the first "PD.EOR" character.</para> <para>If PD.PSC <> 0, output is suspended before the next "PD.EOR" character when this character is input. This will also delete any -"type ahead" input for I$ReadLn.</para> +"type ahead" input for <xref linkend="i.readln"/>.</para> <para>If PD.INT <> 0, and is received on input, a keyboard interrupt signal is sent to the last user of this path. Also it will @@ -3235,13 +3255,13 @@ keyboard interrrupt signal code. This location is normally set to a control-Q character.</para> -<para>If PD.OVF <> 0, It is echoed when I$ReadLn has satisfied its +<para>If PD.OVF <> 0, It is echoed when <xref linkend="i.readln"/> has satisfied its input byte count without finding a "PD.EOR" character.</para> <para>NOTE: It is possible to disable most of these special editing functions by setting the corresponding control character in the path -descriptor to zero by using the I$SetStt service request, or by running -the TMODE utility. A more permanent solution may be had by setting +descriptor to zero by using the <xref linkend="i.setstt"/> service request, or by running +the <command>tmode</command> utility. A more permanent solution may be had by setting the corresponding control character value in the device descriptor module to zero.</para> @@ -3363,7 +3383,7 @@ and third section are specific for SCFMAN and SCFMAN-type device drivers. The option section of the path descriptor contains many device operating parameters whicb may be read or written by the OS9 -I$GetStt or I$SetStt service requests. IOMAN initializes this section +<xref linkend="i.getstt"/> or <xref linkend="i.setstt"/> service requests. IOMAN initializes this section when a path is opened to a device by copying the corresponding device descriptor initialization table. Any values not determined by this table will default to zero.</para> @@ -3581,8 +3601,7 @@ <para>As with all device drivers. SCFMAN device drivers use a standard executable memory module format with a module type of -edevice -drivers (CODE $5). The execution offset address in the +"device driver" (CODE $5). The execution offset address in the module header points to a branch table that has six three byte entries. Each entry is typically a LBRA to the corresponding subroutine. The branch @@ -3672,7 +3691,7 @@ <para>1. Initialize the device static storage.</para> <para>2. Place the IRQ service routine on the IRQ polling list by using -the OS9 F$IRQ service request.</para> +the OS9 <xref linkend="f.irq"/> service request.</para> <para>3. Initialize the device control registers (enable interrupts if necessary).</para> @@ -3718,8 +3737,8 @@ <para>This routine should get the next character from the input buffer. If there is no data ready, this routine should copy its -process ID from V.BUSY into V.WAKE and then use the F$Sleep service -request to put itself to sleep.</para> +process ID from V.BUSY into V.WAKE and then use the <xref linkend="f.sleep"/> +service request to put itself to sleep.</para> <para>Later when data is recieved, the IRQ service routine will leave the data in a buffer, then check V.WAKE to see if any process is @@ -3816,7 +3835,8 @@ <para> This routine is a wild card call used to get (set) the device -parameters specified in the I$GetStt and I$SetStt service requests. +parameters specified in the <xref linkend="i.getstt"/> +and <xref linkend="i.setstt"/> service requests. Currently all of the function codes defined by Microware for SCF-type devices are handled by IOMAN or SCFMAN. Any codes not defined by Microware will be passed to the device driver.</para> @@ -3957,7 +3977,7 @@ NOTE: Static storage used by device drivers is never returned to the free memory pool. Therefore, it is desirable to NEVER terminate any device that might be used again. Modules contained in -the BOOT tile will NEVER be terminated.</para> +the <filename>Boot</filename> file will NEVER be terminated.</para> </sect2> <sect2> @@ -3983,23 +4003,28 @@ Although this routine is not included in the device drivers branch table and not called directly from SCFMAN, it is an important routine in device drivers. The main things that it does are:</para> - -<para>1. Service the device interrupts (recieve data from device or send +<orderedlist numeration="arabic"> +<listitem> +<para>Service the device interrupts (recieve data from device or send data to it). This routine should put its data into and get its data from buffers which are defined in the device static storage.</para> - -<para>2. Wake up any process waiting for I/O to complete by checking +</listitem> +<listitem> +<para>Wake up any process waiting for I/O to complete by checking to see if there is a process ID in V.WAKE (non-zero) and it so send a wakeup signal to that process.</para> - -<para>3. If the device is ready to send more data and the output buffer +</listitem> +<listitem> +<para>If the device is ready to send more data and the output buffer is emoty, disable the device's "ready to transmit" interrupts.</para> - -<para>4. If a pause character is recieved, set V.PAUS in the attached +</listitem> +<listitem> +<para>If a pause character is recieved, set V.PAUS in the attached device static storage to a non-zero value. The address of the attached device static storage is in V.DEV2.</para> - +</listitem> +</orderedlist> <para> When the IRQ service routine finishes servicing an interrupt, it must clear the carry and exit with an RTS instruction.</para> @@ -4071,7 +4096,8 @@ <sect1> <title>Addressing Variables and Data Structures</title> -<para>Programs executed as processes (by FORK and CHAIN system calls or +<para>Programs executed as processes (by <xref linkend="f.fork"/> and +<xref linkend="f.chain"/> system calls or by the Shell) are assigned a RAM memory area for variables, stacks, and data structures at execution-time. The addresses cannot be determined or specified ahead of time. However, a minimum size for @@ -4084,12 +4110,13 @@ process passed a parameter area, it will be located from the value of the SP to the top of memory (Y), and the D register will contain the parameter area size in bytes. If the new process was called by the -shell, the parameter area will contain the part of the shell command +<command>shell</command>, the parameter area will contain +the part of the <command>shell</command> command line that includes the argument (parameter) text. The U register will have the lower bound of the data memory area, and the DP register will contain its page number.</para> -<para>The most important rule is to NOT USE EXTENDED ADDRESSING! +<para>The most important rule is to <emphasis>not use extended addressing!</emphasis> Indexed and direct page addressing should be used exclusively to access data area values and structures. Do not use program-counter relative addressing to find addresses in the data area, but do use it to refer @@ -4148,16 +4175,17 @@ <para>The INIT initialization subroutine within the driver package should allocate static storage for the service routine, get the -service routine address, and execute the F$IRQ system call to add it +service routine address, and execute the <xref linkend="f.irq"/> system call to add it to the IRQ polling table.</para> <para>When a device driver routine does something that will result in an -interrupt, it should immediately execute a F$Sleep service request. +interrupt, it should immediately execute a <xref linkend="f.sleep"/> +service request. This results in the process' deactivation. When the interrupt in question occurs, its service routine is executed after some random interval. It should then do the minimal amount of processing required, and send a "wakeup" signal to its associated process using -the F$Send service request. It may also put some data in its static +the <xref linkend="f.send"/> service request. It may also put some data in its static storage (I/O data and status) which is shared with its associated "sleeping" process.</para> @@ -4197,7 +4225,7 @@ <sect1> <title>A Sample Program</title> -<para>The OS-9 "list" utility command program is shown on this +<para>The OS-9 <command>list</command> utility command program is shown on this and the next page as an example of assembly language programming.</para> <programlisting> @@ -4354,13 +4382,13 @@ <listitem><para>If the target system requires multiprogramming, time-of-day, or other time-related functions, include a CLOCK module for the target system's real-time clock. Also consider how the clock is to - be started,. You may want to ROM the "Setime" command, or + be started,. You may want to ROM the <command>setime</command> command, or have SYSGO start the clock.</para></listitem> <listitem><para>It the target system will receive commands manually, or if any application program uses Shell functions, include the SHELL and SYSGO modules, otherwise include a modified SYSGO module which calls - your application program instead of Shell.</para></listitem> + your application program instead of <command>shell</command>.</para></listitem> </orderedlist> </sect1> @@ -4446,8 +4474,8 @@ <itemizedlist mark="bullet"> <listitem><para>It does additional high-level system initialization, for -example, disk system SYSGO call the shell to process the "Startup" -shell procedure file.</para></listitem> +example, disk system SYSGO call the <command>shell</command> to process the +<filename>Startup</filename> shell procedure file.</para></listitem> <listitem><para>It starts the first "user" process.</para></listitem> @@ -4462,7 +4490,7 @@ <orderedlist numeration="arabic"> <listitem><para>Remove initialization of the working execution directory.</para></listitem> -<listitem><para>Remove processing of the "Startup" procedure file.</para></listitem> +<listitem><para>Remove processing of the <filename>Startup</filename> procedure file.</para></listitem> <listitem><para>Possibly change the name of the first user program from Shell to the name of a applications program. Here are some example name strings:</para> @@ -4522,7 +4550,7 @@ permits a BCS or BCC instruction immediately following the system call to branch on error/no error.</para> -<para>Here is an example system call for the "CLOSE" service request:</para> +<para>Here is an example system call for the <xref linkend="i.close"/> service request:</para> <programlisting> LDA PATHNUM @@ -4553,7 +4581,7 @@ <para>All system calls have a mnemonic name that starts with "F$" for system functions, or "I$" for I/O related requests. These are defined in the assembler-input equate file -called "OS9DEFS".</para> +called <filename>OS9Defs</filename>.</para> <para>In the service request descriptions which follow, registers not explicitly specified as input or output parameters are not altered. @@ -4604,7 +4632,7 @@ the allocation bit map.</para> </sect1> -<sect1> +<sect1 id="f.chain" xreflabel="F$Chain"> <title>F$Chain - Load and execute a new primary module</title> <informaltable frame="none"> @@ -4637,17 +4665,17 @@ </tgroup> </informaltable> -<para>This system call is similar to FORK, but it does not create a new +<para>This system call is similar to <xref linkend="f.fork"/>, but it does not create a new process. It effectively "resets" the calling process' program and data memory areas and begins execution of a new primary module. Open paths are not closed or otherwise affected.</para> <para>This system call is used when it is necessary to execute an entirely new program, but without the overhead of creating a new -process. It is functionally similar to a FORK followed by an EXIT. -but with less processing overhead.</para> - -<para>The sequence of operations taken by CHAIN is as follows: +process. It is functionally similar to a <xref linkend="f.fork"/> followed by an +<xref linkend="f.exit"/>, but with less processing overhead.</para> + +<para>The sequence of operations taken by <xref linkend="f.chain"/> is as follows: </para> <para>1. The system parses the name string ot the new proces' @@ -4659,13 +4687,14 @@ is linked to (several modules may have been loaded from a single file).</para> -<para>2. The process' old primary module is UNLINKED.</para> +<para>2. The process' old primary module is +<emphasis>unlinked</emphasis>.</para> <para>3. The data memory area is reconfigured to the size specified in the new primary module's header.</para> -<para>The diagram below shows how CHAIN sets up the data memory area and -registers for the new module.</para> +<para>The diagram below shows how <xref linkend="f.chain"/> sets up the +data memory area and registers for the new module.</para> <informalfigure> <screen> +-----------------+ <-- Y (highest address) @@ -4697,16 +4726,16 @@ <para> WARNING: The hardware stack pointer (SP) should be located -somewhere in the direct page before the F$Chain service request is +somewhere in the direct page before the <xref linkend="f.chain"/> service request is executed to prevent a "suicide attempt" error or an actual suicide (system crash). This will prevent a suicide from occurring in case the new module requires a smaller data area than what is currently being used. You should allow approximately 200 bytes of stack space -for execution of the F$Chain service request and other system +for execution of the <xref linkend="f.chain"/> service request and other system "overhead".</para> <para> -For more information, please see the F$Fork service request +For more information, please see the <xref linkend="f.fork"/> service request description.</para> </sect1> @@ -4836,7 +4865,7 @@ the allocation bit map.</para> </sect1> -<sect1> +<sect1 id="f.exit" xreflabel="F$Exit"> <title>F$Exit - Terminate the calling process</title> <informaltable frame="none"> @@ -4870,15 +4899,15 @@ closed.</para> <para>The death of the process can be detected by the parent executing a -WAIT call, which returns to the parent the status byte passed by the -child in its EXIT call. The status byte can be an OS-9 error code the +<xref linkend="f.wait"/> call, which returns to the parent the status byte passed by the +child in its <xref linkend="f.exit"/> call. The status byte can be an OS-9 error code the terminating process wishes to pass back to its parent process (the shell assumes this), or can be used to pass a user-defined status value. Processes to be called directly by the shell should only return an OS-9 error code or zero if no error occurred.</para> </sect1> -<sect1> +<sect1 id="f.fork" xreflabel="F$Fork"> <title>F$Fork - Create a new process</title> <informaltable frame="none"> @@ -4935,20 +4964,20 @@ in the diagram on the next page. The execution offset given in the module header is used to set the PC to the module's entry point.</para> -<para>When the shell processes a command line it passes a string in the +<para>When the <command>shell</command> processes a command line it passes a string in the parameter area which is a copy of the parameter part (if any) of the command line. It also inserts an end-of-line character at the end of the parameter string to simplify string-oriented processing. The X register will point to the beginning of the parameter string. If the command line included the optional memory size specification (#n or -#nK), the shell will pass that size as the requested memory size when -executing the FORK.</para> - -<para>If any of the above operations are unsuccessful, the FORK is +#nK), the <command>shell</command> will pass that size as the requested memory size when +executing the <xref linkend="f.fork"/>.</para> + +<para>If any of the above operations are unsuccessful, the <xref linkend="f.fork"/> is aborted and the caller is returned an error.</para> <para>The diagram below -shows how FORK sets up the data memory area and registers for a +shows how <xref linkend="f.fork"/> sets up the data memory area and registers for a newly-created process.</para> <informalfigure> @@ -4982,16 +5011,16 @@ the parameter area.</para> <para>NOTE: Both the child and parent process will execute -concurrently. If the parent executes a F$WAIT call +concurrently. If the parent executes a <xref linkend="f.wait"/> call immediately after the fork, it will wait until the child dies before it resumes execution. Caution should be exercised when recursively -calling a program that uses the F$Fork service request since another +calling a program that uses the <xref linkend="f.fork"/> service request since another child may be created with each "incarnation". This will continue until the process table becomes full.</para> </sect1> -<sect1> -<title>F$Icpt - Set up a signal intercept trap</title> +<sect1 id="f.icpt" xreflabel="F$ICPT"> +<title>F$ICPT - Set up a signal intercept trap</title> <informaltable frame="none"> <tgroup cols="2"> @@ -5000,7 +5029,7 @@ <tbody> <row> <entry>ASSEMBLER CALL:</entry> - <entry>OS9 F$Icpt</entry> + <entry>OS9 F$ICPT</entry> </row> <row> <entry>MACHINE CODE:</entry> @@ -5029,7 +5058,7 @@ the base address of the routine's storage area. After a signal trap has been set, whenever the process receives a signal, its intercept routine will be executed. A signal will abort any process which has -not used the F$ICPT service request to set a signal trap, and its +not used the <xref linkend="f.icpt"/> service request to set a signal trap, and its termination status (B register) will be the signal code. Many interactive programs will set up an intercept routine to handle keyboard abort (control Q), and keyboard interrupt (control C).</para> @@ -5044,10 +5073,10 @@ <para>B = Signal code.</para> <para>NOTE: The value of DP may not be the same as it was when the -F$Icpt call was made.</para> +<xref linkend="f.icpt"/> call was made.</para> <para>Whenever a signal is received. OS-9 will pass the signal code and -the base address of its data area (which was defined by a F$ICPT +the base address of its data area (which was defined by a <xref linkend="f.icpt"/> service request) to the signal intercept routine. The base address of the data area is selected by the user and is typically a pointer to the process' data area.</para> @@ -5101,7 +5130,7 @@ Several processes can have the same user ID.</para> </sect1> -<sect1> +<sect1 id="f.link" xreflabel="F$LINK"> <title>F$LINK - Link to memory module</title> <informaltable frame="none"> @@ -5145,7 +5174,7 @@ the absolute address of the module's execution entry point is returned in Y (as a convenience: this and other information can be obtained from the module header). The module's link count' is -incremented whenever a LINK references its name, thus keeping track +incremented whenever a <xref linkend="f.link"/> references its name, thus keeping track of how many processes are using the module. If the module requested has an attribute byte indicating it is not sharable (meaning it is not reentrant) only one process may link to it at a time.</para> @@ -5201,7 +5230,7 @@ modules from the file into memory, then closes the file. All modules loaded are added to the system module directory, and the first module read is LINKed. The parameters returned are the same as the -LINK call and apply only to the first module loaded.</para> +<xref linkend="f.link"/> call and apply only to the first module loaded.</para> <para>In order to be loaded, the file must have the "execute" permission and contain a module or modules that have a proper module @@ -5209,10 +5238,11 @@ unless a complete pathlist is given.</para> <para>Possible errors: module directory full; memory full; plus errors -that occur on OPEN, READ, CLOSE and LINK system calls.</para> -</sect1> - -<sect1> +that occur on <xref linkend="i.open"/>, +<xref linkend="i.read"/>, <xref linkend="i.close"/> and <xref linkend="f.link"/> system calls.</para> +</sect1> + +<sect1 id="f.mem" xreflabel="F$Mem"> <title>F$Mem - Resize data memory area</title> <informaltable frame="none"> @@ -5307,7 +5337,7 @@ <para>by default. The error reporting routine is vectored and can be replaced with a more elaborate reporting module. To replace this -routine use the F$SSVC service request.</para> +routine use the <xref linkend="f.ssvc"/> service request.</para> </sect1> <sect1> @@ -5415,7 +5445,7 @@ carry set, beginning bit number and size of the largest block.</para> </sect1> -<sect1> +<sect1 id="f.send" xreflabel="F$Send"> <title>F$Send - Send a signal to another process</title> <informaltable frame="none"> @@ -5455,8 +5485,9 @@ <para>If the signal's destination process is sleeping or waiting, it will be activated so that it may process the signal. The signal processing routine (intercept) will be executed if a signal trap was -set up (see F$ICPT), otherwise the signal will abort the destination -process, and the signal code becomes the exit status (see WAIT). An +set up (see <xref linkend="f.icpt"/>), +otherwise the signal will abort the destination +process, and the signal code becomes the exit status (see <xref linkend="f.wait"/>). An exception is the WAKEUP signal, which activates a sleeping process but does not cause the signal intercept routine to be executed.</para> @@ -5478,11 +5509,12 @@ a "sleep" call for a few ticks before a retry to avoid wasting MPU time.</para> -<para>For related information see the F$ICPT, F$WAIT and F$Sleep service +<para>For related information see the <xref linkend="f.icpt"/>, +<xref linkend="f.wait"/> and <xref linkend="f.sleep"/> service request descriptions.</para> </sect1> -<sect1> +<sect1 id="f.sleep" xreflabel="F$Sleep"> <title>F$Sleep - Put calling process to sleep</title> <informaltable frame="none"> @@ -5525,8 +5557,8 @@ <para>The duration of a "tick" is system dependent but is most commonly 100 milliseconds.</para> -<para>Due to the fact that it is not known when the F$Sleep request was -made during the current tick, F$Sleep can not be used for precise +<para>Due to the fact that it is not known when the <xref linkend="f.sleep"/> request was +made during the current tick, <xref linkend="f.sleep"/> can not be used for precise timing. A sleep of one tick is effectively a "give up remaining time slice" request; the process is immediately inserted into the active process queue and will resume execution when it reaches @@ -5577,7 +5609,7 @@ another process' priority only if it has the same user ID.</para> </sect1> -<sect1> +<sect1 id="f.ssvc" xreflabel="F$SSVC"> <title>F$SSVC - Install function request</title> <informaltable frame="none"> @@ -5655,7 +5687,7 @@ </para> <informalfigure> <screen> - OFFSET OS9DEFS + OFFSET OS9Defs MNEMONIC +------+ U ---> ! CC ! $0 R$CC @@ -5709,7 +5741,7 @@ are free for user definition.</para> </sect1> -<sect1> +<sect1 id="f.sswi" xreflabel="F$SSWI"> <title>F$SSWI - Set SWI vector</title> <informaltable frame="none"> @@ -5744,7 +5776,7 @@ </informaltable> <para>Sets up the interrupt vectors for SWI, SWI2 and SWI3 instructions. -Each process has its own local vectors. Each SETSWI call sets up one +Each process has its own local vectors. Each F$SSWI call sets up one type of vector according to the code number passed in A.</para> <literallayout> @@ -5950,7 +5982,7 @@ the module directory.</para> </sect1> -<sect1> +<sect1 id="f.wait" xreflabel="F$Wait"> <title>F$Wait - Wait for child process to die</title> <informaltable frame="none"> @@ -5985,24 +6017,26 @@ </informaltable> <para>The calling process is deactivated until a child process -terminates by executing an EXIT system call, or by receiving a +terminates by executing an <xref linkend="f.exit"/> +system call, or by receiving a signal. The child's ID number and exit status is returned to the parent. If the child died due to a signal, the exit status byte (B register) is the signal code.</para> <para>If the caller has several children, the caller is activated when -the first one dies, so one WAIT system call is required to detect +the first one dies, so one <xref linkend="f.wait"/> +system call is required to detect termination of each child.</para> -<para>If a child died before the WAIT call, the caller is reactivated -almost immediately. WAIT will return an error if the caller has no +<para>If a child died before the <xref linkend="f.wait"/> call, the caller is reactivated +almost immediately. <xref linkend="f.wait"/> will return an error if the caller has no children.</para> -<para>See the EXIT description for more related information.</para> -</sect1> - - -<sect1> +<para>See the <xref linkend="f.exit"/> description for more related information.</para> +</sect1> + + +<sect1 id="f.all64" xreflabel="F$All64"> <title>F$All64 - Allocate a 64 byte memory block</title> <informaltable frame="none"> @@ -6043,8 +6077,9 @@ tour sections. The first 64 bytes of the base page are used as a "page table", which contains the MSB of all pages in the memory structure. Passing a value of zero in the X register will -cause the F$All64 service request to allocate a new base page and the -first 64 byte memory block. Whenever a new page is needed, an F$SRqMem +cause the <xref linkend="f.all64"/> service request to allocate a new base page and the +first 64 byte memory block. Whenever a new page is needed, an +<xref linkend="f.srqmem"/> service request will automatically be executed. The first byte of each block contains the block number; routines using this service request should not alter it. Below is a diagram to show how 7 blocks @@ -6156,7 +6191,7 @@ </informaltable> <para>This system mode service request will return the address of a 64 -byte memory block as described in the F$All64 service request. OS-9 +byte memory block as described in the <xref linkend="f.all64"/> service request. OS-9 used this service request to find process descriptors and path descriptors when given their number.</para> @@ -6252,7 +6287,7 @@ <para>NOTE: THIS IS A PRIVILEGED SYSTEM MODE SERVICE REQUEST</para> </sect1> -<sect1> +<sect1 id="f.irq" xreflabel="F$IRQ"> <title>F$IRQ - Add or remove device from IRQ table</title> <informaltable frame="none"> @@ -6405,12 +6440,12 @@ </informaltable> <para>This system mode service request deallocates a 64 byte block of -memory as described in the F$All64 service request.</para> +memory as described in the <xref linkend="f.all64"/> service request.</para> <para>NOTE: THIS IS A PRIVILEGED SYSTEM MODE SERVICE REQUEST</para> </sect1> -<sect1> +<sect1 id="f.srqmem" xreflabel="F$SRqMem"> <title>F$SRqMem - System memory request</title> <informaltable frame="none"> @@ -6659,7 +6694,7 @@ execution directory is changed.</para> </sect1> -<sect1> +<sect1 id="i.close" xreflabel="I$Close"> <title>I$Close - Close a path to a file/device</title> <informaltable frame="none"> @@ -6693,20 +6728,21 @@ </informaltable> <para>Terminates the I/O path specified by the path number. I/O can no -longer be performed to the file/device, unless another OPEN or CREATE +longer be performed to the file/device, unless another <xref linkend="i.open"/> or +<xref linkend="i.create"/> call is used. Devices that are non-sharable become available to other requesting processes. All OS-9 internally managed buffers and descriptors are deallocated.</para> <para>Note: Because the OS9 F$Exit service request automatically closes all open paths (except the standard I/O paths), it may not he -necessary to close them individually with the OS9 I$Close service request.</para> +necessary to close them individually with the OS9 <xref linkend="i.close"/> service request.</para> <para>Standard I/O paths are not typically closed except when it is desired to change the files/devices they correspond to.</para> </sect1> -<sect1> +<sect1 id="i.create" xreflabel="I$Create"> <title>I$Create - Create a path to a new file</title> <informaltable frame="none"> @@ -6760,7 +6796,8 @@ <para>The access mode parameter passed in register A must be either "WRITE" or "UPDATE". This only affects the file until it is closed; it can be reopened later in any access mode -allowed by the file attributes (see OPEN). Files open for "WRITE" +allowed by the file attributes (see <xref linkend="i.open"/>). +Files open for "WRITE" may allow faster data transfer than "UPDATE", which sometimes needs to preread setors. These access codes are defined as given below: @@ -6778,14 +6815,14 @@ subsequent I/O service requests until the file is closed.</para> <para>No data storage is initially allocated for the file at the time it -is created; this is done automatically by WRITE or explicitly by the -PUTSTAT call.</para> +is created; this is done automatically by <xref linkend="i.write"/> +or explicitly by the PUTSTAT call.</para> <para>An error will occur if the file name already exists in the -directory. CREATE calls that specify non-multiple file devices (such -as printers, terminals, etc.) work correctly: the CREATE behaves the -same as OPEN. Create cannot be used to make directory files (see -MAKDIR).</para> +directory. <xref linkend="i.create"/> calls that specify non-multiple file devices (such +as printers, terminals, etc.) work correctly: the <xref linkend="i.create"/> behaves the +same as <xref linkend="i.open"/>. Create cannot be used to make directory files (see +<xref linkend="i.makdir"/>).</para> </sect1> <sect1> @@ -6916,7 +6953,7 @@ descriptor is not copied.</para> </sect1> -<sect1> +<sect1 id="i.getstt" xreflabel="I$GetStt"> <title>I$GetStt - Get file device status</title> <informaltable frame="none"> <tgroup cols="2"> @@ -6962,9 +6999,10 @@ file manager associated with the path. A typical use is to determine a terminal's parameters for backspace character, delete character, echo on/off, null padding, paging, etc. It is commonly -used in conjunction with the SETSTAT service request which is +used in conjunction with the <xref linkend="i.setstt"/> +service request which is used to set the device operating parameters. Below are presently -defined function codes for GETSTAT:</para> +defined function codes for <xref linkend="i.getstt"/>:</para> <informaltable frame="none"> <tgroup cols="3"> @@ -7219,7 +7257,7 @@ </informaltable> </sect1> -<sect1> +<sect1 id="i.makdir" xreflabel="I$MakDir"> <title>I$MakDir - Make a new directory</title> <informaltable frame="none"> @@ -7252,14 +7290,14 @@ </tbody> </tgroup> </informaltable> -<para>MAKDIR is the only way a new directory file can be created. It +<para><xref linkend="i.makdir"/> is the only way a new directory file can be created. It will create and initialize a new directory as specified by the pathlist. The new directory file contains no entries, except for an entry for itself (".") and its parent directory ("..")</para> -<para>The caller is made the owner of the directory. MAKDIR dies not +<para>The caller is made the owner of the directory. <xref linkend="i.makdir"/> does not return a path number because directory files are not "opened" by -this request (use OPEN to do so). The new directory will +this request (use <xref linkend="i.open"/> to do so). The new directory will automatically have its "directory" bit set in the access permission attributes. The remaining attributes are specified by the byte passed in the B register, which has individual bits @@ -7277,7 +7315,7 @@ </literallayout> </sect1> -<sect1> +<sect1 id="i.open" xreflabel="I$Open"> <title>I$Open - Open a path to a file or device</title> <informaltable frame="none"> <tgroup cols="2"> @@ -7327,7 +7365,7 @@ <para>Update mode can be slightly slower because pre-reading of sectors may be required for random access of bytes within sectors. The access mode must conform to the access permission attributes -associated with the file or device (see CREATE). Only the owner +associated with the file or device (see <xref linkend="i.create"/>). Only the owner may access a file unless the appropiate "public permit" bits are set.</para> @@ -7349,7 +7387,7 @@ in the access mode.</para> </sect1> -<sect1> +<sect1 id="i.read" xreflabel="I$Read"> <title>I$Read - Read data from a file or device</title> <informaltable frame="none"> @@ -7390,7 +7428,7 @@ additional processing or editing such as backspace, line delete, end-of-file, etc.</para> -<para>After all data in a file has been read, the next I$Read service +<para>After all data in a file has been read, the next <xref linkend="i.read"/> service request will return an end of file error.</para> <para>NOTES:</para> @@ -7410,7 +7448,7 @@ </literallayout> </sect1> -<sect1> +<sect1 id="i.readln" xreflabel="I$ReadLn"> <title>I$ReadLn - Read a text line with editing</title> <informaltable frame="none"> @@ -7445,7 +7483,8 @@ </tgroup> </informaltable> -<para>This system call is the same as "READ" except it reads data from +<para>This system call is the same as <xref linkend="i.read"/> +except it reads data from the input file or device until a carriage return character is encountered or until the maximum byte count specified is reached, and that line editing will occur on SCFMAN-type devices. Line @@ -7457,7 +7496,7 @@ than the maximum specified, it will not be accepted and a PD.OVF character (normally bell) will be echoed.</para> -<para>After all data in the file has been read, the next I$ReadLn service +<para>After all data in the file has been read, the next <xref linkend="i.readln"/> service request will return an end of file error.</para> <para>NOTE: For more information on line editing, see 7.1.</para> @@ -7512,7 +7551,7 @@ without error.</para> </sect1> -<sect1> +<sect1 id="i.setstt" xreflabel="I$SetStt"> <title>I$SetStt - Set file/device status</title> <informaltable frame="none"> <tgroup cols="2"> @@ -7557,7 +7596,8 @@ file manager associated with the path. A typical use is to set a terminal's parameters for backspace character, delete character, echo on/off, null padding, paging, etc. It is commonly -used in conjunction with the GETSTAT service request which is +used in conjunction with the <xref linkend="i.getstt"/> +service request which is used to read the device operating parameters. Below are presently defined function codes:</para> @@ -7780,7 +7820,7 @@ </informaltable> </sect1> -<sect1> +<sect1 id="i.write" xreflabel="I$Write"> <title>I$Write - Write data to file or device</title> <informaltable frame="none"> @@ -7815,7 +7855,7 @@ </tgroup> </informaltable> -<para>WRITE outputs one or more bytes to a file or device associated +<para><xref linkend="i.write"/> outputs one or more bytes to a file or device associated with the path number specified. The path must have been OPENed or CREATEd in the WRITE or UPDATE access modes.</para> @@ -7825,7 +7865,7 @@ automatically expanded.</para> </sect1> -<sect1> +<sect1 id="i.writln" xreflabel="I$WritLn"> <title>I$WritLn - Write line of text with editing</title> <informaltable frame="none"> @@ -7860,7 +7900,7 @@ </tgroup> </informaltable> -<para>This system call is similar to WRITE except it writes data until a +<para>This system call is similar to <xref linkend="i.write"/> except it writes data until a carriage return character is encountered. Line editing is also activated for character-oriented devices such as terminals, printers, etc. The line editing refers to auto line feed, null @@ -8484,9 +8524,9 @@ </row> <row> <entry>103F 04</entry> - <entry>F$WAIT</entry> + <entry>F$Wait</entry> <entry>Wait for child process to die.</entry> - <entry></entry> + <entry><xref linkend="f.wait"/></entry> </row> <row> <entry>103F 05</entry> @@ -8514,7 +8554,7 @@ </row> <row> <entry>103F 09</entry> - <entry>F$Icpt</entry> + <entry>F$ICPT</entry> <entry>Set up a signal intercept trap.</entry> <entry></entry> </row> @@ -9059,40 +9099,40 @@ <colspec colwidth="0.3in"/> <colspec colwidth="1.5in"/> <tbody> - <row> - <entry>$1</entry> - <entry>Program</entry> - </row> - <row> - <entry>$2</entry> - <entry>Subroutine module</entry> - </row> - <row> - <entry>$3</entry> - <entry>Multi-module</entry> - </row> - <row> - <entry>$4</entry> - <entry>Data module</entry> - </row> - <row> - <entry>$C</entry> - <entry>System Module</entry> - </row> - <row> - <entry>$D</entry> - <entry>File Manager</entry> - </row> - <row> - <entry>$E</entry> - <entry>Device Driver</entry> - </row> - <row> - <entry>$F</entry> - <entry>Device Descriptor</entry> - </row> - </tbody> - </tgroup> + <row> + <entry>$1</entry> + <entry>Program</entry> + </row> + <row> + <entry>$2</entry> + <entry>Subroutine module</entry> + </row> + <row> + <entry>$3</entry> + <entry>Multi-module</entry> + </row> + <row> + <entry>$4</entry> + <entry>Data module</entry> + </row> + <row> + <entry>$C</entry> + <entry>System Module</entry> + </row> + <row> + <entry>$D</entry> + <entry>File Manager</entry> + </row> + <row> + <entry>$E</entry> + <entry>Device Driver</entry> + </row> + <row> + <entry>$F</entry> + <entry>Device Descriptor</entry> + </row> + </tbody> +</tgroup> </table> @@ -9146,28 +9186,40 @@ <table frame="none"> <title>Module Languages</title> <tgroup cols="2"> -<colspec colwidth="0.3in"/> +<colspec colwidth="0.5in"/> <colspec colwidth="1.5in"/> <tbody> <row> - <entry>$0</entry> - <entry>Data</entry> + <entry>$0</entry> + <entry>Data</entry> </row> <row> - <entry>$1</entry> - <entry>6809 Object code</entry> + <entry>$1</entry> + <entry>6809 Object code</entry> + </row> + <row> + <entry>$2</entry> + <entry>BASIC09 I-code</entry> </row> <row> - <entry>$2</entry> - <entry>BASIC09 I-code</entry> + <entry>$3</entry> + <entry>Pascal P-Code</entry> + </row> + <row> + <entry>$4</entry> + <entry>C I-code</entry> </row> <row> - <entry>$3</entry> - <entry>Pascal P-Code</entry> + <entry>$5</entry> + <entry>Cobol I-code</entry> </row> <row> - <entry>$4</entry> - <entry>Cobol I-code</entry> + <entry>$6</entry> + <entry>Fortan I-code</entry> + </row> + <row> + <entry>$7</entry> + <entry>6309 Object code</entry> </row> </tbody> </tgroup> @@ -9178,12 +9230,12 @@ <tgroup cols="2"> <colspec colwidth="0.3in"/> <colspec colwidth="1.5in"/> - <tbody> - <row> - <entry>$8</entry> - <entry>Reentrant</entry> - </row> - </tbody> + <tbody> + <row> + <entry>$8</entry> + <entry>Reentrant</entry> + </row> + </tbody> </tgroup> </table> @@ -9192,333 +9244,7 @@ </appendix> -<appendix> -<title>Error Codes</title> -<sect1> -<title>OS-9 Error Codes</title> - -<para>The error codes are shown both in hexadecimal (first column) and -decimal (second column). Error codes other than those listed are -generated by programming languages or user programs.</para> - -<informaltable frame="none"> -<tgroup cols="3"> -<colspec colwidth="0.6in"/> -<colspec colwidth="0.6in"/> -<colspec colwidth="3.8in"/> -<thead> -<row> -<entry rowsep="1">HEX</entry> -<entry rowsep="1">DEC</entry> -<entry rowsep="0"></entry> -</row> -</thead> -<tbody> -<row> - <entry>$C8</entry> - <entry>200</entry> - <entry><errorname>PATH TABLE FULL</errorname> - - The file cannot be opened because - the system path table is currently full.</entry></row> -<row> - <entry>$C9</entry> - <entry>201</entry> - <entry><errorname>ILLEGAL PATH NUMBER</errorname> - - Number too large or for non-existant path.</entry></row> -<row> - <entry>$CA</entry> - <entry>202</entry> - <entry><errorname>INTERRUPT POLLING TABLE FULL</errorname></entry></row> -<row> - <entry>$CB</entry> - <entry>203</entry> - <entry><errorname>ILLEGAL MODE</errorname> - - attempt to perform I/O function of which the device or file is incapable.</entry></row> -<row> - <entry>$CC</entry> - <entry>204</entry> - <entry><errorname>DEVICE TABLE FULL</errorname> - - Can't add another device</entry></row> -<row> - <entry>$CD</entry> - <entry>205</entry> - <entry><errorname>ILLEGAL MODULE HEADER</errorname> - - module not loaded because its - sync code, header parity, or CRC is incorrect.</entry></row> -<row> - <entry>$CE</entry> - <entry>206</entry> - <entry><errorname>MODULE DIRECTORY FULL</errorname> - - Can't add another module</entry></row> -<row> - <entry>$CF</entry> - <entry>207</entry> - <entry><errorname>MEMORY FULL</errorname> - - Level One: not enough contiquous RAM free. - Level Two: process address space full</entry></row> -<row> - <entry>$D0</entry> - <entry>208</entry> - <entry><errorname>ILLEGAL SERVICE REQUEST</errorname> - - System call had an illegal code number</entry></row> -<row> - <entry>$D1</entry> - <entry>209</entry> - <entry><errorname>MODULE BUSY</errorname> - - non-sharable module is in use by another process.</entry></row> -<row> - <entry>$D2</entry> - <entry>210</entry> - <entry><errorname>BOUNDARY ERROR</errorname> - - Memory allocation or deallocation request not on a page boundary.</entry></row> -<row> - <entry>$D3</entry> - <entry>211</entry> - <entry><errorname>END OF FILE</errorname> - - End of file encountered on read.</entry></row> -<row> - <entry>$D4</entry> - <entry>212</entry> - <entry><errorname>RETURNING NON-ALLOCATED MEMORY</errorname> - - (NOT YOUR MEMORY) - attempted to deallocate memory not previously assigned.</entry></row> -<row> - <entry>$D5</entry> - <entry>213</entry> - <entry><errorname>NON-EXISTING SEGMENT</errorname> - - device has damaged file structure.</entry></row> -<row> - <entry>$D6</entry> - <entry>214</entry> - <entry><errorname>NO PERMISSION</errorname> - - file attributes do not permit access requested.</entry></row> -<row> - <entry>$D7</entry> - <entry>215</entry> - <entry><errorname>BAD PATH NAME</errorname> - - syntax error in pathlist (illegal character, etc.).</entry></row> -<row> - <entry>$D8</entry> - <entry>216</entry> - <entry><errorname>PATH NAME NOT FOUND</errorname> - - can't find pathlist specified.</entry></row> -<row> - <entry>$D9</entry> - <entry>217</entry> - <entry><errorname>SEGMENT LIST FULL</errorname> - - file is too fragmented to be expanded further.</entry></row> -<row> - <entry>$DA</entry> - <entry>218</entry> - <entry><errorname>FILE ALREADY EXISTS</errorname> - - file name already appears in current directory.</entry></row> -<row> - <entry>$DB</entry> - <entry>219</entry> - <entry><errorname>ILLEGAL BLOCK ADDRESS</errorname> - - device's file structure has been damaged.</entry></row> -<row> - <entry>$DC</entry> - <entry>220</entry> - <entry><errorname>ILLEGAL BLOCK SIZE</errorname> - - device's file structure has been damaged.</entry></row> -<row> - <entry>$DD</entry> - <entry>221</entry> - <entry><errorname>MODULE NOT FOUND</errorname> - - request for link to module not found in directory.</entry></row> - <row> - <entry>$DE</entry> - <entry>222</entry> - <entry><errorname>SECTOR OUT OF RANGE</errorname> - - device file structure damaged or -incorrectly formatted.</entry></row> -<row> - <entry>$DF</entry> - <entry>223</entry> - <entry><errorname>SUICIDE ATTEMPT</errorname> - - request to return memory where your stack is located.</entry></row> -<row> - <entry>$E0</entry> - <entry>224</entry> - <entry><errorname>ILLEGAL PROCESS NUMBER</errorname> - - no such process exists.</entry></row> -<row> - <entry>$E2</entry> - <entry>226</entry> - <entry><errorname>NO CHILDREN</errorname> - - can't wait because process has no children.</entry></row> -<row> - <entry>$E3</entry> - <entry>227</entry> - <entry><errorname>ILLEGAL SWI CODE</errorname> - - must be 1 to 3.</entry></row> -<row> - <entry>$E4</entry> - <entry>228</entry> - <entry><errorname>PROCESS ABORTED</errorname> - - process aborted by signal code 2.</entry></row> -<row> - <entry>$E5</entry> - <entry>229</entry> - <entry><errorname>PROCESS TABLE FULL</errorname> - - can't fork now.</entry></row> -<row> - <entry>$E6</entry> - <entry>230</entry> - <entry><errorname>ILLEGAL PARAMETER AREA</errorname> - - high and low bounds passed in fork call are incorrect.</entry></row> -<row> - <entry>$E7</entry> - <entry>231</entry> - <entry><errorname>KNOWN MODULE</errorname> - - for internal use only.</entry></row> -<row> - <entry>$E8</entry> - <entry>232</entry> - <entry><errorname>INCORRECT MODULE CRC</errorname> - - module has bad CRC value.</entry></row> -<row> - <entry>$E9</entry> - <entry>233</entry> - <entry><errorname>SIGNAL ERROR</errorname> - - receiving process has previous - unprocessed signal pending.</entry></row> -<row> - <entry>$EA</entry> - <entry>234</entry> - <entry><errorname>NON-EXISTENT MODULE</errorname> - - unable to locate module.</entry></row> -<row> - <entry>$EB</entry> - <entry>235</entry> - <entry><errorname>BAD NAME</errorname> - - illegal name syntax.</entry></row> -<row> - <entry>$EC</entry> - <entry>236</entry> - <entry><errorname>BAD HEADER</errorname> - - module header parity incorrect</entry></row> -<row> - <entry>$ED</entry> - <entry>237</entry> - <entry><errorname>RAM FULL</errorname> - - no free system RAM available at this time</entry></row> -<row> - <entry>$EE</entry> - <entry>238</entry> - <entry><errorname>UNKNOWN PROCESS ID</errorname> - - incorrect process ID number</entry></row> -<row> - <entry>$EF</entry> - <entry>239</entry> - <entry><errorname>NO TASK NUMBER AVAILABLE</errorname> - - all task numbers in use</entry></row> -</tbody> -</tgroup> -</informaltable> -</sect1> - -<sect1> -<title>Device Driver/Hardware Errors</title> - -<para>The following error codes are generated by I/O device drivers, and -are somewhat hardware dependent. Consult manufacturer's hardware -manual for more details.</para> - -<informaltable frame="none"> -<tgroup cols="3"> -<colspec colwidth="0.6in"/> -<colspec colwidth="0.6in"/> -<colspec colwidth="3.8in"/> -<thead> -<row> -<entry rowsep="1">HEX</entry> -<entry rowsep="1">DEC</entry> -<entry rowsep="0"></entry> -</row> -</thead> -<tbody> -<row> - <entry>$F0</entry> - <entry>240</entry> - <entry><errorname>UNIT ERROR</errorname> - - device unit does not exist</entry></row> -<row> - <entry>$F1</entry> - <entry>241</entry> - <entry><errorname>SECTOR ERROR</errorname> - - sector number is out of range.</entry></row> -<row> - <entry>$F2</entry> - <entry>242</entry> - <entry><errorname>WRITE PROTECT</errorname> - - device is write protected.</entry></row> -<row> - <entry>$F3</entry> - <entry>243</entry> - <entry><errorname>CRC ERROR</errorname> - - CRC error on read or write verify</entry></row> -<row> - <entry>$F4</entry> - <entry>244</entry> - <entry><errorname>READ ERROR</errorname> - - Data transfer error during disk read - operation, or SCF (terminal) input buffer overrun.</entry></row> -<row> - <entry>$F5</entry> - <entry>245</entry> - <entry><errorname>WRITE ERROR</errorname> - - hardware error during disk write operation.</entry></row> -<row> - <entry>$F6</entry> - <entry>246</entry> - <entry><errorname>NOT READY</errorname> - - device has "not ready" status.</entry></row> -<row> - <entry>$F7</entry> - <entry>247</entry> - <entry><errorname>SEEK ERROR</errorname> - - physical seek to non-existant sector.</entry></row> -<row> - <entry>$F8</entry> - <entry>248</entry> - <entry><errorname>MEDIA FULL</errorname> - - insufficient free space on media.</entry></row> -<row> - <entry>$F9</entry> - <entry>249</entry> - <entry><errorname>WRONG TYPE</errorname> - - attempt to read incompatible media (i.e. - attempt to read double-side disk on single-side drive)</entry></row> -<row> - <entry>$FA</entry> - <entry>250</entry> - <entry><errorname>DEVICE BUSY</errorname> - - non-sharable device is in use</entry></row> -<row> - <entry>$FB</entry> - <entry>251</entry> - <entry><errorname>DISK ID CHANGE</errorname> - - Media was changed with files open</entry></row> -<row> - <entry>$FC</entry> - <entry>252</entry> - <entry><errorname>RECORD IS LOCKED-OUT</errorname> - - Another process is accessing the requested record.</entry></row> -<row> - <entry>$FD</entry> - <entry>253</entry> - <entry><errorname>NON-SHARABLE FILE BUSY</errorname> - - Another process is accessing the requested file.</entry></row> -</tbody> -</tgroup> -</informaltable> -</sect1> -</appendix> - - - +&errorcodesapp; <appendix> @@ -11072,7 +10798,7 @@ a full pathlist. If the access mode is read, write, or update, the current data directory is assumed. If the access mode is execute, the current execution directory is assumed. Note that -if a full pathlist (a pathlist beginning witt a "/") appears, the +if a full pathlist (a pathlist beginning with a "/") appears, the access mode is ignored.</para> <para>ACCESS MODES:</para>