AMX 86 manual

® AM X ™ 86 User's Guide First Printing: November 1, 1990 Last Printing: March 1, 2005 Copyright © 1990 - 2005 KADAK Products Ltd. 206 - 1847 W est Bro adway Avenu e Vancouver, BC, C anada, V6J 1Y 5 Phone: (604) 734-2 796 Fax: (604) 734-8 114[...]

[...]

AMX 86 User's Guide K A DAK i TECHNICAL SUPPORT KADAK Products Ltd. is committed to technical support for its software products. Our programs are desi gned to be easil y incorporated in your s ystems and every effo rt has been made to eliminate errors. Engineering Change Notices (ECNs) are provided periodicall y to repair faults or to improve [...]

ii K A DAK AMX 86 User's Guide Copyright © 1990-2005 by KADAK Products Ltd. All rights reserv ed. No part of this publication may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any language or co mputer language, in any form or by any means, electronic, m echanical, magnetic, optical, ch emical, manu[...]

AMX 86 User's Guide K A DAK iii AMX 86 USER'S GUIDE Table of Cont ents Page Section 1: System Descript ion 1. AMX Overview 1 1.1 Introduction ........................................................................................ 1 1.2 Glossary ............................................................................................. [...]

iv K A DAK AMX 86 User's Guide AMX 86 USER'S GUIDE Table of Contents (Cont'd.) Page Section 1: System Descript ion (Cont'd.) 6. AMX Se m aphore Ma nager 91 6.1 Introduction ........................................................................................ 91 6.2 Semaph ore Use ..............................................[...]

AMX 86 User's Guide K A DAK v AMX 86 USER'S GUIDE Table of Contents (Cont'd.) Page Section 1: System Descript ion (Cont'd.) 12. AMX Link ed List Man ager 139 12.1 Introdu ction ...................................................................................... 139 12.2 Link ed Lists ...........................................[...]

