TABLE OF CONTENTS exec.library exec.library/AddSemaphore exec.library/AttemptSemaphore exec.library/FindResident exec.library/FindSemaphore exec.library/InitCode exec.library/InitResident exec.library/InitSemaphore exec.library/ObtainSemaphore exec.library/ObtainSemaphoreList exec.library/RawDoFmt exec.library/ReleaseSemaphore exec.library/ReleaseSemaphoreList exec.library/RemSemaphore exec.library/Vacate Exec/AddDevice Exec/AddHead Exec/AddIntServer Exec/AddLibrary Exec/AddMemList Exec/AddPort Exec/AddResource Exec/AddTail Exec/AddTask Exec/Allocate Exec/AllocEntry Exec/AllocMem Exec/AllocSignal Exec/AllocTrap Exec/AvailMem Exec/Cause Exec/CheckIO Exec/CloseDevice Exec/CloseLibrary Exec/CopyMem Exec/CopyMemQuick Exec/Deallocate Exec/DoIO Exec/Enqueue Exec/FindName Exec/FindPort Exec/FindTask Exec/FreeEntry Exec/FreeMem Exec/FreeSignal Exec/FreeTrap Exec/GetCC Exec/GetMsg Exec/InitStruct Exec/Insert Exec/MakeLibrary Exec/OpenDevice Exec/OpenLibrary Exec/OpenResource Exec/PutMsg Exec/RemDevice Exec/RemHead Exec/RemIntServer Exec/RemLibrary Exec/Remove Exec/RemPort Exec/RemResource Exec/RemTail Exec/RemTask Exec/ReplyMsg Exec/SendIO Exec/SetExcept Exec/SetFunction Exec/SetIntVector Exec/SetSignal Exec/SetSR Exec/SetTaskPri Exec/Signal Exec/SumLibrary Exec/SuperState Exec/UserState Exec/Wait Exec/WaitIO Exec/WaitPort Exported Imported Included exec.library exec.library NAME Procure -- bid for a message lock (semaphore) SYNOPSIS result = Procure(semaphore, bidMessage) D0 A0 A1 FUNCTION This function is used to obtain a message based semaphore lock. If the lock is immediate, Procure() returns a true result, and the bidMessage is not used. If the semaphore is already locked, Procure() returns false, and the task must wait for the bidMessage to arrive at its reply port. Straight "Semaphores" use the message system. They are therefore queueable, and users may wait on several of them at the same time. This makes them more powerfull than "Signal Semaphores" INPUT semaphore - a semaphore message port. This port is used to queue all pending lockers. This port should be initialized with the PA_IGNORE option, as the MP_SigTask field is used for a pointer to the current locker message (not a task). New semaphore ports must also have the SM_BIDS word initialized to -1. If the semaphore is public, it should be named, its priority set, and the added with AddPort. Message port priority is often used for anti-deadlock locking conventions. RESULT result - true when the semaphore is free. In such cases no waiting needs to be done. If false, then the task should wait at its bidMessage reply port. SEE ALSO Vacate() exec.library/AddSemaphore exec.library/AddSemaphore NAME AddSemaphore -- add a signal semaphore to the system SYNOPSIS AddSemaphore(signalSemaphore) A1 FUNCTION This function attaches a signal semaphore structure to the system's signal semaphore list. The name and priority fields of the semaphore structure should be initialized prior to calling this function. If the user does not to let others rendezvous with this semaphore, he should use InitSemaphore instead. If a semaphore has been added to the naming list, you must be careful to remove the semaphore from the list (via RemSemaphore) before deallocating its memory. Semaphores that are linked together in an allocation list (which ObtainSemaphoreList() would use) may not be added to the system naming list, because both the facilities make use of the same data region. INPUTS signalSemaphore -- an signal semaphore structure SEE ALSO RemSemaphore, FindSemaphore exec.library/AttemptSemaphore exec.library/AttemptSemaphore NAME AttemptSemaphore -- try to obtain without blocking SYNOPSIS success = AttemptSemaphore(signalSemaphore) D0 A0 FUNCTION This call is similar to ObtainSemaphore(), except that it will not block if the semaphore could not be locked. INPUT signalSemaphore -- an initialized signal semaphore structure RESULT success -- TRUE if the semaphore was locked, false if some other task already possesed the semaphore. SEE ALSO ObtainSemaphore(), ReleaseSemaphore(), Procure() exec.library/FindResident exec.library/FindResident NAME FindResident - find a resident module by name SYNOPSIS resident = FindResident(name) D0 A1 FUNCTION Find the resident module with the given name. If found return a pointer to the resident tag structure, else return zero. INPUTS name - pointer to name string RESULT resident - pointer to the resident tag structure or zero if none found. SEE ALSO ResidentTag (RT) structure definition (resident.h) exec.library/FindSemaphore exec.library/FindSemaphore NAME FindSemaphore -- find a given system signal semaphore SYNOPSIS signalSemaphore = FindSemaphore(name) D0 A1 FUNCTION This function will search the system signal semaphore list for a semaphore with the given name. The first semaphore matching this name will be returned. INPUT name - name of the semaphore to find RETURN semaphore - a pointer to the signal semaphore, or zero if not found. exec.library/InitCode exec.library/InitCode NAME InitCode - initialize resident code modules SYNOPSIS InitCode(startClass, version) D0 D1 FUNCTION Initialize all resident modules with the given startClass and with versions equal or greater than that specified. Modules are initialized in a prioritized order. INPUTS startClass - the class of code to be initialized: coldstart, coolstart, warmstart, ... version - a major version number SEE ALSO ResidentTag (RT) structure definition (resident.h) exec.library/InitResident exec.library/InitResident NAME InitResident - initialize resident module SYNOPSIS InitResident(resident, segList) A1 D1 FUNCTION Initialize a module. INPUTS SEE ALSO ResidentTag (RT) structure definition (resident.h) exec.library/InitSemaphore exec.library/InitSemaphore NAME InitSemaphore -- initialize a signal semaphore SYNOPSIS InitSemaphore(signalSemaphore) A0 FUNCTION This function initializes a signal semaphore and prepares it for use. It does not allocate anything, but does initialize list pointers and the semaphore counters. INPUT signalSemaphore -- an uninitialized signal semaphore structure RESULT SEE ALSO ObtainSemaphore(), ReleaseSemaphore(), Procure() exec.library/ObtainSemaphore exec.library/ObtainSemaphore NAME ObtainSemaphore -- gain exclusive access to a semaphore SYNOPSIS ObtainSemaphore(signalSemaphore) A0 FUNCTION Signal semaphores are used to gain exclusive access to an object. ObtainSemaphore is the call used to gain this access. If another user currently has the semaphore locked the call will block until the object is available. If the current task already has locked the semaphore and attempts to lock it again the call will still succeed. A "nesting count" is incremented each time the current owning task of the semaphore calls ObtainSemaphore(). This counter is decremented each time ReleaseSemaphore() is called. When the counter returns to zero the semaphore is actually released, and the next waiting task is called. A queue of waiting tasks is maintained. Each will be called in turn as soon as the current task releases the semaphore. Signal Semaphores are different than Procure()/Vacate() semaphores. The former requires less cpu time, especially if the semaphore is not currently locked. They require very little set up and user thought. The latter flavor of semaphore make no assumptions about how they are used -- they are completely general. Unfortunately they are not as efficient as signal semaphores, and require the locker to have done some setup before doing the call. INPUT signalSemaphore -- an initialized signal semaphore structure RESULT SEE ALSO InitSemaphore(), ReleaseSemaphore(), Procure(), TransferSemaphore() AttemptSemaphore(), ObtainSemaphoreList() exec.library/ObtainSemaphoreList exec.library/ObtainSemaphoreList NAME ObtainSemaphoreList -- get a list of semaphores. SYNOPSIS ObtainSemaphoreList(list) A0 FUNCTION Signal semaphores may be linked together into a list using the ss_Link field. This routine takes a list of these semaphores and attempts to lock all of them at once. This call is prefereable to applying ObtainSemaphore() to each element in the list because it attempts to lock all the elements simultaneously, and won't deadlock if someone is attempting to lock in some other order. This routine assumes that only one task at a time will attempt to lock the entire list of semaphores. In other words, there needs to be a higher level lock (perhaps another signal semaphore...) that is used before someone attempts to lock the semaphore list via ObtainSemaphoreList(). Note that deadlocks may result if this call is used AND someone attempts to use ObtainSemaphore() to lock more than one semaphore on the list. If you wish to lock more than semaphore (but not all of them) then you should obtain the higher level lock (see above) INPUT list -- a list of signal semaphores RESULT SEE ALSO ObtainSemaphore(), ReleaseSemaphore(), Procure(), ReleaseSemaphoreList() exec.library/RawDoFmt exec.library/RawDoFmt NAME RawDoFmt -- format data into a character stream. SYNOPSIS RawDoFmt(FormatString, DataStream, PutChProc, PutChData); A0 A1 A2 A3 FUNCTION perform "C"-language-like formatting of a data stream, outputting the result a character at a time INPUTS FormatString - a "C"-language-like null terminated format string, with the following supported % types: DataStream - a stream of data that is interpreted according to the format string. PutChProc - the procedure to call with each character to be output, called as: PutChProc(Char, PutChData); D0-0:8 A3 the procedure is called with a null Char at the end of the format string. PutChData - an address register that passes thru to PutChProc. EXAMPLE formatString: ASCII "%dth character: %c/ hex: %2x" EVEN DoFmtCall: CLR.L D0 MOVE.B char,D0 MOVE.L D0,-(A7) MOVE.L D0,-(A7) MOVE.W iteration,D0 MOVE.L D0,-(A7) MOVE.L A7,A1 LEA formatString,A0 LEA KPutChar,A2 MOVE.L $0004,Ax MOVE.L SystemLib[Ax],Ay MOVE.L DoFmt[Ay],Az JSR [Az] ADD.W #12,A7 SEE ALSO BUGS FILE on HP64000 exec.library/ReleaseSemaphore exec.library/ReleaseSemaphore NAME ReleaseSemaphore -- make signal semaphore available to others SYNOPSIS ReleaseSemaphore(signalSemaphore) A0 FUNCTION ReleaseSemaphore() is the inverse of ObtainSemaphore(). It makes the semaphore lockable to other users. If tasks are waiting for the semaphore and this this task is done with the semaphore then the next waiting task is signalled. Each ObtainSemaphore() call must be ballanced by exactly one ReleaseSemaphore() call. This is because there is a nesting count maintained in the semaphore of the number of times that the current task has locked the semaphore. The semaphore is not released to other tasks until the number of releases matches the number of obtains. Needless to say, havoc breaks out if the task releases more times than it has obtained. INPUT signalSemaphore -- an initialized signal semaphore structure RESULT SEE ALSO ObtainSemaphore(), Procure() exec.library/ReleaseSemaphoreList exec.library/ReleaseSemaphoreList NAME ReleaseSemaphoreList -- make a list of semaphores available SYNOPSIS ReleaseSemaphoreList(list) A0 FUNCTION ReleaseSemaphoreList() is the inverse of ObtainSemaphoreList(). It releases each element in the semaphore list. Needless to say, havoc breaks out if the task releases more times than it has obtained. INPUT list -- a list of signal semaphores RESULT SEE ALSO ObtainSemaphore(), ReleaseSemaphore(), ObtainSemaphoreList() exec.library/RemSemaphore exec.library/RemSemaphore NAME RemSemaphore -- remove a signal semaphore from the system SYNOPSIS RemSemaphore(signalSemaphore) A1 FUNCTION This function removes a signal semaphore structure from the system's signal semaphore list. Subsequent attempts to rendezvous by name with this semaphore will fail. INPUTS signalSemaphore -- an initialized signal semaphore structure SEE ALSO AddSemaphore, FindSemaphore exec.library/Vacate exec.library/Vacate NAME Vacate -- release a message lock (semaphore) SYNOPSIS Vacate(semaphore) A0 FUNCTION This function releases a previously locked semaphore (see the Procure() function). If another task is waiting for the semaphore, its bidMessage will be sent to its reply port. INPUT semaphore - the semaport message port representing the semaphore to be freed. RESULT SEE ALSO Procure() Exec/AddDevice Exec/AddDevice NAME AddDevice -- add a device to the system SYNOPSIS AddDevice(device) A1 FUNCTION This function adds a new device to the system, making it available to everyone. The device should be ready to be called at this time. INPUTS device - pointer to a properly initialized device node SEE ALSO RemDevice Exec/AddHead Exec/AddHead NAME AddHead -- insert node at the head of a list SYNOPSIS AddHead(list, node) A0 A1 FUNCTION Add a node to the head of a doubly linked list. INPUTS list - a pointer to the target list header node - the node to insert at head Exec/AddIntServer Exec/AddIntServer NAME AddIntServer -- add an interrupt server to the system SYNOPSIS AddIntServer(intNum, interrupt) D0-0:4 A1 FUNCTION This function adds a new interrupt server to a given server chain. The node is located on the chain in a priority dependent position. Higher priority nodes will be serviced first. If this server is the first one, interrupts will be enabled on this chain. Servers are called with the following register conventions: D0 - scratch D1 - scratch A0 - scratch A1 - server data segment pointer (scratch) A5 - jump vector register (scratch) A6 - library base pointer (scratch) all other registers - must be preserved INPUTS intNum - the Portia interrupt bit (0..14). Processor level seven interrupts (NMI) are encoded as intNum 15. interrupt - pointer to an interrupt server node SEE ALSO RemIntServer Exec/AddLibrary Exec/AddLibrary NAME AddLibrary -- add a library to the system SYNOPSIS AddLibrary(library) A1 FUNCTION This function adds a new library to the system making it available to everyone. The library should be ready to be called at this time. It will be added to the system library name list, and the checksum on the library entries will be calculated. INPUTS library - pointer to a properly initialized library structure SEE ALSO RemLibrary Exec/AddMemList Exec/AddMemList NAME AddMemList - add memory to the system free pool SYNOPSIS error = AddMemList( size, attributes, pri, base, name ) D0 D0 D1 D2 A0 A1 FUNCTION Add a new region of memory to the free pool. The first few bytes will be used to hold the MemHeader structure. The rest will be made available to the rest of the world. The new free pool will be added before all other free pools. INPUTS size - the size (in bytes) of the memory area attributes - the attributes word that the memory pool will have pri - the priority for this memory. CHIP memory has a pri of -10, extended memory has a priority of 0 base - the base of the new memory area name - the name that will be used in the memory header, or NULL if no name is to be provided. This name is not copied, so it must remain valid for as long as the memory header is in the system. RESULTS EXCEPTIONS SEE ALSO Allocate, AllocMem, Deallocate BUGS Exec/AddPort Exec/AddPort NAME AddPort -- add a message port to the system SYNOPSIS AddPort(port) A1 FUNCTION This function attaches a message port structure to the system's message port list. The name and priority fields of the port structure should be initialized prior to calling this function. If the user does not require the name and priority fields, they should be initialized to zero. As with the name field in other system list items, the name is useful when more than one task needs to rendezvous on at port. If a port has been added to the naming list, you must be careful to remove the port from the list (via RemPort) before deallocating its memory. INPUTS port - pointer to a message port SEE ALSO RemPort, FindPort Exec/AddResource Exec/AddResource NAME AddResource -- add a resource to the system SYNOPSIS AddResource(resource) A1 FUNCTION This function adds a new resource to the system and makes it available to other users. The resource should be ready to be called at this time. INPUTS resource - pointer to a properly initialized resource node SEE ALSO RemResource Exec/AddTail Exec/AddTail NAME AddTail -- append node to tail of a list SYNOPSIS AddTail(list, node) A0 A1 FUNCTION Add a node to the tail of a doubly linked list. INPUTS list - a pointer to the target list header node - the node to insert at tail Exec/AddTask Exec/AddTask NAME AddTask -- add a task to the system SYNOPSIS AddTask(task, initialPC, finalPC) A1 A2 A3 FUNCTION Add a task to the system. Certain fields of the task control block must be initialized and a minimal stack should be allocated prior to calling this function. This function will temporarily use space from the new task's stack for the task's initial set of registers. This space is allocated starting at the SPREG location specified in the task control block (not from SPUPPER). This means that a task's stack may contain static data put there prior to its execution. This is useful for providing initialized global variables or some tasks may want to use this space for passing the task its initial arguments. A task's initial registers are set to zero (except the PC). INPUTS task - pointer to the task control block initialPC - the initial entry point finalPC - the finalization code entry point. If zero, the system will use a general finalizer. This pointer is placed on the stack as if it were the outermost return address. SEE ALSO RemTask Exec/Allocate Exec/Allocate NAME Allocate -- allocate a block of memory SYNOPSIS memoryBlock = allocate(freeList, byteSize) D0 A0 D0 FUNCTION This function is used to allocate blocks of memory from a given free memory pool. It will return the first free block that is greater than or equal to the requested size. All blocks, whether free or allocated, will be block aligned; hence, all allocation sizes are rounded up to the next block even value (e.g. the minimum allocation resolution is 8 bytes). This function, when used in conjunction with a private free list, can be used to manage an application's internal data memory. INPUTS freeList - points to the memory list header byteSize - the size of the desired block in bytes RESULT memoryBlock - a pointer to the just allocated free block. If there are no free regions large enough to satisfy the request, return zero. If the amount of requested memory is invalid, return zero. EXCEPTIONS If the free list is corrupt, the system will panic. SEE ALSO Deallocate Exec/AllocEntry Exec/AllocEntry NAME AllocEntry -- allocate many regions of memory SYNOPSIS memList = AllocEntry(memList) D0 A0 FUNCTION This routine takes a memList structure and allocates enough memory to hold the required memory as well as a MemList structure to keep track of it. These MemList structures may be linked together in a task control block to keep track of the total memory usage of this task. INPUTS memList -- A MemList structure filled in with MemEntry structures. RESULTS memList -- A different MemList filled in with the actual memory allocated in the me_Addr field, and their sizes in me_Length. If enough memory cannot be obtained, then the requirements of the allocation that failed is returned and bit 31 is set. EXAMPLES The user wants five regions of 2, 4, 8, 16, and 32 bytes in size with requirements of MEMF_CLEAR, MEMF_PUBLIC, MEMF_CHIP.OR.MEMF_CLEAR, MEMF_FAST.OR.MEMF_CLEAR, and MEMF_PUBLIC.OR.MEMF_CLEAR respectively. The following code fragment would do that: MemListDecl: DS.B LN_SIZE * reserve space for list node DC.W 5 * number of entries DC.L MEMF_CLEAR * entry #0 DC.L 2 DC.L MEMF_PUBLIC * entry #1 DC.L 4 DC.L MEMF_CHIP.OR.MEMF_CLEAR * entry #2 DC.L 8 DC.L MEMF_FAST.OR.MEMF_CLEAR * entry #3 DC.L 16 DC.L MEMF_PUBLIC.OR.MEMF_CLEAR * entry #4 DC.L 32 start: LEA MemListDecl,A0 CALLLIB _LVOAllocEntry,A5 BCLR.L #31,D0 BEQ.S success ------- Type of memory that we failed on is in D0 Exec/AllocMem Exec/AllocMem NAME AllocMem -- allocate memory given certain requirements SYNOPSIS memoryBlock = AllocMem(byteSize, requirements) D0 D0 D1-0:31 FUNCTION This is the memory allocator to be used by system code and applications. It provides a means of specifying whether the allocation should be made in a memory area accessible to the chips, or accessible to shared system code. The proper allocation of memory is necessary for system code that needs to be compatibable with memory mapped systems. Memory is allocated based on the "requirements" listed. The rule is that (requirements & attributes) == requirements for any particular memory block. AllocMem will try all memory spaces until one is found with the requested attributes and room for the memory request. INPUTS byteSize - the size of the desired block in bytes This number is rounded up to the next larger block size for the actual allocation. requirements - (still in flux) (see IA_Structs for bit definitions) MEMB_PUBLIC: memory must not be mapped, swapped, or otherwise made non-addressable. ALL MEMORY THAT IS REFERENCED VIA INTERRUPTS AND/OR BY OTHER TASKS MUST BE EITHER PUBLIC OR LOCKED INTO MEMORY! This includes both code and data. MEMB_CHIP: Only certain parts of memory are reachable by the special chip sets' DMA circuitry. Anything that will use on-chip DMA must be in memory with this attribute. DMA includes screen memory, things that are blitted, audio blocks, raw disc buffers, etc. MEMB_FAST: This is non-chip memory. It is possible for the processor to get locked out of chip memory under certain conditions. If one cannot accept these delays, then one should use FAST memory (by default the system will allocate from FAST memory first anyway). MEMB_CLEAR: The memory will be initialized to all zeros. RESULT memoryBlock - a pointer to the allocated free block. If there are no free regions large enough to satisfy the request (or if the amount of requested memory is invalid), return zero. EXAMPLES AllocMem(321,MEMB_CHIP) - private chip memory AllocMem(25,MEMB_PUBLIC) - a "public" system structure that does not require chip memory. EXCEPTIONS If the free list is corrupt, the system will panic. SEE ALSO FreeMem Exec/AllocSignal Exec/AllocSignal NAME AllocSignal -- allocate a signal bit SYNOPSIS signalNum = AllocSignal(signalNum) D0 D0 FUNCTION Allocate a signal bit from the current tasks pool. Either a particular bit, or the next free bit may be allocated. The signal associated with the newly allocated bit will be properly initialized (cleared). If the signal is already in use (or no free signals are available) a -1 is returned. This function can only be used by the currently running task. WARNING Signals may not be allocated or freed from exception handling code. INPUTS signalNum - the desired signal number {of 0..31} or -1 for no preference. RESULTS signalNum - the signal bit number allocated {0..31}. If no signals are available, this function returns -1. SEE ALSO FreeSignal Exec/AllocTrap Exec/AllocTrap NAME AllocTrap -- allocate a processor trap vector SYNOPSIS trapNum = AllocTrap(trapNum) D0 D0 FUNCTION Allocate a trap number from the current task's pool. These trap numbers are those associated with the 68000 TRAP type instructions. Either a particular nnumber, or the next free number may be allocated. If the trap is already in use (or no free traps are available) a -1 is returned. This function can only be used by the currently running task. WARNING Signals may not be allocated or freed from exception handling code. INPUTS trapNum - the desired trap number {of 0..15} or -1 for no preference. RESULTS trapNum - the trap number allocated {of 0..15}. If no traps are available, this function returns -1. SEE ALSO FreeTrap Exec/AvailMem Exec/AvailMem NAME AvailMem -- memory available given certain requirements SYNOPSIS size = AvailMem(requirements) D0 D1 FUNCTION This function returns the size of memory given certain requirements. INPUTS requirements - a requirements mask as specified in AllocMem RESULT size - total free space remaining Exec/Cause Exec/Cause NAME Cause -- cause a software interrupt SYNOPSIS Cause(interrupt) A1 FUNCTION This function causes a software interrupt to occur. If it is called from user mode (and processor level 0), the software interrupt will pre-empt the current task. Currently only 5 software interrupt priorities are implemented: -32, -16, 0, +16, and +32. Priorities in between these values are truncated. Priorities outside the -32/+32 range are not allowed. INPUTS interrupt - pointer to a properly initialized interrupt node Exec/CheckIO Exec/CheckIO NAME CheckIO -- get the IO request status SYNOPSIS result = CheckIO(iORequest) D0 A1 FUNCTION This function determines the current state of an I/O request and returns FALSE if the I/O has not yet completed. This function effectively hides the internals of the I/O completion mechanism. If the I/O has completed, CheckIO will not remove the returned IORequest from the reply port. This should be performed with Remove. This function SHOULD NOT be used to busy loop, waiting for an IO to complete. INPUTS iORequest - pointer to an I/O request block RESULTS result - null if I/O is still in progress. Otherwise D0 points to the IORequest block. Exec/CloseDevice Exec/CloseDevice NAME CloseDevice -- conclude access to a device SYNOPSIS CloseDevice(iORequest) A1 FUNCTION This function informs the system that access to a device/unit previously opened has been concluded. The device may perform certain house-cleaning operations. The I/O request structure is now free to be recycled. INPUTS iORequest - pointer to an I/O request structure SEE ALSO OpenDevice Exec/CloseLibrary Exec/CloseLibrary NAME CloseLibrary -- conclude access to a library SYNOPSIS CloseLibrary(library) A1 FUNCTION This function informs the system that access to the given library has been concluded. The user should not reference the library or any routine in the library after this close. INPUTS library - pointer to a library node SEE ALSO OpenLibrary Exec/CopyMem Exec/CopyMem NAME CopyMem - general purpose memory copy routine SYNOPSIS CopyMem( source, dest, size ) A0 A1 D0 FUNCTION CopyMem is a general purpose, fast memory copy routine. It can deal with arbitrary lengths, with its pointers on arbitrary alignments. It attempts to optimize larger copies with more efficient copies, it uses byte copies for small moves or when pointers are misaligned. This routine may be implemented in a processor dependend fashion. INPUTS source - a pointer to the source data region dest - a pointer to the destination data region size - the size (in bytes) of the memory area RESULTS EXCEPTIONS SEE ALSO CopyMemQuick BUGS Exec/CopyMemQuick Exec/CopyMemQuick NAME CopyMemQuick - optimized memory copy routine SYNOPSIS CopyMemQuick( source, dest, size ) A0 A1 D0 FUNCTION CopyMemQuick is a highly optimized memory copy routine, with restrictions on the size and alignment of its arguments. Both the source and destination pointers must be longword aligned. In addition, the size must be an integral number of longwords (e.g. the size must be evenly divisible by four). This routine may be implemented in a processor dependend fashion. INPUTS source - a pointer to the source data region, long aligned dest - a pointer to the destination data region, long aligned size - the size (in bytes) of the memory area RESULTS EXCEPTIONS SEE ALSO CopyMem BUGS Exec/Deallocate Exec/Deallocate NAME Deallocate -- deallocate a block of memory SYNOPSIS Deallocate(freeList, memoryBlock, byteSize) A0 A1 D0 FUNCTION This function deallocates memory by returning it to the appropriate free memory pool. This function can be used to free an entire block allocated with the above function, or it can be used to free a sub-block of a previously allocated block. If memoryBlock is not on a block boundary (MEM_BLOCKSIZE) then it will be rounded down. Note that this will work correctly with all the memory allocation routines, but may cause surprises if one is freeing only part of a region. If byteSize is null, nothing happens. Also, the size of the block will be rounded up, so the freed block will fill an entire memory block. INPUTS freeList - points to the free list memoryBlock - memory block to return byteSize - the size of the desired block in bytes SEE ALSO Allocate Exec/DoIO Exec/DoIO NAME DoIO -- perform an I/O command and wait for completion SYNOPSIS error = DoIO(iORequest) D0 A1 FUNCTION This function requests a device driver to perform the I/O command specified in the I/O request. This function will always block until the I/O request is completed. INPUTS iORequest - pointer to a properly initialized I/O request RESULTS error - see WaitIO SEE ALSO SendIO, WaitIO Exec/Enqueue Exec/Enqueue NAME Enqueue -- insert or append node to a system queue SYNOPSIS Enqueue(list, node) A0 A1 FUNCTION Insert or append a node into a system queue. The insert is performed based on the node priority -- it will keep the list properly sorted. New nodes will be inserted in front of the first node with a lower priority. Hence a FIFO queue for nodes of equal priority INPUTS list - a pointer to the system queue header node - the node to enqueue Exec/FindName Exec/FindName NAME FindName -- find a system list node with a given name SYNOPSIS node = FindName(start, name) D0 A0 A1 FUNCTION Traverse a system list until a node with the given name is found. To find multiple occurances of a string, this function may be called with a node starting point. INPUTS start - a list header or a list node to start the search (if node, this one is skipped) name - a pointer to a name string terminated with null RESULTS node - a pointer to the node with the same name else zero to indicate that the string was not found. Exec/FindPort Exec/FindPort NAME FindPort -- find a given system message port SYNOPSIS port = FindPort(name) D0 A1 FUNCTION This function will search the system message port list for a port with the given name. The first port matching this name will be returned. INPUT name - name of the port to find RETURN port - a pointer to the message port, or zero if not found. Exec/FindTask Exec/FindTask NAME FindTask -- find a task with the given name or find oneself SYNOPSIS task = FindTask(name) D0 A1 FUNCTION This function will check all task queues for a task with the given name, and return a pointer to its task control block. If a null name pointer is given a pointer to the current task will be returned. INPUT name - pointer to a name string RESULT task - pointer to the task Exec/FreeEntry Exec/FreeEntry NAME FreeEntry -- free many regions of memory SYNOPSIS FreeEntry(memList) A0 FUNCTION This routine takes a memList structure (as returned by AllocEntry) and frees all the entries. INPUTS memList -- pointer to structure filled in with memEntry structures Exec/FreeMem Exec/FreeMem NAME FreeMem -- deallocate with knowledge SYNOPSIS FreeMem(memoryBlock, byteSize) A1 D0 FUNCTION Free a region of memory, returning it to the pool from which it came. INPUTS memoryBlock - memory block to free If the memoryBlock previously returned by an allocation routine. byteSize - the size of the block in bytes SEE ALSO AllocMem Exec/FreeSignal Exec/FreeSignal NAME FreeSignal -- free a signal bit SYNOPSIS FreeSignal(signalNum) D0 FUNCTION This function frees a previously allocated signal bit for reuse. This call must be performed while running in the same task in which the signal was allocated. WARNING Signals may not be allocated or freed from exception handling code. INPUTS signalNum - the signal number to free {0..31} Exec/FreeTrap Exec/FreeTrap NAME FreeTrap -- free a processor trap SYNOPSIS FreeTrap(trapNum) D0 FUNCTION This function frees a previously allocated trap number for reuse. This call must be performed while running in the same task in which the trap was allocated. WARNING Traps may not be allocated or freed from exception handling code. INPUTS trapNum - the trap number to free {of 0..15} Exec/GetCC Exec/GetCC NAME GetCC -- get condition codes in a 68010 compatible way. SYNOPSIS conditions = GetCC() D0 FUNCTION This function provides a means of obtaining the CPU condition codes in a manner that will make 68010 upgrades transparent. INPUTS RESULTS conditions - the 68000/68010 condition codes Exec/GetMsg Exec/GetMsg NAME GetMsg -- get next message from a message port SYNOPSIS message = GetMsg(port) D0 A0 FUNCTION This function receives a message from a given message port. It provides a fast, non-copying message receiving mechanism. The received message is removed from the message port. This function will not wait. If a message is not present this function will return zero. If a program must wait for a message, it can Wait on the signal specified for the port or use the WaitPort function. There can only be one task waiting for any given port. Getting the message does not imply that the message is now free to be reused. When the receiver is finished with the message, it may ReplyMsg it. INPUT port - a pointer to the receiver message port RESULT message - a pointer to the first message available. If there are no messages, return zero. SEE ALSO PutMsg, ReplyMsg, WaitPort Exec/InitStruct Exec/InitStruct NAME InitStruct - initialize memory from a table SYNOPSIS InitStruct(initTable, memory, size); A1 A2 D0-0:16 FUNCTION Clear a memory area except those words whose data and offset values are provided in the initialization table. This initialization table has byte commands to |a ||byte| |given||byte| |once | load |count||word| into |next ||rptr| offset, |repeatitively|. |long| Not all combinations are supported. The offset, when specified, is relative to the memory pointer provided (Memory), and is initially zero. The initialization data (InitTable) contains byte commands whose 8 bits are interpreted as follows: ddssnnnn dd the destination type (and size): 00 next destination, nnnn is count 01 next destination, nnnn is repeat 10 destination offset is next byte, nnnn is count 11 destination offset is next rptr, nnnn is count ss the size and location of the source: 00 long, from the next two aligned words 01 word, from the next aligned word 10 byte, from the next byte 11 ERROR - will cause an ALERT (see below) nnnn the count or repeat: count the (number+1) of source items to copy repeat the source is copied (number+1) times. initTable commands are always read from the next even byte. Given destination offsets are always relative to memory (A2). The command 00000000 ends the InitTable stream: use 00010001 if you really want to copy one longword. 24 bit APTR not supported for 68020 compatibitity -- use long. INPUTS initTable - the beginning of the commands and data to init Memory with. Must be on an even boundary unless only byte initialization is done. memory - the beginning of the memory to initialize. Must be on an even boundary if size is specified. size - the size of memory, which is used to clear it before initializing it via the initTable. If Size is zero, memory is not cleared before initializing. Size is rounded down to the nearest even number before use. --------------------------------------------------------------------- IMPLEMENTATION D0 clear size, command, count and repeat D1 destination offset, command type A0 current Memory pointer A1 current InitTable pointer D0,D1,A0,A1 destroyed Exec/Insert Exec/Insert NAME Insert -- insert a node into a list SYNOPSIS Insert(list, node, listNode) A0 A1 A2 FUNCTION Insert a node into a doubly linked list AFTER a given node position. Insertion at the head of a list is performed by passing a zero value for listNode. INPUTS list - a pointer to the target list header node - the node to insert listNode - the node after which to insert Exec/MakeLibrary Exec/MakeLibrary NAME MakeLibrary -- construct a library SYNOPSIS library = MakeLibrary(vectors, structure, init, dataSize, segList) D0 A0 A1 A2 D0 D1 FUNCTION This function is used for constructing a library vector and data area. Space for the library is allocated from the system's free memory pool. The size fields of the library are filled. The data portion of the library is initialized. A library specific entrypoint is called (init) if present. INPUTS vectors - pointer to an array of function pointers or function displacements. If the first word of the array is -1, then the array contains relative word displacements (based off of vectors); otherwise, the array contains absolute function pointers. The vector list is terminated by a -1 (of the same size as the pointers). structure - points to an "InitStruct" data region. If null, then it will not be called. init - an entry point that will be called before adding the library to the system. If null, it will not be called. When it is called, it will be called with the libAddr in D0 and the segList parameter in A0. The result of the init function will be the result returned by MakeLibrary. dSize - the size of the library data area, including the standard library node data. segList - pointer to a memory segment list (used by DOS) This is passed to a library's init code. RESULT library - the reference address of the library. This is the address used in references to the library, not the beginning of the memory area allocated. EXCEPTION If the library vector table require more system memory than is available, this function will cause a system panic. SEE ALSO InitStruct Exec/OpenDevice Exec/OpenDevice NAME OpenDevice -- gain access to a device SYNOPSIS error = OpenDevice(devName, unitNumber, iORequest, flags) D0 A0 D0 A1 D1 FUNCTION This function opens the named device/unit and initializes the given I/O request block. INPUTS devName - requested device name unitNumber - the unit number to open on that device. The format of the unit number is device specific. iORequest - the I/O request block to be returned with appropriate fields initialized. flags - additional driver specific information. This is sometimes used to request opening a device with exclusive access. RESULTS error - zero if successful, else an error is returned SEE ALSO CloseDevice Exec/OpenLibrary Exec/OpenLibrary NAME OpenLibrary -- gain access to a library SYNOPSIS library = OpenLibrary(libName, version) D0 A1 D0 FUNCTION This function returns a pointer to a library that was previously installed into the system. If the requested library is exists, and if the library version is greater than or equal to the requested version, then the open will succeed. INPUTS libName - the name of the library to open version - the version of the library required. RESULTS library - a library pointer for a successful open, else zero SEE ALSO CloseLibrary Exec/OpenResource Exec/OpenResource NAME OpenResource -- gain access to a resource SYNOPSIS resource = OpenResource(resName) D0 A1 FUNCTION This function returns a pointer to a resource that was prev- iously installed into the system. INPUTS resName - the name of the resource requested. RESULTS resource - if successful, a resource pointer, else null SEE ALSO CloseResource Exec/PutMsg Exec/PutMsg NAME PutMsg -- put a message to a message port SYNOPSIS PutMsg(port, message) A0 A1 FUNCTION This function attaches a message to a given message port. It provides a fast, non-copying message sending mechanism. Messages can be attached to only one port at a time. The message body can be of any size or form. Because messages are not copied, cooperating tasks share the same message memory. The sender task should not recycle the message until it has been replied by the receiver. Of course this depends on the message handling conventions setup by the involved tasks. If the ReplyPort field is non-zero, when the message is replied by the receiver, it will be sent back to that port. Any one of the following actions can be set to occur when a message is put: 1. no special action 2. signal a given task 3. cause a software interrupt 3. cause a software interrupt The action is selected depending on the value set in PB_ACTION of MP_FLAGS. INPUT port - pointer to a message port message - pointer to a message SEE ALSO GetMsg, ReplyMsg Exec/RemDevice Exec/RemDevice NAME RemDevice -- remove a device from the system SYNOPSIS error = RemDevice(device) D0 A1 FUNCTION This function removes an existing device from the system. This function deletes the device from the device name list, so no new opens can occur. INPUTS device - pointer to a device node RESULTS error - zero if successful, else an error is returned SEE ALSO AddDevice Exec/RemHead Exec/RemHead NAME RemHead -- remove the head node from a list SYNOPSIS node = RemHead(list) D0 A0 FUNCTION Get a pointer to the head node and remove it from the list. INPUTS list - a pointer to the target list header RESULT node - the node removed or zero when empty list Exec/RemIntServer Exec/RemIntServer NAME RemIntServer -- remove an interrupt server SYNOPSIS RemIntServer(intNum, interrupt) D0-0:4 A1 FUNCTION This function removes an interrupt server node from the given server chain. If this server was the last one one the chain interrupts will be disabled for intNum. INPUTS intNum - the Portia interrupt bit (0..14) interrupt - pointer to an interrupt server node SEE ALSO AddIntServer Exec/RemLibrary Exec/RemLibrary NAME RemLibrary -- remove a library from the system SYNOPSIS error = RemLibrary(library) D0 A1 FUNCTION This function removes an existing library from the system. It will delete it from the system library name list, so no new opens may be performed. INPUTS library - pointer to a library node structure RESULTS error - zero if successful, else an error number SEE ALSO AddLibrary Exec/Remove Exec/Remove NAME Remove -- remove a node from a list SYNOPSIS Remove(node) A1 FUNCTION Remove a node from a list. INPUTS node - the node to remove Exec/RemPort Exec/RemPort NAME RemPort -- remove a message port from the system SYNOPSIS RemPort(port) A1 FUNCTION This function removes a message port structure from the system's message port list. Subsequent attempts to rendezvous by name with this port will fail. INPUTS port - pointer to a message port SEE ALSO AddPort, FindPort Exec/RemResource Exec/RemResource NAME RemResource -- remove a resource from the system SYNOPSIS RemResource(resource) A1 FUNCTION This function removes an existing resource from the system. INPUTS resource - pointer to a resource node SEE ALSO AddResource Exec/RemTail Exec/RemTail NAME RemTail -- remove the tail node from a list SYNOPSIS node = RemTail(list) D0 A0 FUNCTION Get a pointer to the tail node and remove it from the list. INPUTS list - a pointer to the target list header RESULT node - the node removed or zero when empty list Exec/RemTask Exec/RemTask NAME RemTask -- remove a task from the system SYNOPSIS RemTask(task) A1 FUNCTION This function removes a task from the system. Deallocation of resources should have been performed prior to calling this function. INPUTS task - pointer to the task node representing the task to be removed. A zero value indicates self removal, and will cause the next ready task to begin execution. SEE ALSO AddTask Exec/ReplyMsg Exec/ReplyMsg NAME ReplyMsg -- put a message to its reply port SYNOPSIS ReplyMsg(message) A1 FUNCTION This function sends a message to its reply port. This is usually done when the receiver of a message has finished and wants to return it to the sender (so that it can be re-used or deallocated, whatever). INPUT message - a pointer to the message SEE ALSO ReplyMsg Exec/SendIO Exec/SendIO NAME SendIO -- initiate an I/O command SYNOPSIS SendIO(iORequest) A1 FUNCTION This function requests the device driver to initiate the command specified in the given I/O request. The device will return regardless of whether the I/O has completed. INPUTS iORequest - pointer to an I/O request SEE ALSO DoIO, WaitIO Exec/SetExcept Exec/SetExcept NAME SetExcept -- define certain signals to cause exceptions SYNOPSIS oldSignals = SetExcept(newSignals, signalMask) D0 D0 D1 FUNCTION This function defines which of the task's signals will cause an exception. When any of the signals occurs the task's exception handler will be dispatched. If the signal occurred prior to calling SetExcept, the exception will happen immediately. INPUTS newSignals - the new values for the signals specified in signalMask. signalMask - the set of signals to be effected RESULTS oldSignals - the prior exception signals EXAMPLE Get the current state of all exception signals: SetExcept(0,0) Change a few exception signals: SetExcept($1374,$1074) SEE ALSO Signal, SetSignal Exec/SetFunction Exec/SetFunction NAME SetFunction -- change a function vector in a library SYNOPSIS oldFunc = SetFunction(library, funcOffset, funcEntry) D0 A1 A0.W D0 FUNCTION SetFunction is a functional way of changing those parts of a library that are checksummed. They are changed in such a way that the summing process will never falsely declare a library to be invalid. INPUTS library - a pointer to the library to be changed funcOffset - the offset that FuncEntry should be put at. funcEntry - pointer to new function Exec/SetIntVector Exec/SetIntVector NAME SetIntVector -- set a system interrupt vector SYNOPSIS oldInterrupt = SetIntVector(intNumber, interrupt) D0 D0-0:4 A1 FUNCTION This function provides a mechanism for setting the system interrupt vectors. Both the code and data pointers of the vector are set to the new values. A pointer to the old interrupt structure is returned. When the system calls the specified interrupt code the registers are setup as follows: D0 - scratch D1 - scratch (on entry: active portia interrupts) A0 - scratch (on entry: pointer to chipbase) A1 - scratch (on entry: interrupt's data segment) A5 - jump vector register (scratch on call) A6 - library base pointer (scratch on call) all other registers - must be preserved INPUTS intNum - the Portia interrupt bit number (0..14) interrupt - a pointer to a node structure containing the handler's entry point and data segment pointer. It is a good idea to give the node a name so that other users may identify who currently has control of the interrupt. RESULT A pointer to the prior interrupt node which had control of this interrupt. Exec/SetSignal Exec/SetSignal NAME SetSignal -- define the state of this task's signals SYNOPSIS oldSignals = SetSignal(newSignals, signalMask) D0 D0 D1 FUNCTION This function defines the states of the task's signals. This function is considered dangerous. INPUTS newSignals - the new values for the signals specified in signalSet. signalMask - the set of signals to be effected RESULTS oldSignals - the prior values for all signals EXAMPLE Get the current state of all signals: SetSignal(0,0) Clear all signals: SetSignal(0,FFFFFFFFH) SEE ALSO Signal, Wait Exec/SetSR Exec/SetSR NAME SetSR -- get and/or set processor status register SYNOPSIS oldSR = SetSR(newSR, mask) D0 D0 D1 FUNCTION This function provides a means of modifying the CPU status register in a "safe" way (well, how safe can a function like this be anyway?). This function will only effect the status register bits specified in the mask parameter. The prior content of the entire status register is returned. INPUTS newSR - new values for bits specified in the mask. All other bits are not effected. mask - bits to be changed RESULTS oldSR - the entire status register before new bits EXAMPLES To get the current SR: currentSR = SetSR(0,0); To change the processor interrupt level to 3: oldSR = SetSR($0300,$0700); Set processor interrupts back to prior level: SetSR(oldSR,$0700); Exec/SetTaskPri Exec/SetTaskPri NAME SetTaskPri -- get and set the priority of a task SYNOPSIS oldPriority = SetTaskPri(task, priority) D0-0:8 A1 D0-0:8 FUNCTION This function changes the priority of a task regardless of its state. The old priority of the task is returned. A reschedule is performed, and a context switch may result. INPUTS task - task to be affected priority - the new priority for the task RESULT oldPriority - the tasks previous priority Exec/Signal Exec/Signal NAME Signal -- signal a task SYNOPSIS Signal(task, signals) A1 D0 FUNCTION This function signals a task with the given signals. If the task is currently waiting for one or more of these signals, it will be made ready and a reschedule will occur. If the task is not waiting for any of these signals, the signals will be posted to the task for possible later use. A signal may be sent to a task regardless of whether it's running, ready, or waiting. This function is considered "low level". Its main purpose is to support multiple higher level functions like PutMsg. Generally a user need not perform Signals directly. INPUT task - the task to be signalled signals - the signals to be sent SEE ALSO Wait, SetSignal Exec/SumLibrary Exec/SumLibrary NAME SumLibrary -- compute and check the checksum on a library SYNOPSIS SumLibrary(library) A1 FUNCTION SumLibrary computes a new checksum on a library. It can also be used to check an old checksum. If an old checksum does not match and the library has not been marked as changed then the system will alert the user. INPUTS library - a pointer to the library to be changed EXCEPTIONS An alert will occur if the checksum fails. Exec/SuperState Exec/SuperState NAME SuperState -- enter supervisor state with user stack SYNOPSIS oldSysStack = SuperState() D0 FUNCTION Enter supervisor mode while running on the user's stack. The user still has access to user stack variables. Be careful though, the user stack must be large enough to accommodate space for all interrupt data -- this includes all possible nesting of interrupts. This function is a no op when called from supervisor state. RESULTS oldSysStack - system stack pointer Save this. It will come in useful when you return to user state. If the system is already in supervisor mode, oldSysStack is zero. SEE ALSO UserState Exec/UserState Exec/UserState NAME UserState -- return to user state with user stack SYNOPSIS UserState(sysStack) D0 FUNCTION Return to user state with user stack, from supervisor state with user stack. This function is normally used in conjunction with the SuperState function above. This function must not be called from the user state. INPUT sysStack - supervisor stack pointer SEE ALSO SuperState Exec/Wait Exec/Wait NAME Wait -- wait for one or more signals SYNOPSIS signals = Wait(signalSet) D0 D0 FUNCTION This function will cause the current task to suspend waiting for one or more signals. When any of the specified signals occurs, the task will return to the ready state. If a signal occurred prior to calling Wait, the wait condition will be immediately satisfied, and the task will continue to run. This function cannot be called while in supervisor mode! INPUT signalSet - the set of signals for which to wait. Each bit represents a particular signal. RESULTS Exec/WaitIO Exec/WaitIO NAME WaitIO -- wait for completion of an I/O request SYNOPSIS error = WaitIO(iORequest) D0 A1 FUNCTION This function waits for the specified I/O request to complete. If the I/O has already completed, this function will return immediately. This function should be used with care, as it does not return until the I/O request completes; if the I/O never completes, this function will never return, and your task will hang. If this situation is a possibility, it is safer to use the Wait function, which will return when any particular signal is received. This is how I/O timeouts can be properly handled. INPUTS iORequest - pointer to an I/O request block RESULTS error - zero if successful, else an error is returned SEE ALSO SendIO Exec/WaitPort Exec/WaitPort NAME WaitPort -- wait for a given port to be non-empty SYNOPSIS message = WaitPort(port) D0 A0 FUNCTION This function waits for the given port to become non-empty. If necessary, the Wait function will be called to wait for the port signal. If a message is already present at the port, this function will return immediately. The return value is always a pointer to the first message queued (but it is not removed from the queue. INPUT port - a pointer to the message port RETURN message - a pointer to the first available message SEE ALSO GetMsg Exported Exported Imported Imported Included Included