Fresh Fish 1

home *** CD-ROM | disk | FTP | other *** search

/ Fresh Fish 1 / FFMCD01.bin / bbs / develop / mcx11.lha / MCX11 / MANUAL.DOC < prev next >

Wrap

Text File | 1990-04-11 | 129KB | 3,829 lines

MCX11 MicroController eXecutive for the Motorola MC68HC11 Version 1.3 by A.T. Barrett & Associates 11501 Chimney Rock Houston, Texas 77035 (713)728-9688 April 1990 Support Contact: Mike Wood M/S OE319 Motorola, Inc. 6501 William Cannon Drive West Austin, Texas 78735 (512)891-2717 Neither Motorola, Inc. nor A.T. Barrett & Associates makes any warranty, expressed or implied, with regard to this material including but not limited to merchantability or fitness for a given purpose. The information in this document is subject to change without notice and neither Motorola, Inc. or A.T. Barrett & Associates assumes any responsibility for any errors which may appear herein. Nor shall Motorola, Inc. or A.T. Barrett & Associates bear any liability for use of this material with respect compensatory, special, incidental, consequential, or exemplary damages. MCX11 - MicroController eXecutive for the 68HC11 TABLE OF CONTENTS Section 1 Introduction Page 1.1 Background and Features........................... 1-1 1.2 MCX11 as a Software Component..................... 1-1 1.3 Target Environment................................ 1-2 1.4 Development Environment........................... 1-2 1.5 Manual Format..................................... 1-2 Section 2 MCX11 Functional Overview 2.1 What Is MCX11..................................... 2-1 2.2 Tasks............................................. 2-2 2.3 Multitasking...................................... 2-2 2.4 Priority and Scheduling........................... 2-2 2.5 Intertask Communication and Synchronization....... 2-3 2.6 Time based Functions.............................. 2-4 2.7 Interrupt Service................................. 2-4 Section 3 MCX11 Control & Data Structures 3.1 Tasks.............................................. 3-1 3.1.1 Task Identifier & Priority....................... 3-1 3.1.2 Task State Table................................. 3-2 3.1.3 Stack............................................ 3-3 3.2 Semaphores........................................ 3-3 3.3 Messages and Mailboxes............................ 3-5 3.4 Queues............................................ 3-7 3.5 Timers............................................. 3-8 Section 4 Executive Service Requests (ESRs) 4.1 Purpose........................................... 4-1 4.2 Semaphore ESRs.................................... 4-1 4.3 Message ESRs...................................... 4-2 4.4 Queue ESRs........................................ 4-2 4.5 Task Control ESRs................................. 4-2 4.6 Time Based ESRs................................... 4-2 Section 5 Alphabetical Listing of ESRs 5.1 .delay. - Delay a Task for a Period of Time..... 5-2 5.2 .dequeue. - Get an Entry from a FIFO Queue...... 5-4 5.3 .enqueue. - Insert Data into FIFO Queue......... 5-6 5.4 .execute. - Execute a Task...................... 5-9 5.5 .pend. - Force a Semaphore to a PENDING State.. 5-11 5.6 .purge. - Purge a Task's Timers................ 5-12 5.7 .receive. - Receive a Message.................. 5-14 5.8 .resume. - Resume a Task....................... 5-16 5.9 .send. - Send a Message to a Task.............. 5-17 5.10 .sendw. - Send a Message and Wait............. 5-19 5.11 .signal. - Signal a Semaphore................. 5-20 Page i MCX11 - MicroController eXecutive for the 68HC11 TABLE OF CONTENTS 5.12 .suspend. - Suspend a Task.................... 5-22 5.13 .terminate. - Terminate a Task................ 5-23 5.14 .timer. - Start a Timer....................... 5-24 5.15 .wait. - Wait on Semaphore.................... 5-26 Section 6 System Configuration 6.1 System Configuration Concepts..................... 6-1 6.2 MCX11 System Table Memory Requirements............ 6-1 Section 7 Device Driver & Interrupts 7.1 Driver Concepts................................... 7-1 7.2 Interrupt Service................................. 7-1 7.2.1 Interrupt Processing Variables................... 7-2 7.2.2 Interrupt Processing Code........................ 7-4 Section 8 Advanced Topics 8.1 Other topics...................................... 8-1 Appendix A MCX11 Distributed Source Files............. A-1 Page ii MCX11 - MicroController eXecutive for the 68HC11 SECTION 1 INTRODUCTION 1.1 BACKGROUND AND FEATURES MCX11, the MicroController eXecutive for the MC68HC11, is an efficient software framework for embedded real-time applications using the Motorola MC68HC11 microcontroller. Motorola, Inc. makes MCX11 available free of charge via the Freeware Bulletin Board System. MCX11 is written in the AS11 assembly language which is also available on the Motorola Freeware BBS (512/891-3733). MCX11 provides many features which are designed to support real-time applications. These features include: - Multitasking for up to 126 tasks - Pre-emptive task scheduling by priority - Intertask communication and synchronization via semaphores, messages, and queues. - Support for timed operations - Fast context switch - Very small RAM and ROM requirements - Fifteen Executive Service Request functions 1.2 MCX11 AS A SOFTWARE COMPONENT MCX11 is furnished in AS11 source form and is downloadable via a modem connection to the Freeware BBS. In its distribution form, it is not executable. It may be assembled separately or with the application programs and any device drivers peculiar to the application. MCX11 may be treated as any other software library. The user need not know how MCX11 performs its functions internally. Rather, the user need only know what functions of MCX11 to use to achieve a desired result. Thus, MCX11 becomes much like a large scale integrated circuit component in the hardware. Knowledge of what inputs produce what outputs is all that is needed to use the "chip" successfully. Unlike a chip, however, MCX11 users are provided with the source code to the kernel so that they can exercise complete control over their applications. With the source code, users may even wish to extend the functionality of MCX11 by the addition of new services. This manual is not meant as a tutorial on real-time kernels in general. It is intended to explain the "inputs" and "outputs" of MCX11 as a software component of the user's application. In an effort to assist the user in the Copyright (c) 1989 Page 1 - 1 Motorola, Inc. MCX11 - MicroController eXecutive for the 68HC11 successful employment of MCX11, this manual will cover the following subjects: - basic concepts of MCX11 design - interfaces to the MCX11 services - system generation procedure - assembly procedure for MCX11 and application source files - procedure for merging MCX11 with the application object files 1.3 TARGET ENVIRONMENT MCX11 is designed to operate in an embedded processor, that is, one whose functions are fixed within the application. No assumptions are made about the configuration of the target system. It is the responsibility of the user to define the target environment and to insure that all necessary devices have program support. No distinction is made between Single- Chip Operating mode or Expanded Multiplexed Operating mode in the design of MCX11. If there are special requirements in the application for functions related to a certain operating mode, it will be the responsibility of the user to add them. 1.4 DEVELOPMENT ENVIRONMENT MCX11 development requires a computer compatible with the IBM PC and having at least 256K bytes of RAM, 1 floppy disk, a keyboard, and a video monitor, an RS-232 compatible serial I/O port, a Centronics compatible parallel printer port, and a printer (preferably one which is Epson compatible). A hard disk is very desirable for development work. This configuration is needed to run the AS11 cross assembler and serve as a debug terminal to the target assuming MC68HC11EVM Evaluation Module is being used. Consult the EVM User Manual for specifics on connection tp PC. Recommended software for the development environment besides MS-DOS includes an editor, and the Kermit communications program (public domain). 1.5 MANUAL FORMAT Section 1 of this manual is simply an overview of MCX11. Section 2 gives the functional overview of MCX11. Section 3 details the organization and content of the various MCX11 control and data structures. Copyright (c) 1989 Page 1 - 2 Motorola, Inc. MCX11 - MicroController eXecutive for the 68HC11 Section 4 gives a description of the Executive Service Requests (ESRs) provided by MCX11, subdivided into their classes. Section 5 gives an alphabetical presentation of all MCX11 Executive Service Requests. Section 6 deals with the configuration and generation of MCX11 systems. Section 7 discusses device drivers and interuupt service routines. Section 8 presents technical information on advanced topics related to the use of MCX11. Appendices round out the specifics of necessary user knowledge. Copyright (c) 1989 Page 1 - 3 Motorola, Inc. MCX11 - MicroController eXecutive for the 68HC11 SECTION 2 MCX11 FUNCTIONAL OVERVIEW 2.1 WHAT IS MCX11 A real-time executive provides a software framework within which different processes can operate and gain access to various system resources. Real-time systems usually consist of several processes, or tasks, which need to have control of the system resources at varying times due to the occurrence of external events. These tasks are at various times competing for system resources such as memory, execution time, or peripheral devices. They range from being compute bound to I/O bound. Tasks which are I/O or compute bound cannot be allowed to monopolize a system resource if a more important function requires the same resource. There must be a way of interrupting the operation of the task of lesser importance and granting the needed resource to the more important task. A multitasking real-time executive promotes an orderly transfer of control from one task to another such that efficient usage of the computer's resources is achieved. Orderly transfers require that the executive keep track of the needed resources and the execution state of each task so that they can be granted to each task in a timely manner. The key word there is timely. A real-time system which does not perform a required operation at the correct time has failed. That failure can have consequences which range from the benign to the catastrophic. Response time to a need for executive services and the execution time of such services must be sufficiently fast enough so that no need goes undetected. One way to achieve timeliness is the assignment of a priority to each task. The priority of a task is then used to determine its place within the sequence of execution of all tasks. Tasks of low priority may have their execution pre-empted by a task of higher priority so that the latter can perform some time critical function. An event can be any stimulus which requires a reaction from the executive or a task. Examples of an event would include a timer interrupt, an alarm condition, or a keyboard input. Events may originate externally to the processor or internally from within the software. An executive which responds to these events as the stimuli for allocating resources is said to be event driven. If response time to any event occurs within a period of time which can be Copyright (c) 1989 Page 2 - 1 Motorola, Inc. MCX11 - MicroController eXecutive for the 68HC11 accurately defined and guaranteed, the executive can be said to be deterministic. By these definitions, MCX11 is a deterministic, event driven, multitasking, real-time executive. 2.2 TASKS In MCX11, a task is a program module which exists to perform a defined function or set of functions. A task is independent of other tasks but may establish relationships with other tasks. These relationships may exist in the form of data structures, input/output, or other constructs. A task executes when the MCX11 task dispatcher determines that the resources required by the task are available. Once it begins running, the task has control of all of the system's resources. But as there are other tasks in the system, a running task cannot be allowed to control all of the resources all of the time. Thus, MCX11 employs the concept of multitasking. 2.3 MULTITASKING Multitasking appears to give the computer the apparent ability to be performing multiple operations concurrently. Obviously, the computer cannot be doing two or more things at once as it is a sequential machine. However, with the functions of the system segregated into different tasks, the effect of concurrency can be achieved. In multitasking, each task once given operating control either runs to completion, or to a point where it must wait for an event to occur, for a needed resource to become available, or until it is interrupted. Efficient use of the computer can be obtained by using the time a task might otherwise wait for an event to occur to run another task. This switching from one task to another forms the basis of multitasking. The result is the appearance of several tasks being executed simultaneously. 2.4 PRIORITY AND SCHEDULING When several tasks can be competing for the resource of execution time, the problem is to determine how to grant it so that each gets access to the system in time to perform its function. The solution is to assign a priority to each task indicative of its relative importance to other tasks in the system. MCX11 uses a fixed priority scheme in which up to 126 tasks may be defined. Tasks which have a need to Copyright (c) 1989 Page 2 - 2 Motorola, Inc. MCX11 - MicroController eXecutive for the 68HC11 respond rapidly to events are assigned high priorities. Those which perform functions that are not time critical are assigned lower priorities. It is the priority of each task that determines where it is to run in the hierarchy of tasks. When a task may run depends on what is happening to the tasks of higher priority. Tasks are granted execution time in a strict descending order of priority. While executing, a task may be interrupted by an event which causes a task of higher priority to be runnable. The lower priority task is placed into a temporary state of suspension and execution control is granted to the higher priority task. Eventually, control is returned to the interrupted task and it is resumed at the point of its interruption. Thus, when any task is given execution control, no higher priority task can be in a runnable state. This is a most important point to remember. When all tasks are in an unrunnable state, control is granted to the null task. The null task is a do-nothing task which allows the system to run in an idle mode while waiting for an event which will resume or start a higher priority task. The null task is always the lowest priority task in the system and is always runnable. It is an integral part of the kernel. 2.5 INTERTASK COMMUNICATION AND SYNCHRONIZATION MCX11 provides an environment whereby two or more tasks can communicate with one another. The three major ways in which this is done are through the mechanisms of semaphore signalling, message transmission, and queues. A semaphore is actually a flag which contains information about the state of the associated event. Any event which is used for task synchronization will be associated with a particular semaphore. The occurrence of a specific event can be signalled by manipulating the semaphore associated with that event. Message transmission involves the logical transfer of data packets from one task to another. These data packets are called "messages". Messages are sent from one task and placed in the "mailbox" of the receiving task in the order of the priorities of the senders. Messages may be of any format recognizable by the sender and receiver and data may be passed in either direction. That is, it is possible for two tasks to alternate the roles of sender and receiver. A third technique whereby two tasks can communicate and synchronize is via a first-in-first-out (FIFO) queueing mechanism. The queueing techniques used by MCX11 involve Copyright (c) 1989 Page 2 - 3 Motorola, Inc. MCX11 - MicroController eXecutive for the 68HC11 the physical transfer (copying) of data packets from one task to another. Task synchronization due to queueing operations is automatically performed by MCX11. 2.6 TIME BASED FUNCTIONS An MCX11 system is configured with an interval timer using the Real Time Interrupt (RTI) clock as a peripheral device. The timer permits task control on a timed basis. A generalized scheme using one-shot and cyclic timers in conjunction with semaphores is provided. MCX11 efficiently manages multiple timers using an ordered linked list of pending timer events. A timer for an event is inserted into the linked list in accordance with its duration. A differential technique is employed so that the timer with the shortest time to expiration is at the head of the list. Timed events may even be co-terminous. Directives for scheduling and cancelling timed events are an integral part of the executive. 2.7 INTERRUPT SERVICE Support for a generalized interrupt service scheme is provided within the MCX11 kernel. The Interrupt Service Routine (ISR) code, however, is provided by the User. The rules for writing interrupt service routines that function with MCX11 are quite simple and require only minor housekeeping chores. MCX11 also provides the common Interrupt Service Exit function. This logic is used by all interrupts to determine if a context switch is in order as the result of the interrupt. If no task switch is required, the interrupted task is resumed at the point of the interrupt. If, however, a task switch is in order, the interrupted task's context is saved, the new task's context is loaded and control is given to it. Copyright (c) 1989 Page 2 - 4 Motorola, Inc. MCX11 - MicroController eXecutive for the 68HC11 SECTION 3 MCX11 CONTROL & DATA STRUCTURES In order to understand how MCX11 works and how to build real-time application systems around it, it is necessary to understand how its various control and data structures work. This section describes these structures and their interrelationships. The descriptions will include: - tasks - semaphores - messages and mailboxes - queues - timers The MCX11 executive services which deal with these classes of control and data structures will be presented in a subsequent section. 3.1 TASKS In a real-time application using MCX11, the functions of the system are assigned to various tasks. MCX11 supports up to 126 tasks in a single system. The nature of each task is, of course, application dependent and left to the imagination of the system designer. However, there are attributes which all tasks share. These include: - a task identifier - a priority - a task state table - a stack - a mailbox - an entry point 3.1.1 Task Identifier & Priority Each task is identified by a numerical identifier which is a number from 1 - 126. The task identifier, or number, serves as a reference during executive operations. Task 1 is executed before task 2 which is executed prior to task 3 and so on. Thus, the task number is inversely related to the task's execution priority. The lower the task number, the higher the priority. MCX11 uses this fixed task numbering scheme because it is low in overhead and quite adequate for most applications. The task number permits a direct access to the task's state table without the need for linked lists or other commonly used technique. Copyright (c) 1989 Page 3 - 1 Motorola, Inc. MCX11 - MicroController eXecutive for the 68HC11 3.1.2 Task State Table The state table is commonly referred to as a Task Control Block (TCB). A TCB in MCX11 is contained in two separate sections in order to minimize the use of system RAM. Only those data about the execution state of the task are kept in RAM. Static information about the task is kept in ROM. Both sets of this TCB information are kept in arrays which allow direct access to the data based on the task number. This makes for very quick access without the commonly wasted time of searching a linked list. The RAM portion of the TCB contains only volatile data about the task and includes the following: - the execution state - the stack pointer - the first link in the task's mailbox Whenever the MCX11 dispatcher is looking for a task to execute, it examines the execution state variable to see if the task is runnable or not. The execution state is contained in a single byte and a value of $00 indicates that the task is runnable. Any other content in the task state and the task is blocked from running. The stack pointer contains the address of the current top- of-stack. The first link in the task's mailbox contains the address of the highest priority message waiting to be received by the task. If no message is waiting, the pointer contains zero. The ROM part of the TCB contains: - the initial execution state - the entry point - the base address of the stack - the address of the RAM part of the TCB The initial execution state is specified by the system designer at the time of system configuration. This becomes the initial content of the execution state. By specifying a value of zero, the task will be executed immediately after initialization in accordance with its priority. Specification of a non-zero value will prevent the task from automatically starting execution after initialization. The entry point is the address where the task is to begin execution. Copyright (c) 1989 Page 3 - 2 Motorola, Inc. MCX11 - MicroController eXecutive for the 68HC11 The base address of the stack identifies that location in RAM where the task's stack begins. The address of the RAM part of the TCB table is included for completeness and is sometimes used to save time in setting up the address of the RAM TCB area. 3.1.3 Stack Each task must have a stack on which the context of the task is saved during those periods when the task is not actually executing. The base address of the stack is stored in the ROM portion of the TCB. The stack extends from the base address downward in memory, i.e. towards address $0000, for a number of bytes specified by the given stack size for the task. The size of each task's stack is dependent on many things such as the maximum depth of nested subroutines calls, the maximum amount of working space needed for temporary variables, and the size of any stack frames used by the task. At minimum, the size of the stack must allow for the storage of a complete context which requires nine (9) bytes. If XIRQ is to be used in the design, an extra nine (9) bytes must be allocated to each task's stack due to the possibility of stacking an IRQ followed by an XIRQ. This is possible because the XIRQ cannot be masked and can interrupt an IRQ interrupt service routine at any point. In addition to the stacks needed by the tasks, there is also the need for a stack for MCX11. This system stack must have sufficient space to handle the maximum number of interrupts possible at any given time, less one interrupt. Each interrupt requires nine bytes. MCX11 functions have a worst case stack requirement of seven (7) bytes not including those bytes required for the system stack. The sum of all of the stack requirements should not be allowed to exceed available RAM or there will be trouble. 3.2 SEMAPHORES Semaphores (event flags) are used to synchronize two tasks to the occurrence of an asynchronous event. One task may need to wait for the other to reach a certain point before it can continue. Input/output operations are an example of this type of synchronization. For instance, when an input from an external device is desired by a task, it must wait for the input event to occur. When the input operation is completed, the device driver signals that the event has occurred which indicates the data is available. The signalling process causes the waiting task to resume, Copyright (c) 1989 Page 3 - 3 Motorola, Inc. MCX11 - MicroController eXecutive for the 68HC11 presumably to process the input data. The synchronization of the task with the event is done with the use of a semaphore. There are several forms that a semaphore may take in the design of a real-time kernel. MCX11 uses a basic semaphore construct that is known to handle most events and is low in overhead. A semaphore is referenced by a numerical identifier limited to a value from 1-255. A semaphore identifier of zero has a special meaning. There are three different classes of semaphores used by MCX11 as follows: - Named semaphores - Task semaphores - Queue semaphores Named semaphores are those normally referenced by the user in the application code. Task and queue semaphores are used by MCX11 internally for the purpose of orthogonality with the semaphore service functions. Task semaphores are always referenced by the identifier of zero (0) which is translated by MCX11 into the proper number for the task semaphore. Queue semaphores should never be referenced by the user lest undesirable results should occur. An MCX11 semaphore is a single byte (8 bits) which contains a value representing one of the three possible states in which it can exist. These states are: - PENDING - WAITING - DONE A PENDING state indicates that the event associated with the semaphore has not yet occurred and is therefore pending. The WAITING state shows that not only has the event not yet occurred but a task is waiting for it to happen. The DONE state tells that the event has occurred. MCX11 semaphores have a very strict state transition protocol which is automatically managed by MCX11. The permissible state changes are shown below in Figure 3-1. +------- PENDING------- + | ^ | | |------ | | v | v DONE<--------------- WAITING Figure 3.1 Copyright (c) 1989 Page 3 - 4 Motorola, Inc. MCX11 - MicroController eXecutive for the 68HC11 If a task attempts to wait on a semaphore which is in the DONE state, the wait does not occur and the task is immediately resumed (since the desired event has already happened) and the semaphore state is changed back to PENDING. If a task attempts to wait on a semaphore in the PENDING state, the state of the semaphore is changed to WAITING and the task's execution is suspended until the event occurs. An attempt to wait on a semaphore which is already in the WAITING state can cause unpredictable results and should not be attempted. It should be considered a design error. If an attempt is made to signal a semaphore which is in a PENDING state, the semaphore is placed into the DONE state. As this action does not concern any task, no further action is taken. However, if a signal is sent to a semaphore in the WAITING state, the semaphore transitions to a DONE state and the task waiting on the event is made runnable again. The semaphore is then automatically set back to a PENDING state by MCX11. 3.3 MESSAGES AND MAILBOXES Messages are one of the means by which data is transmitted from a sender to a receiver task. Every task running under MCX11 is capable of being both a message sender and receiver. Each task is assigned a "mailbox" into which are placed all messages sent to it. When a sender task sends a message, it is put into the mailbox of the receiver task. If two or more tasks are sending messages to a single receiver, their messages are put into the mailbox in strict sequence of their priorities, highest priority first. The content of the message is not actually moved from the sender to the receiver when it is sent. Instead, messages are linked into a threaded list according to the priorities of their senders. When the receiver requests receipt of the next message, its address is returned. This technique guarantees the receiver that the highest priority message is received first. It is possible, however, to temporarily suspend this order by requesting only those messages from a particular sender. This is useful when it is desirable not to mix messages on a shared resource, for example, a printer. The mailbox of a task is a threaded (linked) list of all messages sent to but not yet received by that task. The mailbox consists of a pointer (link) to the message sent by the highest priority sender. That message is linked to the next highest priority message and it in turn is linked to the third highest priority message, and so on until the end Copyright (c) 1989 Page 3 - 5 Motorola, Inc. MCX11 - MicroController eXecutive for the 68HC11 of the thread. The last message in a task's mailbox will contain a NULL (value of zero) link. Messages may be sent with or without waiting for a response from the receiver. When a task wants to send a message and wait until the receiver has processed the message, it will include a semaphore number as one of the arguments in the MCX11 send message directive. That semaphore is then associated with the event of completed processing of the message. Once the message is linked into the mailbox of the receiver task, the sender is put into a WAIT state on the message processing complete event. The receiver removes the message from the mailbox and processes it according to the content of the message body. When the receiver no longer needs the data in the body of the message, it signals the semaphore associated with the completion of message processing making the sender task runnable again and, thereby, allowing it to continue its operation. It should be remembered that the body of the message can also be used by the receiver to send a response back to the sender. This is a very efficient way of passing data bi- directionally between two tasks with little overhead. If the sending task does not wish to wait on the action of the receiver or if there is no response required, a message can be sent without waiting for completion of processing. This makes it possible for a sender to send multiple messages to a receiver, or, simply do something else while the receiver processes the message. However, even though a message is sent without waiting for the response, it is still possible at a later time for the sender to wait for the completion of processing event. If the receiver has completed the use of the message by the time the sender waits for that event, the sending task continues operation without interruption. If the receiver has not yet completed processing of the message, the sender must wait for the event to occur. When it does occur, the sender's operation is resumed. A message is a four-element structure set up in a contiguous area of RAM. The first three elements of the message are used by MCX11 to control the transmission. The user need only set up the content of the message body. The format of a MCX11 message is as follows: - Mailbox link (supplied by MCX11) - Task number of sender (supplied by MCX11) Copyright (c) 1989 Page 3 - 6 Motorola, Inc. MCX11 - MicroController eXecutive for the 68HC11 - Message semaphore number (optional) - Message body (supplied by User) The first element in the message provides the link to the next message, if any, in the mailbox. The second element is the task number of the sender. This field is included so that the receiver task can selectively receive only those messages from a specified task. The third element of the message contains an optional message semaphore number. Typically, when a sending task wants to send a message and wait until the receiver has processed the message, it will include a non-zero semaphore number as one of the calling arguments for the MCX11 directive. The sending task will then suspend execution until the receiver task completes the processing of the message content. When the receiver no longer needs the data in the body of the message, it signals the message semaphore to notify the sender that it may continue processing. . The last element, the body, of the message may contain whatever data is required by the receiver task and in whatever format. It may be fixed or variable in length as required. 3.4 QUEUES MCX11 supports first-in-first-out (FIFO) queues having single or multiple bytes per entry. The queues can support multiple producer/single consumer service but are usually employed in only a single producer/single consumer mode. Queues are referenced via a numerical identifier which is unique to each queue. Queue numbers are assigned in the system generation procedure. MCX11 queues differ from messages in that the actual entry data rather than its address is entered into or removed from the queue. Another difference is that the queue entries represent the chronological order of processing. Also, the priorities of the sender or receiver are not considered as with messages. Queues are usually used to handle data such as character stream input/output or other data buffering. Queues require more overhead as they move the data from the source to the queue or vice versa but they also provide automatic synchronization between the queue's producer and its consumer. It is recommended that they not be used where high throughput rates are required. A queue consists of two parts: the queue header and the queue body. The queue header contains that information needed by the MCX11 internal routines to enable them to move Copyright (c) 1989 Page 3 - 7 Motorola, Inc. MCX11 - MicroController eXecutive for the 68HC11 data into and out of the queues properly. The organization of the queue header consists of the following elements: - Width, queue entry size (in bytes) - Depth, maximum length (in entries) - Current size of the queue (in entries) - Put index (in bytes; MCX11 internal use) - Address of queue body - Queue not empty semaphore number - Active semaphore number The first three elements are defined during the system generation process. The Current Size and the Put Index fields are initialized to zero (empty). Both of these fields are maintained internally by the MCX11 queue handling routines. They should never be manipulated by a user task. Semaphores are used to signal internal events such as queue- not- empty or queue-not-full. The semaphores for these events are allocated as a consecutive pair during the system initialization process. The queue-not-full semaphore number is equal to the number of the queue-not-empty semaphore plus one. A queue can have a semaphore active only for those two mutually exclusive events. Consequently only the queue-not- empty semaphore number requires definition in the queue header. The active semaphore number field in the queue header is used to contain the number of the semaphore associated with one of the two possible events. If the queue is empty and a task attempts to remove an entry, the active semaphore field in the queue header is set to contain the number of the queue-not-empty semaphore. Conversely, if a task attempts to put an entry into a queue which is already full, the active semaphore field is set to contain the number of the queue- not-full semaphore. By use of these semaphores, it is possible to send data between tasks asynchronously but without the worry of over- running the queue. 3.5 TIMERS In the descriptions of time based functions to follow in the succeeding sections, it will be important to understand the conventions used by MCX11. All timers in MCX11 are 16-bits long. The two time units used internally by MCX11 are ticks and tocks. A tick gives the amount of time between clock generated system interrupts, or equivalently, the period between clock interrupt service requests. Copyright (c) 1989 Page 3 - 8 Motorola, Inc. MCX11 - MicroController eXecutive for the 68HC11 A tock is an integral number of ticks and is the time unit used by all of the time dependent functions in MCX11. The tick frequency of the RTI clock is set during the system initialization process but was determined, as was the number of ticks per tock, by the system designer during MCX11 system configuration. As an example, suppose the hardware clock is configured to cause interrupts every 25 milliseconds and that 0.25 seconds (250 milliseconds) is the time most convenient interval for timing events in the application. In order to determine the number of ticks per tock, simply divide the desired duration of the tock (250 ms) by the duration of a tick (25 ms). Thus, in this case, 1 tock = 10 ticks. Timer values are defined as the number of clock tocks required to form the needed amount of time. If a timer value is positive, it is used only once (one-shot timer). However, if the value is negative, it is used as a cyclic timer having a period equal to the 2's complement value. For example, if a clock tock equals 250 milliseconds, a timer value of 20 would produce a once-only period of 5 seconds. If the timer were -20, the period is still 5 seconds but the timer is cyclic. All timed event operations and data structures are handled by MCX11. A task should not attempt to manipulate any of the timer related control or data structures. Copyright (c) 1989 Page 3 - 9 Motorola, Inc. MCX11 - MicroController eXecutive for the 68HC11 SECTION 4 EXECUTIVE SERVICE REQUESTS (ESRS) 4.1 PURPOSE Executive Service Requests (ESRs) are the functions that a real-time kernel performs and serve to give it its flavor. This section will describe the classes of the MCX11 directives. The directives are divided into five classes as follows: - Semaphores - Messages - Queues - Task control - Time based A brief functional description of each ESR within the class is given along with their respective calling arguments. The calling arguments needed for each ESR appear below in parentheses. Where two or more arguments are required, they are separated by commas. These are not the actual calling sequences but are for purposes of explanation only. Actual calling sequences are given in Section 5. In the paragraphs below, the ESR function name is enclosed within two periods. This will be the convention used for MCX11 to denote an ESR. The following abbreviations are used below for the arguments: - SEMA Semaphore number - TASK Task number - QUEUE Queue number - TOCK Timer value - PNTR Address pointer or data value - MSG Message address 4.2 SEMAPHORE ESRS A complete set of directives for managing semaphores is provided by MCX11. .wait. (SEMA) wait for a specific sema to be signalled .signal. (SEMA) signal semaphore .pend. (SEMA) reset semaphore state to PENDing Copyright (c) 1989 Page 4 - 1 Motorola, Inc. MCX11 - MicroController eXecutive for the 68HC11 4.3 MESSAGE ESRS The message directives provide a means of transferring large amounts of data between tasks with minimal overhead since only pointers (addresses) are passed. Message receipt acknowledgement is also provided for task synchronization. The format of a MCX11 message and function prototypes are noted. .send. (MSG,TASK) send message to a task .sendw. (MSG,TASK,SEMA) send & wait acknowledgement .receive. (TASK) receive message 4.4 QUEUE ESRS Queue directives provide a means of passing multiple byte packets of information between tasks with automatic task synchronization of queue full and empty conditions. .dequeue. (QUEUE,PNTR) remove entry from queue .enqueue. (QUEUE,PNTR) insert entry into queue 4.5 TASK CONTROL ESRS The task control directives provided by MCX11 allow for low level complete control of tasks and their respective interactions. .resume. (TASK) resume specific task .suspend. (TASK) suspend specific task .terminate. (TASK) terminate specific task .execute. (TASK) execute task from starting point 4.6 TIME BASED ESRS The time based directives provide for the synchronization of tasks with timed events. In addition, a generalized time based semaphore scheme for more advanced time based requirements is provided. .delay. (TASK,SEMA,TOCK) delay task .timer. (TASK,SEMA,TOCK) schedule timer for task/sema .purge. (TASK,SEMA,PNTR) purge timer for task/sema Copyright (c) 1989 Page 4 - 2 Motorola, Inc. MCX11 - MicroController eXecutive for the 68HC11 SECTION 5 ALPHABETICAL LISTING OF ESRs In the pages to follow, each ESR will be shown in alphabetical order. Each ESR will be given in a standard format: Name - brief functional description CLASS One of the five ESR classes of which it is a member. SYNOPSIS The prototype declaration including argument typing. The decimal value of the function code is enclosed in brackets [xx]. DESCRIPTION A description of what the ESR does, data types used, etc. CALLING SEQUENCE The formal AS11 calling sequence for the ESR. The following notations will be used: ACCA = Accumulator A, 8 bits ACCB = Accumulator B, 8 bits IX = Index register X, 16 bits RETURN VALUE A description of the return values from the ESR. EXAMPLE One or more typical ESR uses. The examples assume the syntax of AS11 cross assembler. SEE ALSO List of related ESRs that could be examined in conjunction with the current ESR. Copyright (c) 1989 Page 5 - 1 Motorola, Inc. MCX11 - MicroController eXecutive for the 68HC11 5.1 .delay. - DELAY A TASK FOR A PERIOD OF TIME CLASS Timer SYNOPSIS .delay. (TASK,SEMA,TOCK) [13] DESCRIPTION The delay directive places the specified task into a Wait state for the period defined by the TOCK value. TASK is a task number in the range of 1-126. Or, TASK may be 0 if the reference is to SELF. Thus, a task need not know its own task number to schedule a delay for itself. SEMA is the semaphore number associated with the expiration of the timer. It may be a named semaphore if its number > 0. Or, it may be the task semaphore of the calling task if it is specified as 0. TOCK is a 16-bit timer. If TOCK is > 0, the timer is a one-shot. If TOCK < 0, the timer is cyclic. Caution should be exercised when scheduling delays for other tasks. CALLING SEQUENCE ACCA = Task number (0 if SELF) ACCB = Semaphore number (0 if Task's semaphore) IX = Number of clock tocks to delay swi FCB .delay. return RETURN VALUE None. Registers unchanged. EXAMPLE Assume that the RTI is used as the time base using a 2**23 crystal and the clock TICK is defined to be 15.625 msec. Further assume that there are 8 TICKS per TOCK so that a TOCK is 125 msec. If a 2.5 sec delay is desired for the calling task using a named semaphore, TIMEOUT, the request would appear as: Copyright (c) 1989 Page 5 - 2 Motorola, Inc. MCX11 - MicroController eXecutive for the 68HC11 TOCK equ 8 TOCKTIME equ 1000/8 TOCKTIME = 125 msec TIMEOUT equ 3 Named semaphore #3 . : clra Task is self (ACCA=0) ldab #TIMEOUT Semaphore = TIMEOUT ldx #2500/TOCKTIME Timer = 20 TOCKS swi FCB .delay. . Point of continuation The requesting task would be put into a WAIT state on semaphore TIMEOUT while the 2.5 sec clock runs down. When it expires, TIMEOUT would be signalled and the task would continue at the instruction following the FCB declaration. SEE ALSO .timer., .purge. Copyright (c) 1989 Page 5 - 3 Motorola, Inc. MCX11 - MicroController eXecutive for the 68HC11 5.2 .dequeue. - GET AN ENTRY FROM A FIFO QUEUE CLASS Queue SYNOPSIS .dequeue. (QUEUE,PNTR) [7] DESCRIPTION Dequeue is used to get an entry from a FIFO queue. The number of bytes in the entry is determined by the Width entry in the Queue Header. If the queue is empty, the calling task is placed into an EVENT WAIT state on the queue-not-empty semaphore. If the queue is not empty, the oldest entry in the queue is removed and returned to the calling task. If the size of the queue entry is greater than two bytes, the returned data is in the RAM area beginning at the address specified by PNTR. If the queue entry is one or two bytes, PNTR is ignored and the entry is returned in one or two registers. CALLING SEQUENCE ACCA= Queue number IX = Destination address of queue entry if size > 2 swi FCB .dequeue. return RETURN VALUE If queue entry size = 1, ACCA= queue entry If queue entry size = 2, ACCA = byte 1 of queue entry, and ACCB = byte 2 of queue entry Other registers unchanged EXAMPLE Example #1: There exists a FIFO queue, DBLQ, containing two character entries. The queue currently contains four entries as follows: ab DE Mc xY Copyright (c) 1989 Page 5 - 4 Motorola, Inc. MCX11 - MicroController eXecutive for the 68HC11 A task is programmed to remove the oldest entry in the queue and return it for subsequent processing. The entry is dequeued by: DBLQ equ 4 Queue #4 . : ldaa #DBLQ ACCA = queue # 4 swi FCB .dequeue. . Point of continuation At the instruction following the FCB declaration, ACCA and ACCB will contain the two characters, ab. The queue will now contain the three entries: DE Mc xY Example #2: Another queue exists, QUADQ, which contains four byte entries and is currently empty. The request to get an entry from the queue would appear as: QUADQ equ 5 Queue #5 . : ldaa #QUADQ ACCA = queue # 5 ldx #destn IX = destination address swi FCB .dequeue. . Point of continuation : destn ZMB 4 Where the entry is placed : Since there are no entries available to dequeue, MCX11 puts the task into a WAIT state on the NOT_EMPTY semaphore associated with queue #5. The task will remain in that state until another task puts a 4-byte entry into QUADQ. When that happens, the waiting task is put into the RUN state. The entry is removed and is stored at the specified destination address, destn, and the task continues at the instruction following the FCB declaration. SEE ALSO .enqueue. Copyright (c) 1989 Page 5 - 5 Motorola, Inc. MCX11 - MicroController eXecutive for the 68HC11 5.3 .enqueue. - INSERT DATA INTO FIFO QUEUE CLASS Queue SYNOPSIS .enqueue. (QUEUE,PNTR) [8] DESCRIPTION Enqueue inserts an entry into a FIFO queue. If the queue is full, the calling task is set to a WAIT state on the queue NOT FULL condition. When the queue is not full, the entry is inserted into the queue. If the width of the queue entry is greater than 2 bytes, the data to be put into the queue is found at the address specified by the contents of register IX. If the width is 1 byte, the actual data to be enqueued is found in bits 8-15 of IX. If the width is equal to 2 bytes, then byte 1 of the entry is found in bits 8-15 of IX, and byte 2 is in bits 0-7 of IX. CALLING SEQUENCE ACCA= Queue number IX = Source address of entry to be enqueued if size > 2 Or, IX8-15 = byte to be enqueued if size = 1 Or, IX8-15 = byte 1 and IX0-7 = byte 2 if size = 2 swi FCB .enqueue. return RETURN VALUE None. Registers unchanged. EXAMPLE Example #1: Using the 2-byte queue, DBLQ, defined above, a task wants to put an entry into it. Assume that the queue contents are the three entries: DE Mc xY The queue entry size is two bytes which permits the entry to be passed to the queue routine in ACCA and Copyright (c) 1989 Page 5 - 6 Motorola, Inc. MCX11 - MicroController eXecutive for the 68HC11 ACCB. The request to put a two-byte entry, LW, into DBLQ is: ldaa #DBLQ ACCA = queue # 4 ldx #"LW" IX = "LW" swi FCB .enqueue. . Point of continuation Since the queue has content, no task is waiting for an entry to dequeue; therefore, the entry is put into the queue following the "xY" entry and the task continues at the instruction following the FCB. The new content of DBLQ is: DE Mc xY LW Example #2: Using the queue, QUADQ, previously defined but now containing three entries: abcd EFGH iJkL A request to put a new entry into the queue, MnOp, is given by: ldaa #QUADQ ACCA = queue # 5 ldx #srcadr IX = source address swi FCB .enqueue. . Point of continuation : srcadr FCC "MnOp" : Since the entry size is four bytes, IX must contain the address of the entry to be enqueued. After continuing at the instruction following the FCB declaration, QUADQ contains: abcd EFGH IjKl MnOp Copyright (c) 1989 Page 5 - 7 Motorola, Inc. MCX11 - MicroController eXecutive for the 68HC11 SEE ALSO .dequeue. Copyright (c) 1989 Page 5 - 8 Motorola, Inc. MCX11 - MicroController eXecutive for the 68HC11 5.4 .execute. - EXECUTE A TASK CLASS Task control SYNOPSIS .execute. (TASK) [12] DESCRIPTION The execute task directive is used to start or restart a task from its beginning. The program counter (PC) and stack pointer (SP) are initialized to their starting values and the specified task is made runnable. If the new task is of higher priority than the current task, a context switch is performed and the new task runs, else control is returned to the caller. The task being started cannot be SELF (task number argument = 0). CALLING SEQUENCE ACCA= Task number swi FCB .execute. return RETURN VALUE None. Registers unchanged. EXAMPLE The current task wishes to cause task number 6 to begin execution at its starting point. Task number 6 is currently IDLE. The request appears as: TASK6 equ 6 Task #6 . : ldaa #TASK6 ACCA = task # 6 swi FCB .execute. . Point of continuation If TASK6 is of higher priority, then the current task is interrupted, but still runnable, and TASK6 is made the current task. The task which scheduled TASK6 is not given control again until all other higher priority tasks, including TASK6, are not runnable. When it does continue, it will do so following the FCB declaration. Copyright (c) 1989 Page 5 - 9 Motorola, Inc. MCX11 - MicroController eXecutive for the 68HC11 If TASK6 is of lower priority that the current task, no context switch occurs and the current task continues at the instruction following the FCB declaration. SEE ALSO .terminate. Copyright (c) 1989 Page 5 - 10 Motorola, Inc. MCX11 - MicroController eXecutive for the 68HC11 5.5 .pend. - FORCE A SEMAPHORE TO A PENDING STATE CLASS Semaphore SYNOPSIS .pend. (SEMA) [3] DESCRIPTION To understand the use of the pend directive, recall that the WAIT directive will return control to the calling task immediately if the task requests to wait on a semaphore found to already be in a DONE state. In this sense, semaphores keep a history of their associated events, even if no task is waiting at the time of the signal. If a task needs to go unconditionally into a Event Wait state on a semaphore, a call should first be made to PEND followed closely by a WAIT directive. CALLING SEQUENCE ACCB = Semaphore number swi FCB .pend. return RETURN VALUE None. Registers unchanged. EXAMPLE The current task is going to make use of a semaphore and wants to be certain of its state prior to use. It forces the semaphore into a PENDing condition by the following request: NEWSEMA equ 14 Semaphore #14 . : ldab #NEWSEMA ACCB = semaphore # 14 swi FCB .pend. . Point of continuation SEE ALSO .wait. Copyright (c) 1989 Page 5 - 11 Motorola, Inc. MCX11 - MicroController eXecutive for the 68HC11 5.6 .purge. - PURGE A TASK'S TIMERS CLASS Timer SYNOPSIS .purge. (TASK,SEMA,PNTR) [15] DESCRIPTION The purge timer directive is used to remove all active timers for the specified task or semaphore number. A specification of a zero semaphore number will purge all semaphore timers for the given task. When the purge is completed, the current task is resumed. CALLING SEQUENCE ACCA = Task number (0 if SELF) ACCB = Semaphore number (0 if task semaphore) IX0-7 = Switch: 0 = purge all timers for given task >0 = purge time for given task & sema swi FCB .purge. return RETURN VALUE None. Registers unchanged. EXAMPLE The most common use of this ESR is for the current task to get rid of one or all of its active timers. Since timers are associated with semaphores, the combination of task number and semaphore number is sufficient to identify a timer uniquely. The request to purge the current task's timer associated with the task semaphore appears as: clra ACCA = 0 means SELF clrb ACCB = 0 means task sema ldx #1 Only purge one timer swi FCB .purge. . Point of continuation Copyright (c) 1989 Page 5 - 12 Motorola, Inc. MCX11 - MicroController eXecutive for the 68HC11 If all timers for a task are to be purged, the request appears as: clra ACCA = 0 means SELF ldx #0 Purge all timers swi FCB .purge. . Point of continuation SEE ALSO .timer., .terminate. Copyright (c) 1989 Page 5 - 13 Motorola, Inc. MCX11 - MicroController eXecutive for the 68HC11 5.7 .receive. - RECEIVE A MESSAGE CLASS Message SYNOPSIS .receive. (TASK) [6] DESCRIPTION The receive message directive is used to fetch messages from a calling task's mailbox. Because the messages are placed in the mailbox in the order of the sender's priority, they are processed in the same sequence. If the receiving task specifies a non-zero task number, the first message from that task will be returned. With a zero task number, the first message in the mailbox is returned. If there are no messages in the mailbox, the task's context is saved, and the task is put into a Message WAIT state. When the next message is sent to the task it will be resumed and the attempt to receive a message will be reissued. CALLING SEQUENCE ACCA = Task number if messages from specific task are wanted. Or, ACCA = 0 if highest priority message is wanted. swi FCB .receive. return RETURN VALUE Register IX contains the address of the received message. Other registers unchanged. EXAMPLE Example #1: The current task is a server which operates only when another task sends it a message instructing it to perform some function. The server task receives messages by making a request such as: clra 0 = next message swi FCB .receive. . Point of continuation Copyright (c) 1989 Page 5 - 14 Motorola, Inc. MCX11 - MicroController eXecutive for the 68HC11 The server task will not continue unless there is a message waiting in its mailbox. It will be put into a WAIT state until such time as another task sends it a message. No waiting occurs if a message is already in the mailbox at the time of the request. When the message is available, its address is returned in the IX register. Example #2: If the server wants to receive only those messages from a specific task, and the task's number is to be found in a variable named 'attach', the request is: ldaa attach variable contains task # swi FCB .receive. . Point of continuation : attach ZMB 1 The server task will now only listen for messages from the task whose number is in the variable 'attach'. All other messages will remain in the mailbox of the server. The server will continue only when it has received a message from the specific task. SEE ALSO .send., .sendw. Copyright (c) 1989 Page 5 - 15 Motorola, Inc. MCX11 - MicroController eXecutive for the 68HC11 5.8 .resume. - RESUME A TASK CLASS Task control SYNOPSIS .resume. (TASK) [9] DESCRIPTION The resume directive clears the suspended state of a task caused by a suspend directive. If the resumed task is made runnable and is higher priority, a task switch is performed. Otherwise, control is returned to the calling task. CALLING SEQUENCE ACCA = Task number swi FCB .resume. return RETURN VALUE None. Registers unchanged. EXAMPLE A task which has been previously suspended may be resumed from the point of suspension only by a .resume. request from another task. The request appears as: TASK6 equ 6 Task #6 . : ldaa #TASK6 ACCA = task # 6 swi FCB .resume. . Point of continuation Upon resuming the given task, a context switch may occur if the resumed task is of higher priority than the task making the request. If not, no context switch occurs. The requesting task continues at the instruction following the FCB. SEE ALSO .suspend. Copyright (c) 1989 Page 5 - 16 Motorola, Inc. MCX11 - MicroController eXecutive for the 68HC11 5.9 .send. - SEND A MESSAGE TO A TASK CLASS Message SYNOPSIS .send. (MSG,TASK) [4] DESCRIPTION The send message directive inserts a message into the target task's mailbox in the order of the sending task's priority. If the receiving task is waiting to receive a message and is of higher priority than the sender, a task switch is performed. If the receiving task is of lower priority and waiting on a message, then the receiving task is marked runnable but control is returned on a message, the message is simply inserted to his mailbox for later receipt. CALLING SEQUENCE ACCA = Task number of the receiver ACCB = Semaphore number (task semaphore number = 0) IX = Message address swi FCB .send. return RETURN VALUE None. ACCB will contain the number of the task semaphore if ACCB was = 0 at time of swi. All other registers unchanged. EXAMPLE A task wishing to send a message to a receiver task can do so by the following code: Copyright (c) 1989 Page 5 - 17 Motorola, Inc. MCX11 - MicroController eXecutive for the 68HC11 RCVRTSK equ 12 Receiving task = task #12 MSGSEMA equ 7 Use sema #7 for Message . : ldaa #RCVRTSK ACCA = receiver task # ldab #MSGSEMA ACCB = Message semaphore ldx #msgadr IX = Address of message swi FCB .send. . Point of continuation : msgadr ZMB 4 Message overhead FCC "THIS IS THE MESSAGE BODY" The message located at 'msgadr' will be put into the mailbox of RCVRTSK. Processing in the sending task will resume at the instruction following the FCB declaration. SEE ALSO .receive., .sendw. Copyright (c) 1989 Page 5 - 18 Motorola, Inc. MCX11 - MicroController eXecutive for the 68HC11 5.10 .sendw. - SEND A MESSAGE AND WAIT CLASS Message SYNOPSIS .sendw. (MSG,TASK,SEMA) [5] DESCRIPTION The send message and wait directive is similar to the send message directive described above, except that the sending task is always put into a Event Wait state on the message semaphore. This allows the receiving task to signal the sender when the message processing is complete and/or that there is data returned in the message area. CALLING SEQUENCE ACCA = Task number of the receiver ACCB = Semaphore number (task semaphore number = 0) IX = Message address swi FCB .sendw. return RETURN VALUE None. ACCB will contain the number of the task semaphore if ACCB was = 0 at time of swi. All other registers unchanged. EXAMPLE The example is the same as for .send. except that the ESR request will be .sendw. Another difference is the WAIT state into which the sending task is placed until the receiving task signals the message semaphore. Until that signal is received, the sending task proceeds no further. When the receiver signals the message semaphore, the sending task will continue at the instruction following the FCB. SEE ALSO .send., .receive. Copyright (c) 1989 Page 5 - 19 Motorola, Inc. MCX11 - MicroController eXecutive for the 68HC11 5.11 .signal. - SIGNAL A SEMAPHORE CLASS Semaphore SYNOPSIS .signal. (SEMA) [2] DESCRIPTION The signal semaphore directive sets the state of a specified semaphore to DONE. If the semaphore is currently in a WAIT state, the Event Wait state of the waiting task is removed, and the semaphore is set PENDing. If the waiting task becomes runnable and is of higher priority than the signalling task, the context of the current task is saved, and a context switch is performed. If the state of the semaphore was either PENDing or DONE, the semaphore is placed in the DONE state and the current task is resumed following the signal ESR. CALLING SEQUENCE ACCB = Semaphore number swi FCB .signal. return RETURN VALUE None. Registers unchanged. EXAMPLE Assume that the current task wishes to signal the occurrence of a particular event. The event is associated with a named semaphore, EVNTSEMA. The task signals the semaphore by the following procedure: EVNTSEMA equ 15 Named semaphore #15 . : ldab #EVNTSEMA ACCB = semaphore # 15 swi FCB .signal. . Point of continuation Copyright (c) 1989 Page 5 - 20 Motorola, Inc. MCX11 - MicroController eXecutive for the 68HC11 Depending on the state of semaphore EVNTSEMA, the signal may or may not cause a context switch. The signalling task will continue processing at the instruction following the FCB declaration. SEE ALSO .pend., .wait. Copyright (c) 1989 Page 5 - 21 Motorola, Inc. MCX11 - MicroController eXecutive for the 68HC11 5.12 .suspend. - SUSPEND A TASK CLASS Task control SYNOPSIS .suspend. (TASK) [10] DESCRIPTION The suspend directive causes the specified task to be placed into a suspended state. The suspended state will remain in force until it is removed by a resume, execute, or reset directive. A task may suspend itself. Task 0 indicates the SELF task. CALLING SEQUENCE ACCA = Task number (this may be SELF [0]) swi FCB .suspend. return RETURN VALUE None. Registers unchanged. EXAMPLE The current task wants to suspend itself until some indeterminate point in the future. To do so, it makes the following request: clra ACCA = 0 means SELF swi FCB .suspend. . Point of continuation The task remains in a suspended state until resumed by a .resume. ESR issued from another task. At that time, the resumed task will continue at the instruction following the FCB declaration. SEE ALSO .resume. Copyright (c) 1989 Page 5 - 22 Motorola, Inc. MCX11 - MicroController eXecutive for the 68HC11 5.13 .terminate. - TERMINATE A TASK CLASS Task control SYNOPSIS .terminate. (TASK) [11] DESCRIPTION The terminate directive is used to terminate a task's operation. During termination, the task's state is cleared and the task state is set to Terminated. The timer queue is searched and all active timers for the task are purged. Also, all messages pending for the task are removed. A task number of 0 indicates self termination. In all cases, the highest priority task will execute next. CALLING SEQUENCE ACCA = Task number (may be = 0 if terminating SELF) swi .terminate. return RETURN VALUE None. Registers unchanged. Returns only if not terminating SELF. EXAMPLE The current task commits suicide by terminating itself with the following procedure: clra ACCA = 0 means SELF swi FCB .terminate. There is no point of continuation following a suicide. If another task is terminated by the current task, the current task will continue processing at the instruction following the FCB declaration. SEE ALSO .purge. Copyright (c) 1989 Page 5 - 23 Motorola, Inc. MCX11 - MicroController eXecutive for the 68HC11 5.14 .timer. - START A TIMER CLASS Timer SYNOPSIS .timer. (TASK,SEMA,TOCK) [14] DESCRIPTION The timer directive inserts an entry of the specified time duration into the timer queue. The timer can be cyclic or one-shot. Cyclic timers are indicated by a negative duration while one-shots are of positive duration. Further options allow the timer to be associated either with a specified task number (0 = SELF) or a semaphore number. After the timer is inserted, the current task is resumed. See the Advanced Topic section for task versus semaphore-based timers. CALLING SEQUENCE ACCA = Task number (0 if SELF) ACCB = Semaphore number (0 if task's semaphore) IX = Number of clock tocks in timer. If > 0, timer is a one-shot. If < 0, timer is cyclic. swi FCB .timer. return RETURN VALUE None. ACCA will contain the current task number if ACCA was = 0 at swi. Other registers unchanged. EXAMPLE Example #1: Assume that the current task wants to set up a one-shot timer of 5 seconds. Also assume that the RTI is used as the time base using a 2**23 crystal and the clock TICK is defined to be 15.625 msec. Furthermore, there are 8 TICKS per TOCK so that a TOCK is 125 msec. The setup of a 5 second timer associated with a named semaphore, TIMEOUT, would appear as: Copyright (c) 1989 Page 5 - 24 Motorola, Inc. MCX11 - MicroController eXecutive for the 68HC11 TOCK equ 8 TOCKTIME equ 1000/8 TOCKTIME = 125 msec TIMEOUT equ 3 Named semaphore #3 . : clra Task is self (ACCA=0) ldab #TIMEOUT Semaphore = TIMEOUT ldx #5000/TOCKTIME Timer = 40 TOCKS swi FCB .timer. . Point of continuation The current task would continue processing immediately after the ESR is finished because the .timer. ESR does not cause the requestor to be put into a WAIT state nor is there a context switch possible. The task may attempt to wait on the timer semaphore at some later time. SEE ALSO .purge. Copyright (c) 1989 Page 5 - 25 Motorola, Inc. MCX11 - MicroController eXecutive for the 68HC11 5.15 .wait. - WAIT ON SEMAPHORE CLASS Semaphore SYNOPSIS .wait. (SEMA) [1] DESCRIPTION The wait directive is a fundamental function in MCX11. It is used to make a task wait for a specified event to occur. The event must be associated with the given semaphore. If the semaphore is found to be in a PENDing state, the task is placed into an Event Wait state and the semaphore is changed to WAITing, and the context of the current task is saved. If the semaphore is in a DONE state, no wait occurs and the task resumes immediately. Upon task resumption, the wait directive returns the semaphore number of the event which occurred. CALLING SEQUENCE ACCB = Semaphore number swi FCB .wait. return RETURN VALUE None. Registers unchanged. EXAMPLE The current task wants to wait on a timer semaphore set up by a previous .timer. request. The semaphore is a named semaphore, TIMEOUT. The procedure would appear as follows: TIMEOUT equ 3 Semaphore #3 . : ldab #TIMEOUT ACCB = semaphore # 3 swi FCB .wait. . Point of continuation The current task is put into a WAIT state on semaphore TIMEOUT as a result of this request. It will remain in Copyright (c) 1989 Page 5 - 26 Motorola, Inc. MCX11 - MicroController eXecutive for the 68HC11 this state until another task, in this case, the clock driver, signals TIMEOUT that the timer period has elapsed. The task would then continue at the instruction following the FCB. SEE ALSO .pend., .signal. Copyright (c) 1989 Page 5 - 27 Motorola, Inc. MCX11 - MicroController eXecutive for the MC68HC11 SECTION 6 SYSTEM CONFIGURATION 6.1 SYSTEM CONFIGURATION CONCEPTS Another configuration concept central to the operation of MCX11 is that of pre-definition. Most real time systems used in embedded operations have a fairly static configuration. That is to say, the equipment configuration is not subject to frequent changes nor is the basic system functionality. Consequently, the system designer can define the operating environment so that the operating system dynamics are avoided to the greatest degree possible. In other words, the number of tasks concurrently executing may change but the relative priorities of tasks remain fixed. Thus task priorities can be pre-assigned. The amount of free memory can be computed and established, number of queues and their sizes, and the number of timers and semaphores are all defined prior to runtime. The result is that MCX11 works in an established environment which yields the effect of less system overhead, smaller code, and faster execution; all three being desirable in a real time system. In order to define a MCX11 system configuration it is necessary to configure those data and control structures with the application specific information which MCX11 requires. The configuration is done by creating AS11 source code files which define the necessary information needed to assemble with MCX11 source code to define a particular configuration. The following paragraphs describe the techniques. 6.2 MCX11 SYSTEM TABLE MEMORY REQUIREMENTS MCX11 system tables must necessarily reside in an area of RAM. This section is included to assist the system designer in determining the amount of ROM and RAM required for MCX11 tables. The amount of RAM and ROM may be computed from the equations below given the following system configuration information: NTASKS The number of tasks NNAMSEM The number of named semaphores NQUEUES The number of queues NTIMERS The number of timers Copyright (c) 1989 Page 6 - 1 Motorola, Inc. MCX11 - MicroController eXecutive for the MC68HC11 The symbols above are used by MCX11 and should be considered reserved symbols. These numbers are obviously exclusive of any RAM and ROM requirements of the application tasks. Tasks A Task Control Block occupies 5 bytes of RAM and 7 bytes of ROM. TASK bytes (RAM) = NTASKS * 5 + 5 TASK bytes (ROM) = NTASKS * 7 Semaphores Each semaphore requires 1 byte of RAM. Total system area required for semaphore control is the number of named semaphores + the number of tasks + 2 times the number of queues. SEMA bytes (RAM) = NNAMSEM + NTASKS + 2 * NQUEUES Queues Each queue consists of a queue header and the queue body. Each queue header requires 3 bytes of RAM and 6 bytes of ROM. Each defined queue body requires an area of RAM defined by the product of its Width (W) and its Depth (D). QUEUE bytes (RAM) = NQUEUES * 3 + Sum(Wi * Di), where Wi is the width and Di is the depth of the ith queue, and i ranges from 1 - NQUEUES. QUEUE bytes (ROM) = NQUEUES * 6 Clock Timers require 8 bytes of RAM each. The total area required for timer control and storage is the product of 8 and the number of defined timers. TIMER bytes (RAM) = NTIMERS * 8 Copyright (c) 1989 Page 6 - 2 Motorola, Inc. MCX11 - MicroController eXecutive for the MC68HC11 SECTION 7 DEVICE DRIVER & INTERRUPTS 7.1 DRIVER CONCEPTS Device drivers are program modules which provide an organized software interface between a physical device and the application programs using the device. The intent is to mask the specifics of the device's hardware peculiarities from the application software. By doing so, the application code need only conform to the protocol which the device driver expects in order to perform a function. Each device driver may have a protocol unique to its function, i.e., a disk driver has different functional requirements from an analog-to-digital converter. In order to accommodate the wide range of devices which are found in real-time systems, the device drivers in MCX11 are structured as tasks. As a task, a device driver has the most flexible environment with complete access to system resources via the Executive Service Requests. Actually, a device driver usually consists of two parts: the driver task, and the interrupt service routine (ISR). The latter is used when the device can cause an interrupt to signal the completion of a function or the availability of the device. An ISR exists to handle an exception in the normal flow of processing. The general philosophy of MCX11 drivers is to minimize the time spent in the interrupt service routine and let the task portion handle the real work of the driver. This design concept places no restrictions on the designer for either the ISR or the task functionality. The structure of the ISR is explained more completely in the following section. 7.2 INTERRUPT SERVICE The classic interrupt processing philosophy is to acknowledge the interrupt and save the current processor context. Then a branch is made to a software routine where the code services the specific interrupt and performs any required operations. When the interrupt service routine is complete, control of the main program is resumed at the point of interruption. MCX11 uses a modified version of that sequence. The MC68HC11 microcontroller always pushes the current processor context of nine (9) bytes on the active stack when an interrupt occurs. That having been done, it acknowledges Copyright (c) 1989 Page 7 - 1 Motorola, Inc. MCX11 - MicroController eXecutive for the MC68HC11 the interrupt and vectors automatically to the specific ISR written for that event. The user must initialize each two- byte interrupt vector location specific to his application as part of the initialization code. MCX11 presets the vector locations for the following interrupts. All others not specifically reserved by the MC68HC11 are available to the user. Event Address Clock (RTI) $FFF0-$FFF1 MCX11 ESR request $FFF6-$FFF7 Power On/Reset $FFFE-$FFFF MCX11 uses a modified version of the classical ISR approach. The sequence is the same until the return to the interrupted program is made at the end of the ISR. In MCX11, an interrupt may be the event for which a task is waiting. If so, a notification of the event's occurrence must be given to the task. But the possibility exists that the waiting task has a higher priority than the interrupted task. Notification of the event should remove the wait state from the higher priority task thus making it runnable, assuming it is not otherwise blocked. At that point, a decision has to be made as to how to continue. Whichever task is of higher priority, the one interrupted or the one which was waiting, it will be the one to resume processing. If it is the interrupted task, it resumes at the point of interruption as in the classic sequence. If the latter task is of higher priority, a context switch is performed in which it is made the current task. Its processor context is restored from its stack and the task resumes at the location following the ESR which caused it to wait. The interrupted task remains runnable and will continue at the point of its interruption at some later time when it becomes the highest priority runnable task. MCX11 provides a common exit routine to which all ISRs should branch if there is the possibility of a context switch as the result of the interrupt. The function's primary responsibility is to signal a specified semaphore of the occurrence of an event and to dispatch control to the highest priority task which is runnable after the interrupt has been serviced. 7.2.1 Interrupt Processing Variables In order for MCX11 interrupt servicing to operate properly, it is necessary to observe a few rules of the road. There Copyright (c) 1989 Page 7 - 2 Motorola, Inc. MCX11 - MicroController eXecutive for the MC68HC11 are some system variables which are used during interrupt processing in the ISR and in the common ISR exit routine. These variables must be used only in the ISR and should not be used elsewhere. A listing of the variables and a brief description of them follows. Their addresses are also given as a displacement from the base address of the MCX11 system variables, MCXVAR. MCXVAR may be located at any RAM address but must be predefined and assembled with the MCX11 kernel code. intlvl (address MCXVAR+11) This byte variable is a counter of the number of interrupts stacked but not yet processed completely. When an interrupt occurs in a task, intlvl will always contain a value of zero. The ISR code must increment it by 1 to indicate that an ISR is in process. If a task calls the MCX11 kernel, intlvl is incremented to a value of 1. If an interrupt were to occur while control is in the MCX11 kernel, intlvl would be incremented to 2 by the ISR, etc. MCX11 allows the existence of interruptible ISRs; therefore, intlvl can assume any value up to the number of possible interrupts in the system. As interrupts are processed by the common ISR exit logic, intlvl is decremented. A resumption of processing at the task level can only occur when the decremented value of intlvl becomes zero. Otherwise, the non-zero value indicates the existence of an interrupt which has been incompletely serviced. In that case, the common ISR exit logic returns control to the interrupted ISR and resumes processing at that point. Thus, nested interrupts and re-entrant ISRs are handled cleanly, quickly, and automatically by MCX11. curtsk (address MCXVAR+5) This byte variable contains the number of the current task. It is to be considered a READ-ONLY variable. The user should NEVER write to this variable. It is needed during ISR processing to determine if the MCX11 Dispatcher was interrupted. curtcb (address MCXVAR+6) This 2-byte variable contains the address of the current task's Task Control Block (TCB). The TCB contains an entry for the task's stack pointer. MCX11 interrupt processing requires that the ISR which increments intlvl to a value of 1 must also save the Copyright (c) 1989 Page 7 - 3 Motorola, Inc. MCX11 - MicroController eXecutive for the MC68HC11 current task's stack pointer in its TCB. The variable, curtcb, is READ-ONLY. 7.2.2 Interrupt Processing Code All ISRs which have the capability of causing a context switch should incorporate the following routine as in-line code in the ISR. If the ISR is to be allowed to enable interrupts, this code should precede the CLI instruction. As a rule it should occur early in the ISR but there are exceptions. (Refer to the MCX11 clock driver's ISR, whose entry address has the symbol rtiisr, for a good example of an exception to the rule.) Note that the label, notlvl0, used in the code segment below will need to be changed for each ISR. The symbols ACTSP and SYSTACK are not variables and should not be changed. ACTSP is equated to the value of 1 and represents the displacement into the TCB where the task's stack pointer is stored. SYSTACK is the location of the base of the System Stack area and is defined in the System Configuration source code file, SYSTEM.AS. tst intlvl Test for task level interrupt bne notlvl0 Branch if not task level int tst curtsk See if Dispatcher interrupted beq notlvl0 Branch if so ldx curtcb Get task's TCB address sts ACTSP,x Save task's stack pointer lds #SYSTACK Change to System Stack notlvl0 inc intlvl Increment the interrupt level After this point, the CLI instruction may be inserted if desired. The interrupt service code follows. An important factor in interrupt processing throughput is the length of time interrupts are disabled during the ISR. In all ISRs, interrupts must be disabled long enough to perform the code segment above and only then should interrupts be re-enabled. Ideally, interrupt routines should be performed with interrupts enabled to allow other interrupts to be serviced. The exit from the ISR routine is via a branch to the MCX11 common Interrupt Service Routine Exit routine located at the address having the symbol, isrrtn. This routine allows for optionally signalling a semaphore during the exit process. The ISR may wish to signal a semaphore that the event associated with the interrupt has occurred. To do so, the Copyright (c) 1989 Page 7 - 4 Motorola, Inc. MCX11 - MicroController eXecutive for the MC68HC11 ISR simply puts the number of the semaphore to be signalled into the B-Accumulator and the executes a branch to isrrtn. From there on, the further processing of the interrupt is performed automatically by MCX11. As an example, assume the ISR wants to signal a semaphore and that the label used for the semaphore is EVNTSEMA. Then the concluding code segment in the ISR is ldab #EVNTSEMA Load ACCB with semaphore # jmp isrrtn Jump to exit logic. If no semaphore is to be signalled during the exit routine, the ISR should make sure that the B-Accumulator is cleared before branching to isrrtn. Copyright (c) 1989 Page 7 - 5 Motorola, Inc. MCX11 - MicroController eXecutive for the MC68HC11 SECTION 8 ADVANCED TOPICS 8.1 OTHER TOPICS Other topics of interest will be added to this section as they are researched and documented. Copyright (c) 1989 Page 8 - 1 Motorola, Inc. MCX11 - MicroController eXecutive for the MC68HC11 APPENDIX A MCX11 DISTRIBUTED SOURCE FILES MCX11 is distributed as a collection of files. Those files and their purposes are briefly described below. CLKDRVR.AS The AS11 source code of the RTI clock driver and RTI Interrupt Service Routine. ESREQU.AS These are just the equates for MCX11 ESRs included for completeness. MCX.AS This is the AS11 source code of the MCX11 kernel. Unless you are expanding the functions of the kernel or fixing a reported bug, this file probably won't change too much. SYSTEM.AS This AS11 source code file contains the application specific information and should be studied very closely. It also contains initialization code which may be necessary to change to meet the needs of a given application. The file is pre-configured with the specifications needed for the demonstration programs in file TEST.AS. TEST.AS This is an AS11 source code file containing 4 tasks which demonstrate the use of all of the MCX11 ESRs. It doesn't do anything practical except to give the user a limited look at how to accomplish certain operations. VECTORS.AS AS11 source code containing all of the vectors used by MCX11. This file may need to be edited for a given application. ASSEMBLE.BAT A MS-DOS Batch file used to assemble MCX11 and the TEST programs. It also produces a listing file. MANUAL.DOC Copyright (c) 1989 Page A - 1 Motorola, Inc. MCX11 - MicroController eXecutive for the MC68HC11 The MCX11 User's Manual is contained in this file. It can be printed out directly to any ASCII compatible printer. README.DOC Some notes about getting started with MCX11. Copyright (c) 1989 Page A - 2 Motorola, Inc.