vi K A DAK AMX 86 User's Guide AMX 86 USER'S GUIDE Table of Contents (Cont'd.) Page Appendice s A. AMX 86 Reserved Wo rds 347 B. AMX 86 Error Codes 349 C. Configuration Generator Specifications 353 C.1 Introdu ction ....................................................................................... 353 C.2 User Param eter File Sp[...]

AMX Overview K A DAK 1 1. AMX Overview 1.1 Intr oduction The AMX ™ Multitasking Executive provides a simple solution to the complexity of real- time multitasking. AMX supe rvises the orderly e xecution of a set of application program modules called tasks. AMX allows the s ystem desig ner to concentrat e on the application without becoming overly [...]

2 K A DAK AMX Overview Section Sum ma ry This manual is divided into three sections. Each section is divided into chapters. Section 1 of this manua l describes the AMX Multitasking System and how it is used. Separate chapters ar e provided for each of the AMX managers. Section 2 describes the AMX S y stem Confi guration Builder and the manner in wh[...]

AMX Overview K A DAK 3 1.2 G lo ssary Buffer Pool A collection of data buffers whose use is controlled by the AMX Buffer Man ager. Buffer Pool I d The handle assigned to a buff er 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[...]

4 K A DAK AMX Overview Interrupt Handler An application procedure called from an ISP root to service an interrupting device. Interrupt Servic e Procedure ( I S P) An AMX or application procedure which is executed in response to an external device interrupt requ est. ISP See Interrupt Service Procedur e ISP root The ISP code fragment (produced b y A[...]

AMX Overview K A DAK 5 Message Qu eue An AMX data structure used to manage messages sent to a task mailbox or message exchan g e. A separate mess age queue is provided for ea ch of the four message priorities which a task or message exchan ge can support. Message Priorit y Identifie s which of a task's or messag e exchange' s four message[...]

6 K A DAK AMX Overview Task An application procedure which is executed b y AMX in a way which makes it look as though all such procedures are ex ecuting at once. Task Control Block (TCB) A private data str ucture maintained by AMX for each task in the sy stem . Task I d The handle assigned to a task by AMX for use as a uni que task identifier . Tas[...]

AMX Overview K A DAK 7 1.3 AMX Nomencla ture The following nomenclature has been adopted throu ghout the AMX User's Guide. Processor registers ar e referenced as foll ows: 8-Bit Reg isters AH, AL, BH, BL, CH, CL, DH, DL 16-Bit Registers AX, BX, CX, DX, SP, BP, SI, DI Instruction Pointe r IP Flags (Condition Code) CC Segm ent Re gist ers CS, DS[...]

8 K A DAK AMX Overview This page left blank intentionall y .[...]

General AMX Operation K A DAK 9 2. General AMX Operation 2.1 Introduction to Mult itasking A real-time system is charact erized by the need to respond rapidl y to ev ents occurrin g asynchronousl y in time. A multitasking s y st em is one in which a number of activities or processes must be performed simultaneously without interference with each ot[...]

10 K A DAK General AMX Operation Alarm sc anning will like ly be hardware dependent. We will simplify matters by assuming that a scannin g task must examine all digital inputs every 100 ms. The task must be capable o f detecting al arm changes in the digital inputs. When an alarm is detected, the scanning task must initiate the logging of a messag [...]

General AMX Operation K A DAK 11 2.2 AMX Oper ation AMX Startup Each AMX-based s y stem consists of the AMX execut ive program and a s et of application tasks and interrupt se rvice procedures. This collection of pro grams resident in the memory o f the mic roprocessor configur ation represents the entire operating sy stem . The manner in which the[...]

12 K A DAK General AMX Operation Contr ol Flow Funct ion c a ll s Int errup ts In it ia l iza t io n Restar t Pr oce dure T ask Sc he dule r Services Start Timer Pr oce dure Int errup t Super vi sor Cloc k Ha ndl er Int errup t Servi ce Pr oce dure Kernel Task Us er AMX Ta s k A Ta s k N Cl ock Figure 2.2-1 AMX Gen eral Operation[...]

General AMX Operation K A DAK 13 The Task Sched u ler Following system initialization, AMX proceeds to its Task Scheduler. The Task Scheduler searches its list of av ailable tasks to de termine the highest priority ta sk capable of execution. Task ex ecution priorities are d etermined b y the s y stem d esigner. If no task is ready to be gin execut[...]

14 K A DAK General AMX Operation The Interru pt Supervisor Tasks execute with the processor inter rupt facility ena bled to permit service of externa l devices. When an ex ternal int errupt occu rs, the t ask is interrupt ed in the manner dictat ed by the processor. The pro cessor automatical ly saves the return add ress and some subset of the proc[...]

General AMX Operation K A DAK 15 Timing F acilities The AMX Timer Manager provides a Clock Handler and a Kernel Task to provide complete timing control for y our r eal-time application. The AMX Clock Han dler is independent of any particular hard ware configuration. If AMX timing facilities are to be utilized, a rea l-time clock must be inc luded i[...]

16 K A DAK General AMX Operation Message Queuing One of the more power ful features of AMX is its ability to queue messages for tasks. The queuing facility permits messages to pile up in a controlled fashion, freein g the I SP, Timer Procedure or task which is sending the messa ge to continue with its appointed function. If a task sends a message, [...]

General AMX Operation K A DAK 17 2.3 AMX M anag ers AMX provides a set of managers to simplif y ev ent synchronization, resource manipulation and memory allocation. Not all applications will make use of all of the managers. The system designer can de cide which of the AMX managers is best suited for a particular application. The Time/Date Manager p[...]

18 K A DAK General AMX Operation The AMX 86 Task Mailbox facility provides a ge neral purpose messag e queuing mechanism f or tasks. This service is not provided by a separa te AMX manager; it is an inherent feature of AMX 86. An y task can hav e up to four private mailboxes in which the task can receiv e AMX messages. Tasks, ISPs or Timer Procedur[...]

General AMX Operation K A DAK 19 The Circular L ist Manager provides a genera l purpose circular list f acility for maintaining compact lists of 8-bit, 16- bit or 32-bit var iables. Circular lists are particularl y use ful for managing character streams asso ciated with input/output devices. The Linked List Manager provides a fast, general purpose [...]

20 K A DAK General AMX Operation 2.4 S tartin g AMX An AMX operating system consists of AMX, the subset of its managers which y ou choose to use and y our complement of application programs. All of these modules are connected together to form the AMX oper ating system as described in the AMX Tool Guide. Before la unching AMX, you must establish the[...]

General AMX Operation K A DAK 21 Perm anent Launch In most applica tions, your AMX operating s yste m is resident in ROM or loaded into RAM. AMX is started in real mode and given permanent control o f the processor. An AMX system can be launch ed permanentl y from a main pro gram coded in C as illustrated in the f ollowing example. The implication [...]

22 K A DAK General AMX Operation An AMX sy st em can be launched permanentl y from a startup module coded in assembly language a s illustrated in the f ollowing example. Systems of this type begin execution at the AMX ent ry point AAENTR with the launch parame ter in registe r BX . Register BX[0] must be set to zero to indicate t hat a permanent la[...]

General AMX Operation K A DAK 23 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 temporar y launch. The most common application of this ty p e occurs on PC compa tibles. An AMX operating sy st em is starte d from DOS, allowed to opera te for a while and then [...]

24 K A DAK General AMX Operation When an AMX system is launched fo r temporary execution, it ex ecutes until one of your application tasks c alls the AMX exit procedure ajexit requesting an orderly shutdown of the AMX s y stem (se e Chapter 3.11). The ajexit caller can re turn two parame ters to the procedure t hat launched AMX. On e of these param[...]

Application Ta s ks K A DAK 25 3. Application T asks 3.1 T ask Creation The AMX Multitasking Executive provides a simple solution to the comple xity of rea l- time multitasking . AMX supervises the orderly execution of a set of application program modules called tasks. Eac h task solves a particular problem and provides a specific functional ca pab[...]

26 K A DAK Application Ta s ks Tasks which do not receive messages are written as Large or Medium model C functions without formal parameters. Thes e tasks must be started using AMX pr ocedure ajtrig . For this reason, such tasks are called tri gger task s . For example, a task that immediately ends would appear as follows: void cdecl task1(void) {[...]

Application Ta s ks K A DAK 27 3.2 T ask S tates A task is always in one of the following states: Idl e Ready Run Wait Halt When a task is cr eated, AMX assigns it a Task Contr ol Block and sets it in the idle state. An idle task has no outstanding requests to e xecute pending. It is waiting to be triggered. A read y t ask has an outstanding reques[...]

28 K A DAK Application Ta s ks event of interest or timeout occu rs ajtri g - trigger a task ajwai t - wait ajwat m - timed wait ajsen w - send me ssa ge to tas k mailbox and wait f o r ack ajmxwa t - wait on a message exchange ajsmrs v - reserve a resou rce ajsmwa t - wait on a semaphore ajevwa t - wait for event task ends or is interrupted no hi [...]

Application Ta s ks K A DAK 29 3.3 S tartin g a T ask At startup, AMX initializ es all predefined application tasks into an idle state. Once idle, a task cannot execute until AMX rec eives a directive to start the task. How then does an AMX system get off the ground? Three AMX directi ves are provided t o start a task. These dir ectives are procedu[...]

30 K A DAK Application Ta s ks 3.4 T ask Priority Task prior ities are used by the AMX Ta sk Scheduler to dete rmine which task to execute . At all times, the task with the highest pr iority 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 (lowes[...]

Application Ta s ks K A DAK 31 3.5 T ask Execution AMX starts a task by ma king 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 ex ecution. Requests can come from Restart Procedures, tasks, Interrupt Service Proc[...]

32 K A DAK Application Ta s ks 3.6 T ask and Event Synchr onizati o n AMX offers several simple forms of task/ev ent sy nchronization. Using the ajwait call, a task can unconditionally wa it for an event. The event can be task dependent, de vice dependent or time dependent. The task, having issued an ajwait call, rema ins suspended unconditionally [...]

Application Ta s ks K A DAK 33 The simple featur es included in the AMX k ernel are au gmented by three powerful mechanisms for event s y n chronization provided by separate AMX mana gers. The Semaphor e Manager provides counting semaphores with queuing and timeout facilities for mutual exclusion and re source manageme nt. It also offer s a unique [...]

34 K A DAK Application Ta s ks 3.7 T ask T im ing The AMX Clock Handler and Kernel Task act a s a Timer Manager providing timing facilities for use by tasks. I t has been sho wn in Chapter 3.6 that tasks can wait for an event to occ ur with an automatic timeout. The task is suspended following its wait request until the e vent occur s or the interv[...]

Application Ta s ks K A DAK 35 3.8 Endin g a T ask When a task completes its appointed function, it must relinquish control of the proc essor to AMX. The AMX Task Sc heduler will then g ive control of the processor to the next highest priorit y task ready to execute. AMX starts a task b y a FAR pro cedure call to the task at the task start add ress[...]

36 K A DAK Application Ta s ks 3.9 Me ssage P a ss i ng AMX supports the passing of a message to a task mailbox or messa ge exchange. Messages can be sent to a task by: Application Tasks Interrupt Servic e Procedures Timer Procedures Restart Procedur es Exit Procedures You can send a message to a task mailbox or message exchan ge using the AMX proc[...]

Application Ta s ks K A DAK 37 AMX uses messag e envelopes for pa rameter transmission. AMX gets a free envelope, moves the ca ller's message parameters into it and adds the en velope to the task mailbox or message exchange messa ge queue. If the sender r equested to wait, AMX inserts informa tion into the enve lope which allows AMX to r ememb[...]

38 K A DAK Application Ta s ks Figure 3.9-1 provides an example of the m anner in which messages are allowed to queue on a message exchange. The s ame 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 f ollowing situation is assume d to exist at the m[...]

Application Ta s ks K A DAK 39 In due course the destination task will c ontinue to execute a nd complete its processing of the current messag e, X. Th e destination task will then r equest AMX for a message fr om the message exchange three more times in succession to process messages I, J and K. Finally , the message from ta sk YY will be retrieve[...]

40 K A DAK Application Ta s ks It is important to note that a copy of the sender's message paramete rs is sent to the destination task. Once the sender's paramet ers have been copied into the message envelope, the caller is free to r euse the parameter storage if desir ed. Thus, as soon as procedure ajsend or ajmxsnd (or an y of their var[...]

Application Ta s ks K A DAK 41 Message Extension AMX deliver s message s to a task by copying the message from a message envelope to a message frame on the task's stack. AMX also present s an extension t o the application message on the task's stack. The message ex tension identifies who sent the message and, if a task, whether the sender[...]

42 K A DAK Application Ta s ks 3.10 Rest art Pr ocedu res 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 depe ndent setup prior to the initializa tion of the AMX sy stem. For example, hardware interfaces may requi[...]

Application Ta s ks K A DAK 43 Restart Procedures can enable specific d evice interrupts if requir ed. Note that interrupts from a device should not be enabled until the application ISP has been installed and made ready to handle the interruptin g device. Restart Procedures should not enable the processor interrupt s y stem if your launch parameter[...]

44 K A DAK Application Ta s ks 3.1 1 Exit Pr ocedur es An AMX s y stem can b e shut down in an orderl y fashion b y a task call to procedure ajexit . The manner in which the operating s y stem ends ex ecution is application dependent. For example, hardware interfaces ma y require restoration to their initial states. AMX supervises the shutdown pr o[...]

Application Ta s ks K A DAK 45 Exit Proce dures execute in the context of the task which issued the ajexit c al l. T he y a re therefore fr ee to use all services no rmally availabl e to tasks. For instanc e, 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 P[...]

46 K A DAK Application Ta s ks 3.12 T ask Enhancem ents AMX offers several task enh ancements which, although ra rely used, can occasionall y come in hand y . Thes e enhancements are bri efly summarized below. Task Control Bloc k Extensio n Within a task's Task Control Block, 16 by tes are reserved f or the private use of the task. Their use i[...]

Application Ta s ks K A DAK 47 AMX Kernel Task Priori ty The AMX Kernel Task op erates as the hi ghest priority task in your AMX s y stem. Its execution priorit y is z ero. It has the reserved task tag 'AMXK' . Occasionall y , an application is encountered in which a task must execute at ver y high priority in order to cope with the idios[...]

48 K A DAK Application Ta s ks This page left blank intentionall y .[...]

Interrupt Service Procedures K A DAK 49 4. Interrupt Serv ice Pr ocedures 4.1 The Pr ocessor Interrupt Faci lity The key to e vent-driven, rea l-time, multitasking systems is the proce ssor's interr upt facility . Tasks execute with the interrupt fac ility enable d permitting the syste m to respond to a real-time event. The har dware interrupt[...]

50 K A DAK Interrupt Service Procedures When used with the 8086 family of microprocessors, AMX supports the following exception and interrupt sources: Divide error ( DIV or IDIV instr uction) Non-Maskable interrupt ( NMI hardware signal ) Overflow ( INTO instruction) Bounds error ( BOUND instruction) External devices ( INTR hardw are signal) All ot[...]

Interrupt Service Procedures K A DAK 51 4.2 ISPs for External Interrupts Two types of ISPs exist: nonconforming ISPs and conforming ISPs. Nonconforming ISPs A nonconforming I SP must quickly service the device to remove the interrupting condition. The I SP must preserve all registers which it uses. The nonconformin g ISP cannot make calls to an y A[...]

52 K A DAK Interrupt Service Procedures If the Inter rupt Handler re quested AMX to initiate or resume execution of some task of higher priority th an the interrupted task, the AMX Int errupt Supervisor suspends the interrupted task and marks it as read y to resume execution at the earliest opportunit y. The AMX Task Scheduler is then invoked to de[...]

Interrupt Service Procedures K A DAK 53 Conform ing ISP Construction The construction of an Interrupt Service Pro cedure (ISP) to servic e an external interrupt is a simple proce ss. The conforming ISP consists of two parts: the ISP root and your I nterrupt Hand ler. The ISP root is a code fra gment most easil y created usi ng procedure ajispm . Th[...]

54 K A DAK Interrupt Service Procedures The Interrupt Service Procedure should be cod ed using assembly language if speed of executi on is critical. EXTRN AAINT:FAR EXTRN 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 : : [...]

Interrupt Service Procedures K A DAK 55 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 th e device. Upon return to the ISP from the AMX Interrupt Supervisor [...]

56 K A DAK Interrupt Service Procedures 4.3 Nested Interrupt s AMX supports nested interrupts. The AMX Interrupt Supervisor maintains a private nesting le vel indicator. AMX must be inf ormed of the start ( AAINT ) and end ( AAINX ) of each interrupt. When AMX sees tha t a task has been inter rupted, it switches to a predefined Interrupt Stack. I f[...]

Interrupt Service Procedures K A DAK 57 4.4 ISP /T ask Co mm unication AMX provides a set of service proc edures to ease the communication between tasks and device Interrupt Handlers. Thes e AMX procedures simplif y e vent synchronization and permit para meter passing to ta sks. Wait/Wake Synchronization The ajwait / ajwake pair of procedures is of[...]

58 K A DAK Interrupt Service Procedures Sem aphore Synchr onization The AMX Semaphore Manager provides an ev en more powerful s y n chronization capability . I t p rovides the automatic time out facility and also allows more than one task to wait for the sa me event, with each task de termining its own waiting priorit y . Furthermore, the Interrupt[...]

Interrupt Service Procedures K A DAK 59 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 identify ing the task which it wishes to have executed. This technique can be ver y useful for handling slowl y occurring events[...]

60 K A DAK Interrupt Service Procedures 4.5 T ask Error T raps The 80x86 processor automaticall y detects the occurr ence of execut ion errors such as division by zero, arithmetic overflow or an arra y bound violation. These errors, b y their very na ture, must be ha ndled by the application in the context of the task in whic h they occur. AMX offe[...]

Interrupt Service Procedures K A DAK 61 The task trap handler can be written as a Large or Medium mode l C function with formal parame ters. #include "amx831sd.h" /* AMX Structure Definitions*/ void cdecl tdiverr( struct amxregs regs, /* Register structure */ void FAR *faultp) /* Fault pointer */ { : Process the error : } Since the task t[...]

62 K A DAK Interrupt Service Procedures Note that the C trap handler receives a structure amxregs passed b y value. If your C compiler does not allow such declarati ons, y ou can use casts to coe rce access to the parameter s on the stack as follows: #include "amx831sd.h" /* AMX Structure Definitions*/ void cdecl tdiverr(int dummy) { stru[...]

Interrupt Service Procedures K A DAK 63 INCLUDE AMX831SD.DEF ;AMX Structure Definitions ; USER_CODE SEGMENT BYTE 'CODE' ; ASSUME CS:USER_CODE ; TDIVERR PROC FAR : Access register structure AMXREGS via SS:BP : LES BX,DWORD PTR [BP+(SIZE AMXREGS)] ; ;ES:BX = A(fault) : Process the error : RET ; TDIVERR ENDP ; USER_CODE ENDS[...]

64 K A DAK Interrupt Service Procedures 4.6 Non-M ask able Interrupt The Intel 80x86 processor and equivalents provide a non-mask able interrupt (NM I). 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 lo[...]

Interrupt Service Procedures K A DAK 65 4.7 Speci al Interrupts Nonconforming In terrupts In some s y stems the re may be devices which generate interrupts requiring no communication or synchronization with any task in the system. For example, a high- speed scanner can in terrupt the p rocessor when ever new dat a readin gs are avail able. The ISP [...]

66 K A DAK Interrupt Service Procedures Shared Inte rrupt Handle rs Occasionall y a si ngle Interrupt Handl er can be used to servic e more than one ident ical device. For example, an Int errupt Handler fo r an as ynchronous serial I/O device (U ART) could be used to service the UART for e ach of several communication lines. For the I nterrupt Hand[...]

Interrupt Service Procedures K A DAK 67 The two device I SP roots are illustrated below. Each of the I SP roots calls the I nterrupt Handler deviceih p assing it a pointer to a unique, public, device dep endent data structure ( dcbA or dcbB ). Note that most common C compilers add leading underscores to function and variable names declar ed in C. Y[...]

68 K A DAK Interrupt Service Procedures 4.8 V ector T able Initializ ation The 80x86 processor operating in real mode v ectors 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 m ay be located i n RAM or ROM as dict ated b y your ha[...]

AMX Ti m i ng Control K A DAK 69 5. AMX Timing Control 5.1 Intr oduction to T iming Facilities Most rea l-time sy stems are charac terized by the need to provide prec ise contro l over the timing of activities. A ha rdware clock provides the timing source; AMX provides the control over its use. The unit of time in an AMX syste m is the system tic k[...]

70 K A DAK AMX Ti m i ng Control Calendar Clock The AMX Time/Date Manager provides Y2K compliant time of day calendar support if required. The AMX c alendar clock includes second, minute, hour, da y , month, y ear and day of the week. AMX se rvices are provided t o set and read the calend ar clock. A formatting procedure is also pr ovided to transl[...]

AMX Ti m i ng Control K A DAK 71 5.2 AMX Clock Handler and Kernel T ask AMX includes a conforming clock I SP root, a Clock H andler and a Kernel Task to provide timing f acilities. Wheneve r a clock interr upt occurs, the clock ISP root calls your application clock I nterrupt Handler to dismiss the hardwa re clock interrupt. The ISP root then calls[...]

72 K A DAK AMX Ti m i ng Control Clock ISP Implem entation AMX can provide timing facilities only if a hardware clock interrupt is available. For efficienc y , it is recommended that the clock ISP be coded in assembly language as illustrated below. Note that the cloc k I SP root and Interrupt Handler have been merged, making the clock ISP a sing le[...]

AMX Ti m i ng Control K A DAK 73 In this exampl e, the clock ISP pointer ( CLKIS P ) must be installed into vector number 33 in the processor Interrupt Vector T able (IVT). AMX service procedure AAIVTW has been used in a Restart Procedure for this purpose. W hen the clock interrupt occurs, the processor disa bles the interrupt fa cility, saves the [...]

74 K A DAK AMX Ti m i ng Control It is preferred that the AMX Clock Handler be c alled from a clock ISP coded in assembl y language as in the example alread y provided. However, it is possible to code the clock ISP in C as indica ted in the following e xample. This C solution is not reco mmended since it significant ly increases th e service overhe[...]

AMX Ti m i ng Control K A DAK 75 5.3 Inter val T imers and T imer Proce dur es AMX supports any number of application interval timers in a s y stem. The maximum number in a s y stem is defined in your System Config uration Module (see Chapter 14.5 ). A timer must be crea ted by an application be fore it can be use d. Restart Proce dures, tasks, I S[...]

76 K A DAK AMX Ti m i ng Control The AMX service pro cedures which can be called from a Timer Pro cedure include the following: ajtrig AATRIG Start (trigger) a task with no messa ge ajsend AASEND Start a task by sending it a message at one of 4 priorities ajwake AAWAKE Wake a task which is waiting ajsgnl AASGNL Signal a t ask ajtmcre AATMCRE Create[...]

AMX Ti m i ng Control K A DAK 77 Timer Proce dures can be writte n as Large or Medium mode l C func tions with for mal parame ters. #include "amx831cf.h" /* AMX C Interface Header */ void cdecl truser( /* Timer Procedure */ AMXID timerid, /* timer id */ struct userblock FAR *userp) /* pointer to user block */ { : Do timer expiry processin[...]

78 K A DAK AMX Ti m i ng Control The Timer Procedure can be coded in ass embler 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 P[...]

AMX Ti m i ng Control K A DAK 79 5.4 T ask T im e 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 the n specified as multiples of the AMX sy stem tick. Time slicing is normally disabled. I t is enabled with a call to AMX proce dure [...]

80 K A DAK AMX Ti m i ng Control Figure 5.4-1 illustrates the allocation of pro cessing time to two tasks, B and C. Task B was created fi rst with a time slice interval of 100 AM X s y st em ticks. Task C was creat ed later with a time slice interval of 50 AMX syste m ticks. At time t1 , tasks B and C were both triggered by a higher priorit y task [...]

AMX Ti m i ng Control K A DAK 81 Time slicing can be comple tely disabled at any time with a call to AMX proce dure ajtsof . Procedure ajtson can then be used to enable time slicing. Task time slice inte rvals can be dy namically adjusted using AMX procedure ajtslv to fine tune the shared use of the proc essor based on observed effects. The startin[...]

82 K A DAK AMX Ti m i ng Control 5.5 T ime/Date M anager Most real-time sy st ems require the maintenance of a calendar clock. The AMX Time/Date Manage r provides this facility . The Y2K compliant ca lendar clock ma intained by the Time/Date Manager includes second, minute, hour, day, month and y e ar. Leap year is accounted for. The day of the wee[...]

AMX Ti m i ng Control K A DAK 83 Operation The Time/Date Manager includes two components: an AM X Restart Procedure and a set of service procedures. If your AMX System Configuration Module enables the Time/Date option, AMX automatica lly calls the Time/Date Restart Proc edure dur ing the launch prior to executing any application Restart Proc edure.[...]

84 K A DAK AMX Ti m i ng Control Time/Da te Structu re The Time/Date Man ager provides time and date in the following form. C structure amxtds is defined in the AMX head er file AMX831SD.H . Assembler structure AMX TDS is defined in the AMX definition file AMX831SD.DEF . The C and assembler structure definitions are shown b elow. /* AMX Time/Date S[...]

AMX Ti m i ng Control K A DAK 85 Time/Date Validit y The century is used as follows. At startup, the Time/Date Restart Proc edure resets the century to 0 to indica te that the initial default time and date are incorr ect. Note that the initial time and da te are va lid; they are just not c orrect. At some later time, an application program can issu[...]

86 K A DAK AMX Ti m i ng Control The following conditions exist when y our Time/Date Scheduling Pr ocedure is ca lled by the Time/Date Ma nager Interrupts are en abled. All registers ar e free for use. DS,ES DGROUP segment SS:SP AMX Kernel S tack ready for use BP Offset of paramet ers on stack The direction flag is set to forward. The Scheduling Pr[...]

AMX Ti m i ng Control K A DAK 87 Your Time/Date Scheduling Procedure can b e 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[...]

88 K A DAK AMX Ti m i ng Control Time/Date ASCII Formats The Time/Date Manager procedu re ajtdf can be used to format time and date into a n ASCII character string in an y o f several popular formats. The time and date is presented to ajtdf in the standard AMX time /date structure. The ASC II string is returned in a character buffe r provided by th[...]

AMX Ti m i ng Control K A DAK 89 Figure 5.5-1 describes the format sp ecification by te and the effe ct of each bit in it on the formatting of the time and date . 765432 10 TD1 TD0 C M S W D1 D0 TD1 TD0 Time/Date sele ction 0 0 time followed by date 23:59:59 Sun Jan 31/93 0 1 time only 23:59:59 1 0 date only Sun Jan 31/93 1 1 date followed by time [...]

90 K A DAK AMX Ti m i ng Control This page left blank intentionall y .[...]

AMX Se m aphore M anager K A DAK 91 6. AMX Semaphore Man ager 6.1 Intr oduction E.W. Dijkstra introduce d two primitive opera tions to resolve two seemingly unrelated problems: mutu ally exclusive access b y tasks to critical r esources and th e synchronization of asynchronousl y occurring activities. The ab stract primitive s, called P and V oper [...]

92 K A DAK AMX Se m aphore M anager Your use of the Semaphore Mana ger is optional. If y ou 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 y ou r System Configuration Module which is processed by the Semapho re [...]

AMX Se m aphore M anager K A DAK 93 6.2 Semaphor e Use The Semaphore Manager supports any number of semaphores. Th e maximum number of semaphores in a s y stem is defin ed in your System Configuration Module (see Chapter 14.5). The defined maximum sets an upper limit on the number of actual sem aphores that can be created in your application. A sem[...]

94 K A DAK AMX Se m aphore M anager Counting Sem aphore A counting semaphore is created b y specifying an initial semaphore count greater than or equal to zer o in the call to ajsmcre . When used for mutual ex clusion, 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 t[...]

AMX Se m aphore M anager K A DAK 95 Resource Se maphore AMX resource semaphores provide the simplest mechanism for controlling the access to critical resources. Resources ma y include disk files, I/O devi ces, database components, regions of memory , specific word s of memory or any other entity which is considere d to be a resource. An application[...]

96 K A DAK AMX Se m aphore M anager If the resource does not beco me available within the timeout inter val specifie d by the task, the task will be removed from the resourc e semaphore wait queue and will resume execution with a timeout indica tion. Tasks which need to use a resource but which cannot wait for the resource to be free can still call[...]

AMX Se m aphore M anager K A DAK 97 6.3 Semaphor e Applications Mutual E xclusion Assume that three t asks, A, B and C, require sh ared access to a common data st ructure being used to control some process. Acce ss to the data structure must be mutually exclusive so that one task cannot be modif y ing the data in the structure while another task is[...]

98 K A DAK AMX Se m aphore M anager #include "amx831cf.h" /* AMX C Interface Header */ static AMXID daccess; /* Data access semaphore id */ static struct { int dbpar1; /* parameter 1 */ int dbpar2; /* parameter 2 */ : : } datavar; /* Data variable */ void cdecl rruser(void) /* Restart Procedure */ { ajsmcre(&daccess, 1, "DACS&quo[...]

AMX Se m aphore M anager K A DAK 99 Task/Event Sy nchronizat ion A counting semaphore can be used to provide s ynchronization between a task waitin g for an event and a task, ISP or Timer Proc edure in which the ev ent is detected. Th e following exam ple assumes that a device ISP detects the event . A task creates a counting semaphore with an init[...]

100 K A DAK AMX Se m aphore M anager EXTRN AAINT:FAR ;enter ISP EXTRN AAINX:FAR ;leave ISP EXTRN AASMSIG:FAR ;signal to a semaphore EXTRN _SYNCISP:WORD ;ISP synchronization semaphore id ; ; DVC_CODE SEGMENT BYTE 'CODE' ; ASSUME CS:DVC_CODE ; ; DVCISP PROC FAR CALL AAINT ;tell AMX : Clear interrupt source Check for event : MOV BX,_SYNCISP [...]

AMX Se m aphore M anager K A DAK 101 Resource Nesting Assume that two tasks, A and B, have to share a numeric coproc essor. Furthermore, these two tasks also must share a common librar y pro cedure ncmath which must use the coprocessor. A resource semaphore must be used b ecause ownership of the numeri c coprocessor must be tied to one task a t a t[...]

102 K A DAK AMX Se m aphore M anager #include "amx831cf.h" /* AMX C Interface Header */ static AMXID ncaccess; /* Coprocessor resource */ /* semaphore id */ void cdecl rruser(void) { ajsmcre(&ncaccess, -1, "387P"); /* Create resource semaphore */ } int ncmath( AMXID ncid) /* Semaphore id */ { int status; status = ajsmrsv(nci[...]

AMX Ev ent Mana ger K A DAK 103 7. AMX Ev ent Manager 7.1 Intr oduction The AMX Event Manager provides the most general form of event s ynchronization offered b y AMX. The Event Man ager provides a convenient mechanism for sep arating the tasks waiting fo r events f rom the tasks, Timer Procedures and Interrupt Service Procedures which c an signal [...]

104 K A DAK AMX Ev ent Mana ger The AMX Event Manager provides the followin g event management services: ajevcre AAEVCRE Create an event group ajevdel AAEVDEL Delete an event group ajevsig AAEVSIG Signal one or more events in a group ajevwat AAEVWAT Wait for all/a ny of a set of events in a group (optional timeout) ajevrd AAEVRD Read current st ate[...]

AMX Ev ent Mana ger K A DAK 105 7.2 Event S ynchr onization The AMX Event Manager supports an y number of event groups in a s y stem. Each event group includes 16 event flags. The maximum number of event groups in a syst em is defined in your S y stem Configuration Module (se e Chapter 14.5). The defined maximum sets an upper limit on the number of[...]

106 K A DAK AMX Ev ent Mana ger Events are signalled by tasks, I SPs and Timer Proce dures. The e vent is signalled with a call to procedu re ajevsig . The caller specifi es the group id of the event group which contains the pa rticular ev ent. More than one event can be signa lled in a single call to ajevsig . The caller spe cifies a 16-bit ma sk [...]

AMX Ev ent Mana ger K A DAK 107 7.3 Event F lag Appli c ation The following ex ample, coded in C, is provide d to illustrate the use of the AMX Event Manager for event s ynchronization. The example shows two tasks, A and B, which must be s ynchronized to the state of a motor. Task A must wait for the motor to be turned on. Task B must wait for the [...]

108 K A DAK AMX Ev ent Mana ger #include "amx831cf.h" /* AMX C Interface Header */ static AMXID motorgroup; static unsigned char motorstatus; #define MOTORPORT 0x65 /* Motor status port */ #define MOTORON 0x01 /* Motor on */ #define MOTORMAX 0x02 /* Motor at maximum speed */ #define MOTOREVT (MOTORON + MOTORMAX) void cdecl tpmotor( /* Mot[...]

AMX Ev ent Mana ger K A DAK 109 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 +[...]

110 K A DAK AMX Ev ent Mana ger This page left blank intentionall y .[...]

AMX Message Exchange Manager K A DAK 111 8. AMX M essag e Exc hange Mana ger 8.1 Intr oduction The AMX Message Exchan ge Manager provides a v ery flexible, general purpose mechanism f or inter proce ss communication and sy nchronization using prioritized messages. I n particular, it offers an instant solution to a common problem frequentl y encount[...]

112 K A DAK AMX Message Exchange Manager The task' s wait priority is not to be confused with the message queue prior ity. The message queue prior ity dete rmines the priority orde ring of messag es in the message exchange whe n no task is waiting for a message. The task's wait priority determine s the order of ta sks in the wait queue wh[...]

AMX Message Exchange Manager K A DAK 113 8.2 Me ssage Ex change U se The Message Exchange Manager supports an y number of message exchan ges. The maximum numbe r of message exchanges in a system is def ined in your System Configuration Module (see Chapter 14.5). The defined m aximum sets an upper limit on the number of actual message ex changes tha[...]

114 K A DAK AMX Message Exchange Manager Messages are sent to message exchan ges in AMX message envelopes. The Message Exchange Manager gets a free message envelope from the common pool of envelopes maintained by AMX. You must the refore be sure to allocate enoug h message envelopes to meet the needs of all of y our m essage exchange messa ges as w[...]

AMX Message Exchange Manager K A DAK 115 8.3 Me ssage Ex change Applic ati on The following example, code d 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 processin g tasks, A and B, accept and se rvice the messa ges[...]

116 K A DAK AMX Message Exchange Manager #include "amx831cf.h /* AMX C Interface Header */ #define UMS 12 /* User message size */ extern AMXID dactid; /* Data acquisition task id */ extern AMXID dbtid; /* Data base update task id */ static AMXID msgexch; /* Message exchange id */ struct appmsg { /* Message structure */ short int msgtype; /* Ap[...]

AMX Message Exchange Manager K A DAK 117 void cdecl sttask(void) /* Common task body */ { union msgu msgbuf; /* Message buffer */ int status; /* 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.umsg : } else if (status == AERTMO) [...]

118 K A DAK AMX Message Exchange Manager void cdecl dactask(void) /* Data acquisition task */ { union msgu msgbuf; /* 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 messag[...]

AMX Buffer M anager K A DAK 119 9. AMX Buffer Manage r 9.1 Intr oduction The AMX Buffer Manager simplifies the manage ment of memory buffers in a real-time system. I t provides a general mechanism for the allocation and control o f fixed size buffers. The AMX Buffer Manager provides fast, efficient access to multiple pools of buffers, each buffer r[...]

120 K A DAK AMX Buffer M anager 9.2 Buffer Pool U se The Buffer Manager supports an y number of pools of buffers. The maximum number of buffer pools in a s y stem is defin ed in your System Configuration Module (see Chapter 14.5). The de fined maximum sets an upper limit on the number of actual buffer pools that can be created in your application. [...]

AMX Buffer M anager K A DAK 121 Ge t Buffer Once a buffer pool has be en created, you may call procedure ajbget to get a buf fer from the pool. The Buffer Manager unlinks a buffer from the pool's fre e list, sets the associated buffer use count to one and returns a pointer to the first b y te of the buffe r. You may then store and retrieve an [...]

122 K A DAK AMX Buffer M anager 9.3 Buffer Applicat io ns Consider the following example. A process cont rol system using AMX has a printer on which errors and status messa ges 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 the y have[...]

AMX Buffer M anager K A DAK 123 These solutions each h ave their own advantages and disadvantages. Method 1 requires twice as man y buf fers as the other methods and requir es extra processor time to cop y the message twice. Method 2 cannot displa y the messa ge simultaneously on both the CRT and printer. Also, method 2 requires the displa y task t[...]

124 K A DAK AMX Buffer M anager 9.4 Buffer Manager Cave at s Although the B uffer Manager attempts to check as many error conditions as possible, it cannot protect against a bad s y stem design. However, if a little ca re is taken during system design, the Buffer Mana ger can help make a s ystem more reliabl e than one that uses an ad hoc buffer ma[...]

AMX M em ory Manage r K A DAK rev9 125 10. AMX M em ory Man a ger 10.1 Int roducti on The AMX Memory Manager simplif ies the manag ement of memory in a n AMX system. It provides a g eneral mecha nism for the dynamic allocation and c ontrol of memor y and is specifically de signed for use in a multitasking environment. Multitasking adds pa rticular [...]

126 K A DAK AMX M em ory Manage r The AMX Memory Manager provides the following memor y management services: ajmget AAMGET Get a block of memor y ajmfre AAMFRE Release a blo ck of memory ajmgsz AAMGSZ Get the size of a block of memor y ajmau AAMAU Add to block use count ajmset AAMSET Set memory to a pattern ajmsetf ajmhan AAMHAN Create a h andle to[...]

AMX M em ory Manage r K A DAK 127 10.2 N omencla tur e The following nomenclature has been adopted b y the Memory Manager. A Me mory Section is a contiguous, double word ali gned area of Random Access Memory Random (RAM) which has been specified b y the user to be under the control of the Memor y Manager. A sect ion can exceed 64K b ytes in size. T[...]

128 K A DAK AMX M em ory Manage r 10.3 M em ory Allocation The Memory Manager maintains a single memor y pool. The memory pool consists of any number of memory sections of varying size s measured in byte s. An y memory section size which is a multiple of 4 and gre ater than or equal to 64 bytes is allowed. Usually the memory pool consists of a sing[...]

AMX M em ory Manage r K A DAK 129 Use Count When the Memory Manager allocates a bloc k of memory for the use of a task, it sets the block's use count to one. The block owner may call the Memor y Manager procedur e ajmau to increase th e use count. If the use count is increas ed by one, the block will have to be releas ed twice before it become[...]

130 K A DAK AMX M em ory Manage r 10.4 P rivat e Mem ory Alloc ation A particular l y unique fea ture of the Memory Manager permits any bloc k of memor y (including those acquired from the Memor y Manager) to be treated as a memor y section from which smaller private blocks can be d ynamically allocated. To use this feature, a task calls procedu re[...]

AMX M em ory Manage r K A DAK 131 10.5 M e m ory Ass ignment The sections of memor y which make up the memory pool controlled by the Memor y Manager must be provided b y your application. The Memory Manager makes no assumptions concerning the whereabouts of the memor y over which it has control. Sections of memory ar e assigned to the Memory Manage[...]

132 K A DAK AMX M em ory Manage r 10.6 M em ory Assignm ent Procedur e An application Memory Assignment Procedure must be provided to d y n amically assign memory sections to the Memor y Manager. The Memory Assignment Procedur e is called by the Memory Manager when AMX is started, p rior to execution of an y of y ou r Restart Procedures. The name o[...]

AMX M em ory Manage r K A DAK 133 Your Memory Assignment Procedure can be coded as a Large or Medium model C procedure with formal paramet ers as follows. int cdecl memproc( long *memsizep, /* Pointer to memory size storage */ char **memptrp) /* Pointer to memory pointer storage */ { : : if (another memory section is available) { *memsizep = <si[...]

134 K A DAK AMX M em ory Manage r The Memor y Assi gnment Procedure can be coded in assembler as a FAR proc edure. USER_CODE SEGMENT BYTE 'CODE' ; ASSUME CS:USER_CODE ; PUBLIC MEMPROC ; PARAM STRUC ;Define parameters on stack DW ? ;Save BP DD ? ;Return address MEMSIZEP DD ? ;A(storage for section size in bytes) MEMPTRP DD ? ;A(storage for[...]

AMX Circula r List M anager K A DAK 135 1 1. AMX Circular List Ma nager 1 1.1 Cir c ular L ists The AMX Circular L ist Manager provides a gener al circular list facility for use by application program modules. Circular lists must be located in alte rable memory (RAM). A circ ular list is a data structure used b y an application to maintain an order[...]

136 K A DAK AMX Circula r List M anager 1 1.2 Cir cular List Use A circular l ist is created b y an application wit h a call to procedu re ajrstl . The caller must provide three parameters: the number of slots in the lis t, the si z e of each slot (1, 2 or 4 bytes) and a pointer to RAM stora ge for the circular list. The number of slots in a circul[...]

AMX Circula r List M anager K A DAK 137 1 1.3 Ci r cula r List S tructur e Circular lists are applic ation data structures whi ch are only accessible b y calls to the AMX Circula r List Ma nager. The interna l structure of the list is private to the Circular List Manager. Lists can be creat ed dynamicall y or staticall y b y any application pro gra[...]

138 K A DAK AMX Circula r List M anager The same lists ca n be coded in assembly language a s 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[...]

AMX Linked Li st Manager K A DAK 139 12. AMX Link ed List Manager 12.1 Int roducti on The Linked List Manager provides a ge neral set of fast linked list services suitable for use in real-time systems. The Linked List Manage r removes the tedium and potential f or serious err or inherent in many applications in which list mainte nance is implemente[...]

140 K A DAK AMX Linked Li st Manager 12.2 Link ed Lists Terminology A list header is a structure provided b y the application to be used to anchor a list. The list head er is used to identify a list. The conten t of the list header is pr ivate to the Linked List Manager. An object is an application data stru cture which represents the elements whi [...]

AMX Linked Li st Manager K A DAK 141 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 f resh list. Rotten apples or oranges reside on a rotten list. The list objects are assumed to be data stru ctures describing apples and oranges. Each obje[...]

142 K A DAK AMX Linked Li st Manager 12.3 Link ed List Use A list consists of a list header and objects linked to the list header b y list nodes (or ke y nodes). Storage for the list header must be provided by y ou. A pointer to the list header acts as the list identifier. An empty list is c reated by ca lling proce dure ajlcre with a pointe r to t[...]

AMX Linked Li st Manager K A DAK 143 The following example code d in C illustrates the use of the Linked List Manager. An object called uobject is defined with a ke y node at offset keynode i n the object. An array of ten objects is provided. A ke y ed list keylist is created and th e ten objects are added to the list in random order. The list is t[...]

144 K A DAK AMX Linked Li st Manager void example(void) { int i; struct uobject *objp; /* Object pointer */ int nodeofs; /* Node offset */ nodeofs = (char *)(&objarray[0].keynode) - (char *)&objarray[0]; ajlcre(&keylist, nodeofs); /* Create empty keyed list */ nodeofs = (char *)(&objarray[0].listnode) - (char *)&objarray[0]; ajl[...]

AMX Linked Li st Manager K A DAK 145 The following ex ample coded in asse mbler illustra tes the use of the Linked List Manager. The example mimics the operation of the previous C implementation. It illustrates the optimization effe cts which can be ac hieved by coding in assembler. INCLUDE AMX831SD.DEF ;A MX S tr uc tu re D ef in i ti on s ; UOBJE[...]

146 K A DAK AMX Linked Li st Manager USER_CODE SEGMENT BYTE 'CODE' ;Code segment ; ASSUME CS:USER_CODE, DS:USER_DATA, ES:USER_DATA ; EXTRN RANDOM:FAR ;Random number generator ; EXAMPLE PROC FAR MOV AX,SEG USER_DATA MOV DS,AX ;Assure data access MOV ES,AX ; MOV CX,KEYNODE-(BYTE PTR ID) ;Offset to key node MOV SI,OFFSET KEYLIST ;A(Keyed lis[...]

Advanced T opics K A DAK 147 13. Adva nced T opics 13.1 F atal E xit There are a number of conditions which, if encountered b y AMX, are conside red to be fatal. Any attempt b y AMX to continue execution will lead to unpredictable results at best. All of these conditions ca use AMX to force a branch to its fatal exit handler at ajfatl . Insufficien[...]

148 K A DAK Advanced T opics Fat al Exit Proce dure AMX allows y ou to p rovide a Fatal Exit Procedure of your own by specifying the name of your procedure in y our System Configuration Module (see Chapter 14.5). Whenever AMX or y our applicati on forces a fatal ex it, AMX checks to see if you have provided a Fatal Exit Procedure. I f one is presen[...]

Advanced T opics K A DAK 149 Your Fatal Exit Proce dure can be coded as a Larg e model C procedure as illustrated in the followi ng 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 condi[...]

150 K A DAK Advanced T opics 13.2 U ser Err or Pr ocedur e Most AMX procedures return error status to the caller. The error st atus is a signed integer. AEREROK = 0 No error AERxxx > 0 Warning: possible fault AERxxx < 0 Error: may be unrecov erable The defined erro r codes are summarized in Appendix B. AMX allows you to provide a User Error P[...]

Advanced T opics K A DAK 151 Your User Error Pro cedure can be coded in assembl y language as a FAR procedure. Upon entry to your User Error Pr ocedure, the following c onditions exist: Interrupts are disabled. All registers ar e free for use. AX AMX error code (see AERxxx definitions) DX Task id of curr ent task (0 if error detected in I SP) DS,ES[...]

152 K A DAK Advanced T opics 13.3 T ask Scheduling Ho ok s AMX does not provide direct support for sp ecific hardware ex tensions such as a math coprocessor or a memory management unit. Instead, AMX allows a set of application procedures to be connected to its Task Schedul er. Thes e proc edures can save and restore hardware dependent parameters sp[...]

Advanced T opics K A DAK 153 13.4 A bn ormal T ask T erm ination A task is a procedure whic h is called by the AMX Task Scheduler. The t ask ends execution normall y by returning to AMX. AMX provides p rocedu re ajend whi ch can be used by a task to end execution and return t o AMX under circumstances i n which its stack is deepl y nested. These tw[...]

154 K A DAK Advanced T opics Kill a Task A task can be killed. The task is first stopped as just described. All outstanding requests to the task for its e xecution are purge d. The effect is the sa me as if the task continued to make calls to ajend to e nd its operation until fina lly there were no task execution requests re maining. A task can kil[...]

Advanced T opics K A DAK 155 A Task Termination Procedure can b e coded as a Large or Medium model C procedure as illustrated in the following example. The procedure r eceives an integer reason code indicating whether the task is being stopped, killed or deleted. The mnemonics for these reason codes are provi ded in the AMX head er file AMX831SD.H [...]

156 K A DAK Advanced T opics A Task Termination Procedure can b e coded in assembler as a FAR procedure as indicated in the follo wing example. The procedu re receives an integer reason code i ndicating whether the task is being stopped, killed or deleted. The mnemonics for th ese reason codes are provided in the AMX head er file AMX831SD.DEF . Upo[...]

Advanced T opics K A DAK 157 Term ination Pr ocessing 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 perfor ming some operation whic h AMX deems to be critical. When this oc curs[...]

158 K A DAK Advanced T opics 13.5 T ask Suspend/Resume Some operating s y stems p er mit a task to suspend any task, including itself. This fea ture is then used to implement the equivalent of the AMX task wait procedure ajwait . The ab ility to ar bitrarily suspend a task is one of the most abuse d privileges afford ed by other operating systems. [...]

Advanced T opics K A DAK 159 13.6 Br eak point Man ager The AMX Breakpoint Manager can be used to improve the op eration of th e debugger that you use to test your AMX s y stem. Your use o f the Breakpoint Manager is optional; use it only if it augments your debugger as describ ed below. If you enjoy the use of an in-circuit emulator or hardware as[...]

160 K A DAK Advanced T opics Using the Break point Manager The Breakpoint Manager is included in your application only if it is enabled in your User Paramete r File. Use the AMX Configur ation Builder to edit y our User Paramete r File (see Chapter 14.13). Enable the bre akpoint support option in the Breakpoint parameter window and generate a new S[...]

Advanced T opics K A DAK 161 Interrupt Maski ng The Breakpoint Manager must be tailored to inhibit interrupts at breakpoints. Which interrupts are to b e inhibited and how this is done is both s y stem and hardware dependent. When you include the Breakpoint Manager in your AMX s y stem, module AA831BKA.OBJ is included from the AMX Librar y. This mo[...]

162 K A DAK Advanced T opics NMI Breakpoi nts Some hardware debuggers ma y use the non-maskable interrupt (NM I) to generate breakpoints. The Breakpoint Manager can be tailored to suppo rt such debu g gers b y enabling its NMI handler. When an NMI interrupt is detected, the Breakpoint Manager calls the NM I handler to determine if the interrupt is [...]

AMX Sy stem Configura t io n K A DAK 163 14. AMX System Config uration 14.1 System Configuration Module The AMX System Configuration Module defines the cha racteristics 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[...]

164 K A DAK AMX Sy stem Configura t io n 14.2 System Configuration Builder The AMX Configuration B uilder is a softw are 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 genera tion process by which your System Config uration Modu[...]

AMX Sy stem Configura t io n K A DAK rev8 165 Sy stem Docum ent ati on Template File AM831CG.CTD Sy stem C onfigurati on Template File AM831CG.CT User Parameter File SYSCFG.UP Config uration Manage r Enter/Edit/View AM X Sy st em Param eter s Config uration Generator SYSCFG.ASM SYSCFG.TX T Sy stem Config uration Module File Figure 14.2-1 AMX Config[...]

166 K A DAK AMX Sy stem Configura t io n 14.3 U si ng the Bu ilder Starting t he Builder The AMX Configuration Builder will operate on a PC or compatible running the Microsoft ® Windows ® operating s y stem. The Builder is delivered with the following f iles. File P urpose AM831CM .EXE AMX Configuration Ma nager (utility program) AM831CM .CNT AMX[...]

AMX Sy stem Configura t io n K A DAK 167 Screen Layout Figure 14.3-1 illustrates the Configuration Manager ' s screen la y out. Th e title bar identifies the User Para meter File being created or edited. Below the title bar is the me nu bar from which the operations y ou wish the Mana g er to perform can b e selected. Below the menu bar is an [...]

168 rev9 K A DAK AMX Sy stem Configura t io n Menus All commands to the Conf iguration Manag e r are a vailable as items on the menus present on the menu bar. The File menu provides the conventional New , Open , Sa ve and Save As. .. commands f or creating and e diting your User Parame ter File. It a lso provides the Exit command. When the System C[...]

AMX Sy stem Configura t io n K A DAK 169 If you have modified some of the fields on a propert y page and then decide that these modified values are not correct, use th e Undo P ag e command on the Edit menu or Toolba r to force the Configuration Manager to restor e the content of all fields on the page to the values which were in effect when you mo[...]

170 K A DAK AMX Sy stem Configura t io n 14.4 Sy stem Parameter Definitio n The System Parameter window allows y ou to define th e general operating parameters of your AMX s y stem. The la yout of the window is shown in Figure 14.3-1 in Chapter 14.3. Kernel Options AMX Message Envelopes AMX passes a mess age to a mailbox or message ex change in a m[...]

AMX Sy stem Configura t io n K A DAK 171 AMX Int errupt St ack Size The AMX I nterrupt Supervisor requires a minimum Interrupt Stack size of 128 bytes. The stack size must be a multiple of 4 by t es. In a ddition to this minimum, y ou must a llocate suff icient stack to satisfy the application ISP with the greatest stack usage. If nested interrupts[...]

172 K A DAK AMX Sy stem Configura t io n Ti min g O pt io ns Hardware C lock F requency This parameter defines the fr equency of the AMX hardware clock in hertz. I t is used by AMX to convert milliseconds to equivalent AMX system ticks. I f y our hardware clock frequenc y is not integral, round the clock frequen cy to the nearest non-zero integer. [...]

AMX Sy stem Configura t io n K A DAK 173 14.5 AMX Object Alloc ation The AMX Object Allocation window allows you to define the number of private AMX objects required for each o f the optional AMX managers to be included in your s y stem. The layout of the window is shown below. Maximum Number of Tasks This parameter defines the max imum number of a[...]

174 K A DAK AMX Sy stem Configura t io n Ma ximu m N u mber of Se map hor es This parameter defines the max imum number of resource and countin g semaphores which your system can support concurrentl y . If you do not require any semaphores, set this parameter to 0. Otherwise, the param eter should be set to the number of pr edefined semaphores (see[...]

AMX Sy stem Configura t io n K A DAK 175 Memory Assignment Procedu re Name If you use the AMX Memor y Man ager, you must provide a Memor y Assignment Procedure to assign memor y sections to its memory pool for allocation to tasks (see Chapter 10.6). This parameter sp ecifies the name of that procedu re. If y ou ar e not using the AMX Memory Manager[...]

176 K A DAK AMX Sy stem Configura t io n 14.6 R e st art/Exit Pr ocedur e Definiti on The Launch/Shutdown window displays all of your application Restart and Exit Procedures which will be c alled by AMX at system startup and shutdown. The layout of the window is shown below. The Restart Procedu re List is used to define all of your application Rest[...]

AMX Sy stem Configura t io n K A DAK 177 Add, Edit and De lete R estart and Exit Pr ocedure s To add a new procedure, cli ck on the Add button below the list. A new procedure named ---New--- will a ppear at the bottom of the list. Clic k on the name ---New--- a nd it will be opened rea dy for editing. Enter the name of your procedure. To edit an ex[...]

178 K A DAK AMX Sy stem Configura t io n 14.7 T ask De finit ion The Task Definition window allows you to define the tasks to be automaticall y created by AMX at sy st em startup. You do not have to predefine all of your tasks in this manner; y ou ma y also cr eate tasks dyna mically using ajtkcre . The la y out of the window is shown below.[...]

AMX Sy stem Configura t io n K A DAK 179 Task Tag Each task can have a unique 4-cha racter task tag. This parameter defines that tag. Although AMX does not restrict the content of the task tag field, the Confi guration Manager only supports 4 ASCII characte rs as a tag. Prio ri ty This para meter de fines the execution pr iority of the task. Applic[...]

180 K A DAK AMX Sy stem Configura t io n Medium Model Tasks can be either L a rge or Medium. I f your task is Medium model, check this box. Otherwise, leave this box unchecked. If you declare the task to be Medium, the Builder will a llocate the task's stac k in a segment which is part of group DGROUP so that DS = SS = DGROUP when the task exe[...]

AMX Sy stem Configura t io n K A DAK 181 14.8 Tim er De fin ition The Timer Definition window allows you to define the timers to be automaticall y created by AMX at system startup. You do not have to predefine all of y our timers in this manner; y ou may also cre ate timers dyna mically using ajtmcre . Note that AMX does not automa tically start ti[...]

182 K A DAK AMX Sy stem Configura t io n Tag Each timer can have a unique 4- character time r tag. This pa rameter defines that tag. Although AMX do es not restrict the content of the timer tag field, the Configuration Manager only supports 4 ASCII characte rs as a tag. Id Variable This parameter defines the name of a public variable of t ype AMXID[...]

AMX Sy stem Configura t io n K A DAK 183 14.9 Sem aphore D efinit ion The Semaphore Definition window allows you to define the semaphores to be automatically created b y AMX at system startup. You do not have to predefin e all of your semaphores in this manner; y ou may also dynamicall y c reate resource s emaphores and counting semaphores using aj[...]

184 K A DAK AMX Sy stem Configura t io n Tag Each semaphore can have a unique 4-charact er semaphore tag. This parameter defin es that tag. Although AMX does not restrict the content of the semaphore tag field, the Configuration Manager only supports 4 ASCII characters as a t ag. Id Variable This parameter defines the name of a public variable of t[...]

AMX Sy stem Configura t io n K A DAK 185 14.10 E v ent Gr oup Definition The Event Group Definition window allows you to define the event groups to be automatically created b y AMX at system startup. You do not have to predefin e all of your event groups in this manner; you may also create event groups dynamically using ajevcre . The layout of the [...]

186 K A DAK AMX Sy stem Configura t io n Tag Each event group can have a unique 4-character event group tag. This par ameter 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 t ag. Id Variable This parameter defines the name of a public variable[...]

AMX Sy stem Configura t io n K A DAK 187 14.1 1 Message E xchan ge Def initi on The Message Exchange De finition window allows y o u to define the message exchan ges to be automatically created by AMX at system startup. You do not have to predefine all of your messag e excha nges in this manner ; y ou may also create message e xchanges dynamically [...]

188 K A DAK AMX Sy stem Configura t io n Tag Each message exchange can have a unique 4 -character message ex change tag. This parameter defines that tag. Althoug h AMX does not restrict the content of the message exchange tag field, the Confi g uration Manager only supports 4 ASC II characters as a tag. Id Variable This parameter defines the name o[...]

AMX Sy stem Configura t io n K A DAK 189 14.12 Bu ffer Poo l Defin ition The Buffer Pool Definition window allows you to d efine the buffer pools to be automatically created b y AMX at system startup. You do not have to predefin e all of your buffer pools in this manner; you may also create bu ffer pools d y n amically using ajbcre . The layout of [...]

190 K A DAK AMX Sy stem Configura t io n Tag Each buffer pool can have a unique 4-c haracter buffer pool tag. This pa rameter 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 t ag. Id Variable This parameter defines the name of a public vari ab[...]

AMX Sy stem Configura t io n K A DAK 191 14.13 B reak point Manager Definit i on The AMX Breakpoint Manager can be used to improve the op eration of your debu gger in the AMX multitasking environment. Your use of the Breakpoint Manager is optional. The layout of the window is shown below. Includ e Breakpoint Man ager If you need to use the AMX Brea[...]

192 K A DAK AMX Sy stem Configura t io n This page left blank intentionall y .[...]

AMX Service Procedures K A DAK 193 15. AMX Ser vice P r ocedur es 15.1 Int roducti on The AMX Library pr ovides a wide variety of ser vices from which the real-time system designer can choose. Man y of the services are optional and, i f not used, will not even be present in your final AMX system. This section of the AMX User's Guide differs fr[...]

194 K A DAK AMX Service Procedures 15.2 Sum m ary 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 s y stem. The AMX m anagers are all optional. All of AMX and its manag e rs are fully r eentrant and may b[...]

AMX Service Procedures K A DAK 195 Task Control ajend AAEND End task execution ajgmsg AAGMSG Get the hig hest priority message available Optionally ge t a message of a specific priority ajresum AARESUM Resume a suspended task ajsend AASEND Start a task by sending it a message at one of 4 prioritie s ajsendp ajsenw Optionally wait f or that task to [...]

196 K A DAK AMX Service Procedures Timing Co ntrol ajclk AACLK AMX Clock Handler ajtick AATICK Read elapsed s y stem ticks ajtmcnv AATMCNV Convert milliseconds to system ticks ajtmcre AATMCRE Create an interva l timer ajtmdel AATMDEL Delete an interval timer ajtmrd AATMRD Read an inte rval timer ajtmtag AATMTAG Find timer id of timer with a specif [...]

AMX Service Procedures K A DAK 197 Message Exchange Manager ajmxcre AAMXCRE Create a m essage exchange ajmxdel AAMXDEL Delete a messa ge exchange ajmxget AAMXGET Get a message from a messa ge ex change (no wait) ajmxsnd AAMXSND Send message to a message exchan ge ajmxsndp ajmxtag AAMXTAG Find exchan ge id of message exchan ge with a specifi c tag a[...]

198 K A DAK AMX Service Procedures Circular L ist Manager ajabl AAABL Add to bottom of circular list ajatl AAATL Add to top of circular list ajrbl AARBL Remove from bottom of circular list ajrstl AARSTL Reset a circul ar list ajrtl AARTL Remove from top of circular list Linked List Manager ajlcre AALCRE Create an em pty list ajlhead AALHEAD Find he[...]

AMX Service Procedures K A DAK 199 Processor and C In terface Proced ures In addition to the services provided b y AMX and its managers, the AMX Library includes seve ral C procedure s of a general nature which simplify application programming in real-time systems on your targ et processor. ajcfjlong Long jump to a ma rk set by ajcfjset ajcfjset Se[...]

200 K A DAK AMX Service Procedures AMX 86 PC Supervi sor Service Pr ocedu res 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 procedu res are documented in Chapter 3.9 of the AMX 86 PC Sup[...]

AMX 86 Procedures K A DAK 201 16. AMX 86 Procedures 16.1 Int roducti on A description of every AMX Librar y procedure is provided in this chapte r. The descriptions are ordered alphab etically for eas y reference. Italics are used to distinguish programming examples. Procedure names and variable names which ap pear in narrative text are also displa[...]

202 K A DAK AMX 86 Procedures Where If the procedure has input par ameters, they will be described narrativel y. Results The outputs produced b y the procedure a re always defined. The sta te of the carr y , parity, auxiliary , zero, sign and overflow flag s are of no consequence when progra mming in C. I n assembl y language, the zero and sign fla[...]

AMX 86 Procedures K A DAK 203 Assembly Language Programming If you are programming in assembl y langua g e, refer to Appendix E for a description of the AMX assembly language calling conventions. The appendix includes a summar y of the input and output register specifications for every AM X procedure. Experien ced AMX programmers will usua lly find[...]

204 K A DAK AMX 86 Procedures FAR pointers are passed to AMX as seg:reg as i n the followin g example. status = ajsenw(taskid, priority, (void FAR *)msg); AX AASEND DX CX[14..0] ES:BX CX[15]=1 Specific bi ts in a register reg are ref erenced using the s yntax reg[bit] or reg[highbit..lowbit] . In this ex ample, CX[15] is bit 15 of register CX . CX[[...]

AMX 86 Procedures K A DAK 205 ajabl ajabl Purpose Add to B ottom of Circular List Used by n Task n ISP n Time r Proce dure n Restart P roce dure n Exit Proced ure Setup char item; /* one byte item */ int status; . . status = ajabl(&list, item); AX ES:BX CL,CX or DX:CX Where &list is a pointer to a circular list (see ajrstl ). item is the 1,[...]

206 K A DAK AMX 86 Procedures ajatl ajatl Purpose Add to Top of Circular L ist Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup char item; /* one byte item */ int status; . . status = ajatl(&list, item); AX ES:BX CL,CX or DX:CX Where &list is a pointer to a circular list (see ajrstl ). item is the 1, 2 [...]

AMX 86 Procedures K A DAK 207 ajbau ajb au Purpose Add to B uffer's Use Count Used by n Task n ISP n Time r Proce dure n Restart P roce dure n Exit Proced ure Setup int increment; char *buffp; int status; . . status = ajbau(buffp, increment); AX ES:BX DX Where buffp is a pointer to a buffer obtained with an ajbget call. increment is the signed[...]

208 K A DAK AMX 86 Procedures ajbcr e ajbcre Purpose Create a Bu ffer Pool Used by n Task o ISP o Time r Proce dure n Restar t Pro ced ure n Exit Procedure Setup #include "amx831sd.h" . . AMXID poolid; struct amxbps pooldef; int status; . . status = ajbcre(&pooldef, &poolid); AX ES:BX DX= Where &pooldef is a pointer to the poo[...]

AMX 86 Procedures K A DAK 209 Results Interrupts a re disabled and then re stored to their sta te at the time of the call. Status is returned. AEROK = C all successful AERNFP = No fre e buffer pool AERNBF = No buffe rs defined in your pool definition AERBTS = Buffer size defined in your pool definition is too small If the call is unsuccessful, pool[...]

210 K A DAK AMX 86 Procedures ajbdel ajbdel Purpose Delete a B uffer Pool Used by n Task o ISP o Time r Proce dure n Restar t Pro ced ure n Exit Procedure Setup AMXID poolid; int status; . . status = ajbdel(poolid); AX DX Where poolid is the pool id of the buffer pool to be deleted. Results Interrupts a re disabled and then re stored to their sta t[...]

AMX 86 Procedures K A DAK 211 ajbfr e ajbfre Purpose Free a Bu ffer Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup char *buffp; int status; . . status = ajbfre(buffp); AX ES:BX Where buffp is a pointer to a buffer obtained b y an ajbget call. Results Interrupts a re disabled and then re stored to their sta te[...]

212 K A DAK AMX 86 Procedures ajbget ajb get Purpose Get a Buffer Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup AMXID poolid; char *buffp; int status; . . status = ajbget(poolid, &buffp); AX DX ES:BX= Where poolid is the pool id of the pool from which the buffer is to be obtained. &buffp is a pointer[...]

AMX 86 Procedures K A DAK 213 ajbgsz ajb gsz Purpose Get Size of Buffer Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup char *buffp; unsigned int size; int status; . . status = ajbgsz(buffp, &size) ; AX ES:BX CX= Where buffp is a pointer to a buffer obtained with an ajbget call. size is the size of the buf[...]

214 K A DAK AMX 86 Procedures ajbia ajb ia Purpose In itialize (Reset) All Buffer Pools Used by n Task o ISP o Time r Proce dure n Restar t Pro ced ure n Exit Procedure Setup int status; . . status = ajbia(); AX Results Interrupts a re disabled and then re stored to their sta te at the time of the call. Status is returned. AEROK = C all successful [...]

AMX 86 Procedures K A DAK 215 ajbip ajb ip Purpose In itialize (Reset) O ne Buffer Pool Used by n Task o ISP o Time r Proce dure n Restar t Pro ced ure n Exit Procedure Setup AMXID poolid; int status; . . status = ajbip(poolid); AX DX Where poolid is the pool id of the buffer pool to be initialized. Results Interrupts a re disabled and then re stor[...]

216 K A DAK AMX 86 Procedures ajbtag ajbt ag Purpose Find a Buffer Pool Used by n Task o ISP o Time r Proce dure n Restar t Pro ced ure n Exit Procedure Setup char tag[4]; AMXID poolid; int status; . . status = ajbtag(&poolid, tag); AX DX= [DX:CX] see note Where &poolid is a pointer to storage for the pool id of the buffer pool of interest.[...]

AMX 86 Procedures K A DAK 217 ajcfjlong ajcfj long ajcfjset ajcfjset Purpose ajcfjset Sets a Mark f or a Long Jum p ajcfjlong Long Jumps to that Mark These pr ocedures are provided for AMX portability . They are not replacement s for C library p rocedures longjmp or setjmp although they function in a similar manner. Used by n Task o ISP o Time r Pr[...]

218 K A DAK AMX 86 Procedures Example #include "AMX831CF.H" void cdecl dowork(struct ajxjbuf *jbp); static struct ajxjbuf jumpbuffer; #define STACKSIZE 512 /* Stack size (longs) */ static long newstack[STACKSIZE]; /* Top of stack (grows down) */ #define STACKP (&newstack[STACKSIZE - 1]) void cdecl taskbody(void) { if (ajcfjset(&ju[...]

AMX 86 Procedures K A DAK 219 ajcfstk j m p ajcfstk jmp Purpose Switc h Stacks a nd Jump t o a New P rocedure This procedure is provide d for AMX portability. Used by n Task o ISP o Time r Proce dure o Rest art Proced ure n Exit Proce dure Setup Prototy pe is in file AMX831CF.H . #include "AMX831CF.H" void cdecl ajcfstkjmp(void *vp, void [...]

220 K A DAK AMX 86 Procedures ajclk ajclk Purpose AMX Clock Handler Used by o Task n IS P o T imer Pr oce dure o Rest art Pr oced ure o Exit Proce dure Setup I nterrupts must be disabled. ajclk(); Results Interrupts ma y be enabled and/or disabled and will then be r estored to their state a t the time of the call. Note This procedure is for Clock I[...]

AMX 86 Procedures K A DAK 221 ajdi ajd i ajei aje i Purpose Disable or Enable Interrupts Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup ajdi(); ajei(); Results Interrupts are disabled b y ajdi() or enabled b y ajei() . The interrupt en able flag ( IF ) in the pro cessor status register ( FLAGS ) is reset to 0[...]

222 K A DAK AMX 86 Procedures ajend ajend Purpose End Execution of a Task Used by n Task o ISP o Time r Proce dure o Rest art Proced ure o Exit Proce dure Setup ajend(); Results There is no return from ajend . If a ny task is waiting for this task to finish processing its message, AMX will automatica lly ca ll ajwakc to wake that task. Restrictions[...]

AMX 86 Procedures K A DAK 223 ajentr ajentr Purpose Launch (Ent er) t he AMX Multit asking System Used by o Task o IS P o Timer Pro cedure o Restar t Pro cedur e o Exit Proced ure Setup #include "amx831sd.h" . . struct amxupts FAR *uptp; int launchparm; char *result; int status; . . ajupt(&uptp); status = ajentr(launchparm, uptp, &[...]

224 K A DAK AMX 86 Procedures Results No return unless a task calls ajexit . status = errcode given to ajexit result = 4 by te pa ra meter exitinfo given to ajexit Upon return, interrupts are restored to their state upon entr y to this procedure. Used By Must only b e called by a C main() procedure to start an AMX s y stem. See Also ajexit[...]

AMX 86 Procedures K A DAK 225 ajevcr e a je vcre Purpose Create an Event Group Used by n Task o ISP o Time r Proce dure n Restar t Pro ced ure n Exit Procedure Setup AMXID group; unsigned int ivalue; int status; char tag[4]; . . status = ajevcre(&group, ivalue, tag); AX BX= BX [DX:CX] Where &group is a pointer to storage for the ev ent grou[...]

226 K A DAK AMX 86 Procedures ajevdel aje vdel Purpose Delete an Event Grou p Used by n Task o ISP o Time r Proce dure n Restar t Pro ced ure n Exit Procedure Setup AMXID group; int status; . . status = ajevdel(group); AX BX Where group is the group id of an event group acqui red with a call to ajevcre . Results Interrupts a re disabled and then re[...]

AMX 86 Procedures K A DAK 227 ajevnt ajevnt Purpose Get th e Saved Event Flags Used by n Task o ISP o Time r Proce dure o Rest art Proced ure n Exit Proce dure Setup unsigned int value; . . value = ajevnt(); AX Where value is the state of the 16 e vent flags a t the time the calling task most recentl y complet ed a call to ajevwat. Results Interrup[...]

228 K A DAK AMX 86 Procedures ajevrd ajevrd Purpose Read th e Current Even t States in an Ev ent Group Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup AMXID group; unsigned int value; int status; . . status = ajevrd(group, &value); AX BX CX= Where group is the group id of an event group acqui red with a ca[...]

AMX 86 Procedures K A DAK 229 ajevsi g ajevsi g Purpose Si gnal Event(s) i n an Event Group Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup AMXID group; unsigned int mask; unsigned int value; int status; . . status = ajevsig(group, mask, value); AX see note Where group is the group id of an event group acqui r[...]

230 K A DAK AMX 86 Procedures ajevtag ajevtag Purpose Find an Event G roup Used by n Task o ISP o Time r Proce dure n Restar t Pro ced ure n Exit Procedure Setup AMXID group; char tag[4]; int status; . . status = ajevtag(&group, tag); AX BX= [DX:CX] see note Where &group is a pointer to storage for the ev ent group id if the event group of [...]

AMX 86 Procedures K A DAK 231 ajev wat ajev wat Purpose Wait for Event(s) in an Event Group Used by n Task o ISP o Time r Proce dure o Rest art Proced ure n Exit Proce dure Setup AMXID group; unsigned int mask; unsigned int value; int match; long timeout; int status; . . status = ajevwat(group, mask, value, match, timeout); AX see note Where group [...]

232 K A DAK AMX 86 Procedures Results Interrupts are disabled and then en abled upon return. Status is returned. AEROK = Call successful; eve nt match occu rred AERTMO = Timed out before event match occurred AERTMV = Invalid timeout interval (<0) AERNSG = Invalid event gr oup id If the events in the group match y our event selection criterion wh[...]

AMX 86 Procedures K A DAK 233 ajexit aje xit Purpose Leave (Exit) the AMX Multitasking System Used by n Task o ISP o Time r Proce dure o Rest art Proced ure o Exit Proce dure Setup char *exitinfo; int errcode; . . ajexit(errcode, exitinfo); CX DX:BX Where errcode is the error code to be returne d to the ajentr caller as status . exitinfo is any 4-b[...]

234 K A DAK AMX 86 Procedures ajfatl ajfatl Purpose Fatal Exit from AMX Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup int errcode; . . ajfatl(errcode); CX Where errcode is an error code which will be passed to your Fatal Exit Procedure if one was provided in your User Paramet er File. Results There is no ret[...]

AMX 86 Procedures K A DAK 235 ajfl agrd, ajflagrddi ajfl agrd, ajflagrddi ajfl agwr ajfl agwr Purpose Read Processo r Flags Read Processor Flags and Disable Interrupts Write Processor Flags Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup unsigned int flags; . . flags = ajflagrd(); /* Read current flags */ flag[...]

236 K A DAK AMX 86 Procedures ajgms g ajgm sg Purpose Get Message from Task Mailbox Used by n Task o ISP o Time r Proce dure o Rest art Proced ure n Exit Proce dure Setup int priority; char msg[AMXMSZ]; int status; . . status = ajgmsg(priority, msg); AX CX ES:BX Where priority is the priorit y of the task mailbox from which the me ssage is to be fe[...]

AMX 86 Procedures K A DAK 237 ajgofs ajg ofs Purpose Get Pointer Of f set Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup unsigned int ofs; char FAR *pntr; . . ofs = ajgofs(pntr); Results Interrupts are untouched. The 16-bit unsig ned integer value of the o ffset part of the FAR pointer variable pntr is return[...]

238 K A DAK AMX 86 Procedures ajgseg ajg seg Purpose Get Pointer Seg men t Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup unsigned short int seg; char FAR *pntr; . . seg = ajgseg(pntr); Results Interrupts are untouched. The 16-bit unsig ned integer value of the se g ment selector part of the FAR pointer varia[...]

AMX 86 Procedures K A DAK 239 ajgsr eg ajgsr eg Purpose Get Seg ment Registers Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup #include "amx831sd.h" . . struct amxsregs sregarray; . . ajgsreg(&sregarray); Where &sregarray is a pointer to storage to receiv e the current contents of the 8086 se[...]

240 K A DAK AMX 86 Procedures ajhook ajh ook Purpose Insta ll Task Sche duler Hooks Used by n Task o ISP o Tim er P ro cedur e o Rest art Pr oced ure n Exit Proce dure Setup struct { int (*uhstart)(); int (*uhend)(); int (*uhsuspend)(); int (*uhresume)(); } userhooks; . . ajhook((void FAR *)&userhooks); /* Install hooks */ ES:BX . . ajhook(NULL[...]

AMX 86 Procedures K A DAK 241 ajinb ajinb ajinw aji nw Purpose Re ad an 8-Bit Input P ort (Byte) Read a 16-Bit Input Port (Word) Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup int portno; char portbyte; short int portword; . . portbyte = ajinb(portno); portword = ajinw(portno); Where portno is the port number[...]

242 K A DAK AMX 86 Procedures ajint ajint ajinx ajinx Purpose Begin Interrupt Service Used by o Task n IS P o T imer Pr oce dure o Rest art Pr oced ure o Exit Proce dure Setup ajint(); Results Interrupts are disabled. The AMX Interrupt Supervisor saves all registers on the caller's stack. If a task has just been interr upted, AMX switches to t[...]

AMX 86 Procedures K A DAK 243 ajispm ajispm Purpose Make a Conforming ISP Root This procedure c reates an AMX root ISP per mitting a standard C fun ction to serve as an AMX Interrupt Service Procedu re. Used by n Task o ISP o Time r Proce dure n Restar t Pro ced ure n Exit Procedure Setup #include "amx831sd.h" . . struct amxisps isproot; [...]

244 K A DAK AMX 86 Procedures ajitrp ajitrp Purpose Install a Task Trap Handler Install a task trap handler to service divide error, overflow or bound check error traps. Used by n Task o ISP o Time r Proce dure o Rest art Proced ure o Exit Proce dure Setup int inttype; void handler(); int status; . . status = ajitrp(inttype, handler); AX DX ES:BX W[...]

AMX 86 Procedures K A DAK 245 ajivtr ajivtr Purpose Read an Interrupt Vector Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup int inttype; void (*oldproc)(); int status; . . status = ajivtr(inttype, &oldproc); AX DX ES:BX Where inttype is the 8086 interrupt type (0-255). &oldproc is a pointer to storage[...]

246 K A DAK AMX 86 Procedures ajivtw aji vtw Purpose Write an Interrupt Vector Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup int inttype; void newproc(); int status; . . status = ajivtw(inttype, newproc); AX DX ES:BX Where inttype is the 8086 interrupt type (0-255). newproc is a pointer to the new interrupt [...]

AMX 86 Procedures K A DAK 247 ajivtx aji vtx Purpose Exch ange an Interrup t Vector Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup int inttype; void (*oldproc)(); void newproc(); int status; . . status = ajivtx(inttype, newproc, &oldproc); AX DX ES:BX DS:DI Where inttype is the 8086 interrupt type (0-255)[...]

248 K A DAK AMX 86 Procedures ajlcr e ajlcre Purpose Create an Empty List Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup #include "amx831sd.h" . . struct amxlhs list; int offset; . . ajlcre(&list, offset); DS:SI CX Where &list is a pointer to the list hea der. offset is the node offset (in b[...]

AMX 86 Procedures K A DAK 249 ajlhead ajlhead Purpose Find Firs t Object on List Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup #include "amx831sd.h" . . struct amxlhs list; struct appobj *object; . . object = ajlhead(&list); ES:BX DS:SI Where &list is a pointer to the list hea der. Results [...]

250 K A DAK AMX 86 Procedures ajlinsc ajl insc Purpose In sert Object before Current Obje ct on List Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup #include "amx831sd.h" . . struct amxlhs list; struct appobj *newobj, *curobj; . . ajlinsc(&list, newobj, curobj); DS:SI ES:BX CX:DI Where &list [...]

AMX 86 Procedures K A DAK 251 ajlinsh ajl insh Purpose Insert Object at Head of List Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup #include "amx831sd.h" . . struct amxlhs list; struct appobj *object; . . ajlinsh(&list, object); DS:SI ES:BX Where &list is a pointer to the list hea der. objec[...]

252 K A DAK AMX 86 Procedures ajlinsk ajl insk Purpose In sert Object into Keyed List Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup #include "amx831sd.h" . . struct amxlhs list; struct appobj *object; unsigned int key; . . ajlinsk(&list, object, key); DS:SI ES:BX CX Where &list is a pointer[...]

AMX 86 Procedures K A DAK 253 ajlinst ajl inst Purpose Insert O bject at Tail of List Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup #include "amx831sd.h" . . struct amxlhs list; struct appobj *object; . . ajlinst(&list, object); DS:SI ES:BX Where &list is a pointer to the list hea der. obje[...]

254 K A DAK AMX 86 Procedures ajlmerg ajlm erg Purpose Merg e Two Lists Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup #include "amx831sd.h" . . struct amxlhs destlist, srclist; struct appobj *destobj, *srcobj; . . ajlmerg(&destlist, &srclist, destobj, srcobj); see note Where &destlist i[...]

AMX 86 Procedures K A DAK 255 Note Assembly la nguage call is: PUSH <segment srcobj> PUSH <offset srcobj> PUSH <segment destobj> PUSH <offset destobj> PUSH <segment scrlist> PUSH <offset scrlist> PUSH <segment destlist> PUSH <offset destlist> CALL AALMERG ADD SP,16 Restrictions You must not merge two [...]

256 K A DAK AMX 86 Procedures ajlnext ajlnext Purpose Find Next Object on List Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup #include "amx83lsd.h" . . struct amxlhs list; struct appobj *object, *curobj; . . object = ajlnext(&list, curobj); ES:BX DS:SI ES:BX Where &list is a pointer to the l[...]

AMX 86 Procedures K A DAK 257 ajlordk ajlordk Purpose Reorder an Object in a Key ed List Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup #include "amx831sd.h" . . struct amxlhs list; struct appobj *object; unsigned int key; . . ajlordk(&list, object, key); DS:SI ES:BX CX Where &list is a poin[...]

258 K A DAK AMX 86 Procedures ajlpr ev ajlpr ev Purpose Find Previou s Object on List Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup #include "amx831sd.h" . . struct amxlhs list; struct appobj *object, *curobj; . . object = ajlprev(&list, curobj); ES:BX DS:SI ES:BX Where &list is a pointer t[...]

AMX 86 Procedures K A DAK 259 ajlrm vc ajlrm vc Purpose Remove Object from List Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup #include "amx831sd.h" . . struct amxlhs list; struct appobj *object; . . ajlrmvc(&list, object); DS:SI ES:BX Where &list is a pointer to the list hea der. object is [...]

260 K A DAK AMX 86 Procedures ajlrm vh ajlrm vh Purpose Remove Object from Head of List Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup #include "amx831sd.h" . . struct amxlhs list; struct appobj *object; . . object = ajlrmvh(&list); ES:BX DS:SI Where &list is a pointer to the list hea der. R[...]

AMX 86 Procedures K A DAK 261 ajlrm vt ajlrm vt Purpose Remove Object from Tail of List Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup #include "amx831sd.h" . . struct amxlhs list; struct appobj *object; . . object = ajlrmvt(&list); ES:BX DS:SI Where &list is a pointer to the list hea der. R[...]

262 K A DAK AMX 86 Procedures ajltail a jltail Purpose Find Last Object on List Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup #include "amx831sd.h" . . struct amxlhs list; struct appobj *object; . . object = ajltail(&list); ES:BX DS:SI Where &list is a pointer to the list hea der. Results I[...]

AMX 86 Procedures K A DAK 263 ajmau ajm au Purpose Add to Memory Block Use Coun t Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup char *blockp; int increment; int status; . . status = ajmau(blockp, increment); AX ES:BX DX Where blockp is a pointer to a memor y block alloc ated by aj mget or ajmgeh . increment [...]

264 K A DAK AMX 86 Procedures ajmfr e ajmfre Purpose Free Previously Allo cated Block Used by n Task o ISP o Time r Proce dure n Restar t Pro ced ure n Exit Procedure Setup char *blockp; int status; . . status = ajmfre(blockp); AX ES:BX Where blockp is a pointer to a memor y block alloc ated by aj mget or ajmgeh . Results Interrupts a re disabled a[...]

AMX 86 Procedures K A DAK 265 ajmgeh ajm g eh Purpose Get a Memory Block Using a Memory Handle Used by n Task o ISP o Time r Proce dure n Restar t Pro ced ure n Exit Procedure Setup long size; char *blockp; long memsize; char *handle; int status; . . status = ajmgeh(size, &blockp, &memsize, handle); AX DX:CX ES:BX= DX:CX= ES:BX Where size i[...]

266 K A DAK AMX 86 Procedures ajmget ajm g et Purpose Get a Memory Block Used by n Task o ISP o Time r Proce dure n Restar t Pro ced ure n Exit Procedure Setup long size; char *blockp; long memsize; int status; . . status = ajmget(size, &blockp, &memsize); AX DX:CX ES:BX= DX:CX= Where size is the number of b y tes of memory required. &b[...]

AMX 86 Procedures K A DAK 267 ajmgsz ajm gsz Purpose Get Size of Memory Block Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup char *blockp; long blksize; int status; . . status = ajmgsz(blockp, &blksize); AX ES:BX DX:CX= Where blockp is a pointer to a memor y block alloc ated by aj mget or ajmgeh . &bl[...]

268 K A DAK AMX 86 Procedures ajmh an ajmh an Purpose Creat e Memory Handle f or Private Alloca tion Used by n Task o ISP o Time r Proce dure n Restar t Pro ced ure n Exit Procedure Setup char *blockp; long memsize; char *handle; int status; . . status = ajmhan(blockp, memsize, &handle); AX ES:BX DX:CX ES:BX= Where blockp is a point er to an ar[...]

AMX 86 Procedures K A DAK 269 ajmodl ajm odl Purpose Get th e DGROUP Segmen t Value Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup ajmodl(); Results Interrupts are untouched. The data segment re gister DS is set to the base segment of group DGROUP . This procedure is provided for use with mix ed memory models[...]

270 K A DAK AMX 86 Procedures ajmset ajm s et Purpose Set (Fill) M emory Used by n Task o ISP o Time r Proce dure n Restar t Pro ced ure n Exit Procedure Setup char *mempntr; long memsize; unsigned short int pattern; int status; . . status = ajmset(mempntr, memsize, pattern); AX ES:BX DX:CX SI Where mempntr is a pointer to the memory area which is [...]

AMX 86 Procedures K A DAK 271 ajmxcr e ajmxcre Purpose Create a Message Exchange Used by n Task o ISP o Time r Proce dure n Restar t Pro ced ure n Exit Procedure Setup AMXID exchange; int mb0, mb1, mb2, mb3; char tag[4]; int status; . . status = ajmxcre(&exchange, mb0, mb1, mb2, mb3, tag); AX BX= @ES:BX (see note) [DX:CX] Where &exchange is[...]

272 K A DAK AMX 86 Procedures ajmxdel ajm xdel Purpose Delete a Message Exchange Used by n Task o ISP o Time r Proce dure n Restar t Pro ced ure n Exit Procedure Setup AMXID exchange; int status; . . status = ajmxdel(exchange); AX BX Where exchange is the exchange id of the messa ge exchange to be deleted. Results Interrupts a re disabled and then [...]

AMX 86 Procedures K A DAK 273 ajmxget ajm xget Purpose Get a Message fro m a Message Exchange (no wait) Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup AMXID exchange; char msg[AMXMSZ]; int status; . . status = ajmxget(exchange, msg); AX BX ES:SI Where exchange is the message e xchange id acquire d by a call t[...]

274 K A DAK AMX 86 Procedures ajmxsnd ajm xsnd Purpose Send Message to Message Exchange Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup AMXID exchange; char msg[AMXMSZ]; int priority; int status; . . status = ajmxsnd(exchange, priority, msg); AX BX DX ES:SI Where exchange is the message e xchange id acquire d [...]

AMX 86 Procedures K A DAK 275 ajmxsndp ajm x sndp Purpose Send Message to a Message Exchange Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure 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 is the [...]

276 K A DAK AMX 86 Procedures ajmxtag ajmxtag Purpose Find a Message Exchange Used by n Task o ISP o Time r Proce dure n Restar t Pro ced ure n Exit Procedure Setup AMXID exchange; char tag[4]; int status; . . status = ajmxtag(&exchange, tag); AX BX= [DX:CX] see note Where &exchange is a pointer to st orage for the message ex change id of t[...]

AMX 86 Procedures K A DAK 277 ajmx wat ajmxwat Purpose Wait for a Message from a Message Exchange Used by n Task o ISP o Time r Proce dure o Rest art Proced ure n Exit Proce dure Setup AMXID exchange; char msg[AMXMSZ]; long timeout; unsigned int priority; . . status = ajmxwat(exchange, msg, timeout, priority); AX BX ES:SI DX:CX DI Where exchange is[...]

278 K A DAK AMX 86 Procedures ajoutb ajoutb ajout w ajout w Purpose Write to an 8-Bit Output Port (Byte) Write to a 16-Bit Output Port (Word) Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup int portno; char portbyte; short int portword; . . ajoutb(portno, portbyte); ajoutw(portno, portword); Where portno is th[...]

AMX 86 Procedures K A DAK 279 ajpr oc ajproc ajpr ocq a jpr ocq Purpose Call Software Procedure You can use this pro cedure to call any software proc edure which, because of register setup requirem ents, cannot otherwise be called from C. Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup #include "amx831sd.[...]

280 K A DAK AMX 86 Procedures Results Interrupts will be in the state in whic h they are left b y the called procedure when it exits. All reg isters in regarray reflect the values in t he proc essor registe rs at t he time the calle d procedure ended. The real processor registers are only affect ed at the inst ant the software procedure call is mad[...]

AMX 86 Procedures K A DAK 281 ajprvl ajpr vl Purpose Lower Task Privilege Used by n Task o ISP o Time r Proce dure o Rest art Proced ure n Exit Proce dure Setup ajprvl(); Results Interrupts a re disabled and then re stored to their sta te at the time of the call. Restrictions Must follow every ca ll to ajprvr . Once ajprvr is called, task switching[...]

282 K A DAK AMX 86 Procedures ajprvr ajpr vr Purpose Raise Task Privilege Used by n Task o ISP o Time r Proce dure o Rest art Proced ure n Exit Proce dure Setup ajprvr(); Results Interrupts a re disabled and then re stored to their sta te at the time of the call. Restrictions Must be fo llowed by a call to ajprvl as soon as possible to lower the pr[...]

AMX 86 Procedures K A DAK 283 ajrbl ajrbl Purpose Remove from Bottom of Circular List Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup char item; /* one byte item */ int status; . . status = ajrbl(&list, &item); AX ES:BX CL=, CX= or DX:CX= Where &list is a pointer to a circular list (see ajrstl ). &[...]

284 K A DAK AMX 86 Procedures ajre sum a jr esum Purpose Re sume a Suspende d Task Resume a task known to be suspended as a result of an ajsusp call. Used by n Task n ISP n Time r Proce dure o Re start Pro ced ure n Exit Proce dure Setup AMXID taskid; int status; . . status = ajresum(taskid); AX DX Where taskid is the task id of the task to be r es[...]

AMX 86 Procedures K A DAK 285 ajrstl ajrstl Purpose In itialize (Reset) a Circu lar List Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup /* define type of slots */ typedef char SLOT1; /* byte slot */ typedef short int SLOT2; /* word slot */ typedef long SLOT4; /* double word slot */ /* define number of slots i[...]

286 K A DAK AMX 86 Procedures ajrtl ajrtl Purpose Remove from Top of Circular List Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup char item; /* one byte item */ int status; . . status = ajrtl(&list, &item); AX BX CL=, CX= or DX:CX= Where &list is a pointer to a circular list (see ajrstl ). &it[...]

AMX 86 Procedures K A DAK 287 ajsend ajsend Purpose Send a Message to a Task Mailbox To request AMX to send a message to a task at a given priorit y and to begin execution of that task as soon as possible. Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup AMXID taskid; int priority; char msg[AMXMSZ]; int status;[...]

288 K A DAK AMX 86 Procedures ajsendp ajsendp Purpose Send a Message to a Task Mailbox To request AMX to send a message to a task at a given priorit y and to begin execution of that task as soon as possible. Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup AMXID taskid; int priority; int status; int parm1; int [...]

AMX 86 Procedures K A DAK 289 ajsen w ajsen w Purpose Send a Message to a Task Mailbox (Wait for Ack) To request AMX to send a message to a task at a given priorit y 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 r eceives the message and mak es an [...]

290 K A DAK AMX 86 Procedures Results Interrupts a re disabled and then re stored to their sta te at the time of the call. Status is returned. AEROK = C all successful AERNST = Invalid task id AERNME = No fre e message envelope AERNMB = No task mailbox of the specified priority AERMBF = Task mailbox is full An immediate switch to the highest priori[...]

AMX 86 Procedures K A DAK 291 ajsen wp ajsenwp Purpose Send a Message to a Task Mailbox (Wait for Ack) To request AMX to send a message to a task at a given priorit y 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 r eceives the message and mak es an[...]

292 K A DAK AMX 86 Procedures Results Interrupts a re disabled and then re stored to their sta te at the time of the call. Status is returned. AEROK = C all successful AERNST = Invalid task id AERNME = No fre e message envelope AERNMB = No task mailbox of the specified priority AERMBF = Task mailbox is full An immediate switch to the highest priori[...]

AMX 86 Procedures K A DAK 293 ajsgnl ajs gnl Purpose Signal a Task Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup AMXID taskid; unsigned int tsignals; unsigned long siginfo; int status; . . status = ajsgnl(taskid, tsignals, &siginfo); AX DX BX[14..0] BX:CX= BX[15]=0 Where taskid is the task id of the task[...]

294 K A DAK AMX 86 Procedures Results ( continued) AERTNW = Task was not waiting for any of these sig nals. These signals are now pending for the task. At least one of these signals was alre ady pending impl y i ng a signal overrun. Variable siginfo can be examined to see which signals caused the overrun. Siginfo provides additional information con[...]

AMX 86 Procedures K A DAK 295 ajsgrd ajsgrd Purpose Rea d Pending Task Signa ls Used by n Task o ISP o Time r Proce dure o Rest art Proced ure n Exit Proce dure Setup unsigned int tsignals; . . tsignals = ajsgrd(); AX Where tsignals is the current sta te of the calling task's task signa ls. Results Interrupts are untouched. tsignals contains t[...]

296 K A DAK AMX 86 Procedures ajsgr es ajsgr es Purpose Rese t Pending Task Signa ls Used by n Task o ISP o Time r Proce dure o Rest art Proced ure n Exit Proce dure Setup unsigned int tsignals; . . ajsgres(tsignals); BX[14..0] BX[15]=0 Where tsignals is a 15-bit mask ide ntify ing the task signals to be rese t. Only the least sig nificant 15 bits [...]

AMX 86 Procedures K A DAK 297 ajsgwa t ajsgwat Purpose Wait for Task Signal(s) Used by n Task o ISP o Time r Proce dure o Rest art Proced ure n Exit Proce dure Setup unsigned int tsignals; long timeout; int match; int status; unsigned int sigrecv; . . status = ajsgwat(tsignals, match, timeout, &sigrecv); AX BX[14..0] BX[15] DX:CX BX= Where tsig[...]

298 K A DAK AMX 86 Procedures Results Interrupts are disabled and then en abled upon return. Status is returned. AEROK = C all successful AERTM0 = Timed out before required signals occurred AERTMV = Invalid timeout interval (<0) sigrecv identifies the received task signals which satisfied the match criteria or those which had occurre d prior to [...]

AMX 86 Procedures K A DAK 299 ajsint ajsint ajsintq ajsintq Purpose Gene rate Software In terrupt Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup #include "amx831sd.h" . . struct amxregs regarray; int inttype; unsigned int regeax: . . regeax = ajsint(inttype, &regarray); or regeax = ajsintq(intty[...]

300 K A DAK AMX 86 Procedures Results Interrupts will be in the state in which they are left by the interrupt procedure when it ex its. All reg isters in regarray reflect the values in t he proc essor registe rs at t he time the interr upt procedure ended. The real processor registers are only affect ed at the instant the software interrupt ca ll i[...]

AMX 86 Procedures K A DAK 301 ajsmcr e ajsmcr e Purpose Create a S emaphore Used by n Task o ISP o Time r Proce dure n Restar t Pro ced ure n Exit Procedure Setup AMXID semid; int value; char tag[4]; int status; . . status = ajsmcre(&semid, value, tag); AX BX= BX [DX:CX] Where &semid is a pointer to storage for the semapho re id of the sema[...]

302 K A DAK AMX 86 Procedures ajsmdel ajsm del Purpose Delete a S emaphore Used by n Task o ISP o Time r Proce dure n Restar t Pro ced ure n Exit Procedure Setup AMXID semid; int status; . . status = ajsmdel(semid); AX BX Where semid is the semaphore id of a resou rce or counting semaphore acquired by a call to ajsmcre . Results Interrupts a re dis[...]

AMX 86 Procedures K A DAK 303 ajsmfr e ajsmfr e Purpose Uncond itionally Free a Resour ce Semaphore Used by n Task o ISP o Time r Proce dure o Rest art Proced ure n Exit Proce dure Setup AMXID semid; int status; . . status = ajsmfre(semid); AX BX Where semid is the semaphore id of a resource semaphore acquired by a call to ajsmcre . Results Interru[...]

304 K A DAK AMX 86 Procedures ajsmget ajsm get Purpose Get Use of a Semaphore (no wait) Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup AMXID semid; int status; . . status = ajsmget(semid); AX BX Where semid is the semaphore id of a countin g semaphore acquired by a call to ajsmcre . Results Interrupts a re di[...]

AMX 86 Procedures K A DAK 305 ajsmrl s ajsmrl s Purpose Release a R esource Semaphore Used by n Task o ISP o Time r Proce dure o Rest art Proced ure n Exit Proce dure Setup AMXID semid; int status; . . status = ajsmrls(semid); /* nested release */ AX BX Where semid is the semaphore id of a resource semaphore acquired by a call to ajsmcre . Results [...]

306 K A DAK AMX 86 Procedures ajsmrs v ajsmrs v Purpose Reserv e a Resource Semaph ore Used by n Task o ISP o Time r Proce dure o Rest art Proced ure n Exit Proce dure Setup AMXID semid; long timeout; unsigned int priority; int status; . . status = ajsmrsv(semid, timeout, priority); AX BX DX:CX DI Where semid is the semaphore id of a resource semap[...]

AMX 86 Procedures K A DAK 307 Results Interrupts are disabled and then en abled upon return. Status is returned. AEROK = C all successful AERNSS = Invalid semaphore id AERTMO = Timed out without being grant ed the resource AERTMV = Invalid timeout interval (<0) The ca lling ta sk will be suspended waiting for the resource if the resource is owne[...]

308 K A DAK AMX 86 Procedures ajsmsi g ajsm sig Purpose Signal a Se maphor e Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup AMXID semid; int status; . . status = ajsmsig(semid); AX BX Where semid is the semaphore id of a countin g semaphore acquired by a call to ajsmcre . Results Interrupts a re disabled and [...]

AMX 86 Procedures K A DAK 309 ajsmtag ajsm tag Purpose F ind a Sem aphore Used by n Task o ISP o Time r Proce dure n Restar t Pro ced ure n Exit Procedure Setup AMXID semid; char tag[4]; int status; . . status = ajsmtag(&semid, tag); AX BX= [DX:CX] see note Where semid is a pointer to storage for the semaphore id of the semaphore o f interest. [...]

310 K A DAK AMX 86 Procedures ajsm wat ajsmwat Purpose Wait on a Semaphore Used by n Task o ISP o Time r Proce dure o Rest art Proced ure n Exit Proce dure Setup AMXID semid; long timeout; unsigned int priority; int status; . . status = ajsmwat(semid, timeout, priority); AX BX DX:CX DI Where semid is the semaphore id of a countin g semaphore acquir[...]

AMX 86 Procedures K A DAK 311 ajsofs ajs ofs Purpose Set Poin ter Off set Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup unsigned int ofs; char FAR *pntr; . . ajsofs(&pntr, ofs); Results Interrupts are untouched. The offset part of t he FAR pointer variable pntr is set to the 16-bit unsigned value of ofs [...]

312 K A DAK AMX 86 Procedures ajsseg ajs seg Purpose Set Poin ter Segmen t Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup unsigned short int seg; char FAR *pntr; . . ajsseg(&pntr, seg); Results Interrupts are untouched. The segment sele ctor part of the FAR pointer va riable pntr is set to the 16-bit unsi[...]

AMX 86 Procedures K A DAK 313 ajssr eg ajssr eg Purpose Set S egment Registers Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup #include "amx831sd.h" . . struct amxsregs sregarray; . . ajssreg(&sregarray); Where &sregarray is a pointer to a structure definin g the selector values to be set in [...]

314 K A DAK AMX 86 Procedures ajsusp ajs usp Purpose Suspen d a Task Used by n Task o ISP n Time r Proce dure n Restart P roce dure n Exit Proced ure Setup AMXID taskid; int status; . . status = ajsusp(taskid); AX DX Where taskid is the task id of the task to be suspended. Results Interrupts a re disabled and then re stored to their sta te at the t[...]

AMX 86 Procedures K A DAK 315 ajtdf ajtdf Purpose Format Time and Date as an ASCII String Used by n Task o ISP o Time r Proce dure n Restar t Pro ced ure n Exit Procedure 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 is an AMX[...]

316 K A DAK AMX 86 Procedures ajtdg ajtdg Purpose Get Cu rrent Time an d Date Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup #include "amx831sd.h" . . struct amxtds tdbuf; . . ajtdg(&tdbuf); ES:BX Where &tdbuf is a pointer to the structure which is to receiv e the current time and date. The [...]

AMX 86 Procedures K A DAK 317 ajtds ajtds Purpose Set th e Time and Date Used by n Task o ISP o Time r Proce dure n Restar t Pro ced ure n Exit Procedure Setup #include "amx831sd.h" . . struct amxtds tdbuf; . . Initialize tdbuf with new time and date. . . ajtds(&tdbuf); ES:BX Where &tdbuf is a pointer to the structure which contai[...]

318 K A DAK AMX 86 Procedures ajtick ajtick Purpose Read S ystem Tick Counter Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup unsigned long tickcnt; . . tickcnt = ajtick(); DX:AX Results Interrupts are untouched. tickcnt is the current value of the AMX s y stem tick counter. Note The AMX s y stem tick counte r[...]

AMX 86 Procedures K A DAK 319 ajtk cre ajtk cre Purpose Create a New Task Used by n Task o ISP o Time r Proce dure n Restar t Pro ced ure n Exit Procedure Setup #include "amx831sd.h" . . struct amxtdts tdt; AMXID taskid; int status; . . status = ajtkcre(&tdt, &taskid); AX ES:BX DX= Where &tdt is a pointer to the task's de[...]

320 K A DAK AMX 86 Procedures ajtk del ajtkdel Purpose Delete a Ta sk This procedure r emoves a task fr om your AMX s ystem. Its task id will no longer be valid. Used by n Task o ISP o Time r Proce dure o Rest art Proced ure n Exit Proce dure Setup AMXID taskid; int priority; int status; . . status = ajtkdel(taskid, priority); AX DX CX Where taskid[...]

AMX 86 Procedures K A DAK 321 ajtk id ajtk id Purpose Get Task Id of Current Task Used by n Task o ISP o Time r Proce dure o Rest art Proced ure n Exit Proce dure Setup AMXID taskid; . . taskid = ajtkid(); AX Where taskid is the task id of the cur rently executing ta sk. Results Interrupts are untouched. See Also ajtktcb, ajtktag[...]

322 K A DAK AMX 86 Procedures ajtk ill ajtk ill Purpose Kill a Task This procedure will force a ready, executin g or suspended task to end. All messages in the ta sk's mailboxes at the time of the kill request will be flushed. All requests f or task execution pending at the time of the kill request will be e rased. Used by n Task n ISP n Time [...]

AMX 86 Procedures K A DAK 323 ajtk pry ajtkpry Purpose Chan ge Task Priority Used by n Task o ISP n Time r Proce dure n Restart P roce dure n Exit Proced ure Setup AMXID taskid; int priority; int status; . . status = ajtkpry(taskid, priority); AX DX CX Where taskid is the task id of the task whose priorit y is to be changed. priority is the desired[...]

324 K A DAK AMX 86 Procedures ajtk stp ajtkstp Purpose Stop Execution of Task This procedure will f orce a ready, e xecuting or suspended task to end. Used by n Task n ISP n Time r Proce dure o Re start Pro ced ure n Exit Proce dure Setup AMXID taskid; int status; . . status = ajtkstp(taskid); AX DX Where taskid is the task id of the task to be sto[...]

AMX 86 Procedures K A DAK 325 ajtk sts ajtksts Purpose Get Status of a Task Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup #include "amx831sd.h" . . struct amxsbs tasksts; AMXID taskid; int status; . . status = ajtksts(taskid, &tasksts); AX DX ES:BX Where taskid is the task id of the task for wh[...]

326 K A DAK AMX 86 Procedures ajtk tag ajtktag Purpose Find a Task Used by n Task o ISP o Time r Proce dure n Restar t Pro ced ure n Exit Procedure Setup char tag[4]; AMXID taskid; int status; . . status = ajtktag(&taskid, tag); AX DX= [CX:DX] see note Where &taskid is a pointer to storage for the task id of the task o f interest. tag is a [...]

AMX 86 Procedures K A DAK 327 ajtk tcb ajtktcb Purpose Get Task Control Block Pointer Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup #include "amx831sd.h" . . struct amxtcbs *tcbp; AMXID taskid; int status; . . status = ajtktcb(taskid, &tcbp); AX DX ES:BX= Where taskid is the task id of the task[...]

328 K A DAK AMX 86 Procedures ajtk trm ajtktrm Purpose En able/Disable Extern al Task Termination Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup AMXID taskid; void ttproc(); int status; . . status = ajtktrm(taskid, ttproc); AX DX ES:BX Where taskid is the task id of the task whose Termination Procedure is to [...]

AMX 86 Procedures K A DAK 329 ajtmcnv ajtm cnv Purpose Conver t Millisec onds to System Ticks Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup unsigned long ms; long ntick; . . ntick = ajtmcnv(ms); DX:CX DX:CX Where ms is the number of milliseconds. ntick is the equivalent interval in AMX s y stem ticks. Result[...]

330 K A DAK AMX 86 Procedures ajtmcr e ajtmcre Purpose Create an Interval Timer Used by n Task o ISP o Time r Proce dure n Restar t Pro ced ure n Exit Procedure Setup void tproc(); AMXID timerid; long tperiod; struct tuser *tparam; char tag[4]; int status; . . status = ajtmcre(&timerid, tperiod, tproc, tparam, tag); AX DX= ES:BX is A(Timer Defi[...]

AMX 86 Procedures K A DAK 331 ajtmdel ajtm del Purpose Delete an Interval Timer Used by n Task o ISP n Time r Proce dure n Restart P roce dure n Exit Proced ure Setup AMXID timerid; . . status = ajtmdel(timerid); AX DX Where timerid is the timer id identify in g the timer to be de leted. Results Interrupts a re disabled and then re stored to their [...]

332 K A DAK AMX 86 Procedures ajtmrd ajtm rd Purpose Read th e Current Value of an Interval Timer Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup AMXID timerid; long tval; . . tval = ajtmrd(timerid); DX:CX DX Where timerid is the timer id identify in g the timer whose value is r equired. tval is the timer valu[...]

AMX 86 Procedures K A DAK 333 ajtmtag ajtm tag Purpose Find an Interval Tim e r Used by n Task o ISP o Time r Proce dure n Restar t Pro ced ure n Exit Procedure Setup AMXID timerid; char tag[4]; int status; . . status = ajtmtag(&timerid, tag); AX DX= [DX:CX] see note Where &timerid is a pointer to storag e for the timer id of the interval t[...]

334 K A DAK AMX 86 Procedures ajtm wr ajtmwr Purpose Start/Stop an Interval Timer Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup AMXID timerid; long tval; int status; . . status = ajtmwr(timerid, tval); AX DX BX:CX Where timerid is the timer id identifying the timer to be started or stopped. tval is the timer[...]

AMX 86 Procedures K A DAK 335 ajtrig ajtr ig Purpose Trigger a T ask To request AMX to start a task without sending a message to the task. Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup AMXID taskid; int status; . . status = ajtrig(taskid); AX DX Where taskid is the task id of the task to be triggered. Result[...]

336 K A DAK AMX 86 Procedures ajtslv ajt slv Purpose Change a Task's Tim e Slice Interval Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup AMXID taskid; unsigned int tslice; int status; . . status = ajtslv(taskid, tslice); AX DX CX Where taskid is the task id of the task whose time slice inter val is to be[...]

AMX 86 Procedures K A DAK 337 ajtsof ajt sof ajtson ajt son Purpose Disable Tim e Slicing Enable Tim e Slicing Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup ajtsof(); /* Disable time slicing */ or ajtson(); /* Enable time slicing */ Results Interrupts are untouched. See Also ajtslv[...]

338 K A DAK AMX 86 Procedures ajupt ajupt Purpose Fetch Poin ter to User Para meter Tab le Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup #include "amx831sd.h" . . struct amxupts FAR *uptp; /* User Parameter Table pointer */ . . ajupt(&uptp); Where &uptp is a FAR pointer to stora ge for a FA[...]

AMX 86 Procedures K A DAK 339 ajver ajver Purpose Get AMX Version Number Used by n Task n ISP n Time r Proce dure n Re start Proce dure n Exit Proced ure Setup unsigned long version; . . version = ajver(); DX:AX Where version is the AMX version number in the hex adecimal format 0x0086rrmm where rr is the major revision number ( 03 ) mm is the minor[...]

340 K A DAK AMX 86 Procedures ajwa it ajwa it Purpose Wait Unconditionally for a Wake Request Used by n Task o ISP o Time r Proce dure o Rest art Proced ure n Exit Proce dure Setup ajwait(); Results Interrupts are en abled. The task will be suspende d until some other task, I SP or Timer Procedure issues an ajwake call to wake this task. If a task [...]

AMX 86 Procedures K A DAK 341 ajwak c ajwak c Purpose Wake Calling Task (Acknowledge Receipt of Message) To allow the current ta sk to wake up the task which sent the messag e which is being processed b y the current task. Used by n Task o ISP o Time r Proce dure o Rest art Proced ure n Exit Proce dure Setup int status; . . status = ajwakc(); AX Re[...]

342 K A DAK AMX 86 Procedures ajwak cs ajwak cs Purpose Wake Calling Task (Acknowledge Receipt of Message wi th Status) To allow the current ta sk to wake up the task which sent the messag e which is being proce ssed b y the current task and return completion status to that task. Used by n Task o ISP o Time r Proce dure o Rest art Proced ure n Exit[...]

AMX 86 Procedures K A DAK 343 ajwak e ajwak e Purpose Wake a Waiting Task To wake up a task known to be waiting because of an ajwait or ajwatm call. Used by n Task n ISP n Time r Proce dure o Re start Pro ced ure n Exit Proce dure Setup AMXID taskid; int status; . . status = ajwake(taskid); AX DX Where taskid is the task id of the task to be wakene[...]

344 K A DAK AMX 86 Procedures ajwap r ajwapr Purpose Reset a Pending Wake Request This call only affects the ca lling task. Used by n Task o ISP o Time r Proce dure o Rest art Proced ure n Exit Proce dure Setup ajwapr(); Results Interrupts are untouched. Note This procedure provides a simplified form of task signal reset (see ajsgres ). See Also aj[...]

AMX 86 Procedures K A DAK 345 ajwatm aj watm Purpose Task Delay or Timed Wait for a Wake Request Used by n Task o ISP o Time r Proce dure o Rest art Proced ure n Exit Proce dure Setup long tval; int status; . . status = ajwatm(tval); AX DX:CX Where tval is the required wait interval or del ay period measured in AMX system ticks. Tval must be positi[...]

346 K A DAK AMX 86 Procedures This page left blank intentionall y .[...]

AMX 86 Reserved Words K A DAK 347 A. AMX 86 Reserved W ords ajpppppp AMX C procedure name pppppp AAPPPPPP AMX assembl y lan guage procedure name PPPPPP amxttttt AMX C structure name of t ype ttttt AMXID AMX object identi fier (handle) cdecl Procedures use C param eter passing conventions AMssssss Reserved s y mbols defined in AM X header files AERx[...]

348 K A DAK AMX 86 Reserved Words This page left blank intentionall y .[...]

AMX 86 Error Co des K A DAK 349 B. AMX 86 Err o r Codes AMX error codes are signed inte gers. Codes less than zero are er ror codes. Codes greater than zero are warning codes. To assist y ou during testing , the hexadecimal va lue of the least significant 16-bits of the er ror code is listed as it might a ppear in a register or memory dump. Mnem on[...]

350 K A DAK AMX 86 Error Co des AMX 86 Er ror Codes ( continued) Mnem onic Value Value Meaning (dec) (hex) AERNBF -30 0xFFE2 No buffers defined AERNFP -31 0xFFE1 No free buffer pool AERNEB -32 0xFFE0 No free event grou p AEREVU -33 0xFFDF Event group in use -34 0xFFDE reserved -35 0xFFDD reserved -36 0xFFDC reserved AERMNA * -37 0xFFDB Memory not a[...]

AMX 86 Error Co des K A DAK 351 AMX 86 Fatal Exit Codes Mnem onic Value Value Meaning (dec) (hex) AERFX1 ● 1 0x0001 Not enough memory in AMX Data Segment AERFX2 ● 2 0x0002 Divide, overflow, bound error in I S P AERFX3 ● 3 0x0003 Divide, overflow, bound error occu rred: in a Restart Procedur e or in a Timer Proc edure or in a task with no task[...]

352 K A DAK AMX 86 Error Co des This page left blank intentionall y .[...]

Generator Specifications K A DAK 353 C. Configuration Gener a t or Specification s C.1 Intr oduction If you are not doing your software development on a PC or compatible runnin g Microsoft ® Windows ® , then y ou will be unable to use the interac tive Configuration Manager for Windows to create and edit y our AMX S y stem Configuration Module. Yo[...]

354 K A DAK Generator Specifications C.2 User Parameter File Specificatio n The User Para meter F ile is a tex t file str uctured a s illustrated in F igure C.2-1. The file consists of a sequence of k eywords of the form ...XXX which begin in column one. Each keyword is followed by one or more param eters which you must provide. ; Constant definiti[...]

Generator Specifications K A DAK 355 The example in Figure C.2-1 uses s y mbolic names for all of the parameters following each of the ke y wo rds. The symbols correspond to the screen fi elds described in Chapt er 14. You are referr ed to that chapter for detailed descriptions of ea ch of the parameters. The order of ke y wo rds in the User Parame[...]

356 K A DAK Generator Specifications Each of your pred efined tasks must be defined using ke y word ...TDT . Th e order of these de finitions will determine their order of creation by AMX. If you do not wish to predefine any ta sks, delete the line with keyw ord ...TDT. The paramete rs in each ta sk definition are as follows. TKPROC Task procedure [...]

Generator Specifications K A DAK 357 Each of your pred efined semaphore s must be defined using the ke y word ...SEM . The order of these def initions will determine their order of creation by AMX. If you do not wish to predefine an y semaphores, delet e the line with keyword ...SEM . The parameters in each sem aphore definition are as follows: SMV[...]

358 K A DAK Generator Specifications Each of your pred efined message exchanges must be defined using the keyword ...MEX . The order of these definitions will determine the ir order of creation by AMX. I f y ou do not wish to predefine any message ex changes, delete the line with keyword ...MEX . The parameters in e ach message exchan ge definiti o[...]

Generator Specifications K A DAK 359 C.3 System Configurat ion T emplate The Sy stem Configur ation Template is an a ssembly language source file which defines a System Config uration Module for any system using AMX and its managers. It is recomme nded that you list file AM831CG.CT and ex ami ne it care full y before tr y ing to read this descripti[...]

360 K A DAK Generator Specifications Macro para meters appea r in the macro body as parameter ide ntifiers. A par ameter identifier is a decimal integer preced ed and followe d b y the delimiter character d efined in the macro definiti on statement ( ~1~ , ~2~ , etc.). The number identif ies the para meter in the particula r parameter list spe cifi[...]

Generator Specifications K A DAK 361 The first statem ent in this ex ample is a directi ve defining an in cremental variabl e named &TN . Both its initial value and increme nt are 1. Note that this directive begins with the assembler comment char acter ( ; ) and the para meter delimite r cha racter ( ~ in this example) required by all KADAK mac[...]

362 K A DAK Generator Specifications C.4 Porting the C onfigurat ion Gener a tor The Configuration Manager uses the Configuration Generator to ge nerate 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 y our d evelopment system. The Configuration Ge ne[...]

Generator Specifications K A DAK 363 By defa ult, the Configura tion Generator uses the ma cro identific ation characte r ( ; in our exampl e) from the macro directive as a com ment charact er to identif y the com ments inserted into the output file in response to the -w switch. This default assumption can be overridden using the -b and -e switches[...]

364 K A DAK Generator Specifications This page left blank intentionall y .[...]

Structure/Consta nt Def initions K A DAK 365 D. AMX 86 S tructure and Constant Defi nitions D.1 AMX C S tructures and Consta nts AMX Laun ch Parameter (s ee 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 [...]

366 K A DAK Structure/Consta nt Def initions AMX Task Stat us Block Struc ture struct amxsbs { AMXID amsbtid; /* task id */ char amsbtag1; /* task tag */ char amsbtag2; char amsbtag3; char amsbtag4; unsigned long amsbst; /* task status */ unsigned long amsbsig; /* pending signals */ long amsbtmr; /* task timer (time remaining) */ unsigned short int[...]

Structure/Consta nt Def initions K A DAK 367 AMX Extend ed Message Paramete r Structur e (passed on stack above AM X message when starting a task) struct amxmsgxs { AMXID amxmscid; /* calling task's id */ short int amxmsfn; /* AMX function code */ /* (see definitions) */ short int amxmsrsv[4]; /* reserved */ }; AMX Function Codes (field amxmsf[...]

368 K A DAK Structure/Consta nt Def initions AMX User Para meter Tabl e Structur e struct amxupts { void (**ampbrpl)(); /* A(Restart Procedure List) */ void (**ampbepl)(); /* A(Exit Procedure List) */ long ampbcfga; /* Configuration attributes */ short int ampbdgrp; /* user's DGROUP segment selector */ short int ampbnmev; /* number of message [...]

Structure/Consta nt Def initions K A DAK 369 Configuration A ttribut es (field AMPBCFGA ) #define AMCAMTK 1 /* Some Medium tasks */ #define AMCAMUP 2 /* Some Medium user procedures */ #define AMCAS24 4 /* Use 24-bit address space */ AMX Time/Dat e Structure struct amxtds { unsigned char amtdsec; /* seconds (0-59) */ unsigned char amtdmin; /* minute[...]

370 K A DAK Structure/Consta nt Def initions AMX List He ader St ructure (doubly linked list s) struct amxlhs { struct amxlhs *amlhhead; /* list head */ struct amxlhs *amlhtail; /* list tail */ unsigned int amlhoffs; /* byte offset to object node */ }; AMX List Node Stru cture struct amxlns { struct amxlns *amlnnext; /* next node in list */ struct [...]

Structure/Consta nt Def initions K A DAK 371 AMX Register A rray Structure struct amxregs { unsigned short int amxrf; /* Flags (LS byte only) */ unsigned short int amxrax; /* Register AX */ unsigned short int amxrbx; /* Register BX */ unsigned short int amxrcx; /* Register CX */ unsigned short int amxrdx; /* Register DX */ unsigned short int amxrsi[...]

372 K A DAK Structure/Consta nt Def initions AMX C Jump Bu ffer Stru cture struct ajxjbuf { unsigned short int xjbretadr; /* ofs(return address) */ unsigned short int xjbcs; /* Register CS */ unsigned short int xjbsp; /* Stack pointer offset */ unsigned short int xjbss; /* Stack pointer segment */ unsigned short int xjbbx; /* Register BX */ unsigne[...]

Structure/Consta nt Def initions K A DAK 373 D.2 AMX Assembler S tructur es and Constants AMX Laun ch Parameter (s ee AAENTR ) AMLPTMP EQU 1 ;Temporary launch ; ;Default is permanent launch ; AMLPVA EQU 2 ;Vector table is alterable ; ;Default is non alterable table ; AMLPIE EQU 4 ;Launch with interrupts enabled ;Default is disabled interrupts AMX T[...]

374 K A DAK Structure/Consta nt Def initions AMX Task Stat us Block Struc ture AMXSBS STRUC ; AMSBTID DW ? ;task id AMSBTAG1 DB ? ;task tag AMSBTAG2 DB ? AMSBTAG3 DB ? AMSBTAG4 DB ? AMSBST DD ? ;task status AMSBSIG DD ? ;pending signals AMSBTMR DD ? ;task timer (time remaining) AMSBSLC DW ? ;time slice AMSBCC DW ? ;call count AMSBATR DW ? ;task att[...]

Structure/Consta nt Def initions K A DAK 375 AMX Extended Message Paramete r Structure (passed on stack above AM X message when starting a task) AMXMSGXS STRUC ; AMXMSCID DW ? ;calling task's id AMXMSFN DW ? ;AMX function code AMXMSRSV DW 4 DUP(?) ;reserved ; AMXMSGXS ENDS AMX Function Codes (field AMXMSFN ) AMXMSFNM EQU 0 ;no message on stack[...]

376 K A DAK Structure/Consta nt Def initions AMX User Para meter Tabl e Structur e AMXUPTS STRUC ; AMPBRPL DD ? ;A(Restart Procedure List) AMPBEPL DD ? ;A(Exit Procedure List) AMPBCFGA DD ? ;Configuration attributes AMPBDGRP DW ? ;user's DGROUP segment selector AMPBNMEV DW ? ;number of message envelopes AMPBUMS DW ? ;user message size (bytes) [...]

Structure/Consta nt Def initions K A DAK 377 Configuration A ttribut es (field AMBPCFGA ) AMCAMTK EQU 1 ;Some Medium tasks AMCAMUP EQU 2 ;Some Medium user procedures AMCAS24 EQU 4 ;Use 24-bit address space AMX Time/Dat e Structure AMXTDS STRUC ; AMTDSEC DB ? ;seconds AMTDMIN DB ? ;minutes AMTDHR DB ? ;hours AMTDDY DB ? ;day AMTDMN DB ? ;month AMTDY[...]

378 K A DAK Structure/Consta nt Def initions AMX List He ader St ructure (doubly linked list s) AMXLHS STRUC ; AMLHHEAD DD ? ;Head of list AMLHTAIL DD ? ;Tail of list AMLHOFFS DW ? ;Byte offset to object node ; AMXLHS ENDS AMX List Node Stru cture AMXLNS STRUC ; AMLNNEXT DD ? ;Next node in list AMLNPREV DD ? ;Previous node in list ; AMXLNS ENDS AMX[...]

Structure/Consta nt Def initions K A DAK 379 AMX Register A rray Structure AMXREGS STRUC ; AMXRF DW ? ;Flags (LS byte only) AMXRAX DW ? ;Register AX AMXRBX DW ? ;Register BX AMXRCX DW ? ;Register CX AMXRDX DW ? ;Register DX AMXRSI DW ? ;Register SI AMXRDI DW ? ;Register DI AMXRBP DW ? ;Register BP AMXRDS DW ? ;Register DS AMXRES DW ? ;Register ES ;[...]

380 K A DAK Structure/Consta nt Def initions This page left blank intentionall y .[...]

AMX 86 Assembler Interface K A DAK 381 E. AMX 86 Assembler Interface This appendix summarizes the a ssembly language ca lling sequences for a ll AMX procedures. The procedur es are organized in functional groups. Within each group the procedures are listed alphabetic ally. All procedures ar e called as follows: EXTRN AAxxxx:FAR ;external FAR proced[...]

382 K A DAK AMX 86 Assembler Interface The following notes are refer enced in the procedure descriptions in this appendix . Note: 1. All registers are pres erved, including AX . 2. Registers CX , DX , SI are unalt ered. All other registers a re undefined. 3. All registers are restor ed to the state the y were in when AAINT was calle d. 4. Registers[...]

AMX 86 Assembler Interface K A DAK 383 PROCEDURE C ASM PURP OSE PARAME TERS IN OUT AX = ERRORS E D R System Control ajentr AA ENTR E nter A MX multit asking w orld L aunch Parame ters BX no nnn Exit allow ed? (0=No , 1=Yes) bit 0 IVT a lt era ble bit 1 (0=No, 1= Yes ) Interru p ts enab led b it 2 (0=No, 1= Yes ) A(AM X U ser P ar ame ter Ta ble ) D[...]

384 K A DAK AMX 86 Assembler Interface PROCEDURE C ASM PURP OSE PARAME TERS IN OUT AX = ERRORS E D R Task Control aj end AA END End ta sk execu tion no no o (no retu rn ) ajgmsg AAGMSG Get message from task mailbox A(Storage for message) ES:BX AERCWT on n Mail box pr iori ty (0 to 3) CX AERNMG (4=highest priority messag e) aj resu m A ARES UM Res u[...]

AMX 86 Assembler Interface K A DAK 385 PROCEDURE C ASM PURP OSE PARAME TERS IN OUT AX = ERRORS E D R Task Control (continue d) ajtki ll AATKIL L Kill a task Task id DX AERNST on n AER AN A ajtkpry AATKPRY Change task's e xecution priority Task id DX AERNST on n Task's new priority CX AERIT P ajtk stp AATKS TP St op a task Task id DX AERNS[...]

386 K A DAK AMX 86 Assembler Interface PROCEDURE C ASM PURP OSE PARAME TERS IN OUT AX = ERRORS E D R Interrupt Co ntrol ajint AAI NT Begin inte rrupt ser vice AMX I nterr upt St ack S S:S P Note 2 ono DGROUP segment DS,ES ajinx AAI NX End i nte rrupt ser vice Note 3 ono aji spm AAISPM Mak e an I SP root A (Storage for ISP root) ES:BX n o ooo A(I nt[...]

AMX 86 Assembler Interface K A DAK 387 PROCEDURE C ASM PURP OSE PARAME TERS IN OUT AX = ERRORS E D R Timing Co ntrol ajclk AACLK A MX Clo ck Handle r Note 1 nnn ajti ck A A T ICK Read elaps ed s ystem ti cks DX:AX no on n ajtm cn v AATM CNV Convert millis ec onds to s yst em ticks Interval (ms) DX:CX no ooo Inte rval (system tic ks) DX :CX ajtmcre [...]

388 K A DAK AMX 86 Assembler Interface PROCEDURE C ASM PURP OSE PARAME TERS IN OUT AX = ERRORS E D R Semaphore Manag er ajsmcre AAS MCRE Cre ate a se maphore I nitial value (0 to 327 67) BX A ERISV on n (-1 for resource semaph ore) A ERNSB Tag DX:CX Not e 5 Sem aphore id BX ajsmde l AASMD EL De lete a sem aphore Sem aphore id BX AERN SS on n AER SI[...]

AMX 86 Assembler Interface K A DAK 389 PROCEDURE C ASM PURP OSE PARAME TERS IN OUT AX = ERRORS E D R Event M ana ger ajevc re AAEVCRE Create a n event grou p Init ial va lu e for event group B X AERNE B on n Tag DX:CX Not e 5 Gro up id BX ajevd el AAEVDEL Delete a n event gr ou p Grou p id BX AERNS G on n AER EV U ajevn t AAEVN T Get sa ved event s[...]

390 K A DAK AMX 86 Assembler Interface PROCEDURE C ASM PURP OSE PARAME TERS IN OUT AX = ERRORS E D R Messa ge Ex chan ge Manager ajmxcre AA MXCRE Create a m essage ex change Tag DX :CX AERNXB on n A( Mailbo x siz e de finitio n) ES:BX AE RMBZ DW size m ailbox 0 N ote 5 DW size m ailbox 1 DW size m ailbox 2 DW size m ailbox 3 Exchange id BX ajmxde l[...]

AMX 86 Assembler Interface K A DAK 391 PROCEDURE C ASM PURP OSE PARAME TERS IN OUT AX = ERRORS E D R Buffer M anager ajba u AA BAU Add to buffer use count A( buffe r) ES :BX AER BNU on n Increm en t for b uffer u se count DX AERB UV AER NSP ajbcre AABC R E Create a buffer p ool A(Bu ffer Pool Defin i tion) ES:BX AERB TS on n Pool id DX AER NBF AER [...]

392 K A DAK AMX 86 Assembler Interface PROCEDURE C ASM PURP OSE PARAME TERS IN OUT AX = ERRORS E D R Memory Manager ajm au A AM AU Add to block use count A(memor y block) ES:BX AER MIB on n Increm en t for u se coun t DX AERMNU AER MO V ajmfr e AA MFRE Free a block of m emo ry A(memo ry blo ck) ES: BX AERMI B on n AER MN U ajmgeh AAMGEH Get a b loc[...]

AMX 86 Assembler Interface K A DAK 393 PROCEDURE C ASM PURP OSE PARAME TERS IN OUT AX = ERRORS E D R Link ed List Mana ger ajlcre AAL CRE Create an e mpty list A(List He ader) DS:SI no ooo Node offset CX ajlhea d AA LHEA D Find head of l ist A(List He ader) DS :SI N ote 6 ooo A(F irst object) ES:BX (0:0 i f list is em pt y) ajlin sc AA L INSC I nse[...]

394 K A DAK AMX 86 Assembler Interface PROCEDURE C ASM PURP OSE PARAME TERS IN OUT AX = ERRORS E D R Link ed List Mana ger (continue d) ajlrm vc AALRMVC R emove speci fic obj ec t from list A(List Hea d er) DS:S I no on n A( Specif ic objec t) ES:BX ajlrmv h AA L RMVH Re move object at hea d of list A (List He ader) DS:SI N ote 6 on n A(Ob j ect ) [...]

Index K A DAK Index- 1 Numerals 24-bit m emory addre ssing 1, 12 5, 171 A AACLK 73 AAENTR 22 AAI NT 54, 55, 56, 7 3 AA INX 55, 56 , 73 ajabl 13 5, 205 ajatl 13 5, 206 ajbau 52, 119, 1 21, 207 ajbcr e 119, 120, 17 4, 189, 208 ajbdel 119, 12 1, 21 0 ajbf re 52, 76, 1 19, 121, 21 1 ajbge t 52, 7 6, 11 9, 121, 212 ajbgs z 119, 1 21, 213 ajbia 1 19, 214[...]

Index- 2 K A DAK Index ajsm cre 91, 93, 94 , 95, 98, 99, 174, 183, 301 ajsm del 91, 93, 99, 30 2 ajsmf re 91, 95, 303 ajsmget 9 1 , 94, 304 ajsm rls 91, 95, 305 ajsmrs v 28, 91, 95, 96, 306 ajsms ig 52, 5 8, 76, 9 1, 94, 308 ajsmtag 9 1, 93, 30 9 ajsmw at 28, 58, 91, 94, 98, 99, 31 0 ajsofs 311 ajsseg 312 ajssreg 313 ajsusp 15 8, 314 ajtdf 70, 82, [...]

Index K A DAK Index- 3 Class of AMX service buff er pool, buff er 197 C langua ge inte rfa ce 199 circular list 198 counting semaphor e 196 eve nt group 196 interrupt co ntrol 19 4 linked list 198 memory allocation 197 message exch ange 197 PC Super visor 2 00 proces sor su pport 199 resour ce s ema phore 1 96 sys tem control 1 94 task c ontrol 19 [...]

Index- 4 K A DAK Index F FAR pointe rs 204 Fatal error 3 Fatal exit 3, 60, 147, 14 8, 149, 175 Fatal ex it codes 147, 1 48, 149, 351 Fatal Exit Procedure 147 , 148 , 149 , 175 interrupt state 148 stack size 14 8 Faults (p rocesso r exceptions) 68 Fences (stack) 4 6 File nam es (AMX file s) 7 Flags (see Ev ent group, f lags) free 125 Function protot[...]

Index K A DAK Index- 5 M Mailbox 4, 26 (see Message (task), mailbox) ack nowle dge me ssage 35 mess age que ue 4 Make utilitie s (Refer to AMX Tool Guid es) malloc 12 5 Math coproc e s s or 101, 10 2, 15 2 Mem ory addr essing (24-bit) 1, 125 , 171 Mem ory alloc ation 18, 125, 12 6, 128 – 34 Me mor y as si gn men t (see Memor y Assignment Pr ocedu[...]

Index- 6 K A DAK Index P PC Super visor (see PC Superv isor Ref erence Ma nual) Service P rocedure Su mmary 200 Preem ption 13 Priority (see Ev ent group, w ait for event(s )) (see Kernel Task, p riority) (see Message ex ch ange, message p riority) (see Message ex ch ange, wait for mess age) (see Sema phore, cou nting, w ait) (see Sem aphore, r eso[...]

Index K A DAK Index- 7 Stack s ize Exit Procedure s 44, 45 Fatal Exit Procedure 1 48 Interrupt Service Procedu re 51, 56, 65 Interrupt Stac k 51, 56, 6 5, 171 Kernel Sta ck 42, 43, 65, 76, 77, 85, 8 6, 87, 1 70 Resta rt Proce dures 42, 43 task 44, 45, 51, 61, 65, 15 5, 15 6, 179 Task Term ina tion Pr oce dur e 155, 15 6 Task Trap Handler 61 Tim e/D[...]

Index- 8 K A DAK Index Task term ination 153, 15 4, 155, 156, 157 delete 154, 155, 15 6, 15 7 deletion pri ority 157 enable/disable 154 kill 154, 155, 156, 15 7 Service P rocedure Su mmary 195 stop 153, 154, 15 5, 15 6, 157 Task Term ina tion Pr oce dur e 154, 15 5, 15 6, 36 6, 374 Task Trap Handler 60, 6 1, 62, 6 3, 147 stack size 61 TCB ( see Tas[...]