® AMX™ 86 User's Guide First Printing: Last Printing: November 1, 1990 March 1, 2005 Copyright © 1990 - 2005 KADAK Products Ltd.
TECHNICAL SUPPORT KADAK Products Ltd. is committed to technical support for its software products. Our programs are designed to be easily incorporated in your systems and every effort has been made to eliminate errors. Engineering Change Notices (ECNs) are provided periodically to repair faults or to improve performance. You will automatically receive these updates during the product's initial support period.
Copyright © 1990-2005 by KADAK Products Ltd. All rights reserved. No part of this publication may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any language or computer language, in any form or by any means, electronic, mechanical, magnetic, optical, chemical, manual or otherwise, without the prior written permission of KADAK Products Ltd., Vancouver, B.C., CANADA. DISCLAIMER KADAK Products Ltd.
AMX 86 USER'S GUIDE Table of Contents Page Section 1: System Description 1. AMX Overview 1 1.1 Introduction ........................................................................................ 1.2 Glossary ............................................................................................. 1.3 AMX Nomenclature ........................................................................... 2. General AMX Operation 2.1 2.2 2.3 2.4 9 Introduction to Multitasking .................................
AMX 86 USER'S GUIDE Table of Contents (Cont'd.) Page Section 1: System Description (Cont'd.) 6. AMX Semaphore Manager 91 6.1 Introduction ........................................................................................ 6.2 Semaphore Use ................................................................................... 6.3 Semaphore Applications .................................................................... 7. AMX Event Manager 91 93 97 103 7.1 Introduction .............................
AMX 86 USER'S GUIDE Table of Contents (Cont'd.) Page Section 1: System Description (Cont'd.) 12. AMX Linked List Manager 139 12.1 Introduction ...................................................................................... 139 12.2 Linked Lists ...................................................................................... 140 12.3 Linked List Use ................................................................................ 142 13. Advanced Topics 13.1 13.2 13.3 13.4 13.5 13.
AMX 86 USER'S GUIDE Table of Contents (Cont'd.) Page Appendices A. AMX 86 Reserved Words 347 B. AMX 86 Error Codes 349 C. Configuration Generator Specifications 353 C.1 C.2 C.3 C.4 Introduction ....................................................................................... User Parameter File Specification ..................................................... System Configuration Template ........................................................ Porting the Configuration Generator ...........
1. AMX Overview 1.1 Introduction The AMX™ Multitasking Executive provides a simple solution to the complexity of realtime multitasking. AMX supervises the orderly execution of a set of application program modules called tasks. AMX allows the system designer to concentrate on the application without becoming overly concerned about the multitasking aspects of the solution.
Section Summary This manual is divided into three sections. Each section is divided into chapters. Section 1 of this manual describes the AMX Multitasking System and how it is used. Separate chapters are provided for each of the AMX managers. Section 2 describes the AMX System Configuration Builder and the manner in which it is used to create your AMX System Configuration Module. Section 3 is the application programming guide.
1.2 Glossary Buffer Pool A collection of data buffers whose use is controlled by the AMX Buffer Manager. Buffer Pool Id The handle assigned to a buffer pool by AMX for use as a unique buffer pool identifier. Circular List An application data structure used to maintain a list of 1, 2 or 4 byte elements with the ability to add and remove elements at both the top (head) and bottom (tail) of the list.
Interrupt Handler An application procedure called from an ISP root to service an interrupting device. Interrupt Service Procedure (ISP) An AMX or application procedure which is executed in response to an external device interrupt request. ISP See Interrupt Service Procedure ISP root The ISP code fragment (produced by AMX function ajispm()) which informs AMX that an interrupt has occurred and calls an application Interrupt Handler.
Message Queue An AMX data structure used to manage messages sent to a task mailbox or message exchange. A separate message queue is provided for each of the four message priorities which a task or message exchange can support. Message Priority Identifies which of a task's or message exchange's four message queues is to receive the AMX message. Nonconforming ISP An Interrupt Service Procedure which bypasses AMX completely and hence cannot use any AMX service procedures.
Task An application procedure which is executed by AMX in a way which makes it look as though all such procedures are executing at once. Task Control Block (TCB) A private data structure maintained by AMX for each task in the system. 6 Task Id The handle assigned to a task by AMX for use as a unique task identifier. Task Priority The priority at which a task executes. Tasks which have the same task priority are actually ordered in priority according to the order in which the tasks were created.
1.3 AMX Nomenclature The following nomenclature has been adopted throughout the AMX User's Guide.
This page left blank intentionally.
2. General AMX Operation 2.1 Introduction to Multitasking A real-time system is characterized by the need to respond rapidly to events occurring asynchronously in time. A multitasking system is one in which a number of activities or processes must be performed simultaneously without interference with each other. A system in which several activities must operate simultaneously with time-critical precision is called a real-time multitasking system.
Alarm scanning will likely be hardware dependent. We will simplify matters by assuming that a scanning task must examine all digital inputs every 100 ms. The task must be capable of detecting alarm changes in the digital inputs. When an alarm is detected, the scanning task must initiate the logging of a message. However, the scanning task is not allowed the luxury of waiting until the message is printed. It must continue scanning for additional alarms at the same 100 ms rate.
2.2 AMX Operation AMX Startup Each AMX-based system consists of the AMX executive program and a set of application tasks and interrupt service procedures. This collection of programs resident in the memory of the microprocessor configuration represents the entire operating system. The manner in which the operating system begins execution is application dependent. In ROM-based systems, automatic hardware vectoring to the program start address is often implemented.
Start User AMX Control Flow Function calls Initialization Interrupts Restart Procedure Services Task Scheduler Task N Task A Kernel Task Timer Procedure Clock Interrupt Service Procedure Interrupt Supervisor Clock Handler Figure 2.
The Task Scheduler Following system initialization, AMX proceeds to its Task Scheduler. The Task Scheduler searches its list of available tasks to determine the highest priority task capable of execution. Task execution priorities are determined by the system designer. If no task is ready to begin execution, AMX sits with interrupts enabled, waiting for some external event to generate an interrupt. AMX begins task execution at the task's defined start address.
The Interrupt Supervisor Tasks execute with the processor interrupt facility enabled to permit service of external devices. When an external interrupt occurs, the task is interrupted in the manner dictated by the processor. The processor automatically saves the return address and some subset of the processor state (registers, flags, etc.) and branches to an Interrupt Service Procedure (ISP). The exact vectoring method is determined by the hardware configuration employed in the system.
Timing Facilities The AMX Timer Manager provides a Clock Handler and a Kernel Task to provide complete timing control for your real-time application. The AMX Clock Handler is independent of any particular hardware configuration. If AMX timing facilities are to be utilized, a real-time clock must be included in the configuration. The hardware clock interrupt must be serviced by a conforming ISP.
Message Queuing One of the more powerful features of AMX is its ability to queue messages for tasks. The queuing facility permits messages to pile up in a controlled fashion, freeing the ISP, Timer Procedure or task which is sending the message to continue with its appointed function. If a task sends a message, it can suspend itself until the message has been received and processed by some other task.
2.3 AMX Managers AMX provides a set of managers to simplify event synchronization, resource manipulation and memory allocation. Not all applications will make use of all of the managers. The system designer can decide which of the AMX managers is best suited for a particular application. The Time/Date Manager provides Y2K compliant time of day calendar support if required. The AMX calendar clock includes second, minute, hour, day, month, year and day of the week.
The AMX 86 Task Mailbox facility provides a general purpose message queuing mechanism for tasks. This service is not provided by a separate AMX manager; it is an inherent feature of AMX 86. Any task can have up to four private mailboxes in which the task can receive AMX messages. Tasks, ISPs or Timer Procedures can send messages to such a task mailbox. The messages are ordered in each task mailbox according to their order of arrival.
The Circular List Manager provides a general purpose circular list facility for maintaining compact lists of 8-bit, 16-bit or 32-bit variables. Circular lists are particularly useful for managing character streams associated with input/output devices. The Linked List Manager provides a fast, general purpose doubly-linked list facility for maintaining lists of arbitrary application data structures (objects).
2.4 Starting AMX An AMX operating system consists of AMX, the subset of its managers which you choose to use and your complement of application programs. All of these modules are connected together to form the AMX operating system as described in the AMX Tool Guide. Before launching AMX, you must establish the required operating mode for the particular target processor you are using. AMX 86 operates only in the 8086 real mode.
Permanent Launch In most applications, your AMX operating system is resident in ROM or loaded into RAM. AMX is started in real mode and given permanent control of the processor. An AMX system can be launched permanently from a main program coded in C as illustrated in the following example. The implication of starting AMX from a main C program is that a C startup module has already provided a stack before procedure main was called.
An AMX system can be launched permanently from a startup module coded in assembly language as illustrated in the following example. Systems of this type begin execution at the AMX entry point AAENTR with the launch parameter in register BX. Register BX[0] must be set to zero to indicate that a permanent launch is required. Register pair ES:SI must provide a pointer to the User Parameter Table in the System Configuration Module which defines the characteristics of your AMX system.
Temporary Launch Your AMX operating system can be started, allowed to run for a while and then stopped. This type of operation is called a temporary launch. The most common application of this type occurs on PC compatibles. An AMX operating system is started from DOS, allowed to operate for a while and then forced to return to DOS. If you wish to start an AMX system for temporary execution from a module coded in assembler, refer to the source code for procedure ajentr in AMX source file AJ831KI.
When an AMX system is launched for temporary execution, it executes until one of your application tasks calls the AMX exit procedure ajexit requesting an orderly shutdown of the AMX system (see Chapter 3.11). The ajexit caller can return two parameters to the procedure that launched AMX. One of these parameters is an integer which is received as errcode from the ajentr call. The other is a double word parameter stored in the variable provided in the call to ajentr.
3. Application Tasks 3.1 Task Creation The AMX Multitasking Executive provides a simple solution to the complexity of realtime multitasking. AMX supervises the orderly execution of a set of application program modules called tasks. Each task solves a particular problem and provides a specific functional capability within the system. The maximum number of tasks in a system is user defined in your System Configuration Module (see Chapter 14.5).
Tasks which do not receive messages are written as Large or Medium model C functions without formal parameters. These tasks must be started using AMX procedure ajtrig. For this reason, such tasks are called trigger tasks. For example, a task that immediately ends would appear as follows: void cdecl task1(void) { } Tasks which must receive a message are written as Large or Medium model C functions which receive a set of parameters. Tasks that receive messages are called message tasks.
3.2 Task States A task is always in one of the following states: Idle Ready Run Wait Halt When a task is created, AMX assigns it a Task Control Block and sets it in the idle state. An idle task has no outstanding requests to execute pending. It is waiting to be triggered. A ready task has an outstanding request to execute or is ready to resume execution after having been interrupted or waiting. A task which is executing is the only task which is in the run state.
Idle no requests outstanding ajtrig - trigger a task ajsend - send message to a task Ready no higher priority task running task ends or is interrupted Run ajwait ajwatm - wait - timed wait ajsenw - send message to task mailbox and wait for ack ajevwat ajmxwat ajsgwat ajsmrsv ajsmwat - wait for event - wait on a message exchange - wait for task signal - reserve a resource - wait on a semaphore Wait event of interest or timeout occurs Figure 3.
3.3 Starting a Task At startup, AMX initializes all predefined application tasks into an idle state. Once idle, a task cannot execute until AMX receives a directive to start the task. How then does an AMX system get off the ground? Three AMX directives are provided to start a task. These directives are procedure calls to AMX. The ajtrig call is used to trigger a task without a message. The ajsend call is used to send a message to a task.
3.4 Task Priority Task priorities are used by the AMX Task Scheduler to determine which task to execute. At all times, the task with the highest priority which is capable of execution will run. A task's priority is defined at the time the task is created. Task priorities range from 0 (highest) to 255 (lowest). Priorities 0 and 128 to 255 inclusive are reserved for AMX use. The AMX Kernel Task executes at priority 0 above all other tasks. Application tasks can be assigned priorities 1 to 127 inclusive.
3.5 Task Execution AMX starts a task by making a FAR procedure call to the task. AMX starts execution of a task at the task start address specified in the task's definition. The task is started in response to a request for its execution. Requests can come from Restart Procedures, tasks, Interrupt Service Procedures or Timer Procedures (see Chapter 3.3). AMX starts the task when no tasks of higher priority are capable of execution.
3.6 Task and Event Synchronization AMX offers several simple forms of task/event synchronization. Using the ajwait call, a task can unconditionally wait for an event. The event can be task dependent, device dependent or time dependent. The task, having issued an ajwait call, remains suspended unconditionally until another task, an Interrupt Service Procedure or a Timer Procedure issues an ajwake call requesting AMX to wake up the particular waiting task.
The simple features included in the AMX kernel are augmented by three powerful mechanisms for event synchronization provided by separate AMX managers. The Semaphore Manager provides counting semaphores with queuing and timeout facilities for mutual exclusion and resource management. It also offers a unique resource semaphore which extends to semaphores the concept of ownership of the corresponding resource. The Event Manager offers the best solution for complex event coordination.
3.7 Task Timing The AMX Clock Handler and Kernel Task act as a Timer Manager providing timing facilities for use by tasks. It has been shown in Chapter 3.6 that tasks can wait for an event to occur with an automatic timeout. The task is suspended following its wait request until the event occurs or the interval specified in the call expires. The ajwatm call to AMX can also be used by a task to implement a delay. The delay interval is specified in system ticks.
3.8 Ending a Task When a task completes its appointed function, it must relinquish control of the processor to AMX. The AMX Task Scheduler will then give control of the processor to the next highest priority task ready to execute. AMX starts a task by a FAR procedure call to the task at the task start address. The task program is, therefore, a procedure. When the task is finished, it returns to AMX in normal end-of-procedure fashion. A task may wish to abort execution under error conditions.
3.9 Message Passing AMX supports the passing of a message to a task mailbox or message exchange. Messages can be sent to a task by: Application Tasks Interrupt Service Procedures Timer Procedures Restart Procedures Exit Procedures You can send a message to a task mailbox or message exchange using the AMX procedure ajsend (or its variation ajsendp) or ajmxsnd respectively. The maximum number of parameter bytes that can be sent in a message is configured by you in your System Configuration Module.
AMX uses message envelopes for parameter transmission. AMX gets a free envelope, moves the caller's message parameters into it and adds the envelope to the task mailbox or message exchange message queue. If the sender requested to wait, AMX inserts information into the envelope which allows AMX to remember that the sending task has been suspended waiting for acknowledgement of the receipt of its message by some other task.
Figure 3.9-1 provides an example of the manner in which messages are allowed to queue on a message exchange. The same message queuing technique is used when messages are sent to a task's private mailboxes within its Task Control Block (TCB). In the example, the following situation is assumed to exist at the message exchange on which the destination task is waiting. The message exchange has four message queues corresponding to the four priority levels at which it can post messages.
In due course the destination task will continue to execute and complete its processing of the current message, X. The destination task will then request AMX for a message from the message exchange three more times in succession to process messages I, J and K. Finally, the message from task YY will be retrieved from the message exchange and processed. Figure 3.9-2 illustrates the situation at the destination task at the instant it begins to process the message from task YY.
It is important to note that a copy of the sender's message parameters is sent to the destination task. Once the sender's parameters have been copied into the message envelope, the caller is free to reuse the parameter storage if desired. Thus, as soon as procedure ajsend or ajmxsnd (or any of their variations) returns to its caller, the parameter variables are free for reuse. A message which is delivered to a task in one of its mailboxes is copied directly to the task's stack prior to starting the task.
Message Extension AMX delivers messages to a task by copying the message from a message envelope to a message frame on the task's stack. AMX also presents an extension to the application message on the task's stack. The message extension identifies who sent the message and, if a task, whether the sender is waiting for a response. The message extension is provided for the use of private AMX tasks such as the Kernel Task. Application tasks should rarely be aware of its presence.
3.10 Restart Procedures The manner in which the operating system begins execution is application dependent. Execution begins in the user domain providing the opportunity for hardware specific and application dependent setup prior to the initialization of the AMX system. For example, hardware interfaces may require custom configuring. In some systems, it might be desirable to perform a memory integrity check before system startup is permitted.
Restart Procedures can enable specific device interrupts if required. Note that interrupts from a device should not be enabled until the application ISP has been installed and made ready to handle the interrupting device. Restart Procedures should not enable the processor interrupt system if your launch parameter indicated that AMX was to execute with interrupts disabled during the launch. In this case, AMX will disable interrupts upon completion of your Restart Procedure.
3.11 Exit Procedures An AMX system can be shut down in an orderly fashion by a task call to procedure ajexit. The manner in which the operating system ends execution is application dependent. For example, hardware interfaces may require restoration to their initial states. AMX supervises the shutdown process by sequentially calling all of the application Exit Procedures in the order defined in the Exit Procedure List in your System Configuration Module (see Chapter 14.6).
Exit Procedures execute in the context of the task which issued the ajexit call. They are therefore free to use all services normally available to tasks. For instance, an Exit Procedure could use ajsenw to send a shutdown message to a task and wait for that task to do its shutdown processing. When the Exit Procedure resumes after the ajsenw call, it returns to AMX which then calls the next Exit Procedure in the list.
3.12 Task Enhancements AMX offers several task enhancements which, although rarely used, can occasionally come in handy. These enhancements are briefly summarized below. Task Control Block Extension Within a task's Task Control Block, 16 bytes are reserved for the private use of the task. Their use is completely determined by the application. A Task Control Block for a particular task can be located using procedure ajtktcb. The private storage is located at offset AMTCBUSR in the Task Control Block.
AMX Kernel Task Priority The AMX Kernel Task operates as the highest priority task in your AMX system. Its execution priority is zero. It has the reserved task tag 'AMXK'. Occasionally, an application is encountered in which a task must execute at very high priority in order to cope with the idiosyncrasies of an extremely high speed device. In such cases, the priority of the AMX Kernel Task can be dropped from zero to some lower priority determined by you for your application.
This page left blank intentionally.
4. Interrupt Service Procedures 4.1 The Processor Interrupt Facility The key to event-driven, real-time, multitasking systems is the processor's interrupt facility. Tasks execute with the interrupt facility enabled permitting the system to respond to a real-time event. The hardware interrupt mechanism is an automatic facility provided by the processor. AMX permits the system designer to determine how the hardware interrupt facility will be employed. Tasks must execute with the interrupt facility enabled.
When used with the 8086 family of microprocessors, AMX supports the following exception and interrupt sources: Divide error Non-Maskable interrupt Overflow Bounds error External devices (DIV or IDIV instruction) (NMI hardware signal) (INTO instruction) (BOUND instruction) (INTR hardware signal) All other special processor exceptions such as invalid opcode (type 6) or the 80386 general protection exception (type 13) are not handled by AMX. They must be specifically serviced by your own exception handler.
4.2 ISPs for External Interrupts Two types of ISPs exist: nonconforming ISPs and conforming ISPs. Nonconforming ISPs A nonconforming ISP must quickly service the device to remove the interrupting condition. The ISP must preserve all registers which it uses. The nonconforming ISP cannot make calls to any AMX service procedures. The nonconforming ISP executes in the context of the process (task, ISP, AMX kernel) which was interrupted. The ISP therefore uses the stack of the interrupted process.
If the Interrupt Handler requested AMX to initiate or resume execution of some task of higher priority than the interrupted task, the AMX Interrupt Supervisor suspends the interrupted task and marks it as ready to resume execution at the earliest opportunity. The AMX Task Scheduler is then invoked to determine the highest priority task capable of execution. If interrupts nest, the Interrupt Supervisor defers its task switching checks until all of the concurrent interrupts have been serviced.
Conforming ISP Construction The construction of an Interrupt Service Procedure (ISP) to service an external interrupt is a simple process. The conforming ISP consists of two parts: the ISP root and your Interrupt Handler. The ISP root is a code fragment most easily created using procedure ajispm. The Interrupt Handler can be written in as a Large or Medium model C function without formal parameters. If the C function makes any calls to AMX, restrictions for ISPs must be obeyed.
The Interrupt Service Procedure should be coded using assembly language if speed of execution is critical. EXTRN EXTRN AAINT:FAR AAINX:FAR ; DVC_CODE SEGMENT BYTE 'CODE' ; PUBLIC DVCISP ; The ISP is located in user program memory ; ASSUME CS:DVC_CODE ; DVCISP PROC FAR CALL AAINT ;let AMX know : : Perform all device service. All registers are free for use. Interrupts may be enabled if nesting is supported.
The AMX Interrupt Supervisor, when invoked, switches to an Interrupt Stack provided by you in your System Configuration Module. The AMX Interrupt Supervisor then returns to the application ISP. The ISP must perform all services required by the device. Upon return to the ISP from the AMX Interrupt Supervisor entry procedure AAINT, the registers are initialized as follows. Interrupts are disabled. All registers are free for use.
4.3 Nested Interrupts AMX supports nested interrupts. The AMX Interrupt Supervisor maintains a private nesting level indicator. AMX must be informed of the start (AAINT) and end (AAINX) of each interrupt. When AMX sees that a task has been interrupted, it switches to a predefined Interrupt Stack. If AMX detects that the interrupt has occurred during execution of a device Interrupt Service Procedure, then no stack switching occurs. The interrupted ISP is suspended and the new ISP is started.
4.4 ISP/Task Communication AMX provides a set of service procedures to ease the communication between tasks and device Interrupt Handlers. These AMX procedures simplify event synchronization and permit parameter passing to tasks. Wait/Wake Synchronization The ajwait/ajwake pair of procedures is often used for event synchronization. A task issues an ajwait call to AMX to wait unconditionally for an event.
Semaphore Synchronization The AMX Semaphore Manager provides an even more powerful synchronization capability. It provides the automatic timeout facility and also allows more than one task to wait for the same event, with each task determining its own waiting priority. Furthermore, the Interrupt Handler need not know the identity of the waiting tasks (if any) or their chosen waiting priorities.
Task Triggering An Interrupt Handler can communicate with a task by invoking the task's execution. When an interrupt occurs, the Interrupt Handler issues the ajtrig call to AMX identifying the task which it wishes to have executed. This technique can be very useful for handling slowly occurring events. For example, a device generates an interrupt and the Interrupt Handler responds by acquiring a block of data from the device.
4.5 Task Error Traps The 80x86 processor automatically detects the occurrence of execution errors such as division by zero, arithmetic overflow or an array bound violation. These errors, by their very nature, must be handled by the application in the context of the task in which they occur. AMX offers tasks a convenient method of trapping such errors. For each task, AMX maintains a pointer to a task trap handler for each detectable error.
The task trap handler can be written as a Large or Medium model C function with formal parameters. #include "amx831sd.h" /* AMX Structure Definitions*/ void cdecl tdiverr( struct amxregs regs, void FAR *faultp) { : Process the error : } /* Register structure /* Fault pointer */ */ Since the task trap handler executes in the context of the task, the task's stack must account for the stack used by the handler.
Note that the C trap handler receives a structure amxregs passed by value. If your C compiler does not allow such declarations, you can use casts to coerce access to the parameters on the stack as follows: #include "amx831sd.
INCLUDE AMX831SD.
4.6 Non-Maskable Interrupt The Intel 80x86 processor and equivalents provide a non-maskable interrupt (NMI). This interrupt cannot be inhibited by software. You have complete control over the non-maskable interrupt ISP. Usually, the NMI interrupt is used to signal a catastrophic event such as a pending loss of power. The ISP must process the interrupt in an application-dependent fashion, restore all registers and return to the point of interruption if feasible.
4.7 Special Interrupts Nonconforming Interrupts In some systems there may be devices which generate interrupts requiring no communication or synchronization with any task in the system. For example, a highspeed scanner can interrupt the processor whenever new data readings are available. The ISP reads the new data and stores it in memory for subsequent use by any module requiring the information. These modules always use the most recently available value as seen in memory.
Shared Interrupt Handlers Occasionally a single Interrupt Handler can be used to service more than one identical device. For example, an Interrupt Handler for an asynchronous serial I/O device (UART) could be used to service the UART for each of several communication lines. For the Interrupt Handler to be shared, the code must be reentrant. This usually implies that the information unique to each UART (such as the device port address and line status) must be in a data structure accessible by the handler.
The two device ISP roots are illustrated below. Each of the ISP roots calls the Interrupt Handler deviceih passing it a pointer to a unique, public, device dependent data structure (dcbA or dcbB). Note that most common C compilers add leading underscores to function and variable names declared in C. Your application must install the pointers to ISP roots DVCROOT1 and DVCROOT2 into the processor Interrupt Vector Table prior to enabling interrupt generation by the corresponding devices.
4.8 Vector Table Initialization The 80x86 processor operating in real mode vectors to an Interrupt Service Procedure (ISP) directly through its Interrupt Vector Table which, in AMX nomenclature, is simply called the AMX Vector Table. The Vector Table may be located in RAM or ROM as dictated by your hardware configuration. If the Vector Table is in RAM, it can be further characterized as alterable or not.
5. AMX Timing Control 5.1 Introduction to Timing Facilities Most real-time systems are characterized by the need to provide precise control over the timing of activities. A hardware clock provides the timing source; AMX provides the control over its use. The unit of time in an AMX system is the system tick which is a fixed interval derived from the hardware clock. The system tick interval is user selectable. Typically, it is set at 10 ms or 100 ms.
Calendar Clock The AMX Time/Date Manager provides Y2K compliant time of day calendar support if required. The AMX calendar clock includes second, minute, hour, day, month, year and day of the week. AMX services are provided to set and read the calendar clock. A formatting procedure is also provided to translate the calendar time and date from the internal format in which it is maintained by AMX into an ASCII string in several of the most popular formats.
5.2 AMX Clock Handler and Kernel Task AMX includes a conforming clock ISP root, a Clock Handler and a Kernel Task to provide timing facilities. Whenever a clock interrupt occurs, the clock ISP root calls your application clock Interrupt Handler to dismiss the hardware clock interrupt. The ISP root then calls the AMX Clock Handler to trigger the AMX Kernel Task if required.
Clock ISP Implementation AMX can provide timing facilities only if a hardware clock interrupt is available. For efficiency, it is recommended that the clock ISP be coded in assembly language as illustrated below. Note that the clock ISP root and Interrupt Handler have been merged, making the clock ISP a single body of code. It is assumed in this example that interrupt number 33 has been allocated for clock use.
In this example, the clock ISP pointer (CLKISP) must be installed into vector number 33 in the processor Interrupt Vector Table (IVT). AMX service procedure AAIVTW has been used in a Restart Procedure for this purpose. When the clock interrupt occurs, the processor disables the interrupt facility, saves the flags and the return address on the interrupted task's stack and fetches the ISP pointer from vector 33 in the IVT. The processor then jumps to the clock ISP at address CLKISP in program memory.
It is preferred that the AMX Clock Handler be called from a clock ISP coded in assembly language as in the example already provided. However, it is possible to code the clock ISP in C as indicated in the following example. This C solution is not recommended since it significantly increases the service overhead for every clock interrupt. The clock ISP and Restart Procedure can be written as Large or Medium model C functions without formal parameters. 74 #include "amx831cf.
5.3 Interval Timers and Timer Procedures AMX supports any number of application interval timers in a system. The maximum number in a system is defined in your System Configuration Module (see Chapter 14.5). A timer must be created by an application before it can be used. Restart Procedures, tasks, ISPs and Timer Procedures can create timers. It is recommended that only Restart Procedures and tasks be used to create timers. AMX procedure ajtmcre is used to create a timer.
The AMX service procedures which can be called from a Timer Procedure include the following: ajtrig ajsend ajwake ajsgnl AATRIG AASEND AAWAKE AASGNL Start (trigger) a task with no message Start a task by sending it a message at one of 4 priorities Wake a task which is waiting Signal a task ajtmcre ajtmdel ajtmrd ajtmwr ajtmcnv AATMCRE AATMDEL AATMRD AATMWR AATMCNV Create an interval timer Delete an interval timer Read an interval timer Start/stop an interval timer Convert milliseconds to system ticks
Timer Procedures can be written as Large or Medium model C functions with formal parameters. #include "amx831cf.h" /* AMX C Interface Header */ void cdecl truser( AMXID timerid, struct userblock FAR *userp) { : Do timer expiry processing : } /* Timer Procedure /* timer id /* pointer to user block */ */ */ is the timer id assigned by AMX to the interval timer when it was created. the 32-bit application parameter provided when the timer was created.
The Timer Procedure can be coded in assembler as a FAR procedure as follows: TMR_CODE SEGMENT BYTE 'CODE' ; ; The Timer Procedure is located in user program memory ; ASSUME CS:TMR_CODE ; TRUSER PROC FAR MOV DX,WORD PTR [BP] ;DX = timer id LES BX,DWORD PTR [BP+2] ;ES:BX = 32-bit timer parameter : : Timer Procedure code goes here : : RET ; TRUSER ENDP ; TMR_CODE ENDS 78 KADAK AMX Timing Control
5.4 Task Time Slicing AMX provides task time slicing as an option. The AMX system must be configured to include a clock if time slicing is to be possible. Time slice intervals are then specified as multiples of the AMX system tick. Time slicing is normally disabled. It is enabled with a call to AMX procedure ajtson. It can be disabled again with a subsequent call to ajtsof.
Figure 5.4-1 illustrates the allocation of processing time to two tasks, B and C. Task B was created first with a time slice interval of 100 AMX system ticks. Task C was created later with a time slice interval of 50 AMX system ticks. At time t1, tasks B and C were both triggered by a higher priority task A which then ended. Since task B was created first, it executes first. Thereafter, in the absence of any other higher priority task activity, the processor is shared by tasks B and C as illustrated.
Time slicing can be completely disabled at any time with a call to AMX procedure ajtsof. Procedure ajtson can then be used to enable time slicing. Task time slice intervals can be dynamically adjusted using AMX procedure ajtslv to fine tune the shared use of the processor based on observed effects. The starting and ending of time sliced tasks are not synchronized to the AMX clock.
5.5 Time/Date Manager Most real-time systems require the maintenance of a calendar clock. Time/Date Manager provides this facility. The AMX The Y2K compliant calendar clock maintained by the Time/Date Manager includes second, minute, hour, day, month and year. Leap year is accounted for. The day of the week (Mon to Sun) is also maintained. An application Scheduling Procedure can be connected to the calendar clock to provide activity scheduling based on the time of day.
Operation The Time/Date Manager includes two components: an AMX Restart Procedure and a set of service procedures. If your AMX System Configuration Module enables the Time/Date option, AMX automatically calls the Time/Date Restart Procedure during the launch prior to executing any application Restart Procedure. The calendar clock is set to 00:00:00 Monday October 01/1990 (the distribution date of the Time/Date Manager).
Time/Date Structure The Time/Date Manager provides time and date in the following form. C structure amxtds is defined in the AMX header file AMX831SD.H. Assembler structure AMXTDS is defined in the AMX definition file AMX831SD.DEF. The C and assembler structure definitions are shown below.
Time/Date Validity The century is used as follows. At startup, the Time/Date Restart Procedure resets the century to 0 to indicate that the initial default time and date are incorrect. Note that the initial time and date are valid; they are just not correct. At some later time, an application program can issue a call to the Time/Date service procedure ajtds to set a correct time and date.
The following conditions exist when your Time/Date Scheduling Procedure is called by the Time/Date Manager Interrupts are enabled. All registers are free for use. DS,ES DGROUP segment SS:SP AMX Kernel Stack ready for use BP Offset of parameters on stack The direction flag is set to forward. The Scheduling Procedure can be written as a Large or Medium model C procedure as follows: #include "amx831sd.
Your Time/Date Scheduling Procedure can be coded in assembly language as a FAR procedure as follows: INCLUDE AMX831SD.DEF ;AMX Structure Definitions ; ; TDS_CODE SEGMENT BYTE 'CODE' ; ; Time/Date Scheduling Procedure located in program memory ; ASSUME CS:TDS_CODE ; PUBLIC TDSHD ; TDSHD PROC FAR MOV AL,[BP].AMTDSEC ;AL = seconds : MOV DL,[BP].
Time/Date ASCII Formats The Time/Date Manager procedure ajtdf can be used to format time and date into an ASCII character string in any of several popular formats. The time and date is presented to ajtdf in the standard AMX time/date structure. The ASCII string is returned in a character buffer provided by the caller. See Chapter 16 for the ajtdf calling sequence.
Figure 5.5-1 describes the format specification byte and the effect of each bit in it on the formatting of the time and date.
This page left blank intentionally.
6. AMX Semaphore Manager 6.1 Introduction E.W. Dijkstra introduced two primitive operations to resolve two seemingly unrelated problems: mutually exclusive access by tasks to critical resources and the synchronization of asynchronously occurring activities. The abstract primitives, called P and V operators, operate on a variable called a semaphore. Many variations of these P and V operators have been implemented since their first introduction.
Your use of the Semaphore Manager is optional. If you intend to use it, you must indicate so in your System Configuration Module. You must also provide a hardware clock and include the AMX timing facilities. Semaphores can be predefined in your System Configuration Module which is processed by the Semaphore Manager at startup. Semaphores which are predefined are automatically created by the Semaphore Manager.
6.2 Semaphore Use The Semaphore Manager supports any number of semaphores. The maximum number of semaphores in a system is defined in your System Configuration Module (see Chapter 14.5). The defined maximum sets an upper limit on the number of actual semaphores that can be created in your application. A semaphore must be created by an application before it can be used. Restart Procedures, tasks, ISPs and Timer Procedures can create semaphores.
Counting Semaphore A counting semaphore is created by specifying an initial semaphore count greater than or equal to zero in the call to ajsmcre. When used for mutual exclusion, the semaphore should be given an initial value of one. If a semaphore is initialized with a semaphore value of n, it can be used to control access to n resources of a particular type. For instance, a counting semaphore with an initial count of three could be used to control access to three printers in a system.
Resource Semaphore AMX resource semaphores provide the simplest mechanism for controlling the access to critical resources. Resources may include disk files, I/O devices, database components, regions of memory, specific words of memory or any other entity which is considered to be a resource. An application task requests ownership of a resource with a call to the Semaphore Manager. If the resource is available, the task is granted immediate ownership of it.
If the resource does not become available within the timeout interval specified by the task, the task will be removed from the resource semaphore wait queue and will resume execution with a timeout indication. Tasks which need to use a resource but which cannot wait for the resource to be free can still call ajsmrsv. However, they must specify a timeout value of less than zero so that they will not wait on the resource semaphore queue.
6.3 Semaphore Applications Mutual Exclusion Assume that three tasks, A, B and C, require shared access to a common data structure being used to control some process. Access to the data structure must be mutually exclusive so that one task cannot be modifying the data in the structure while another task is accessing it. A semaphore with an initial count of one is required because there is only one data structure to manage.
#include "amx831cf.h" /* AMX C Interface Header */ static AMXID daccess; /* Data access semaphore id */ /* parameter 1 /* parameter 2 */ */ /* Data variable */ /* Restart Procedure */ /* Create counting semaphore */ /* Task A */ /* Wait for access */ static struct { int dbpar1; int dbpar2; : : } datavar; void cdecl rruser(void) { ajsmcre(&daccess, 1, "DACS"); } void cdecl sttaskA(void) { if (ajsmwat(daccess, 0, 20) == AEROK) { datavar.dbpar1 = 1; /* Set parameters datavar.
Task/Event Synchronization A counting semaphore can be used to provide synchronization between a task waiting for an event and a task, ISP or Timer Procedure in which the event is detected. The following example assumes that a device ISP detects the event. A task creates a counting semaphore with an initial count of zero. The task then starts the device and waits on the semaphore. When the event of interest is detected by the ISP, it signals to the semaphore.
EXTRN EXTRN EXTRN EXTRN AAINT:FAR AAINX:FAR AASMSIG:FAR _SYNCISP:WORD ; ; DVC_CODE SEGMENT BYTE 'CODE' ; ASSUME CS:DVC_CODE ; ; DVCISP PROC FAR CALL AAINT : Clear interrupt source Check for event : MOV BX,_SYNCISP CALL AASMSIG : : CALL AAINX IRET ; DVCISP ENDP ; DVC_CODE ENDS ;enter ISP ;leave ISP ;signal to a semaphore ;ISP synchronization semaphore id ;tell AMX ;BX = semaphore id ;signal to semaphore ;tell AMX ;end of interrupt In this example, we have mixed C and assembly language for illustration
Resource Nesting Assume that two tasks, A and B, have to share a numeric coprocessor. Furthermore, these two tasks also must share a common library procedure ncmath which must use the coprocessor. A resource semaphore must be used because ownership of the numeric coprocessor must be tied to one task at a time and the owner must be allowed to make nested resource reservation calls. In the example, Task A waits indefinitely (timeout value = 0) at priority level 20 for the use of the numeric coprocessor.
#include "amx831cf.
7. AMX Event Manager 7.1 Introduction The AMX Event Manager provides the most general form of event synchronization offered by AMX. The Event Manager provides a convenient mechanism for separating the tasks waiting for events from the tasks, Timer Procedures and Interrupt Service Procedures which can signal the event. The Event Manager also allows more than one task to simultaneously wait for a particular event.
The AMX Event Manager provides the following event management services: ajevcre ajevdel ajevsig ajevwat AAEVCRE AAEVDEL AAEVSIG AAEVWAT ajevrd ajevnt ajevtag AAEVRD AAEVNT AAEVTAG Create an event group Delete an event group Signal one or more events in a group Wait for all/any of a set of events in a group (optional timeout) Read current state of events in a group Get state of event flags at completion of event wait Find the event group id of an event group with a specific tag Your use of the Event Man
7.2 Event Synchronization The AMX Event Manager supports any number of event groups in a system. Each event group includes 16 event flags. The maximum number of event groups in a system is defined in your System Configuration Module (see Chapter 14.5). The defined maximum sets an upper limit on the number of actual event groups that are available through the Event Manager in your application. Each event in a group is represented by a boolean flag representing the state of the event.
Events are signalled by tasks, ISPs and Timer Procedures. The event is signalled with a call to procedure ajevsig. The caller specifies the group id of the event group which contains the particular event. More than one event can be signalled in a single call to ajevsig. The caller specifies a 16-bit mask identifying the particular event flags in the group and a 16-bit value which specifies the new state of each of these selected event flags.
7.3 Event Flag Application The following example, coded in C, is provided to illustrate the use of the AMX Event Manager for event synchronization. The example shows two tasks, A and B, which must be synchronized to the state of a motor. Task A must wait for the motor to be turned on. Task B must wait for the motor to be on and up to its maximum speed. A 100 millisecond interval timer samples a motor control status register to determine the state of the motor.
#include "amx831cf.
void cdecl sttaskA(void) { /* Task A /* Wait forever for motor on if (ajevwat(motorgroup, MOTORON, MOTORON, 0, 0) == AEROK) { : Motor is on. Process accordingly. : } } void cdecl sttaskB(void) { /* Task B /* Wait 5 seconds for motor /* on and at maximum speed if (ajevwat(motorgroup, MOTOREVT, MOTORON + MOTORMAX, 1, ajtmcnv(5000)) == AERTMO) { : Motor not on and up to speed. Take recovery action. : } */ */ */ */ */ else { : Motor is on and up to speed. Process accordingly.
This page left blank intentionally.
8. AMX Message Exchange Manager 8.1 Introduction The AMX Message Exchange Manager provides a very flexible, general purpose mechanism for inter process communication and synchronization using prioritized messages.
The task's wait priority is not to be confused with the message queue priority. The message queue priority determines the priority ordering of messages in the message exchange when no task is waiting for a message. The task's wait priority determines the order of tasks in the wait queue when more than one task is waiting for a message to arrive at an empty message exchange.
8.2 Message Exchange Use The Message Exchange Manager supports any number of message exchanges. The maximum number of message exchanges in a system is defined in your System Configuration Module (see Chapter 14.5). The defined maximum sets an upper limit on the number of actual message exchanges that can be created in your application. A message exchange must be created by an application before it can be used. Restart Procedures, tasks, ISPs and Timer Procedures can create exchanges.
Messages are sent to message exchanges in AMX message envelopes. The Message Exchange Manager gets a free message envelope from the common pool of envelopes maintained by AMX. You must therefore be sure to allocate enough message envelopes to meet the needs of all of your message exchange messages as well as your task messages. Receive Any task, ISP or Timer Procedure can get a message from a message exchange by calling procedure ajmxget.
8.3 Message Exchange Application The following example, coded in C, is provided to illustrate the use of the AMX Message Exchange Manager. This example illustrates a solution to the problem posed in the introduction (Chapter 8.1). Two message processing tasks, A and B, accept and service the messages from the data acquisition and data base tasks and the Timer Procedure. The processing tasks expect messages to arrive within 5 seconds.
#include "amx831cf.
void cdecl sttask(void) { union msgu msgbuf; int status; /* Common task body */ /* Message buffer */ /* Wait at priority 0 for /* up to 5 sec for message status = ajmxwat(msgexch, &msgbuf, ajtmcnv(5000), 0); */ */ if (status == AEROK) { : Process the message in msgbuf.
void cdecl dactask(void) { union msgu msgbuf; /* Data acquisition task */ /* Message buffer */ : Perform data acquisition functions : if (no_error) { : Construct message in msgbuf.umsg : /* Send message at priority 3 ajmxsnd(msgexch, 3, &msgbuf); : } else { /* Error has occurred! : Construct message in msgbuf.
9. AMX Buffer Manager 9.1 Introduction The AMX Buffer Manager simplifies the management of memory buffers in a real-time system. It provides a general mechanism for the allocation and control of fixed size buffers. The AMX Buffer Manager provides fast, efficient access to multiple pools of buffers, each buffer representing a fixed size block of memory.
9.2 Buffer Pool Use The Buffer Manager supports any number of pools of buffers. The maximum number of buffer pools in a system is defined in your System Configuration Module (see Chapter 14.5). The defined maximum sets an upper limit on the number of actual buffer pools that can be created in your application. A pool of buffers consists of any number of buffers of a uniform size measured in bytes. Any even buffer size greater than or equal to eight bytes is allowed, up to the limits of a 64K memory segment.
Get Buffer Once a buffer pool has been created, you may call procedure ajbget to get a buffer from the pool. The Buffer Manager unlinks a buffer from the pool's free list, sets the associated buffer use count to one and returns a pointer to the first byte of the buffer. You may then store and retrieve any data in the buffer as desired. If there are no free buffers available in the pool when a request to get a buffer from the pool is made, the Buffer Manager returns an error indication to the caller.
9.3 Buffer Applications Consider the following example. A process control system using AMX has a printer on which errors and status messages are to be logged. These messages are generated by several tasks as they perform their process control functions. These tasks must not wait for the printer because they have more important work to do. Furthermore, each message size may exceed the standard AMX message size. A printer task receives the messages from the other tasks and outputs them to the printer.
These solutions each have their own advantages and disadvantages. Method 1 requires twice as many buffers as the other methods and requires extra processor time to copy the message twice. Method 2 cannot display the message simultaneously on both the CRT and printer. Also, method 2 requires the display task to know about the printer task's mailbox. Method 3 is the most desirable.
9.4 Buffer Manager Caveats Although the Buffer Manager attempts to check as many error conditions as possible, it cannot protect against a bad system design. However, if a little care is taken during system design, the Buffer Manager can help make a system more reliable than one that uses an ad hoc buffer management method. The most important concept to understand about the Buffer Manager is buffer ownership. The Buffer Manager owns all free buffers. You must never modify these in any way.
10. AMX Memory Manager 10.1 Introduction The AMX Memory Manager simplifies the management of memory in an AMX system. It provides a general mechanism for the dynamic allocation and control of memory and is specifically designed for use in a multitasking environment. Multitasking adds particular difficulties to the general problem of memory allocation.
The AMX Memory Manager provides the following memory management services: ajmget ajmfre ajmgsz ajmau ajmset ajmsetf ajmhan ajmgeh AAMGET AAMFRE AAMGSZ AAMAU AAMSET Get a block of memory Release a block of memory Get the size of a block of memory Add to block use count Set memory to a pattern AAMHAN AAMGEH Create a handle to a private memory section Get a block of memory from a private memory section Your use of the Memory Manager is optional.
10.2 Nomenclature The following nomenclature has been adopted by the Memory Manager. A Memory Section is a contiguous, double word aligned area of Random Access Memory Random (RAM) which has been specified by the user to be under the control of the Memory Manager. A section can exceed 64K bytes in size. The AMX Memory Pool is the private collection of one or more memory sections under the control of the Memory Manager from which tasks can request memory to be allocated for their private use.
10.3 Memory Allocation The Memory Manager maintains a single memory pool. The memory pool consists of any number of memory sections of varying sizes measured in bytes. Any memory section size which is a multiple of 4 and greater than or equal to 64 bytes is allowed. Usually the memory pool consists of a single large memory section. Memory sections are given to the Memory Manager by your Memory Assignment Procedure at startup.
Use Count When the Memory Manager allocates a block of memory for the use of a task, it sets the block's use count to one. The block owner may call the Memory Manager procedure ajmau to increase the use count. If the use count is increased by one, the block will have to be released twice before it becomes free. The block use count provides the key to memory block ownership. The Memory Manager owns all free blocks in its memory pool. One or more tasks can own an already allocated memory block.
10.4 Private Memory Allocation A particularly unique feature of the Memory Manager permits any block of memory (including those acquired from the Memory Manager) to be treated as a memory section from which smaller private blocks can be dynamically allocated. To use this feature, a task calls procedure ajmhan giving it a pointer to a private area of memory whose access is to be controlled by the Memory Manager. Blocks allocated by procedure ajmget or ajmgeh are suitable for this purpose.
10.5 Memory Assignment The sections of memory which make up the memory pool controlled by the Memory Manager must be provided by your application. The Memory Manager makes no assumptions concerning the whereabouts of the memory over which it has control. Sections of memory are assigned to the Memory Manager by your application. You must provide a Memory Assignment Procedure which will be called by the Memory Manager to acquire the memory sections over which it is to have control.
10.6 Memory Assignment Procedure An application Memory Assignment Procedure must be provided to dynamically assign memory sections to the Memory Manager. The Memory Assignment Procedure is called by the Memory Manager when AMX is started, prior to execution of any of your Restart Procedures. The name of your Memory Assignment Procedure must be provided in your System Configuration Module (see Chapter 14.5). The Memory Assignment Procedure receives two pointers as parameters.
Your Memory Assignment Procedure can be coded as a Large or Medium model C procedure with formal parameters as follows.
The Memory Assignment Procedure can be coded in assembler as a FAR procedure.
11. AMX Circular List Manager 11.1 Circular Lists The AMX Circular List Manager provides a general circular list facility for use by application program modules. Circular lists must be located in alterable memory (RAM). A circular list is a data structure used by an application to maintain an ordered list of 8-bit, 16-bit or 32-bit elements. The elements are stored in slots in the list. Each list contains a fixed, user defined number of slots.
11.2 Circular List Use A circular list is created by an application with a call to procedure ajrstl. The caller must provide three parameters: the number of slots in the list, the size of each slot (1, 2 or 4 bytes) and a pointer to RAM storage for the circular list. The number of slots in a circular list is limited only by available memory and by the fact that the list must reside within one 64K byte segment in memory.
11.3 Circular List Structure Circular lists are application data structures which are only accessible by calls to the AMX Circular List Manager. The internal structure of the list is private to the Circular List Manager. Lists can be created dynamically or statically by any application program. The following examples illustrate 8-bit, 16-bit and 32-bit lists created in C. defined to be the number of slots in each list.
The same lists can be coded in assembly language as follows: USER_DATA SEGMENT WORD 'DATA' ; ; Circular Lists must be in program data ; NSLOT EQU 64 ; EVEN ;Force word alignment BYTELIST LABEL WORD DW 4 DUP(?) ;Header DB NSLOT DUP(?) ;Slots ; EVEN ;Force word alignment WORDLIST LABEL WORD DW 4 DUP(?) ;Header DW NSLOT DUP(?) ;Slots ; EVEN ;Force word alignment PNTRLIST LABEL WORD DW 4 DUP(?) ;Header DD NSLOT DUP(?) ;Slots ; USER_DATA ENDS 138 KADAK AMX Circular List Manager
12. AMX Linked List Manager 12.1 Introduction The Linked List Manager provides a general set of fast linked list services suitable for use in real-time systems. The Linked List Manager removes the tedium and potential for serious error inherent in many applications in which list maintenance is implemented by each programmer in unique and varying ways. The Linked List Manager offers a feature not often found in similar utilities.
12.2 Linked Lists Terminology A list header is a structure provided by the application to be used to anchor a list. The list header is used to identify a list. The content of the list header is private to the Linked List Manager. An object is an application data structure which represents the elements which reside on a list. For example, AMX maintains a list of Task Control Blocks (TCBs). Each TCB is an instance of a data structure representing the state of a task. Hence, the TCB qualifies as an object.
Figure 12.2-1 illustrates three doubly linked lists of apples and oranges. All apples and oranges reside on a fruit list. Fresh apples or oranges reside on a fresh list. Rotten apples or oranges reside on a rotten list. The list objects are assumed to be data structures describing apples and oranges. Each object contains two list nodes: one for use with the fresh list or rotten list, the other for use with the fruit list.
12.3 Linked List Use A list consists of a list header and objects linked to the list header by list nodes (or key nodes). Storage for the list header must be provided by you. A pointer to the list header acts as the list identifier. An empty list is created by calling procedure ajlcre with a pointer to the list header storage. When the list is created, you must specify the node offset (byte displacement) at which link nodes (key nodes) will be found in objects which can reside on the list.
The following example coded in C illustrates the use of the Linked List Manager. An object called uobject is defined with a key node at offset keynode in the object. An array of ten objects is provided. A keyed list keylist is created and the ten objects are added to the list in random order. The list is then perused to locate the actual position in the list of the sixth object in the array. The object is removed from the keyed list and added to the tail of a simple doubly linked list called extlist.
void example(void) { int i; struct uobject *objp; int nodeofs; /* Object pointer /* Node offset */ */ nodeofs = (char *)(&objarray[0].keynode) - (char *)&objarray[0]; ajlcre(&keylist, nodeofs); /* Create empty keyed list */ nodeofs = (char *)(&objarray[0].
The following example coded in assembler illustrates the use of the Linked List Manager. The example mimics the operation of the previous C implementation. It illustrates the optimization effects which can be achieved by coding in assembler. ; UOBJECT ID DATA KEYNODE MOREDATA LISTNODE LASTDATA UOBJECT ; OBJSIZ NUMOBJ ; USER_DATA ; KEYLIST EXTLIST ; OBJARRAY ; USER_DATA ; INCLUDE AMX831SD.
USER_CODE ; SEGMENT BYTE 'CODE' ;Code segment ASSUME CS:USER_CODE, DS:USER_DATA, ES:USER_DATA EXTRN RANDOM:FAR PROC MOV MOV MOV FAR AX,SEG USER_DATA DS,AX ES,AX MOV MOV CALL CX,KEYNODE-(BYTE PTR ID) SI,OFFSET KEYLIST AALCRE ;Offset to key node ;A(Keyed list) ;Create keyed list MOV MOV CALL CX,LISTNODE-(BYTE PTR ID) SI,OFFSET EXTLIST AALCRE ;Offset to list node ;A(Extraction list) ;Create extraction list MOV MOV MOV SI,OFFSET KEYLIST BX,OFFSET OBJARRAY DI,1 ;A(keyed list) ;A(first object) ;i
13. Advanced Topics 13.1 Fatal Exit There are a number of conditions which, if encountered by AMX, are considered to be fatal. Any attempt by AMX to continue execution will lead to unpredictable results at best. All of these conditions cause AMX to force a branch to its fatal exit handler at ajfatl. Insufficient Memory The most common of these conditions occurs at startup. Many of the AMX managers include a Restart Procedure which is executed by AMX during its startup phase.
Fatal Exit Procedure AMX allows you to provide a Fatal Exit Procedure of your own by specifying the name of your procedure in your System Configuration Module (see Chapter 14.5). Whenever AMX or your application forces a fatal exit, AMX checks to see if you have provided a Fatal Exit Procedure. If one is present, AMX calls the procedure. If no Fatal Exit Procedure exists or if the procedure returns to AMX, AMX will disable the external interrupt system and halt. Only a hardware reset can be used to recover.
Your Fatal Exit Procedure can be coded as a Large model C procedure as illustrated in the following example. #include "amx831ec.h" /* AMX Error Code Definitions void cdecl fatalexit( int error) /* Fatal exit error code { : Inhibit all interrupt sources Provide an external indication of the fatal condition : } */ */ Halt Locations If AMX takes its fatal exit and you have not provided a Fatal Exit Procedure (or if your procedure returns to AMX), AMX will disable interrupts and halt at entry point AMHALT.
13.2 User Error Procedure Most AMX procedures return error status to the caller. The error status is a signed integer. AEREROK AERxxx AERxxx =0 >0 <0 No error Warning: possible fault Error: may be unrecoverable The defined error codes are summarized in Appendix B. AMX allows you to provide a User Error Procedure to trap all errors generated by calls to AMX functions. You do so by specifying the name of your procedure in your System Configuration Module (see Chapter 14.5).
Your User Error Procedure can be coded in assembly language as a FAR procedure. Upon entry to your User Error Procedure, the following conditions exist: Interrupts are disabled. All registers are free for use. AX AMX error code (see AERxxx definitions) DX Task id of current task (0 if error detected in ISP) DS,ES GROUP segment SS:SP Stack in effect at the time of the error The direction flag is set to forward.
13.3 Task Scheduling Hooks AMX does not provide direct support for specific hardware extensions such as a math coprocessor or a memory management unit. Instead, AMX allows a set of application procedures to be connected to its Task Scheduler. These procedures can save and restore hardware dependent parameters specific to your application whenever a task switch occurs. There are four critical points within the AMX Task Scheduler.
13.4 Abnormal Task Termination A task is a procedure which is called by the AMX Task Scheduler. The task ends execution normally by returning to AMX. AMX provides procedure ajend which can be used by a task to end execution and return to AMX under circumstances in which its stack is deeply nested. These two methods by which a task may end execution are considered normal termination. A task has to be running to end in this fashion. No other task can force a task, other than itself, to end.
Kill a Task A task can be killed. The task is first stopped as just described. All outstanding requests to the task for its execution are purged. The effect is the same as if the task continued to make calls to ajend to end its operation until finally there were no task execution requests remaining. A task can kill itself. A task that has been killed does not cease to exist. Any new requests to trigger the task or to send messages to it will be honored.
A Task Termination Procedure can be coded as a Large or Medium model C procedure as illustrated in the following example. The procedure receives an integer reason code indicating whether the task is being stopped, killed or deleted. The mnemonics for these reason codes are provided in the AMX header file AMX831SD.H. Upon entry to the Task Termination Procedure, the following conditions exist: Interrupts are enabled. All registers are free for use. A reason code is provided as a parameter.
A Task Termination Procedure can be coded in assembler as a FAR procedure as indicated in the following example. The procedure receives an integer reason code indicating whether the task is being stopped, killed or deleted. The mnemonics for these reason codes are provided in the AMX header file AMX831SD.DEF. Upon entry to the procedure, the following conditions exist: Interrupts are enabled. All registers are free for use.
Termination Processing AMX will only stop or kill a task which is running, waiting or ready to execute. A task can be deleted if it is in any of these states or idle. Occasionally, a request to terminate a task will occur while that task is performing some operation which AMX deems to be critical. When this occurs, AMX allows the task to complete the critical operation and then forces the abnormal termination.
13.5 Task Suspend/Resume Some operating systems permit a task to suspend any task, including itself. This feature is then used to implement the equivalent of the AMX task wait procedure ajwait. The ability to arbitrarily suspend a task is one of the most abused privileges afforded by other operating systems.
13.6 Breakpoint Manager The AMX Breakpoint Manager can be used to improve the operation of the debugger that you use to test your AMX system. Your use of the Breakpoint Manager is optional; use it only if it augments your debugger as described below. If you enjoy the use of an in-circuit emulator or hardware assisted debugger, you will not need to use the Breakpoint Manager.
Using the Breakpoint Manager The Breakpoint Manager is included in your application only if it is enabled in your User Parameter File. Use the AMX Configuration Builder to edit your User Parameter File (see Chapter 14.13). Enable the breakpoint support option in the Breakpoint parameter window and generate a new System Configuration Module. Then assemble the module and link your AMX system as described in the AMX 86 Tool Guide.
Interrupt Masking The Breakpoint Manager must be tailored to inhibit interrupts at breakpoints. Which interrupts are to be inhibited and how this is done is both system and hardware dependent. When you include the Breakpoint Manager in your AMX system, module AA831BKA.OBJ is included from the AMX Library. This module contains procedure AMBKOF to inhibit selective interrupts at a breakpoint and procedure AMBKON to restore these interrupts upon resumption from the breakpoint. Module AA831BKA.
NMI Breakpoints Some hardware debuggers may use the non-maskable interrupt (NMI) to generate breakpoints. The Breakpoint Manager can be tailored to support such debuggers by enabling its NMI handler. When an NMI interrupt is detected, the Breakpoint Manager calls the NMI handler to determine if the interrupt is actually a breakpoint. In some 8086 PC configurations, the NMI interrupt is multiplexed to detect memory parity errors and to service a numeric coprocessor such as the Intel 8087, 80287 or 80387.
14. AMX System Configuration 14.1 System Configuration Module The AMX System Configuration Module defines the characteristics of your AMX system. The AMX Configuration Builder, described in Chapter 14.2, will create this module for you. The System Configuration Module includes the following components. The User Parameter Table provides AMX with the following information pertinent to the system you are creating.
14.2 System Configuration Builder The AMX Configuration Builder is a software generation tool which can be used to create your AMX System Configuration Module. The Builder helps to reduce total system implementation time by eliminating the manual generation process by which your System Configuration Module would otherwise have to be produced. The Builder consists of two components: the Configuration Manager and the Configuration Generator.
Enter/Edit/View AMX System Parameters Configuration Manager User Parameter File SYSCFG.UP System Configuration Template File AM831CG.CT Configuration Generator System Documentation Template File AM831CG.CTD System Configuration Module File SYSCFG.TXT SYSCFG.ASM Figure 14.
14.3 Using the Builder Starting the Builder The AMX Configuration Builder will operate on a PC or compatible running the Microsoft® Windows® operating system. The Builder is delivered with the following files. File AM831CM AM831CM AM831CM AM831CG AM831CG AM831CG Purpose .EXE .CNT .HLP .EXE .CT .
Screen Layout Figure 14.3-1 illustrates the Configuration Manager's screen layout. The title bar identifies the User Parameter File being created or edited. Below the title bar is the menu bar from which the operations you wish the Manager to perform can be selected. Below the menu bar is an optional Toolbar with buttons for many of the most frequently used menu commands. At the bottom of the screen is the status bar.
Menus All commands to the Configuration Manager are available as items on the menus present on the menu bar. The File menu provides the conventional New, Open, Save and Save As... commands for creating and editing your User Parameter File. It also provides the Exit command. When the System Configuration Module selector icon is the currently active selector, the Generate... command on the File menu can be used to generate your System Configuration Module and the File, Document...
If you have modified some of the fields on a property page and then decide that these modified values are not correct, use the Undo Page command on the Edit menu or Toolbar to force the Configuration Manager to restore the content of all fields on the page to the values which were in effect when you moved to that property page. When you go to save your User Parameter File or prepare to move to another property page, the Configuration Manager will validate all parameters on the page which you are leaving.
14.4 System Parameter Definition The System Parameter window allows you to define the general operating parameters of your AMX system. The layout of the window is shown in Figure 14.3-1 in Chapter 14.3. Kernel Options AMX Message Envelopes AMX passes a message to a mailbox or message exchange in a message envelope. The application parameters which form the message are copied into the envelope and added to the task mailbox or message exchange.
AMX Interrupt Stack Size The AMX Interrupt Supervisor requires a minimum Interrupt Stack size of 128 bytes. The stack size must be a multiple of 4 bytes. In addition to this minimum, you must allocate sufficient stack to satisfy the application ISP with the greatest stack usage. If nested interrupts are possible, then the worst case interrupt nesting must be analyzed and additional interrupt stack size allocated.
Timing Options Hardware Clock Frequency This parameter defines the frequency of the AMX hardware clock in hertz. It is used by AMX to convert milliseconds to equivalent AMX system ticks. If your hardware clock frequency is not integral, round the clock frequency to the nearest non-zero integer. AMX Clock Conversion Factor The AMX system tick is measured in multiples of hardware clock interrupts. This parameter specifies the number of hardware clock interrupts required for each system tick.
14.5 AMX Object Allocation The AMX Object Allocation window allows you to define the number of private AMX objects required for each of the optional AMX managers to be included in your system. The layout of the window is shown below. Maximum Number of Tasks This parameter defines the maximum number of application tasks which your system can support concurrently. The upper limit for this parameter is 100 tasks. The value for this parameter should be the number of predefined tasks (see Chapter 14.
Maximum Number of Semaphores This parameter defines the maximum number of resource and counting semaphores which your system can support concurrently. If you do not require any semaphores, set this parameter to 0. Otherwise, the parameter should be set to the number of predefined semaphores (see Chapter 14.9) plus the maximum number of resource or counting semaphores that you will dynamically create using ajsmcre.
Memory Assignment Procedure Name If you use the AMX Memory Manager, you must provide a Memory Assignment Procedure to assign memory sections to its memory pool for allocation to tasks (see Chapter 10.6). This parameter specifies the name of that procedure. If you are not using the AMX Memory Manager, leave this field empty (blank).
14.6 Restart/Exit Procedure Definition The Launch/Shutdown window displays all of your application Restart and Exit Procedures which will be called by AMX at system startup and shutdown. The layout of the window is shown below. The Restart Procedure List is used to define all of your application Restart Procedures which will be called by AMX at system startup. The Restart Procedures will be called by AMX in the order in which they appear in the list.
Add, Edit and Delete Restart and Exit Procedures To add a new procedure, click on the Add button below the list. A new procedure named ---New--- will appear at the bottom of the list. Click on the name ---New--- and it will be opened ready for editing. Enter the name of your procedure. To edit an existing procedure's name, double click on the name in the object list. The name will be opened ready for editing. To delete an existing procedure, click on the procedure's name in the object list.
14.7 Task Definition The Task Definition window allows you to define the tasks to be automatically created by AMX at system startup. You do not have to predefine all of your tasks in this manner; you may also create tasks dynamically using ajtkcre. The layout of the window is shown below.
Task Tag Each task can have a unique 4-character task tag. This parameter defines that tag. Although AMX does not restrict the content of the task tag field, the Configuration Manager only supports 4 ASCII characters as a tag. Priority This parameter defines the execution priority of the task. Application task priorities range from 1 (highest) to 127 (lowest). More than one task can be given the same task priority.
Medium Model Tasks can be either Large or Medium. If your task is Medium model, check this box. Otherwise, leave this box unchecked. If you declare the task to be Medium, the Builder will allocate the task's stack in a segment which is part of group DGROUP so that DS = SS = DGROUP when the task executes. Task Message Queues (Mailboxes) AMX allows creation of a task with a set of four private message queues (mailboxes) on which the task can receive AMX messages.
14.8 Timer Definition The Timer Definition window allows you to define the timers to be automatically created by AMX at system startup. You do not have to predefine all of your timers in this manner; you may also create timers dynamically using ajtmcre. Note that AMX does not automatically start timers defined this way. Your application must call ajtmwr to actually start the timer. The layout of the window is shown below.
Tag Each timer can have a unique 4-character timer tag. This parameter defines that tag. Although AMX does not restrict the content of the timer tag field, the Configuration Manager only supports 4 ASCII characters as a tag. Id Variable This parameter defines the name of a public variable of type AMXID in the System Configuration Module in which AMX will save the timer id of the timer. Timer Procedure Name This parameter defines the name of the Timer Procedure to be called whenever the timer expires.
14.9 Semaphore Definition The Semaphore Definition window allows you to define the semaphores to be automatically created by AMX at system startup. You do not have to predefine all of your semaphores in this manner; you may also dynamically create resource semaphores and counting semaphores using ajsmcre. The layout of the window is shown below.
Tag Each semaphore can have a unique 4-character semaphore tag. This parameter defines that tag. Although AMX does not restrict the content of the semaphore tag field, the Configuration Manager only supports 4 ASCII characters as a tag. Id Variable This parameter defines the name of a public variable of type AMXID in the System Configuration Module in which AMX will save the semaphore id of the semaphore. Type This option field defines the type of semaphore to be created, resource or counting.
14.10 Event Group Definition The Event Group Definition window allows you to define the event groups to be automatically created by AMX at system startup. You do not have to predefine all of your event groups in this manner; you may also create event groups dynamically using ajevcre. The layout of the window is shown below.
Tag Each event group can have a unique 4-character event group tag. This parameter defines that tag. Although AMX does not restrict the content of the event group tag field, the Configuration Manager only supports 4 ASCII characters as a tag. Id Variable This parameter defines the name of a public variable of type AMXID in the System Configuration Module in which AMX will save the event group id of the event group.
14.11 Message Exchange Definition The Message Exchange Definition window allows you to define the message exchanges to be automatically created by AMX at system startup. You do not have to predefine all of your message exchanges in this manner; you may also create message exchanges dynamically using ajmxcre. The layout of the window is shown below.
Tag Each message exchange can have a unique 4-character message exchange tag. This parameter defines that tag. Although AMX does not restrict the content of the message exchange tag field, the Configuration Manager only supports 4 ASCII characters as a tag. Id Variable This parameter defines the name of a public variable of type AMXID in the System Configuration Module in which AMX will save the message exchange id of the message exchange.
14.12 Buffer Pool Definition The Buffer Pool Definition window allows you to define the buffer pools to be automatically created by AMX at system startup. You do not have to predefine all of your buffer pools in this manner; you may also create buffer pools dynamically using ajbcre. The layout of the window is shown below.
Tag Each buffer pool can have a unique 4-character buffer pool tag. This parameter defines that tag. Although AMX does not restrict the content of the buffer pool tag field, the Configuration Manager only supports 4 ASCII characters as a tag. Id Variable This parameter defines the name of a public variable of type AMXID in the System Configuration Module in which AMX will save the buffer pool id of the buffer pool.
14.13 Breakpoint Manager Definition The AMX Breakpoint Manager can be used to improve the operation of your debugger in the AMX multitasking environment. Your use of the Breakpoint Manager is optional. The layout of the window is shown below. Include Breakpoint Manager If you need to use the AMX Breakpoint Manager to shut off all task activity when your debugger hits a breakpoint, check this box. Otherwise, leave the box unchecked.
This page left blank intentionally.
15. AMX Service Procedures 15.1 Introduction The AMX Library provides a wide variety of services from which the real-time system designer can choose. Many of the services are optional and, if not used, will not even be present in your final AMX system. This section of the AMX User's Guide differs from the others because it is intended for use as a programming guide. The remainder of this chapter introduces you to the AMX programming environment.
15.2 Summary of Services AMX provides a wide variety of services from which the real-time system designer can choose. Many of the services are optional and, if not used, will not even be present in your AMX system. The AMX managers are all optional. All of AMX and its managers are fully reentrant and may be placed in Read Only Memory (ROM). The following lists summarize all of the AMX procedures which are accessible to the user. They are grouped functionally for easy reference.
Task Control ajend ajgmsg AAEND AAGMSG ajresum ajsend ajsendp ajsenw ajsenwp ajsgnl ajsgrd ajsgres ajsgwat ajsusp ajtkcre ajtkid ajtkpry ajtksts ajtktag ajtktcb ajtrig ajwait ajwakc ajwakcs AARESUM AASEND ajwake ajwapr ajwatm AAWAKE AAWAPR AAWATM End task execution Get the highest priority message available Optionally get a message of a specific priority Resume a suspended task Start a task by sending it a message at one of 4 priorities Optionally wait for that task to receive the message AASGNL AASG
Timing Control ajclk ajtick ajtmcnv ajtmcre ajtmdel ajtmrd ajtmtag ajtmwr ajtslv ajtsof ajtson AACLK AATICK AATMCNV AATMCRE AATMDEL AATMRD AATMTAG AATMWR AATSLV AATSOF AATSON AMX Clock Handler Read elapsed system ticks Convert milliseconds to system ticks Create an interval timer Delete an interval timer Read an interval timer Find timer id of timer with a specific tag Start/stop an interval timer Change a task's time slice interval Disable time slicing Enable time slicing Time/Date Manager ajtdf ajtdg a
Message Exchange Manager ajmxcre ajmxdel ajmxget ajmxsnd ajmxsndp ajmxtag ajmxwat AAMXCRE AAMXDEL AAMXGET AAMXSND Create a message exchange Delete a message exchange Get a message from a message exchange (no wait) Send message to a message exchange AAMXTAG AAMXWAT Find exchange id of message exchange with a specific tag Wait for message to arrive at a message exchange (optional timeout) Buffer Manager ajbau ajbcre ajbdel ajbfre ajbget ajbgsz ajbia ajbip ajbtag AABAU AABCRE AABDEL AABFRE AABGET AABGSZ
Circular List Manager ajabl ajatl ajrbl ajrstl ajrtl AAABL AAATL AARBL AARSTL AARTL Add to bottom of circular list Add to top of circular list Remove from bottom of circular list Reset a circular list Remove from top of circular list Linked List Manager ajlcre ajlhead ajlinsc ajlinsh ajlinsk ajlinst ajlmerg ajlnext ajlordk ajlprev ajlrmvc ajlrmvh ajlrmvt ajltail 198 AALCRE AALHEAD AALINSC AALINSH AALINSK AALINST AALMERG AALNEXT AALORDK AALPREV AALRMVC AALRMVH AALRMVT AALTAIL Create an empty list Find
Processor and C Interface Procedures In addition to the services provided by AMX and its managers, the AMX Library includes several C procedures of a general nature which simplify application programming in real-time systems on your target processor.
AMX 86 PC Supervisor Service Procedures In addition to the services provided by AMX and its managers, the AMX 86 PC Supervisor Library includes several C procedures which are of use only if the AMX 86 PC Supervisor is used by your application. These procedures are documented in Chapter 3.9 of the AMX 86 PC Supervisor Reference Manual.
16. AMX 86 Procedures 16.1 Introduction A description of every AMX Library procedure is provided in this chapter. descriptions are ordered alphabetically for easy reference. The Italics are used to distinguish programming examples. Procedure names and variable names which appear in narrative text are also displayed in italics. Occasionally a lower case procedure name or variable name may appear capitalized if it occurs as the first word in a sentence.
Where If the procedure has input parameters, they will be described narratively. Results The outputs produced by the procedure are always defined. The state of the carry, parity, auxiliary, zero, sign and overflow flags are of no consequence when programming in C. In assembly language, the zero and sign flags reflect the value of the error code AERxxxx, if any, returned by AMX in register AX. The direction flag, if used, is always restored to its original state.
Assembly Language Programming If you are programming in assembly language, refer to Appendix E for a description of the AMX assembly language calling conventions. The appendix includes a summary of the input and output register specifications for every AMX procedure. Experienced AMX programmers will usually find that the appendix is all that is required as a programmer's reference guide. New AMX users will want to reference the detailed AMX procedure descriptions provided in this chapter.
FAR pointers are passed to AMX as seg:reg as in the following example. status = ajsenw(taskid, priority, (void FAR *)msg); AX AASEND DX CX[14..0] ES:BX CX[15]=1 Specific bits in a register reg are referenced using the syntax reg[bit] or reg[highbit..lowbit]. In this example, CX[15] is bit 15 of register CX. CX[14..0] is bits 0 to 14 inclusive of register CX. Unspecified bits in a register must be 0.
ajabl ajabl Purpose Add to Bottom of Circular List Used by n Setup char item; /* one byte item int status; . . status = ajabl(&list, item); AX ES:BX CL,CX or DX:CX Where &list item Results n Task AMX 86 Procedures n Timer Procedure n Restart Procedure n Exit Procedure */ is a pointer to a circular list (see ajrstl). is the 1, 2 or 4 byte item to be added to the list. Interrupts are disabled and then restored to their state at the time of the call.
ajatl ajatl Purpose Add to Top of Circular List Used by n Setup char item; /* one byte item int status; . . status = ajatl(&list, item); AX ES:BX CL,CX or DX:CX Where &list item Results n Task 206 n Timer Procedure n Restart Procedure n Exit Procedure */ is a pointer to a circular list (see ajrstl). is the 1, 2 or 4 byte item to be added to the list. Interrupts are disabled and then restored to their state at the time of the call. Status 0 = 1 = -1 = See Also ISP is returned.
ajbau ajbau Purpose Add to Buffer's Use Count Used by n Setup int char int . . status = AX Where n Task buffp ISP Timer Procedure n Restart Procedure n Exit Procedure increment; *buffp; status; ajbau(buffp, increment); ES:BX DX is a pointer to a buffer obtained with an ajbget call. increment Results n is the signed value to be added to the buffer use count. Interrupts are disabled and then restored to their state at the time of the call. is returned.
ajbcre ajbcre Purpose Create a Buffer Pool Used by n Setup #include "amx831sd.h" . . AMXID poolid; struct amxbps pooldef; int status; . . status = ajbcre(&pooldef, &poolid); AX ES:BX DX= Where &pooldef Task o ISP o Timer Procedure n Restart Procedure n Exit Procedure is a pointer to the pool definition which describes the buffer pool to be created. The pool definition structure amxbps is defined in header file AMX831SD.H (see Appendix D).
Results Interrupts are disabled and then restored to their state at the time of the call. Status AEROK AERNFP AERNBF AERBTS is returned. = Call successful = No free buffer pool = No buffers defined in your pool definition = Buffer size defined in your pool definition is too small If the call is unsuccessful, poolid will be undefined.
ajbdel ajbdel Purpose Delete a Buffer Pool Used by n Setup AMXID poolid; int status; . . status = ajbdel(poolid); AX DX Where poolid Results Interrupts are disabled and then restored to their state at the time of the call. Task Status AEROK AERNSP o ISP o Timer Procedure n Restart Procedure n Exit Procedure is the pool id of the buffer pool to be deleted. is returned.
ajbfre ajbfre Purpose Free a Buffer Used by n Setup char *buffp; int status; . . status = ajbfre(buffp); AX ES:BX Where buffp Results Interrupts are disabled and then restored to their state at the time of the call. n Task ISP n Timer Procedure n Restart Procedure n Exit Procedure is a pointer to a buffer obtained by an ajbget call. Status AEROK AERBNU AERNSP is returned.
ajbget ajbget Purpose Get a Buffer Used by n Setup AMXID char int . . status = AX Where Results Task n ISP n Timer Procedure n Restart Procedure n Exit Procedure poolid; *buffp; status; ajbget(poolid, &buffp); DX ES:BX= poolid is the pool id of the pool from which the buffer is to be obtained. &buffp is a pointer to storage for the returned pointer to the buffer. Interrupts are disabled and then restored to their state at the time of the call. Status AEROK AERNSP AERWNB is returned.
ajbgsz ajbgsz Purpose Get Size of Buffer Used by n Setup char unsigned int . . status = AX Where buffp size Results n Task ISP n Timer Procedure n Restart Procedure n Exit Procedure *buffp; int size; status; ajbgsz(buffp, &size); ES:BX CX= is a pointer to a buffer obtained with an ajbget call. is the size of the buffer in bytes. Interrupts are untouched. Status AEROK AERBNU AERNSP is returned.
ajbia ajbia Purpose Initialize (Reset) All Buffer Pools Used by n Setup int status; . . status = ajbia(); AX Results Interrupts are disabled and then restored to their state at the time of the call. Task Status AEROK AERBTS o ISP o Timer Procedure n Restart Procedure n Exit Procedure is returned. = Call successful = Buffer size defined for some pool is too small If this error occurs, the Buffer Manager's private data has been corrupted. You should consider this error to be fatal.
ajbip ajbip Purpose Initialize (Reset) One Buffer Pool Used by n Setup AMXID poolid; int status; . . status = ajbip(poolid); AX DX Where poolid Results Interrupts are disabled and then restored to their state at the time of the call. Task Status AEROK AERNSP AERBTS o ISP o Timer Procedure n Restart Procedure n Exit Procedure is the pool id of the buffer pool to be initialized. is returned.
ajbtag ajbtag Purpose Find a Buffer Pool Used by n Setup char AMXID int . . status = AX Where Task ISP o Timer Procedure n Restart Procedure n Exit Procedure tag[4]; poolid; status; ajbtag(&poolid, tag); DX= [DX:CX] see note is a pointer to storage for the pool id of the buffer pool of interest. &poolid tag Results o is a pointer to a 4-character name identifying the buffer pool of interest. Interrupts are disabled and then restored to their state at the time of the call.
ajcfjlong ajcfjset Purpose ajcfjlong ajcfjset ajcfjset Sets a Mark for a Long Jump ajcfjlong Long Jumps to that Mark These procedures are provided for AMX portability. They are not replacements for C library procedures longjmp or setjmp although they function in a similar manner. Used by n Setup Prototype is in file AMX831CF.H. #include "AMX831CF.
Example #include "AMX831CF.
ajcfstkjmp Purpose ajcfstkjmp Switch Stacks and Jump to a New Procedure This procedure is provided for AMX portability. Used by n Setup Prototype is in file AMX831CF.H. #include "AMX831CF.H" void cdecl ajcfstkjmp(void *vp, void *stackp, void (*procp)()); Where vp o Task o ISP Timer Procedure o Restart Procedure n Exit Procedure is a pointer which is passed as a parameter to the new procedure. is a pointer to a properly aligned block of memory for use as a stack.
ajclk ajclk Purpose AMX Clock Handler Used by o Setup Task n ISP o Timer Procedure o Restart Procedure o Exit Procedure Interrupts must be disabled. ajclk(); Results Interrupts may be enabled and/or disabled and will then be restored to their state at the time of the call. Note This procedure is for Clock Interrupt Service Procedure use only. Restrictions If you code your clock ISP in C, it must be coded as a C interrupt procedure as described in Chapter 5.2.
ajdi ajei ajdi ajei Purpose Disable or Enable Interrupts Used by n Setup ajdi(); ajei(); Results Interrupts are disabled by ajdi() or enabled by ajei(). Task n ISP n Timer Procedure n Restart Procedure n Exit Procedure The interrupt enable flag (IF) in the processor status register (FLAGS) is reset to 0 to disable interrupts or set to 1 to enable interrupts. Restrictions Interrupts should be enabled within a short time after they are disabled or system performance will be degraded.
ajend ajend Purpose End Execution of a Task Used by n Setup ajend(); Results There is no return from ajend. Task o ISP o Timer Procedure o Restart Procedure o Exit Procedure If any task is waiting for this task to finish processing its message, AMX will automatically call ajwakc to wake that task. Restrictions Ajend can only be used to terminate the task which is making the call.
ajentr ajentr Purpose Launch (Enter) the AMX Multitasking System Used by o Setup #include "amx831sd.h" . . struct amxupts FAR *uptp; int launchparm; char *result; int status; . . ajupt(&uptp); status = ajentr(launchparm, uptp, AX BX ES:SI Where Task o ISP launchparm o Timer Procedure Restart Procedure o Exit Procedure &result); DX:BX= is a launch parameter bit mask.
Results No return unless a task calls ajexit. status result = = given to ajexit 4 byte parameter exitinfo given to ajexit errcode Upon return, interrupts are restored to their state upon entry to this procedure. 224 Used By Must only be called by a C main() procedure to start an AMX system.
ajevcre ajevcre Purpose Create an Event Group Used by n Setup AMXID unsigned int char . . status = AX Where Task ISP o Timer Procedure n Restart Procedure n Exit Procedure group; int ivalue; status; tag[4]; ajevcre(&group, ivalue, tag); BX= BX [DX:CX] is a pointer to storage for the event group id of the event group allocated to the caller. &group ivalue tag Results o is the initial value of the 16 event flags in the group. is a 4-character name tag for the event group.
ajevdel ajevdel Purpose Delete an Event Group Used by n Setup AMXID group; int status; . . status = ajevdel(group); AX BX Where group Results Interrupts are disabled and then restored to their state at the time of the call. o Task ISP o Timer Procedure n Restart Procedure n Exit Procedure is the group id of an event group acquired with a call to ajevcre. is returned. = Call successful = Event group is still in use One or more tasks are still waiting for events in the group.
ajevnt ajevnt Purpose Get the Saved Event Flags Used by n Setup unsigned int value; . . value = ajevnt(); AX Where value Results Interrupts are untouched. Task o ISP o Timer Procedure o Restart Procedure n Exit Procedure is the state of the 16 event flags at the time the calling task most recently completed a call to ajevwat. A task can wait for events in an event group by calling ajevwat. Ajevnt is used to retrieve the state of the event flags at the time the ajevwat call completed.
ajevrd ajevrd Purpose Read the Current Event States in an Event Group Used by n Setup AMXID unsigned int . . status = AX Where n Task group ISP n Timer Procedure n Restart Procedure n Exit Procedure group; int value; status; ajevrd(group, &value); BX CX= is the group id of an event group acquired with a call to ajevcre. is a pointer to storage to receive the current state of the 16 event flags of the particular event group. &value Results Interrupts are untouched.
ajevsig ajevsig Purpose Signal Event(s) in an Event Group Used by n Setup AMXID unsigned unsigned int . . status = AX Where n Task group mask ISP n Timer Procedure n Restart Procedure n Exit Procedure group; int mask; int value; status; ajevsig(group, mask, value); see note is the group id of an event group acquired with a call to ajevcre. is a 16-bit mask identifying the event flags of interest in the group.
ajevtag ajevtag Purpose Find an Event Group Used by n Setup AMXID char int . . status = AX Where Task ISP o Timer Procedure n Restart Procedure n Exit Procedure group; tag[4]; status; ajevtag(&group, tag); BX= [DX:CX] see note is a pointer to storage for the event group id if the event group of interest. &group tag Results o is a pointer to a 4-character name identifying the event group of interest. Interrupts are disabled and then restored to their state at the time of the call.
ajevwat ajevwat Purpose Wait for Event(s) in an Event Group Used by n Setup AMXID unsigned unsigned int long int . . status = AX Where o Task group mask ISP o Timer Procedure o Restart Procedure n Exit Procedure group; int mask; int value; match; timeout; status; ajevwat(group, mask, value, match, timeout); see note is the group id of an event group acquired with a call to ajevcre. is a 16-bit mask identifying the event flags of interest in the group.
Results Interrupts are disabled and then enabled upon return. Status AEROK AERTMO AERTMV AERNSG is returned. = Call successful; event match occurred = Timed out before event match occurred = Invalid timeout interval (<0) = Invalid event group id If the events in the group match your event selection criterion when you call ajevwat, the calling task continues execution immediately without waiting.
ajexit ajexit Purpose Leave (Exit) the AMX Multitasking System Used by n Setup char *exitinfo; int errcode; . . ajexit(errcode, exitinfo); CX DX:BX Where errcode Task o ISP o Timer Procedure o Restart Procedure o Exit Procedure is the error code to be returned to the ajentr caller as status. exitinfo is any 4-byte parameter to be copied to the ajentr result variable. In this example, the pointer value exitinfo returned to the ajentr caller.
ajfatl ajfatl Purpose Fatal Exit from AMX Used by n Setup int errcode; . . ajfatl(errcode); CX Task n ISP n Timer Procedure n Restart Procedure n Exit Procedure Where errcode is an error code which will be passed to your Fatal Exit Procedure if one was provided in your User Parameter File. Results There is no return from ajfatl. If you have not provided a Fatal Exit Procedure or if it returns to AMX, AMX will halt at location AMHALT.
ajflagrd, ajflagrddi ajflagwr ajflagrd, ajflagrddi ajflagwr Purpose Read Processor Flags Read Processor Flags and Disable Interrupts Write Processor Flags Used by n Setup unsigned int flags; . . flags = ajflagrd(); flags = ajflagrddi(); Task n ISP n Timer Procedure n Restart Procedure . . ajflagwr(flags); Results Ajflagrd and ajflagrddi return (FLAGS) at the time of the call.
ajgmsg ajgmsg Purpose Get Message from Task Mailbox Used by n Setup int char int . . status = AX Where Task o ISP o Timer Procedure o Restart Procedure n Exit Procedure priority; msg[AMXMSZ]; status; ajgmsg(priority, msg); CX ES:BX is the priority of the task mailbox from which the message is to be fetched.
ajgofs ajgofs Purpose Get Pointer Offset Used by n Setup unsigned int ofs; char FAR *pntr; . . ofs = ajgofs(pntr); Results Interrupts are untouched. Task n ISP n Timer Procedure n Restart Procedure n Exit Procedure The 16-bit unsigned integer value of the offset part of the FAR pointer variable pntr is returned in ofs.
ajgseg ajgseg Purpose Get Pointer Segment Used by n Setup unsigned short int seg; char FAR *pntr; . . seg = ajgseg(pntr); Results Interrupts are untouched. Task n ISP n Timer Procedure n Restart Procedure n Exit Procedure The 16-bit unsigned integer value of the segment selector part of the FAR pointer variable pntr is returned in seg.
ajgsreg ajgsreg Purpose Get Segment Registers Used by n Setup #include "amx831sd.h" . . struct amxsregs sregarray; . . ajgsreg(&sregarray); Where &sregarray Results Interrupts are untouched. See Also ajssreg AMX 86 Procedures Task n ISP n Timer Procedure n Restart Procedure n Exit Procedure is a pointer to storage to receive the current contents of the 8086 segment registers. The structure amxsregs is defined in header file AMX831SD.H (see Appendix D).
ajhook ajhook Purpose Install Task Scheduler Hooks Used by n Setup struct { Task o o Timer ISP Procedure o Restart Procedure n Exit Procedure int (*uhstart)(); int (*uhend)(); int (*uhsuspend)(); int (*uhresume)(); } userhooks; . . ajhook((void FAR *)&userhooks); ES:BX . . ajhook(NULL); ES:BX=0 Where /* Install hooks */ /* Remove hooks */ is a FAR pointer to an array of four pointers to your scheduler procedures.
ajinb ajinw ajinb ajinw Purpose Read an 8-Bit Input Port (Byte) Read a 16-Bit Input Port (Word) Used by n Setup int char short int . . portbyte portword Where Task portno n ISP n Timer Procedure Restart Procedure n Exit Procedure portno; portbyte; portword; = ajinb(portno); = ajinw(portno); is the port number. portbyte is the data byte read. portword is the data word read. Results Interrupts are untouched.
ajint ajinx ajint ajinx Purpose Begin Interrupt Service Used by o Setup ajint(); Results Interrupts are disabled. Task n ISP o Timer Procedure o Restart Procedure o Exit Procedure The AMX Interrupt Supervisor saves all registers on the caller's stack. If a task has just been interrupted, AMX switches to the AMX Interrupt Stack before returning to the ajint caller. Purpose End Interrupt Service Used by o Setup ajinx(); Results Interrupts are disabled.
ajispm Purpose ajispm Make a Conforming ISP Root This procedure creates an AMX root ISP permitting a standard C function to serve as an AMX Interrupt Service Procedure. Used by n Setup #include "amx831sd.h" . . struct amxisps isproot; void intproc(); . . ajispm(intproc, &isproot); CX:DX ES:BX Where intproc Task o ISP o Timer Procedure n Restart Procedure n Exit Procedure is a pointer to a C procedure to be called from the root ISP.
ajitrp Purpose ajitrp Install a Task Trap Handler Install a task trap handler to service divide error, overflow or bound check error traps. Used by n Setup int void int . . status = AX Where Task o inttype 0 4 5 Timer Procedure o Restart Procedure o Exit Procedure inttype; handler(); status; ajitrp(inttype, handler); DX ES:BX is the 8086 interrupt type is a pointer to the task's trap handler for the particular error trap. Interrupts are untouched.
ajivtr ajivtr Purpose Read an Interrupt Vector Used by n Setup int void int . . status = AX Where Task n inttype ISP n Timer Procedure n Restart Procedure n Exit Procedure inttype; (*oldproc)(); status; ajivtr(inttype, &oldproc); DX ES:BX is the 8086 interrupt type (0-255). is a pointer to storage for a copy of the function pointer from the specified entry in the Interrupt Vector Table. &oldproc Results Interrupts are disabled and then restored to their state at the time of the call.
ajivtw ajivtw Purpose Write an Interrupt Vector Used by n Setup int void int . . status = AX Where Task n inttype newproc Results ISP n Timer Procedure n Restart Procedure n Exit Procedure inttype; newproc(); status; ajivtw(inttype, newproc); DX ES:BX is the 8086 interrupt type (0-255). is a pointer to the new interrupt handler. Interrupts are disabled and then restored to their state at the time of the call. Status AEROK AERIPR is returned.
ajivtx ajivtx Purpose Exchange an Interrupt Vector Used by n Setup int void void int . . status = AX Where Task n inttype ISP n Timer Procedure n Restart Procedure n Exit Procedure inttype; (*oldproc)(); newproc(); status; ajivtx(inttype, newproc, &oldproc); DX ES:BX DS:DI is the 8086 interrupt type (0-255). is a pointer to the new interrupt handler. newproc is a pointer to storage for the pointer to the current interrupt handler.
ajlcre ajlcre Purpose Create an Empty List Used by n Setup #include "amx831sd.h" . . struct amxlhs list; int offset; . . ajlcre(&list, offset); DS:SI CX Where &list Task n ISP n Timer Procedure n Restart Procedure n Exit Procedure is a pointer to the list header. is the node offset (in bytes) at which the list node is located in application objects to be linked in this list. offset Results Interrupts are untouched. The list header is initialized to define an empty list.
ajlhead ajlhead Purpose Find First Object on List Used by n Setup #include "amx831sd.h" . . struct amxlhs list; struct appobj *object; . . object = ajlhead(&list); ES:BX DS:SI Where &list Results Interrupts are untouched. n Task ISP n Timer Procedure n Restart Procedure n Exit Procedure is a pointer to the list header. object = pointer to the first object on the list. object = NULL if the list is empty. The object remains on the list.
ajlinsc ajlinsc Purpose Insert Object before Current Object on List Used by n Setup #include "amx831sd.h" . . struct amxlhs list; struct appobj *newobj, *curobj; . . ajlinsc(&list, newobj, curobj); DS:SI ES:BX CX:DI Where &list n Task ISP n Timer Procedure n Restart Procedure n Exit Procedure is a pointer to the list header. is a pointer to the new object to be inserted before the object specified by curobj. newobj curobj Results 250 is a pointer to a particular object on the list.
ajlinsh ajlinsh Purpose Insert Object at Head of List Used by n Setup #include "amx831sd.h" . . struct amxlhs list; struct appobj *object; . . ajlinsh(&list, object); DS:SI ES:BX Where &list n Task AMX 86 Procedures n Timer Procedure n Restart Procedure n Exit Procedure is a pointer to the list header. object Results ISP is a pointer to the object to be inserted as the new head of the list. Interrupts are disabled and then restored to their state at the time of the call.
ajlinsk ajlinsk Purpose Insert Object into Keyed List Used by n Setup #include "amx831sd.h" . . struct amxlhs list; struct appobj *object; unsigned int key; . . ajlinsk(&list, object, key); DS:SI ES:BX CX Where &list n Task Results n Timer Procedure n Restart Procedure n Exit Procedure is a pointer to the list header. object key ISP is a pointer to the object to be inserted into the list. is the insertion key. Objects are inserted in order of ascending key values.
ajlinst ajlinst Purpose Insert Object at Tail of List Used by n Setup #include "amx831sd.h" . . struct amxlhs list; struct appobj *object; . . ajlinst(&list, object); DS:SI ES:BX Where &list n Task AMX 86 Procedures n Timer Procedure n Restart Procedure n Exit Procedure is a pointer to the list header. object Results ISP is a pointer to the object to be inserted as the new tail of the list. Interrupts are disabled and then restored to their state at the time of the call.
ajlmerg ajlmerg Purpose Merge Two Lists Used by n Setup #include "amx831sd.h" . . struct amxlhs destlist, srclist; struct appobj *destobj, *srcobj; . . ajlmerg(&destlist, &srclist, destobj, srcobj); see note Where &destlist Task n ISP &srclist destobj srcobj Results n Timer Procedure n Restart Procedure n Exit Procedure is a pointer to the destination list header. is a pointer to the source list header. is a pointer to the insertion point on the destination list.
Note Assembly language call is: PUSH PUSH PUSH PUSH PUSH PUSH PUSH PUSH CALL ADD srcobj> destobj> destobj> scrlist> scrlist> destlist> destlist> Restrictions You must not merge two lists if either of the lists is a keyed list.
ajlnext ajlnext Purpose Find Next Object on List Used by n Setup #include "amx83lsd.h" . . struct amxlhs list; struct appobj *object, *curobj; . . object = ajlnext(&list, curobj); ES:BX DS:SI ES:BX Where &list n Task n Timer Procedure n Restart Procedure n Exit Procedure is a pointer to the list header. curobj Results ISP is a pointer to an object on this list. Interrupts are untouched. object = pointer to the next object on the list following the object specified by curobj.
ajlordk ajlordk Purpose Reorder an Object in a Keyed List Used by n Setup #include "amx831sd.h" . . struct amxlhs list; struct appobj *object; unsigned int key; . . ajlordk(&list, object, key); DS:SI ES:BX CX Where &list n Task ISP n Timer Procedure n Restart Procedure n Exit Procedure is a pointer to the list header. is a pointer to the object on the list which is to be moved within the list. object key Results is the value of the new key for object.
ajlprev ajlprev Purpose Find Previous Object on List Used by n Setup #include "amx831sd.h" . . struct amxlhs list; struct appobj *object, *curobj; . . object = ajlprev(&list, curobj); ES:BX DS:SI ES:BX Where &list n Task n Timer Procedure n Restart Procedure n Exit Procedure is a pointer to the list header. curobj Results ISP is a pointer to an object on this list. Interrupts are untouched.
ajlrmvc ajlrmvc Purpose Remove Object from List Used by n Setup #include "amx831sd.h" . . struct amxlhs list; struct appobj *object; . . ajlrmvc(&list, object); DS:SI ES:BX Where &list n Task AMX 86 Procedures n Timer Procedure n Restart Procedure n Exit Procedure is a pointer to the list header. object Results ISP is a pointer to the object to be removed from the list. Interrupts are disabled and then restored to their state at the time of call.
ajlrmvh 260 ajlrmvh Purpose Remove Object from Head of List Used by n Setup #include "amx831sd.h" . . struct amxlhs list; struct appobj *object; . . object = ajlrmvh(&list); ES:BX DS:SI Where &list Results Interrupts are disabled and then restored to their state at the time of the call. n Task ISP n Timer Procedure n Restart Procedure n Exit Procedure is a pointer to the list header. object = pointer to the object removed from the head of the list.
ajlrmvt ajlrmvt Purpose Remove Object from Tail of List Used by n Setup #include "amx831sd.h" . . struct amxlhs list; struct appobj *object; . . object = ajlrmvt(&list); ES:BX DS:SI Where &list Results Interrupts are disabled and then restored to their state at the time of the call. AMX 86 Procedures n Task ISP n Timer Procedure n Restart Procedure n Exit Procedure is a pointer to the list header. object = pointer to the object removed from the tail of the list.
ajltail ajltail Purpose Find Last Object on List Used by n Setup #include "amx831sd.h" . . struct amxlhs list; struct appobj *object; . . object = ajltail(&list); ES:BX DS:SI Where &list Results Interrupts are untouched. n Task ISP n Timer Procedure n Restart Procedure n Exit Procedure is a pointer to the list header. object = pointer to the last object on the list. object = NULL if the list is empty. The object remains on the list.
ajmau ajmau Purpose Add to Memory Block Use Count Used by n Setup char int int . . status = AX Where Task blockp n ISP n Timer Procedure n Restart Procedure n Exit Procedure *blockp; increment; status; ajmau(blockp, increment); ES:BX DX is a pointer to a memory block allocated by ajmget or ajmgeh. increment is the signed value to be added to the memory block's use count. Results Interrupts are disabled and then restored to their state at the time of the call. is returned.
ajmfre ajmfre Purpose Free Previously Allocated Block Used by n Setup char *blockp; int status; . . status = ajmfre(blockp); AX ES:BX Where blockp Results Interrupts are disabled and then restored to their state at the time of the call. Task Status AEROK AERMIB AERMNU o ISP o Timer Procedure n Restart Procedure n Exit Procedure is a pointer to a memory block allocated by ajmget or ajmgeh. is returned.
ajmgeh ajmgeh Purpose Get a Memory Block Using a Memory Handle Used by n Setup long char long char int . . status = AX Where o Task size ISP o Timer Procedure n Restart Procedure n Exit Procedure size; *blockp; memsize; *handle; status; ajmgeh(size, &blockp, &memsize, handle); DX:CX ES:BX= DX:CX= ES:BX is the number of bytes of memory required. is a pointer to storage for the returned pointer to the memory block.
ajmget ajmget Purpose Get a Memory Block Used by n Setup long char long int . . status = AX Where o Task size ISP o Timer Procedure n Restart Procedure n Exit Procedure size; *blockp; memsize; status; ajmget(size, &blockp, &memsize); DX:CX ES:BX= DX:CX= is the number of bytes of memory required. is a pointer to storage for the returned pointer to the memory block. &blockp is a pointer to storage for the actual usable size in bytes of the memory block at blockp.
ajmgsz ajmgsz Purpose Get Size of Memory Block Used by n Setup char long int . . status = AX Where Task blockp n ISP n Timer Procedure n Restart Procedure n Exit Procedure *blockp; blksize; status; ajmgsz(blockp, &blksize); ES:BX DX:CX= is a pointer to a memory block allocated by ajmget or ajmgeh. is a pointer to storage for the usable size in bytes of the memory block at blockp. &blksize Results Interrupts are disabled and then restored to their state at the time of the call.
ajmhan ajmhan Purpose Create Memory Handle for Private Allocation Used by n Setup char long char int . . status = AX Where Task o ISP o Timer Procedure n Restart Procedure n Exit Procedure *blockp; memsize; *handle; status; ajmhan(blockp, memsize, &handle); ES:BX DX:CX ES:BX= is a pointer to an area of memory whose access is to be controlled by the Memory Manager. Blocks allocated by ajmget or ajmgeh are suitable. blockp memsize is the size of the memory block at blockp.
ajmodl ajmodl Purpose Get the DGROUP Segment Value Used by n Setup ajmodl(); Results Interrupts are untouched. Task n ISP n Timer Procedure n Restart Procedure n Exit Procedure The data segment register DS is set to the base segment of group DGROUP. This procedure is provided for use with mixed memory models.
ajmset ajmset Purpose Set (Fill) Memory Used by n Setup char long unsigned int . . status = AX Where Results Task o ISP o Timer Procedure n Restart Procedure n Exit Procedure *mempntr; memsize; short int pattern; status; ajmset(mempntr, memsize, pattern); ES:BX DX:CX SI is a pointer to the memory area which is to be filled with the pattern. mempntr memsize is the size in bytes of the memory area at mempntr. pattern is the 16-bit fill pattern. Interrupts are untouched.
ajmxcre ajmxcre Purpose Create a Message Exchange Used by n Setup AMXID int char int . . status = AX Where Task o ISP o Timer Procedure n Restart Procedure n Exit Procedure exchange; mb0, mb1, mb2, mb3; tag[4]; status; ajmxcre(&exchange, mb0, mb1, mb2, mb3, tag); BX= @ES:BX (see note) [DX:CX] is a pointer to storage for the message exchange id of the message exchange allocated to the caller.
ajmxdel ajmxdel Purpose Delete a Message Exchange Used by n Setup AMXID exchange; int status; . . status = ajmxdel(exchange); AX BX Where exchange Results Interrupts are disabled and then restored to their state at the time of the call. Task Status AEROK AERNSX AERXIU o ISP o Timer Procedure n Restart Procedure n Exit Procedure is the exchange id of the message exchange to be deleted. is returned.
ajmxget ajmxget Purpose Get a Message from a Message Exchange (no wait) Used by n Setup AMXID char int . . status = AX Where Task ISP exchange msg Results n n Timer Procedure n Restart Procedure n Exit Procedure exchange; msg[AMXMSZ]; status; ajmxget(exchange, msg); BX ES:SI is the message exchange id acquired by a call to ajmxcre. is an array name or pointer to AMXMSZ consecutive bytes of storage into which the message will be copied if it is available.
ajmxsnd ajmxsnd Purpose Send Message to Message Exchange Used by n Setup AMXID char int int . . status = AX Where Task n ISP exchange n Timer Procedure n Restart Procedure n Exit Procedure exchange; msg[AMXMSZ]; priority; status; ajmxsnd(exchange, priority, msg); BX DX ES:SI is the message exchange id acquired by a call to ajmxcre. is the priority of the message.
ajmxsndp ajmxsndp Purpose Send Message to a Message Exchange Used by n Setup AMXID exchange; int priority; int status; int parm1; int parm2; . . status = ajmxsndp(exchange, priority, parm1, parm2...); AX AAMXSND BX DX @ES:SI Where exchange Task n ISP n Timer Procedure n Restart Procedure n Exit Procedure is the message exchange id acquired by a call to ajmxcre. is the priority of the message.
ajmxtag ajmxtag Purpose Find a Message Exchange Used by n Setup AMXID char int . . status = AX Where Task ISP o Timer Procedure n Restart Procedure n Exit Procedure exchange; tag[4]; status; ajmxtag(&exchange, tag); BX= [DX:CX] see note is a pointer to storage for the message exchange id of the message exchange of interest. &exchange tag Results o is a pointer to a 4-character name identifying the message exchange of interest.
ajmxwat ajmxwat Purpose Wait for a Message from a Message Exchange Used by n Setup AMXID char long unsigned . . status = AX Where Task o ISP exchange msg o Timer Procedure o Restart Procedure n Exit Procedure exchange; msg[AMXMSZ]; timeout; int priority; ajmxwat(exchange, msg, BX ES:SI timeout, priority); DX:CX DI is the message exchange id acquired by a call to ajmxcre.
ajoutb ajoutw 278 ajoutb ajoutw Purpose Write to an 8-Bit Output Port (Byte) Write to a 16-Bit Output Port (Word) Used by n Setup int portno; char portbyte; short int portword; . . ajoutb(portno, portbyte); ajoutw(portno, portword); Where portno Task n ISP n Timer Procedure n Restart Procedure n Exit Procedure is the port number. portbyte is the data byte to be written. portword is the data word to be written. Results Interrupts are untouched.
ajproc ajprocq Purpose ajproc ajprocq Call Software Procedure You can use this procedure to call any software procedure which, because of register setup requirements, cannot otherwise be called from C. Used by n Setup #include "amx831sd.h" . . void someproc(); struct amxregs regarray; unsigned int regeax: . .
Results Interrupts will be in the state in which they are left by the called procedure when it exits. All registers in regarray reflect the values in the processor registers at the time the called procedure ended. The real processor registers are only affected at the instant the software procedure call is made. Restrictions The flags register in regarray can be set prior to calling ajproc. Only the least significant 8 bits of the real flags register are altered to match the value specified in regarray.
ajprvl ajprvl Purpose Lower Task Privilege Used by n Setup ajprvl(); Results Interrupts are disabled and then restored to their state at the time of the call. Task o ISP o Timer Procedure o Restart Procedure n Exit Procedure Restrictions Must follow every call to ajprvr. Once ajprvr is called, task switching is inhibited until ajprvl is called.
ajprvr ajprvr Purpose Raise Task Privilege Used by n Setup ajprvr(); Results Interrupts are disabled and then restored to their state at the time of the call. Task o ISP o Timer Procedure o Restart Procedure n Exit Procedure Restrictions Must be followed by a call to ajprvl as soon as possible to lower the privilege level. Task switching is inhibited until ajprvl is called. Once ajprvr has been called, the task must not issue any AMX calls which would force the task to wait or end.
ajrbl ajrbl Purpose Remove from Bottom of Circular List Used by n Setup char item; /* one byte item int status; . . status = ajrbl(&list, &item); AX ES:BX CL=, CX= or DX:CX= Where &list n Task ISP n Timer Procedure n Restart Procedure n Exit Procedure */ is a pointer to a circular list (see ajrstl). is a pointer to storage for the 1, 2 or 4 byte item to be removed from the list. If &item is NULL (0L), the item is deleted from the list but is not returned to the caller.
ajresum Purpose ajresum Resume a Suspended Task Resume a task known to be suspended as a result of an ajsusp call. Used by n Setup AMXID taskid; int status; . . status = ajresum(taskid); AX DX Where taskid Results Interrupts are disabled and then restored to their state at the time of the call. Task Status AEROK AERNST n ISP n Timer Procedure o Restart Procedure n Exit Procedure is the task id of the task to be resumed. is returned.
ajrstl ajrstl Purpose Initialize (Reset) a Circular List Used by n Setup /* define type of slots typedef char SLOT1; typedef short int SLOT2; typedef long SLOT4; Task n ISP n Timer Procedure n Restart Procedure n Exit Procedure /* byte slot /* word slot /* double word slot /* define number of slots in list #define NSLOT 64 int SLOT4 } list; header[4]; slots[NSLOT]; */ */ */ */ */ struct { . .
ajrtl ajrtl Purpose Remove from Top of Circular List Used by n Setup char item; /* one byte item int status; . . status = ajrtl(&list, &item); AX BX CL=, CX= or DX:CX= Where &list n Task ISP n Timer Procedure n Restart Procedure n Exit Procedure */ is a pointer to a circular list (see ajrstl). &item is a pointer to storage for the 1, 2 or 4 byte item to be removed from the list. If &item is NULL (0L), the item is deleted from the list but is not returned to the caller.
ajsend Purpose ajsend Send a Message to a Task Mailbox To request AMX to send a message to a task at a given priority and to begin execution of that task as soon as possible. Used by n Setup AMXID int char int . . status = AX Where Task taskid n ISP n Timer Procedure n Restart Procedure n Exit Procedure taskid; priority; msg[AMXMSZ]; status; ajsend(taskid, priority, msg); DX CX ES:BX is the task id of the task to whom the message is to be sent. is the priority of the message.
ajsendp Purpose ajsendp Send a Message to a Task Mailbox To request AMX to send a message to a task at a given priority and to begin execution of that task as soon as possible. Used by n Setup AMXID taskid; int priority; int status; int parm1; int parm2; . . status = ajsendp(taskid, priority, parm1, parm2...); AX AASEND DX CX @ES:BX Where taskid Task n ISP n Timer Procedure n Restart Procedure n Exit Procedure is the task id of the task to whom the message is to be sent.
ajsenw Purpose ajsenw Send a Message to a Task Mailbox (Wait for Ack) To request AMX to send a message to a task at a given priority and to begin execution of that task as soon as possible. The task making the request is placed into the wait state until either: 1. the called task receives the message and makes an ajwakc call, or 2. the called task receives the message and ends by making an ajend call or by returning to AMX.
Results Interrupts are disabled and then restored to their state at the time of the call. Status AEROK AERNST AERNME AERNMB AERMBF is returned. = Call successful = Invalid task id = No free message envelope = No task mailbox of the specified priority = Task mailbox is full An immediate switch to the highest priority ready task will occur. If the call is successful, status will be >= 0. By definition, the value 0 is the AMX error code AEROK.
ajsenwp Purpose ajsenwp Send a Message to a Task Mailbox (Wait for Ack) To request AMX to send a message to a task at a given priority and to begin execution of that task as soon as possible. The task making the request is placed into the wait state until either: 1. the called task receives the message and makes an ajwakc call, or 2. the called task receives the message and ends by making an ajend call or by returning to AMX.
Results Interrupts are disabled and then restored to their state at the time of the call. Status AEROK AERNST AERNME AERNMB AERMBF is returned. = Call successful = Invalid task id = No free message envelope = No task mailbox of the specified priority = Task mailbox is full An immediate switch to the highest priority ready task will occur. If the call is successful, status will be >= 0. By definition, the value 0 is the AMX error code AEROK.
ajsgnl ajsgnl Purpose Signal a Task Used by n Setup AMXID unsigned unsigned int . . status = AX Where Task taskid n n ISP Timer Procedure n Restart Procedure n Exit Procedure taskid; int tsignals; long siginfo; status; ajsgnl(taskid, tsignals, DX BX[14..0] BX[15]=0 &siginfo); BX:CX= is the task id of the task to be signalled. is a 15-bit mask identifying the task signals to be sent to the specified task. Only the least significant 15 bits of tsignals (bits 0 to 14) are used.
Results (continued) AERTNW = Task was not waiting for any of these signals. These signals are now pending for the task. At least one of these signals was already pending implying a signal overrun. Variable siginfo can be examined to see which signals caused the overrun. provides additional information concerning the results of the signal. Bits 0 to 14 identify signal overruns.
ajsgrd ajsgrd Purpose Read Pending Task Signals Used by n Setup unsigned int tsignals; . . tsignals = ajsgrd(); AX Where tsignals Results Interrupts are untouched. Task o ISP o Timer Procedure o Restart Procedure n Exit Procedure is the current state of the calling task's task signals. contains the current value of each of the task's 15 task signals in the least significant 15 bits (bits 0 to 14). All other bits of tsignals will be 0.
ajsgres ajsgres Purpose Reset Pending Task Signals Used by n Setup unsigned int tsignals; . . ajsgres(tsignals); BX[14..0] BX[15]=0 Where tsignals Results Interrupts are untouched. Task o ISP o Timer Procedure o Restart Procedure n Exit Procedure is a 15-bit mask identifying the task signals to be reset. Only the least significant 15 bits of tsignals (bits 0 to 14) are used. Set a bit to force the reset of the corresponding task signal. All other bits must be 0.
ajsgwat ajsgwat Purpose Wait for Task Signal(s) Used by n Setup unsigned long int int unsigned . . status = AX Where Task o ISP o Timer Procedure o Restart Procedure n Exit Procedure int tsignals; timeout; match; status; int sigrecv; ajsgwat(tsignals, BX[14..0] match, BX[15] timeout, &sigrecv); DX:CX BX= is a 15-bit mask identifying the task signals of interest. Only the least significant 15 bits of tsignals (bits 0 to 14) are used. Set a bit to wait for the corresponding task signal.
Results Interrupts are disabled and then enabled upon return. Status AEROK AERTM0 AERTMV is returned. = Call successful = Timed out before required signals occurred = Invalid timeout interval (<0) identifies the received task signals which satisfied the match criteria or those which had occurred prior to timeout. sigrecv If waiting for any of n task signals (match = 0), AEROK: sigrecv identifies which of the n task signals occurred. AERTMO: sigrecv = 0.
ajsint ajsintq ajsint ajsintq Purpose Generate Software Interrupt Used by n Setup #include "amx831sd.h" . . struct amxregs regarray; int inttype; unsigned int regeax: . . regeax = ajsint(inttype, ®array); Task n ISP n Timer Procedure n Restart Procedure n Exit Procedure or regeax = ajsintq(inttype, ®array); Where inttype is the interrupt type (number 0 to 255).
Results Interrupts will be in the state in which they are left by the interrupt procedure when it exits. All registers in regarray reflect the values in the processor registers at the time the interrupt procedure ended. The real processor registers are only affected at the instant the software interrupt call is made. Restrictions The flags register in regarray can be set prior to calling ajsint.
ajsmcre ajsmcre Purpose Create a Semaphore Used by n Setup AMXID int char int . . status = AX Where Task o ISP o Timer Procedure n Restart Procedure n Exit Procedure semid; value; tag[4]; status; ajsmcre(&semid, value, tag); BX= BX [DX:CX] is a pointer to storage for the semaphore id of the semaphore allocated to the caller. &semid is the initial value of the semaphore.
ajsmdel ajsmdel Purpose Delete a Semaphore Used by n Setup AMXID semid; int status; . . status = ajsmdel(semid); AX BX Where semid Results Interrupts are disabled and then restored to their state at the time of the call. Task ISP o Timer Procedure n Restart Procedure n Exit Procedure is the semaphore id of a resource or counting semaphore acquired by a call to ajsmcre. Status AEROK AERNSS AERSIU 302 o is returned.
ajsmfre ajsmfre Purpose Unconditionally Free a Resource Semaphore Used by n Setup AMXID semid; int status; . . status = ajsmfre(semid); AX BX Where semid is the semaphore ajsmcre. Results Interrupts are disabled and then restored to their state at the time of the call. Task Status AEROK AERNSS AERRNY Note o ISP o Timer Procedure o Restart Procedure n Exit Procedure id of a resource semaphore acquired by a call to is returned.
ajsmget ajsmget Purpose Get Use of a Semaphore (no wait) Used by n Setup AMXID int Task n ISP n Timer Procedure n Restart Procedure n Exit Procedure semid; status; . . status = ajsmget(semid); AX BX Where semid is the semaphore ajsmcre. Results Interrupts are disabled and then restored to their state at the time of the call. Status AEROK AERNSS AERSBY Note Restriction id of a counting semaphore acquired by a call to is returned.
ajsmrls ajsmrls Purpose Release a Resource Semaphore Used by n Setup AMXID semid; int status; . . status = ajsmrls(semid); AX BX Task o ISP o Timer Procedure o Restart Procedure n Exit Procedure /* nested release */ Where semid is the semaphore ajsmcre. Results Interrupts are disabled and then restored to their state at the time of the call. Status AEROK AERNSS AERRNY Note id of a resource semaphore acquired by a call to is returned.
ajsmrsv ajsmrsv Purpose Reserve a Resource Semaphore Used by n Setup AMXID long unsigned int . . status = AX Where Task o ISP o Timer Procedure o Restart Procedure n Exit Procedure semid; timeout; int priority; status; ajsmrsv(semid, timeout, priority); BX DX:CX DI semid is the semaphore ajsmcre. id of a resource semaphore acquired by a call to is the maximum interval measured in AMX system ticks which the caller is prepared to wait for the resource. Timeout must be positive.
Results Interrupts are disabled and then enabled upon return. Status AEROK AERNSS AERTMO AERTMV is returned. = Call successful = Invalid semaphore id = Timed out without being granted the resource = Invalid timeout interval (<0) The calling task will be suspended waiting for the resource if the resource is owned by some other task. When the resource is finally available for use by the caller, the procedure will return with status = AEROK.
ajsmsig ajsmsig Purpose Signal a Semaphore Used by n Setup AMXID semid; int status; . . status = ajsmsig(semid); AX BX Where semid is the semaphore ajsmcre. Results Interrupts are disabled and then restored to their state at the time of the call. Task Status AEROK AERNSS AERNME n ISP n Timer Procedure n Restart Procedure n Exit Procedure id of a counting semaphore acquired by a call to is returned.
ajsmtag ajsmtag Purpose Find a Semaphore Used by n Setup AMXID char int . . status = AX Where Task ISP o Timer Procedure n Restart Procedure n Exit Procedure semid; tag[4]; status; ajsmtag(&semid, tag); BX= [DX:CX] see note is a pointer to storage for the semaphore id of the semaphore of interest. semid tag Results o is a pointer to a 4-character name identifying the semaphore of interest. Interrupts are disabled and then restored to their state at the time of the call.
ajsmwat ajsmwat Purpose Wait on a Semaphore Used by n Setup AMXID long unsigned int . . status = AX Where Task o ISP o Timer Procedure o Restart Procedure n Exit Procedure semid; timeout; int priority; status; ajsmwat(semid, timeout, priority); BX DX:CX DI semid is the semaphore ajsmcre. id of a counting semaphore acquired by a call to is the maximum interval measured in AMX system ticks which the caller is prepared to wait for the semaphore. Timeout must be positive.
ajsofs ajsofs Purpose Set Pointer Offset Used by n Setup unsigned int ofs; char FAR *pntr; . . ajsofs(&pntr, ofs); Results Interrupts are untouched. Task n ISP n Timer Procedure n Restart Procedure n Exit Procedure The offset part of the FAR pointer variable pntr is set to the 16-bit unsigned value of ofs.
ajsseg ajsseg Purpose Set Pointer Segment Used by n Setup unsigned short int seg; char FAR *pntr; . . ajsseg(&pntr, seg); Results Interrupts are untouched. Task n ISP n Timer Procedure n Restart Procedure n Exit Procedure The segment selector part of the FAR pointer variable pntr is set to the 16-bit unsigned value of seg.
ajssreg ajssreg Purpose Set Segment Registers Used by n Setup #include "amx831sd.h" . . struct amxsregs sregarray; . . ajssreg(&sregarray); Where &sregarray Results Interrupts are untouched. Restriction This procedure does NOT modify segment registers CS or SS to reflect the values in structure sregarray.
ajsusp ajsusp Purpose Suspend a Task Used by n Setup AMXID taskid; int status; . . status = ajsusp(taskid); AX DX Where taskid Results Interrupts are disabled and then restored to their state at the time of the call. Task o ISP n Timer Procedure n Restart Procedure n Exit Procedure is the task id of the task to be suspended. The task will be suspended until some other task, ISP or Timer Procedure issues an ajresum call to resume this task. Status AEROK AERNST Note is returned.
ajtdf ajtdf Purpose Format Time and Date as an ASCII String Used by n Setup #include "amx831sd.h" . . struct amxtds tdbuf; char ascii[26]; int format; int n; . . n = ajtdf(&tdbuf, format, ascii); AX ES:BX DL DS:DI Where tdbuf Task o ISP o Timer Procedure n Restart Procedure n Exit Procedure is an AMX time/date structure containing the time and date (returned by ajtdg) which is to be formatted. The structure amxtds is defined in header file AMX831SD.H (see Appendix D).
ajtdg 316 ajtdg Purpose Get Current Time and Date Used by n Setup #include "amx831sd.h" . . struct amxtds tdbuf; . . ajtdg(&tdbuf); ES:BX Where &tdbuf Results Interrupts are disabled and then restored to their state at the time of the call. See Also ajtds, ajtdf Task n ISP n Timer Procedure n Restart Procedure n Exit Procedure is a pointer to the structure which is to receive the current time and date. The structure amxtds is defined in header file AMX831SD.H (see Appendix D).
ajtds ajtds Purpose Set the Time and Date Used by n Setup #include "amx831sd.h" . . struct amxtds tdbuf; . . Initialize tdbuf with new time and date. . . ajtds(&tdbuf); ES:BX Where &tdbuf Results Interrupts are disabled and then restored to their state at the time of the call. Task o ISP o Timer Procedure n Restart Procedure n Exit Procedure is a pointer to the structure which contains the new time and date. The structure amxtds is defined in header file AMX831SD.H (see Appendix D).
ajtick ajtick Purpose Read System Tick Counter Used by n Setup unsigned long tickcnt; . . tickcnt = ajtick(); DX:AX Results Interrupts are untouched. Task n tickcnt Note 318 ISP n Timer Procedure n Restart Procedure n Exit Procedure is the current value of the AMX system tick counter. The AMX system tick counter is set to 0 when your AMX system is launched. It is incremented once for every elapsed system tick. It wraps from 232-1 to 0.
ajtkcre ajtkcre Purpose Create a New Task Used by n Setup #include "amx831sd.h" . . struct amxtdts tdt; AMXID taskid; int status; . . status = ajtkcre(&tdt, &taskid); AX ES:BX DX= Where &tdt Task o ISP o Timer Procedure n Restart Procedure n Exit Procedure is a pointer to the task's definition. All fields in structure tdt must be valid before ajtkcre is called. The structure amxtdts is defined in header file AMX831SD.H (see Appendix D).
ajtkdel Purpose ajtkdel Delete a Task This procedure removes a task from your AMX system. Its task id will no longer be valid. Used by n Setup AMXID int int . . status = AX Where Task taskid o ISP o Timer Procedure o Restart Procedure n Exit Procedure taskid; priority; status; ajtkdel(taskid, priority); DX CX is the task id of the task to be deleted. is the task execution priority at which the deletion is to occur.
ajtkid ajtkid Purpose Get Task Id of Current Task Used by n Setup AMXID taskid; . . taskid = ajtkid(); AX Where taskid Results Interrupts are untouched. See Also ajtktcb, ajtktag AMX 86 Procedures Task o ISP o Timer Procedure o Restart Procedure n Exit Procedure is the task id of the currently executing task.
ajtkill Purpose ajtkill Kill a Task This procedure will force a ready, executing or suspended task to end. All messages in the task's mailboxes at the time of the kill request will be flushed. All requests for task execution pending at the time of the kill request will be erased. Used by n Setup AMXID taskid; int status; . . status = ajtkill(taskid); AX DX Where taskid Results Interrupts are disabled and then restored to their state at the time of the call.
ajtkpry ajtkpry Purpose Change Task Priority Used by n Setup AMXID int int . . status = AX Where Task taskid o ISP AMX 86 Procedures n Restart Procedure n Exit Procedure taskid; priority; status; ajtkpry(taskid, priority); DX CX is the desired priority of the task (1 to 127). Interrupts are disabled and then restored to their state at the time of the call. Status AEROK AERNST AERITP See Also Timer Procedure is the task id of the task whose priority is to be changed.
ajtkstp Purpose ajtkstp Stop Execution of Task This procedure will force a ready, executing or suspended task to end. Used by n Setup AMXID taskid; int status; . . status = ajtkstp(taskid); AX DX Where taskid Results Interrupts are disabled and then restored to their state at the time of the call. Task Status AEROK AERNST AERANA n ISP n Timer Procedure o Restart Procedure n Exit Procedure is the task id of the task to be stopped. is returned.
ajtksts ajtksts Purpose Get Status of a Task Used by n Setup #include "amx831sd.h" . . struct amxsbs tasksts; AMXID taskid; int status; . . status = ajtksts(taskid, &tasksts); AX DX ES:BX Where taskid Task n ISP n Timer Procedure n Restart Procedure n Exit Procedure is the task id of the task for which status is required. &tasksts is a pointer to storage for the task status. The structure amxsbs is defined in header file AMX831SD.H (see Appendix D).
ajtktag ajtktag Purpose Find a Task Used by n Setup char AMXID int . . status = AX Where Task &taskid tag Results o ISP o Timer Procedure n Restart Procedure n Exit Procedure tag[4]; taskid; status; ajtktag(&taskid, tag); DX= [CX:DX] see note is a pointer to storage for the task id of the task of interest. is a pointer to a 4-character name identifying the task of interest. Interrupts are untouched. Status AEROK AERNST is returned.
ajtktcb ajtktcb Purpose Get Task Control Block Pointer Used by n Setup #include "amx831sd.h" . . struct amxtcbs *tcbp; AMXID taskid; int status; . . status = ajtktcb(taskid, &tcbp); AX DX ES:BX= Where taskid n Task ISP n Timer Procedure n Restart Procedure n Exit Procedure is the task id of the task for which the Task Control Block pointer is required. &tcbp is a pointer to storage for the pointer to the Task Control Block. The structure amxtcbs is defined in header file AMX831SD.
ajtktrm ajtktrm Purpose Enable/Disable External Task Termination Used by n Setup AMXID void int . . status = AX Where Task taskid n ISP n Timer Procedure n Restart Procedure n Exit Procedure taskid; ttproc(); status; ajtktrm(taskid, ttproc); DX ES:BX is the task id of the task whose Termination Procedure is to be set. is a pointer to the Task Termination Procedure which is to be executed by the task whenever the task is stopped, killed or deleted (see ajtkstp, ajtkill, ajtkdel).
ajtmcnv ajtmcnv Purpose Convert Milliseconds to System Ticks Used by n Setup unsigned long ms; long ntick; . . ntick = ajtmcnv(ms); DX:CX DX:CX Where ms Task ISP n Timer Procedure n Restart Procedure n Exit Procedure is the number of milliseconds. ntick Results n is the equivalent interval in AMX system ticks. Interrupts are untouched. ntick is the interval value in system ticks.
ajtmcre ajtmcre Purpose Create an Interval Timer Used by n Setup void tproc(); AMXID timerid; long tperiod; struct tuser *tparam; char tag[4]; int status; . . status = ajtmcre(&timerid, tperiod, tproc, tparam, tag); ES:BX is A(Timer Definition Structure) AX DX= See structure AMXTMS defined in header file AMX831SD.DEF (see Appendix D).
ajtmdel ajtmdel Purpose Delete an Interval Timer Used by n Setup AMXID timerid; . . status = ajtmdel(timerid); AX DX Where timerid Results Interrupts are disabled and then restored to their state at the time of the call. Task o ISP Timer Procedure n Restart Procedure n Exit Procedure is the timer id identifying the timer to be deleted. Status is AEROK AERNSTM Note n returned.
ajtmrd ajtmrd Purpose Read the Current Value of an Interval Timer Used by n Setup AMXID timerid; long tval; . . tval = ajtmrd(timerid); DX:CX DX Where timerid Task tval Results n ISP n Timer Procedure n Restart Procedure n Exit Procedure is the timer id identifying the timer whose value is required. is the timer value in system ticks. Interrupts are disabled and then restored to their state at the time of the call.
ajtmtag ajtmtag Purpose Find an Interval Timer Used by n Setup AMXID char int . . status = AX Where Task ISP o Timer Procedure n Restart Procedure n Exit Procedure timerid; tag[4]; status; ajtmtag(&timerid, tag); DX= [DX:CX] see note is a pointer to storage for the timer id of the interval timer of interest. &timerid tag Results o is a pointer to a 4-character name identifying the timer of interest. Interrupts are disabled and then restored to their state at the time of the call.
ajtmwr ajtmwr Purpose Start/Stop an Interval Timer Used by n Setup AMXID long int . . status = AX Where Task n timerid ISP n Timer Procedure n Restart Procedure n Exit Procedure timerid; tval; status; ajtmwr(timerid, tval); DX BX:CX is the timer id identifying the timer to be started or stopped. is the timer interval measured in AMX system ticks. Tval must be positive. Set tval to 0 to stop a timer.
ajtrig Purpose ajtrig Trigger a Task To request AMX to start a task without sending a message to the task. Used by n Setup AMXID taskid; int status; . . status = ajtrig(taskid); AX DX Where taskid Results Interrupts are disabled and then restored to their state at the time of the call. Task Status AEROK AERNST n ISP n Timer Procedure n Restart Procedure n Exit Procedure is the task id of the task to be triggered. is returned.
ajtslv ajtslv Purpose Change a Task's Time Slice Interval Used by n Setup AMXID unsigned int . . status = AX Where Task taskid n ISP n Timer Procedure n Restart Procedure n Exit Procedure taskid; int tslice; status; ajtslv(taskid, tslice); DX CX is the task id of the task whose time slice interval is to be altered. is the new time slice interval in AMX system ticks. (0 <= tslice < 65536) Set tslice to 0 to stop time slicing the task. tslice Results Interrupts are untouched.
ajtsof ajtson ajtsof ajtson Purpose Disable Time Slicing Enable Time Slicing Used by n Setup ajtsof(); Task n ISP n Timer Procedure n Restart Procedure n Exit Procedure /* Disable time slicing */ /* Enable time slicing */ or ajtson(); Results Interrupts are untouched.
ajupt ajupt Purpose Fetch Pointer to User Parameter Table Used by n Setup #include "amx831sd.h" . . struct amxupts FAR *uptp; /* User Parameter Table pointer */ . . ajupt(&uptp); Where &uptp Task n ISP n Timer Procedure n Restart Procedure n Exit Procedure is a FAR pointer to storage for a FAR pointer to your system's User Parameter Table. The structure amxupts is defined in header file AMX831SD.H (see Appendix D). 338 Results Interrupts are untouched.
ajver ajver Purpose Get AMX Version Number Used by n Setup unsigned long version; . . version = ajver(); DX:AX Where version is the AMX version number in the 0x0086rrmm where rr is the major revision number (03) mm is the minor revision number (00) Results Interrupts are untouched.
ajwait ajwait Purpose Wait Unconditionally for a Wake Request Used by n Setup ajwait(); Results Interrupts are enabled. Task o ISP o Timer Procedure o Restart Procedure n Exit Procedure The task will be suspended until some other task, ISP or Timer Procedure issues an ajwake call to wake this task. If a task has an outstanding wake request pending when it calls ajwait, the task will continue execution immediately without waiting.
ajwakc Purpose ajwakc Wake Calling Task (Acknowledge Receipt of Message) To allow the current task to wake up the task which sent the message which is being processed by the current task. Used by n Setup int status; . . status = ajwakc(); AX Results Interrupts are disabled and then restored to their state at the time of the call. Task Status AEROK AERCNW AERNMT o ISP o Timer Procedure o Restart Procedure n Exit Procedure is returned.
ajwakcs Purpose ajwakcs Wake Calling Task (Acknowledge Receipt of Message with Status) To allow the current task to wake up the task which sent the message which is being processed by the current task and return completion status to that task. Used by n Setup int status; int result; . . status = ajwakcs(result); AX CX Where result Results Interrupts are disabled and then restored to their state at the time of the call.
ajwake Purpose ajwake Wake a Waiting Task To wake up a task known to be waiting because of an ajwait or ajwatm call. Used by n Setup AMXID taskid; int status; . . status = ajwake(taskid); AX DX Where taskid Results Interrupts are disabled and then restored to their state at the time of the call. Task Status AEROK AERWKP AERNST AERTNW n ISP n Timer Procedure o Restart Procedure n Exit Procedure is the task id of the task to be wakened. is returned.
ajwapr Purpose ajwapr Reset a Pending Wake Request This call only affects the calling task. Used by n Setup ajwapr(); Results Interrupts are untouched. Note Task o ISP o Timer Procedure o Restart Procedure n Exit Procedure This procedure provides a simplified form of task signal reset (see ajsgres).
ajwatm Purpose ajwatm Task Delay or Timed Wait for a Wake Request Used by n Setup long tval; int status; . . status = ajwatm(tval); AX DX:CX Where tval Results Interrupts are enabled. Task o ISP o Timer Procedure o Restart Procedure n Exit Procedure is the required wait interval or delay period measured in AMX system ticks. Tval must be positive. If tval = 0, the caller will not wait. is returned.
This page left blank intentionally.
A. AMX 86 Reserved Words ajpppppp AAPPPPPP amxttttt AMX C procedure name pppppp AMX assembly language procedure name PPPPPP AMX C structure name of type ttttt AMXID cdecl AMssssss AMX object identifier (handle) Procedures use C parameter passing conventions Reserved symbols defined in AMX header files AERxxxxx AERWxxxx AERFxxxx AMX Error Code xxxxx AMX Warning Code xxxx AMX Fatal Exit Code xxxx AA831FFF.XXX AM831FFF.XXX AMX831FF.XXX AJ831FFF.XXX AA832FFF.
This page left blank intentionally.
B. AMX 86 Error Codes AMX error codes are signed integers. Codes less than zero are error codes. Codes greater than zero are warning codes. To assist you during testing, the hexadecimal value of the least significant 16-bits of the error code is listed as it might appear in a register or memory dump.
AMX 86 Error Codes (continued) Mnemonic Value Value (dec) (hex) Meaning AERNBF AERNFP AERNEB AEREVU -30 -31 -32 -33 -34 -35 -36 -37 -38 -39 0xFFE2 0xFFE1 0xFFE0 0xFFDF 0xFFDE 0xFFDD 0xFFDC 0xFFDB 0xFFDA 0xFFD9 No buffers defined No free buffer pool No free event group Event group in use reserved reserved reserved Memory not available Invalid memory block pointer Memory block not in use AERMOV AERNSX -40 -41 0xFFD8 0xFFD7 AERNXB AERXIU AERMBZ AERNSB AERNSG AERNSTM AERTMV AERIRS -42 -43 -44 -45 -46
AMX 86 Fatal Exit Codes Mnemonic Value Value (dec) (hex) Meaning AERFX1 AERFX2 AERFX3 ● ● ● 1 2 3 0x0001 0x0002 0x0003 Not enough memory in AMX Data Segment Divide, overflow, bound error in ISP Divide, overflow, bound error occurred: in a Restart Procedure or in a Timer Procedure or in a task with no task trap handler AERFX4 AERFX5 AERFX6 ● ● ● 4 5 6 0x0004 0x0005 0x0006 Attempt to exit from a permanent AMX system reserved ROMed AMX kernel received a request which it is not configured to handle
This page left blank intentionally.
C. Configuration Generator Specifications C.1 Introduction If you are not doing your software development on a PC or compatible running Microsoft® Windows®, then you will be unable to use the interactive Configuration Manager for Windows to create and edit your AMX System Configuration Module. You may, however, still be able to use the Configuration Generator to assist you in this process by porting it to your development system as described in Appendix C.4. As described in Chapter 14.
C.2 User Parameter File Specification The User Parameter File is a text file structured as illustrated in Figure C.2-1. The file consists of a sequence of keywords of the form ...XXX which begin in column one. Each keyword is followed by one or more parameters which you must provide. ; Constant definitions ...UPT NME,UMS,CLP,CLF,NTK,NTM ...STK ESS,ISS ...OPT TSLICE,NSM,NEV,NMX,NBP,ROMS,CAT,BKPT ; ; Time/Date Manager selection ...TAD UPSHED ; ; Your Fatal Exit Procedure and User Error Procedure ...
The example in Figure C.2-1 uses symbolic names for all of the parameters following each of the keywords. The symbols correspond to the screen fields described in Chapter 14. You are referred to that chapter for detailed descriptions of each of the parameters. The order of keywords in the User Parameter File is not particularly critical. For convenience, the keywords have been ordered to closely follow the order of the corresponding entries in your System Configuration Module.
Each of your predefined tasks must be defined using keyword ...TDT. The order of these definitions will determine their order of creation by AMX. If you do not wish to predefine any tasks, delete the line with keyword ...TDT. The parameters in each task definition are as follows.
Each of your predefined semaphores must be defined using the keyword ...SEM. The order of these definitions will determine their order of creation by AMX. If you do not wish to predefine any semaphores, delete the line with keyword ...SEM.
Each of your predefined message exchanges must be defined using the keyword ...MEX. The order of these definitions will determine their order of creation by AMX. If you do not wish to predefine any message exchanges, delete the line with keyword ...MEX.
C.3 System Configuration Template The System Configuration Template is an assembly language source file which defines a System Configuration Module for any system using AMX and its managers. It is recommended that you list file AM831CG.CT and examine it carefully before trying to read this description. The template file consists of KADAK macro definitions for all of the various components of a System Configuration Module. The macro definitions are followed by code generating instances of these macros.
Macro parameters appear in the macro body as parameter identifiers. A parameter identifier is a decimal integer preceded and followed by the delimiter character defined in the macro definition statement (~1~, ~2~, etc.). The number identifies the parameter in the particular parameter list specified by the parameter keyword. The parameter is copied from the User Parameter File into the source language macro body replacing the particular identifier.
The first statement in this example is a directive defining an incremental variable named &TN. Both its initial value and increment are 1. Note that this directive begins with the assembler comment character (;) and the parameter delimiter character (~ in this example) required by all KADAK macro directives. The variable name is a string of printable characters preceded and followed by one or more space and/or tab characters.
C.4 Porting the Configuration Generator The Configuration Manager uses the Configuration Generator to generate your System Configuration Module. If you are not doing your development on a PC or compatible, you may wish to port the Configuration Generator to your development system. The Configuration Generator is a utility program provided with AMX. The program is written in C with portability in mind. Source file AM831CG.C is delivered with AMX.
By default, the Configuration Generator uses the macro identification character (; in our example) from the macro directive as a comment character to identify the comments inserted into the output file in response to the -w switch. This default assumption can be overridden using the -b and -e switches to define alternate comment delimiter strings. The strings sss can be up to 16 characters long. Special characters must be inserted using the character pair ^x for each special character.
This page left blank intentionally.
D. AMX 86 Structure and Constant Definitions D.1 AMX C Structures and Constants AMX Launch Parameter (see AAENTR) #define AMLPTMP 1 /* Temporary launch */ /* Default is permanent launch */ #define AMLPVA 2 /* Vector table is alterable /* Default is non alterable /* table */ */ */ #define AMLPIE 4 /* Launch with interrupts /* enabled.
AMX Task Status Block Structure struct amxsbs { AMXID char char char char unsigned unsigned long unsigned unsigned unsigned AMXID amsbtid; amsbtag1; amsbtag2; amsbtag3; amsbtag4; long amsbst; long amsbsig; amsbtmr; short int amsbslc; short int amsbcc; short int amsbatr; amsbctid; short int amsbcwat; short int amsbpry; unsigned short int amsbmc0; unsigned short int amsbmc1; unsigned short int amsbmc2; unsigned short int amsbmc3; }; /* task id /* task tag */ */ /* /* /* /* /* /* /* /* /* /* /* /* /* /*
AMX Extended Message Parameter Structure (passed on stack above AMX message when starting a task) struct amxmsgxs { AMXID amxmscid; short int amxmsfn; short int amxmsrsv[4]; }; /* /* /* /* calling task's id AMX function code (see definitions) reserved */ */ */ */ /* /* /* /* no message on stack message on stack message on stack; sender waiting */ */ */ */ AMX Function Codes (field amxmsfn) #define AMXMSFNM #define AMXMSFMS #define AMXMSFMW Structure/Constant Definitions 0 1 2 KADAK 367
AMX User Parameter Table Structure struct amxupts { void (**ampbrpl)(); void (**ampbepl)(); long ampbcfga; short int ampbdgrp; short int ampbnmev; short int ampbums; void *ampbmes; void *ampbistk; unsigned int ampbesz; unsigned int ampbisz; unsigned int ampblen; short int ampbclkp; short int ampbclkf; void (*ampbtds)(); void (*ampbfex)(); void (*ampberr)(); 368 /* /* /* /* /* /* /* /* /* /* /* /* /* /* /* /* A(Restart Procedure List) */ A(Exit Procedure List) */ Configuration attributes */ user's DGROUP
Configuration Attributes (field AMPBCFGA) #define AMCAMTK 1 #define AMCAMUP 2 #define AMCAS24 4 /* Some Medium tasks */ /* Some Medium user procedures */ /* Use 24-bit address space */ AMX Time/Date Structure struct amxtds { unsigned unsigned unsigned unsigned unsigned unsigned unsigned unsigned char char char char char char char char amtdsec; amtdmin; amtdhr; amtddy; amtdmn; amtdyr; amtdow; amtdcen; /* /* /* /* /* /* /* /* /* /* seconds (0-59) */ minutes (0-59) */ hours (0-23) */ day (1-31) */ month
AMX List Header Structure (doubly linked lists) struct amxlhs { struct amxlhs *amlhhead; struct amxlhs *amlhtail; unsigned int amlhoffs; }; /* list head */ /* list tail */ /* byte offset to object node */ AMX List Node Structure struct amxlns { struct amxlns *amlnnext; struct amxlns *amlnprev; }; /* next node in list /* previous node in list */ */ /* next node in list /* previous node in list /* node key */ */ */ AMX Key Node Structure struct amxlks { struct amxlks *amlknext; struct amxlks *amlkprev;
AMX Register Array Structure struct amxregs { unsigned unsigned unsigned unsigned unsigned unsigned unsigned unsigned unsigned unsigned }; short short short short short short short short short short int int int int int int int int int int amxrf; amxrax; amxrbx; amxrcx; amxrdx; amxrsi; amxrdi; amxrbp; amxrds; amxres; /* /* /* /* /* /* /* /* /* /* Flags (LS byte only) Register AX Register BX Register CX Register DX Register SI Register DI Register BP Register DS Register ES */ */ */ */ */ */ */ */ */ */
AMX C Jump Buffer Structure struct ajxjbuf { unsigned unsigned unsigned unsigned unsigned unsigned unsigned unsigned unsigned unsigned unsigned unsigned }; 372 short short short short short short short short short short short short int int int int int int int int int int int int xjbretadr; xjbcs; xjbsp; xjbss; xjbbx; xjbcx; xjbsi; xjbes; xjbdi; xjbds; xjbbp; xjbrsrv; /* /* /* /* /* /* /* /* /* /* /* /* KADAK ofs(return address) Register CS Stack pointer offset Stack pointer segment Register BX Regist
D.
AMX Task Status Block Structure AMXSBS ; AMSBTID AMSBTAG1 AMSBTAG2 AMSBTAG3 AMSBTAG4 AMSBST AMSBSIG AMSBTMR AMSBSLC AMSBCC AMSBATR AMSBIDC AMSBCWAT AMSBPRY AMSBMC0 AMSBMC1 AMSBMC2 AMSBMC3 ; AMXSBS STRUC DW DB DB DB DB DD DD DD DW DW DW DW ? ? ? ? ? ? ? ? ? ? ? ? DW DW DW DW DW DW ? ? ? ? ? ? ;task id ;task tag ;task status ;pending signals ;task timer (time remaining) ;time slice ;call count ;task attributes ;caller's task id ;(-1=ISP; 0=AATRIG) ;caller waiting if <> 0 ;task priority ;message count; m
AMX Extended Message Parameter Structure (passed on stack above AMX message when starting a task) AMXMSGXS ; AMXMSCID AMXMSFN AMXMSRSV ; AMXMSGXS STRUC DW DW DW ? ? 4 DUP(?) ;calling task's id ;AMX function code ;reserved ENDS AMX Function Codes (field AMXMSFN) AMXMSFNM EQU AMXMSFMS EQU AMXMSFMW EQU Structure/Constant Definitions 0 1 2 ;no message on stack ;message on stack ;message on stack ;sender waiting KADAK 375
AMX User Parameter Table Structure AMXUPTS ; AMPBRPL AMPBEPL AMPBCFGA AMPBDGRP AMPBNMEV AMPBUMS AMPBMES AMPBISTK AMPBESZ AMPBISZ AMPBLEN AMPBCLKP AMPBCLKF AMPBTDS AMPBFEX AMPBERR ; AMPBTKMX AMPBTKPR AMPBTKDF ; AMPBTMMX AMPBTMPR AMPBTMDF AMPBSMMX AMPBSMPR AMPBSMDF ; AMPBEVMX AMPBEVPR AMPBEVDF ; AMPBMXMX AMPBMXPR AMPBMXDF ; AMPBBPMX AMPBBPPR AMPBBPDF ; AMPBMAP ; AMPBDMN AMPBPCS AMPBDBA AMPBPED AMPBPXD ; AMXUPTS 376 STRUC DD DD DD DW DW DW DD DD DW DW DW DW DW DD DD DD ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ;A(Re
Configuration Attributes (field AMBPCFGA) AMCAMTK AMCAMUP AMCAS24 EQU EQU EQU 1 2 4 ;Some Medium tasks ;Some Medium user procedures ;Use 24-bit address space AMX Time/Date Structure AMXTDS ; AMTDSEC AMTDMIN AMTDHR AMTDDY AMTDMN AMTDYR AMTDOW AMTDCEN ; ; AMXTDS STRUC DB DB DB DB DB DB DB DB ? ? ? ? ? ? ? ? ;seconds ;minutes ;hours ;day ;month ;year ;day of week ;0 if time/date is incorrect ;century if time/date is correct ENDS AMX Timer Definition Structure AMXTMS ; AMTMPROC AMTMPER AMTMPARM AMTMTAG
AMX List Header Structure (doubly linked lists) AMXLHS ; AMLHHEAD AMLHTAIL AMLHOFFS ; AMXLHS STRUC DD DD DW ? ? ? ;Head of list ;Tail of list ;Byte offset to object node ENDS AMX List Node Structure AMXLNS ; AMLNNEXT AMLNPREV ; AMXLNS STRUC DD DD ? ? ;Next node in list ;Previous node in list ENDS AMX Key Node Structure AMXLKS ; AMLKNEXT AMLKPREV AMLKKEY ; AMXLKS 378 STRUC DD DD DW ? ? ? ;Next node in list ;Previous node in list ;Node key ENDS KADAK Structure/Constant Definitions
AMX Register Array Structure AMXREGS ; AMXRF AMXRAX AMXRBX AMXRCX AMXRDX AMXRSI AMXRDI AMXRBP AMXRDS AMXRES ; AMXREGS STRUC DW DW DW DW DW DW DW DW DW DW ? ? ? ? ? ? ? ? ? ? ;Flags (LS byte only) ;Register AX ;Register BX ;Register CX ;Register DX ;Register SI ;Register DI ;Register BP ;Register DS ;Register ES ENDS AMX Segment Register Array Structure AMXSREGS ; AMXSRDS AMXSRES AMXSRSS AMXSRCS ; AMXSREGS STRUC DW DW DW DW ? ? ? ? ;Register ;Register ;Register ;Register DS ES SS CS ENDS AMX Inter
This page left blank intentionally.
E. AMX 86 Assembler Interface This appendix summarizes the assembly language calling sequences for all AMX procedures. The procedures are organized in functional groups. Within each group the procedures are listed alphabetically. All procedures are called as follows: EXTRN AAxxxx:FAR ;external FAR procedure . .
The following notes are referenced in the procedure descriptions in this appendix. Note: 382 1. All registers are preserved, including AX. 2. Registers CX, DX, SI are unaltered. All other registers are undefined. 3. All registers are restored to the state they were in when AAINT was called. 4. Registers AX, BX, CX and DX are altered. All other registers are preserved. 5. A tag 'ABCD' is presented in DX:CX with 'A' in CL and 'D' in DH. 6. AX is 0 and flags = Z if ES:BX is 0:0.
PROCEDURE C ASM PURPOSE PARAMETERS IN OUT AX = ERRORS E D R n n n System Control ajentr AAENTR Enter AMX multitasking world Launch Parameters Exit allowed? (0=No, 1=Yes) IVT alterable (0=No, 1=Yes) Interrupts enabled (0=No, 1=Yes) A(AMX User Parameter Table) errcode exitinfo BX bit 0 bit 1 bit 2 no DS:SI AX DX:BX ajexit AAEXIT Leave AMX multitasking world (no return) errcode exitinfo CX DX:BX no n n o ajfatl AAFATL Fatal exit (no return) Fatal Exit Code CX no o n o ajhoo
PROCEDURE C ASM PURPOSE PARAMETERS IN OUT AX = ERRORS E D R no n o o Task Control 384 ajend AAEND End task execution (no return) ajgmsg AAGMSG Get message from task mailbox A(Storage for message) Mailbox priority (0 to 3) (4=highest priority message) ES:BX CX AERCWT AERNMG o n n ajresum AARESUM Resume a task suspended by ajsusp Task id DX AERNST o n n ajsend ajsendp ajsenw ajsenwp AASEND Start a task by sending it a message at one of 4 priorities Task id A(message) Pro
PROCEDURE C ASM PURPOSE PARAMETERS IN OUT AX = ERRORS E D R Task Control (continued) ajtkill AATKILL Kill a task Task id DX AERNST AERANA o n n ajtkpry AATKPRY Change task's execution priority Task id Task's new priority DX CX AERNST AERITP o n n ajtkstp AATKSTP Stop a task Task id DX AERNST AERANA o n n ajtksts AATKSTS Fetch task status Task id A(storage for result) DX ES:BX AERNST o n n ajtktag AATKTAG Find task id of task with a specific task tag Task tag T
PROCEDURE C ASM PURPOSE PARAMETERS IN OUT AX = ERRORS E D R Note 2 o n o Note 3 o n o Interrupt Control 386 ajint AAINT Begin interrupt service AMX Interrupt Stack DGROUP segment ajinx AAINX End interrupt service ajispm AAISPM Make an ISP root A(Storage for ISP root) A(Interrupt Procedure) ES:BX CX:DX no o o o ajitrp AAITRP Install task trap handler Interrupt type 0,4 or 5 A(task trap handler) DX ES:BX AERITT o o o ajivtr AAIVTR Read entry in IVT Interrupt type
PROCEDURE C ASM PURPOSE PARAMETERS IN OUT AX = ERRORS E D R Note 1 n n n no o n n no o o o AERNTM AERTMV Note 5 o n n AERNSTM o n n AERNSTM o n n AERNSTM Note 5 o n n Timing Control ajclk AACLK AMX Clock Handler ajtick AATICK Read elapsed system ticks ajtmcnv AATMCNV Convert milliseconds to system ticks ajtmcre AATMCRE Create an interval timer DX:AX Interval (ms) Interval (system ticks) DX:CX A(Timer Definition) Timer id ES:BX DX:CX DX ajtmdel AATMDEL
PROCEDURE C ASM PURPOSE PARAMETERS IN OUT AX = ERRORS E D R AERISV AERNSB Note 5 o n n Semaphore Manager ajsmcre AASMCRE Initial value (0 to 32767) (-1 for resource semaphore) Tag Semaphore id BX DX:CX BX ajsmdel AASMDEL Delete a semaphore Semaphore id BX AERNSS AERSIU o n n ajsmfre AASMFRE Free a resource (unconditional) Resource semaphore id BX AERNSS AERRNY o n n ajsmget AASMGET Get use of a semaphore (no wait) Semaphore id BX AERNSS AERSBY o n n ajsmrls AASMR
PROCEDURE C ASM PURPOSE PARAMETERS IN OUT AX = ERRORS E D R AERNEB Note 5 o n n AERNSG AEREVU o n n no o o o AERNSG o o o Note 4 o n n AERNSG AERNME o n n AERNSG Note 5 o n n AERTMO AERNSG AERTMV n n o Event Manager ajevcre AAEVCRE Create an event group Initial value for event group Tag Group id BX DX:CX BX ajevdel AAEVDEL Delete an event group Group id ajevnt AAEVNT Get saved event state Event value ajevrd AAEVRD Read current event state Group id Ev
PROCEDURE C ASM PURPOSE PARAMETERS IN OUT AX = ERRORS E D R AERNXB AERMBZ Note 5 o n n Message Exchange Manager ajmxcre AAMXCRE Tag A(Mailbox size definition) DW size mailbox 0 DW size mailbox 1 DW size mailbox 2 DW size mailbox 3 Exchange id DX:CX ES:BX BX ajmxdel AAMXDEL Delete an exchange Exchange id BX AERNSX AERXIU o n n ajmxget AAMXGET Get a message from an exchange (no wait) Exchange id A(Storage for message) BX ES:SI AERNSX AERNMG o n n Note 4 o n n AERNSX AERMBF
PROCEDURE C ASM PURPOSE PARAMETERS IN OUT AX = ERRORS E D R AERBNU AERBUV AERNSP o n n AERBTS AERNBF AERNFP o n n Buffer Manager ajbau AABAU Add to buffer use count A(buffer) Increment for buffer use count ES:BX DX ajbcre AABCRE Create a buffer pool A(Buffer Pool Definition) Pool id ES:BX DX ajbdel AABDEL Delete a buffer pool Pool id DX AERNSP o n n ajbfre AABFRE Free a buffer A(buffer) ES:BX AERBNU AERNSP o n n ajbget AABGET Get a buffer from a specific pool
PROCEDURE C ASM PURPOSE PARAMETERS IN OUT AX = ERRORS E D R Memory Manager ajmau AAMAU Add to block use count A(memory block) Increment for use count ES:BX DX AERMIB AERMNU AERMOV o n n ajmfre AAMFRE Free a block of memory A(memory block) ES:BX AERMIB AERMNU o n n ajmgeh AAMGEH Get a block of memory from a private section Required memory size Handle A(allocated memory block) Size of block or available memory DX:CX ES:BX AERMNA AERMIB o n n Required memory size A(allocated
PROCEDURE C ASM PURPOSE PARAMETERS IN OUT AX = ERRORS E D R no o o o Note 6 o o o Linked List Manager ajlcre AALCRE Create an empty list A(List Header) Node offset DS:SI CX ajlhead AALHEAD Find head of list A(List Header) A(First object) (0:0 if list is empty) DS:SI ES:BX ajlinsc AALINSC Insert before specific object A(List Header) A(New object) A(Specific object) DS:SI ES:BX CX:DI no o n n ajlinsh AALINSH Insert at head of list A(List Header) A(Object) DS:SI ES:BX n
PROCEDURE C ASM PURPOSE PARAMETERS IN OUT AX = ERRORS E D R no o n n Note 6 o n n Note 6 o n n Note 6 o o o Linked List Manager (continued) ajlrmvc AALRMVC Remove specific object from list A(List Header) A(Specific object) DS:SI ES:BX ajlrmvh AALRMVH Remove object at head of list A(List Header) A(Object) (0:0 if list is empty) DS:SI A(List Header) A(Object) (0:0 if list is empty) DS:SI A(List Header) A(Last object) (0:0 if list is empty) DS:SI ajlrmvt ajltail AALRMVT
Numerals 24-bit memory addressing 1, 125, 171 A AACLK 73 AAENTR 22 AAINT 54, 55, 56, 73 AAINX 55, 56, 73 ajabl 135, 205 ajatl 135, 206 ajbau 52, 119, 121, 207 ajbcre 119, 120, 174, 189, 208 ajbdel 119, 121, 210 ajbfre 52, 76, 119, 121, 211 ajbget 52, 76, 119, 121, 212 ajbgsz 119, 121, 213 ajbia 119, 214 ajbip 119, 215 ajbtag 119, 120, 216 ajcfjlong 217 ajcfjset 217 ajcfstkjmp 219 ajclk 220 ajdi 221 ajei 221 ajend 35, 61, 153, 154, 155, 222 ajentr 11, 20, 21, 23, 44, 223 ajevcre 104, 105, 108, 174, 185, 225
ajsmcre 91, 93, 94, 95, 98, 99, 174, 183, 301 ajsmdel 91, 93, 99, 302 ajsmfre 91, 95, 303 ajsmget 91, 94, 304 ajsmrls 91, 95, 305 ajsmrsv 28, 91, 95, 96, 306 ajsmsig 52, 58, 76, 91, 94, 308 ajsmtag 91, 93, 309 ajsmwat 28, 58, 91, 94, 98, 99, 310 ajsofs 311 ajsseg 312 ajssreg 313 ajsusp 158, 314 ajtdf 70, 82, 88, 315 ajtdg 70, 82, 316 ajtds 70, 82, 85, 317 ajtick 318 ajtkcre 25, 173, 178, 319 ajtkdel 153, 320 ajtkid 321 ajtkill 153, 322 ajtkpry 47, 323 ajtkstp 153, 324 ajtksts 325 ajtktag 25, 326 ajtktcb 46,
Class of AMX service buffer pool, buffer 197 C language interface 199 circular list 198 counting semaphore 196 event group 196 interrupt control 194 linked list 198 memory allocation 197 message exchange 197 PC Supervisor 200 processor support 199 resource semaphore 196 system control 194 task control 195 task termination 195 time/date 196 timing control 196 Clock frequency 71, 172 Clock Handler 3, 15, 34, 65, 71–74 Clock installation 71–74 Clock Interrupt Handler 71–74 Clock ISP 15, 65, 71–74 Clock ISP roo
F FAR pointers 204 Fatal error 3 Fatal exit 3, 60, 147, 148, 149, 175 Fatal exit codes 147, 148, 149, 351 Fatal Exit Procedure 147, 148, 149, 175 interrupt state 148 stack size 148 Faults (processor exceptions) 68 Fences (stack) 46 File names (AMX files) 7 Flags (see Event group, flags) free 125 Function prototyping 201 G Group id (see Event group, id) Groups DGROUP 31, 42, 44, 55, 62, 76, 86, 132, 148, 151, 156, 180 Grow a memory block 129 H Halt 149 Handle 3 (see also Memory pool, handle) I I/O, device
M Mailbox 4, 26 (see Message (task), mailbox) acknowledge message 35 message queue 4 Make utilities (Refer to AMX Tool Guides) malloc 125 Math coprocessor 101, 102, 152 Memory addressing (24-bit) 1, 125, 171 Memory allocation 18, 125, 126, 128–34 Memory assignment (see Memory Assignment Procedure) Memory Assignment Procedure 131–34, 175 Memory block 4, 125–34 find size 129 free 18, 125, 126, 128, 130 get 18, 125, 126, 128, 130 header 127 ownership 18, 125, 126, 127, 128, 129 resize (grow or shrink) 129 use
P S PC Supervisor (see PC Supervisor Reference Manual) Service Procedure Summary 200 Preemption 13 Priority (see Event group, wait for event(s)) (see Kernel Task, priority) (see Message exchange, message priority) (see Message exchange, wait for message) (see Semaphore, counting, wait) (see Semaphore, resource, reserve) (see Task termination, deletion priority) (see Task, priority) Priority scheduling 30 Privileged (see Task, privileged) Procedures, AMX Beginning on page 193 Ending on page 345 Procedures,
Stack size Exit Procedures 44, 45 Fatal Exit Procedure 148 Interrupt Service Procedure 51, 56, 65 Interrupt Stack 51, 56, 65, 171 Kernel Stack 42, 43, 65, 76, 77, 85, 86, 87, 170 Restart Procedures 42, 43 task 44, 45, 51, 61, 65, 155, 156, 179 Task Termination Procedure 155, 156 Task Trap Handler 61 Time/Date Scheduling Procedure 85, 86, 87 Timer Procedure 76, 77 User Error Procedure 150, 151 User Scheduler Hooks 152 Structure definitions 365–79 Suspend task 158 Symbols, AMX reserved 7, 347 Synchronization
Task termination 153, 154, 155, 156, 157 delete 154, 155, 156, 157 deletion priority 157 enable/disable 154 kill 154, 155, 156, 157 Service Procedure Summary 195 stop 153, 154, 155, 156, 157 Task Termination Procedure 154, 155, 156, 366, 374 Task Trap Handler 60, 61, 62, 63, 147 stack size 61 TCB (see Task Control Block) 6 Testing 159, 160, 161, 162 Tick (see Clock tick) (see System tick) Time slice 6, 70, 79, 80, 81 enable/disable 79, 80, 81, 172 interval 5, 79, 80, 81 Time/Date ASCII formatting 88, 89 cen
