Novos. Preemptive Priority Scheduling Environment. Services Reference Guide

Transcription

1 Novos Environments for Embedded Systems Preemptive Priority Scheduling Environment (Novos PPS) Services Reference Guide Embedded Environments Co. Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 1 of 214

2 Disclaimers Embedded Environments Co. (Company), provides this Services Reference Guide as is WITHOUT WARRANTY OF ANY KIND, WHETHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. The complete text of the Novos Documentation License is available at the Company website, The Company reserves the right to revise this publication at any time and to make changes to its content and the software it represents and without obligation to inform any person or entity of such revisions or changes. Trademarks Novos and the following derivatives are trademarks of Embedded Environments Co: Novos, Novos FB, Novos Foreground/Background, Novos EFB, Novos Extended Foreground/Background, Novos FCFS, Novos First Come, First Served Scheduling, Novos RRS, Novos Round Robin Scheduling, Novos PPS, Novos Pre-emptive Priority Scheduling Other product and company names mentioned in this document may be the trademarks or registered trademarks of their respective owners. Copyrights Ownership of and all copyrights to the source code of the Novos environment as it relates to this document are held by Embedded Environments Co. It is distributed as free software. You can copy it, modify it and even redistribute it under the terms of the Novos Software License as published on the Company website, Ownership of and all rights to this publication, including the copyright, are held and/or reserved by Embedded Environments Co. This document is licensed to you as the sole user. No part of this document may be reproduced, photocopied, stored on a retrieval system, redistributed or transmitted without the express written consent of the Company. Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 2 of 214

3 Modification History Version # Major Release # Minor Release # Date Author Revised Sections Oct-2016 ATB Initial release Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 3 of 214

4 Table of Contents Disclaimers.. 2 Trademarks.. 2 Copyrights. 2 Modification History.. 3 Table of Contents.. 4 List of Tables 9 List of Properties Structures.. 10 Foreword. 11 Chapter 1 How to Use This Guide 12 Scope of this Guide.. 12 Novos Usage 12 Commercial Use 13 Errors and Inaccuracies. 13 Conventions Used in This Guide 13 Cautions, Tips and Notes. 13 Chapter 2 The Novos Preemptive Priority Scheduling Environment.. 15 Features. 16 Kernel Service Format 16 The Service Name. 17 Service Template.. 17 Service Name. 17 Service Prototype. 17 Service Completion Codes.. 18 Terminal Error Codes. 18 Chapter 3 Object Classes. 19 Objects 20 Object Properties.. 20 Object Identifiers 20 Novos PPS Services 21 Chapter 4 Special Services. 22 System Properties. 22 Special Services. 23 ES_AllocateSystemRAM.. 24 ES_AllocateUserRAM. 26 ES_GetNovosVersion. 28 Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 4 of 214

5 ES_DisableTaskScheduler.. 29 ES_EnableTaskScheduler 30 PORT_EnterISR 31 PORT_ExitISR 32 PORT_InitNovos 33 PORT_SchedDIH. 35 Chapter 5 Foreground Entities 36 Foreground Entity Properties.. 36 DIH Properties 36 EAR Properties.. 36 FG Task Properties.. 37 Foreground Entity Services.. 37 ES_CloseDIH.. 38 ES_CloseEAR 39 ES_CloseFGTask. 40 ES_CreateDIH 41 ES_CreateEAR.. 42 ES_CreateFGTask.. 43 ES_ExecuteFGTask 44 Chapter 6 Task Class. 45 Task Properties.. 45 Task Services.. 46 ES_AbortTask. 47 ES_ChangeTaskPriority 49 ES_ChangeTaskTimeQuantum. 51 ES_CloseTask 55 ES_CreateTask. 57 ES_DefTaskAction 58 ES_DefTaskCommon. 61 ES_ExecuteTask.. 63 ES_FindTask.. 65 ES_GetSelfTaskID 66 ES_GetTaskCommon. 67 ES_GetTaskName 69 ES_GetTaskPriority. 71 ES_GetTaskState. 73 ES_GetTaskTimeQuantum.. 75 Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 5 of 214

6 ES_ResumeTask.. 76 ES_SleepSelfTask 78 ES_SuspendTask. 80 ES_TerminateSelfTask.. 82 ES_WakeUpTask. 84 ES_YieldSelfTask. 86 Chapter 7 Counter Class.. 88 Counter Properties 88 Counter Class Services.. 88 ES_DisableTimeBaseCounter 90 ES_EnableTimeBaseCounter. 91 ES_GetTimeBaseCounter 92 ES_ProcessCounterTicks. 93 ES_SetTimeBaseCounter. 95 Chapter 8 Alarm Class 96 Alarm Properties. 96 Alarm Class Services.. 96 ES_ArmAlarm. 98 ES_CancelAlarm 100 ES_CloseAlarm ES_CreateAlarm. 104 ES_DefAlarmAction ES_FindAlarm ES_GetAlarmName ES_PendAlarm 110 ES_ReArmAlarm 113 Chapter 9 Event Group Class Event Group Properties 115 Event Groups Services. 115 ES_ClearEventGroupFlags ES_CloseEventGroup ES_CreateEventGroup 120 ES_DefEventGroupAction. 121 ES_FindEventGroup. 124 ES_GetEventGroupMSFlag ES_GetEventGroupName. 127 ES_PendEventGroupFlags 129 Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 6 of 214

7 ES_SetEventGroupFlags 133 Chapter 10 Queue Class 135 Queue Properties 135 Queue Services 135 ES_CloseQueue. 137 ES_CreateQueue ES_DefQueueAction. 140 ES_DequeueData ES_EnqueueData ES_FindQueue 151 ES_GetQueueName. 152 ES_GetQueueSize 154 Chapter 11 Semaphore Class. 156 Semaphore Properties. 156 Semaphore Services. 157 ES_CloseSema ES_CreateSema. 159 ES_DefSemaAction ES_FindSema ES_GetSemaCount ES_GetSemaName ES_PendSema 167 ES_PendSemaM 170 ES_PostSema. 174 ES_PostSemaM. 176 ES_SetSemaCount 179 Chapter 12 Memory Pool Class Memory Pool Properties Memory Pool Services. 181 ES_ClosePool ES_CreatePool 184 ES_DefPoolAction. 185 ES_FindPool. 188 ES_FreePoolBlk. 189 ES_GetPoolBlk 191 ES_GetPoolBlkSize ES_GetPoolFreeBlkCount. 196 Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 7 of 214

8 ES_GetPoolName. 197 Chapter 13 Mutex Class. 199 Mutex Properties. 199 Mutex Services. 200 ES_AcquireMutex ES_CloseMutex ES_CreateMutex 206 ES_FindMutex. 207 ES_GetMutexCeiling 208 ES_GetMutexName ES_GetMutexOwner. 211 ES_ReleaseMutex. 212 Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 8 of 214

9 List of Tables Table 3-1 Supported Classes in Novos PPS Environment. 19 Table 3-2 Distribution of Novos PPS Service 21 Table 4-1 Summary of Special Services.. 23 Table 5-1 Summary of Foreground Entity Services 37 Table 6-1 Summary of Task Services 46 Table 7-1 Summary of Counter Class Services 88 Table 8-1 Summary of Alarm Class Services 96 Table 9-1 Summary of Event Group Class Services Table 10-1 Summary of Queue Class Services 135 Table 11-1 Semaphore Types Table 11-2 Summary of Semaphore Class Services. 157 Table 12-1 Memory Pool Types 181 Table 12-2 Summary of Memory Pool Class Services. 181 Table 13-1 Priority Inversion Protocols. 200 Table 13-2 Summary of Mutex Class Services. 200 Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 9 of 214

10 List of Properties Structures Properties 4-1 Novos PPS System Properties 22 Properties 5-1 DIH Properties. 36 Properties 5-2 EAR Properties 36 Properties 5-3 FG Task Properties 37 Properties 6-1 Task Properties Structure.. 45 Properties 8-1 Alarm Properties Structure 96 Properties 9-1 Event Group Properties Structure 115 Properties 10-1 Queue Properties Structure 135 Properties 11-1 Semaphore Properties Structure. 156 Properties 12-1 Memory Pool Properties Structure Properties 13-1 Mutex Properties Structure. 199 Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 10 of 214

11 Foreword Over many years as a designer and developer of schedulers, real-time kernels and executives, and real-time operating system (RTOS) products for embedded systems, I have witnessed the effect that the choice of environment has on the success or failure of a project. For the past 25 years or so, the environment of choice has tended towards the RTOS. There are many RTOS products available in the market today and they are solid, proven packages. Some are free and some are not. But without regard to their license fee, or lack thereof, an RTOS is not always the best foundation for the application at hand. With the advent of the Internet of Things (IoT), there will be billions of processors used in tens of thousands of IoT applications. Some of these applications will be good candidates for the RTOS environment. Many others will not because the typical RTOS is likely to be overkill in terms of functionality and footprint. I believe that developers of embedded systems, whether for IoT or general applications, will benefit from environment choices other than the typical RTOS. The Novos environments for embedded systems represent those choices. They were created for use in applications that use resource constrained 8-, 16- and 32-bit CPUs. The Novos environments are not only easy to use but very well suited for use where the designer has to be mindful of the constraints imposed by RAM, ROM and power budgets. It is my opinion that the application itself dictates the environment for which it is best suited. That is especially true for embedded systems that share a single primary resource the processor. Central to the environment is how the application shares that processor. The essence of processor sharing is best described as scheduling, of which there are many types. Some are simple and some not so simple. Numerous questions about scheduling will confront the designer. Do application components require priorities? Does the application need preemptive scheduling? Is a cooperative scheduling policy sufficient? Is deterministic performance necessary? Is a simple loop-based approach sufficient? Hard or soft real-time? Albert Einstein is often quoted as saying Everything should be made as simple as possible, but not simpler. In deference to Dr. Einstein, a good dictum for engineering an embedded system is to use the simplest environment with the simplest scheduling policy that fits the application s requirements. It makes good sense because simpler environments tend to make testing and maintenance easier. Taken together, the use of the appropriate environment for the application greatly improves the probability of achieving a successful result. Thank you for choosing a Novos environment and we trust you will find it meets your application s requirements and is also easy to use. And if you have ideas on its usage, extensions or ways to improve the product, we would like to hear from you. In the meantime, good luck with your development. Tom Barrett Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 11 of 214

12 Chapter 1: Chapter 1 How to Use This Guide Scope of this Guide This guide contains a complete explanation of each service in the Novos Preemptive Priority Scheduling (PPS) environment, including its input parameters, outputs, errors, completion codes and an example of its use. This is a stand-alone document intended to provide information you need to assist your use of the product and to help you achieve a successful application development. It is not meant to be a tutorial on how to design or implement multitasking applications that use preemptive priority scheduling. You do not need to know the internal code details of how a service operates. Instead, you only need to know which function to use in order to cause a desired application behavior. However, if you want to learn more, you have the source code and are free to explore. And if you want to learn even more, there is an accompanying manual, The Novos Preemptive Priority Scheduling Environment User Guide, that provides detailed information on the internals of the Novos PPS environment and how best to use it. The information in it is very useful at many different levels and will provide you, along with this manual, in-depth knowledge about successfully employing the Novos PPS environment in your embedded application. For more information, please go to our website at Novos Usage Unless you have agreed to and purchased a commercial license to the Novos Preemptive Priority Scheduling environment, your use of this publication and the related source code is limited to your personal use only. The Company has invested considerable time and expense in order to provide the source code for the Novos Preemptive Priority Scheduling Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 12 of 214

13 Chapter 1: environment free of charge for non-commercial use. We do not ask for nor require a portion of any compensation you might receive from your efforts that incorporate it. Our compensation comes partly from your purchase of the license to this Guide. By accepting that license you have agreed to treat us in a fair and equitable manner. Distribution, copying or otherwise making this Guide available to third parties is not fair treatment. Doing so would not only put you in violation of that agreement, but you would be depriving us of revenue that will go towards product improvement and as compensation for our efforts. Commercial Use For commercial use, the Novos license includes an initial warranty period within which Embedded Environments Co. will provide you with maintenance and updates to your licensed product. For more information on commercial use licenses for Novos environments, please visit our website at Errors and Inaccuracies Every effort has been made to ensure that the information herein is correct and accurately reflects the capabilities and services of the Novos Preemptive Priority Scheduling environment. However, as in all such documents, technical inaccuracies and typographical errors do occur. Should you detect such errors, we invite you to submit information about them to us. The Company will make changes to this document from time-to-time and we will correct errors and incorporate useful changes into any new editions. Your comments and assistance in this effort helps us improve the product and benefits other users. Conventions Used in This Guide This document uses several conventions that are intended to improve your experience in using it. Some of the conventions are typographical and some are graphical. Cautions, Tips and Notes Warnings or cautions, tips and notes are graphical icons intended to highlight an associated paragraph or concept in order to save you time and to improve your understanding of the product. The presented information is of critical importance and you should understand it and take it into consideration in your development. Failing to do so may lead you to induce errors that can lead to unintended system behavior or cause a loss of time. This is information useful to clarify a particular point about the current or recent topic. Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 13 of 214

14 Chapter 1: An idea or usage suggestion that may help you solve a problem related to the current topic Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 14 of 214

15 Chapter 2: Chapter 2 The Novos Preemptive Priority Scheduling Environment This document addresses the services in the Novos Preemptive Priority Scheduling (PPS) environment. The Novos PPS environment is an efficient multitasking framework for embedded systems that have limited resources and have deterministic or real-time requirements. The environment is based on the concept of an application built around a queue of Background tasks that gain CPU control in descending order of their priorities in the queue of tasks eligible (i.e., ready) to receive CPU control. In Preemptive Priority Scheduling, a task retains CPU control until it is preempted by another task of higher priority, until it blocks to pend on some resource or event, or until it yields or terminates. In the Novos PPS environment, other Background tasks can be scheduled using the policies of First Come, First Served (FCFS) and by Round Robin (RRS). Background tasks scheduled by these policies must be of a single priority with respect to the policy. The Scheduler grants CPU control to the Background tasks only when there is no Foreground activity. In the Foreground, a set of entities manage operations such as servicing device interrupts, taking action on the occurrence of certain events or high priority data processing. A Foreground entity is a lightweight task that has no context. Every Foreground entity Deferred Interrupt Handler, Event Action Routine or Foreground Task has a fixed priority that defines where in the priority queue it is to run. Once it begins its operations, it runs to completion, although it may be interrupted or pre-empted by a higher priority Foreground entity. Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 15 of 214

16 Chapter 2: The Scheduler uses Preemptive Priority scheduling for Foreground entities having different priorities but uses First Come, First Served scheduling within a priority. Because of the common service model, interrupt servicing design and Application Program Interface (API), the Novos Preemptive Priority Scheduling environment provides the basis for sound system design and implementation of embedded applications that meet current requirements while preserving the potential for product evolution to more complex environments or to other processors. Features The Novos PPS environment provides many features to support applications on resource-restricted processors, including: Multiple Background Tasks for the application and special operations Each Background Task has its own stack for local variables and saving and restoring CPU context Background task scheduling using policies of Preemptive Priority, Round Robin (Time sliced) and First Come, First Served Each Background task has its own time quantum that defines how long it can remain in control of the CPU High priority Foreground entities Deferred Interrupt Handlers, Event Action Routines and Foreground Tasks All Foreground entities use one stack Pre-emptive scheduling of Foreground entities Can achieve hard real-time performance when used with Rate/Deadline Monotonic Analysis of Foreground Tasks Efficient interrupt management model Flexible set of services for all supported classes Services callable from interrupt service routines Data transfer between Foreground entities and the Background Tasks Support for time-based operations Event detection and Event Action Routines available for some objectbased events Exclusive access to resources with three methods of priority inversion management Runtime definition of objects in all classes Small code and data footprint Link-time scaling Kernel Service Format The following chapters are separated by class type and describe each service in detail. The descriptions are in alphabetical order of the service name. Each description begins on a new page and incorporates a standard template that includes the following elements: Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 16 of 214

17 Chapter 2: The Service Name The service name is formed as an imperative sentence started with a prefix of either ES_ or PORT_ followed by a verb followed by a class identifier and/or a class-related noun followed by the list of input parameters to the service. Or, more formally, <ES_ PORT_><verb><class>[<noun>]<(parameters)>, where, the angle brackets (<>) denote required strings, the vertical bar ( ) denotes a field chosen from two or more choices (OR), and the square brackets ([]) denote an optional field. Service Template All Novos RRS services are presented in the same manner. Each follows a template as described below: Service Name A brief textual synopsis of the service s functionality. Prototype Inputs value ServiceName(type parameter1,, type parametern) parameter1 Parameter 1 of a defined type Other parameters parametern Output Parameter N of a defined type value Value returned to the caller by the service Service Completion Codes Interpretation (see below) Enumerated value that provides information about how the service completed of the service and options to its operation Example /* C code fragments that show an example of how to use the service */ See Also Terminal Error Codes References to related services Error codes given to the Terminal Error Handler Function Code given to Terminal Error Handler Service Prototype Code passed to Terminal Error Handler that identifies the service that produces or detects the terminal error Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 17 of 214

18 Chapter 2: The Prototype section of the service description will show the ANSI C declaration and argument prototype for the service as it appears in the Novos_api.h file that is part of each Novos environment source code package. Note that the Novos_api.h file may contain the use of the keywords near and far. These are included because the Novos environments are ported to processors for which the C compilers require their use for efficient compilation and linking. Service Completion Codes Most Novos services return a code, directly as the value of the service or indirectly via a pointer in the service s parameter list, which informs the calling entity how the service completed. Novos Service Completion Codes (NSCC) always begin with the prefix CC_. For example, successful completion of a service is generally coded as CC_GOOD. Terminal Error Codes If the Novos environment code is compiled with DIAGNOSTICS defined, a service encountering a fatal error condition will produce a Terminal Error Packet that it passes to the Terminal Error Manager. Those data are available to assist in locating the source of a problem. Once the Terminal Error Manager is entered, it does not leave except when RETURN_FROM_TE_MANAGER is defined. The default is for the Novos environment to be compiled with RETURN_FROM_TE_MANAGER undefined. However, if the Novos environment is compiled with RETURN_FROM_TE_MANAGER defined, the Terminal Error Manager will return control to the offending service with a Service Completion Code of CC_TERMINAL_ERROR. It will be the responsibility of the user to handle the error situation. Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 18 of 214

19 Chapter 3: Chapter 3 Object Classes The Novos PPS environment supports ten object classes, each of which has a set of services to manage both basic and advanced system software needs in an organized, coherent way that gives the user of the Novos Environments a solid foundation for rapid system development, testing and verification. Table 3-1 Supported Classes in Novos PPS Environment Class Special Services Foreground Entities Tasks Counter Alarms Usage Perform special actions such as System Initialization, that are independent of any class Deferred Interrupt Handlers, Event Action Routines and Foreground Tasks perform application operations in the Foreground and communicate with other execution entities via Novos services to synchronize with events, pass data between themselves, the Background tasks and the Idle Task Execution entity for the Background, each of which has its own stack to permit multitasking Provides ways to handle a system timebase so that some operations can take place with respect to time Establishes a way of handling time-based operations with respect to the system timebase maintained by the Counter class. A single system timebase can support any number of application-defined alarms, which can be either one-shot or cyclic in nature. Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 19 of 214

20 Chapter 3: Class Event Groups Queues Semaphores Memory Pools Mutexes Usage Allows any execution entity to indicate the occurrence of one or more events and to test for them in a simple and efficient way with AND/OR Boolean logic. Supports passing data to/from execution entities even if they exist in different operational planes. Supports both First-In-First-Out (FIFO) and Last-In-First-Out (LIFO) ordering of data passage Provides a means to synchronize Background tasks and Foreground tasks with certain events and to provide a lowlevel mechanism for exclusive access to an associated resource Provides a deterministic means for allocating and releasing fixed-size blocks of RAM for use by the application Provides a way to acquire and release exclusive access to an associated resource Objects Objects in a class are data structures that services manipulate to achieve a desired system behavior. Execution entities create the objects with program code as there is no static object creation in the Novos environments. Before an execution entity may reference an object in any class, that object must have been previously created and its properties defined through the use of Novos services. It is an error to reference an object that is not in existence. In the Novos PPS environment, objects are created and may be closed when no longer needed. It is also possible to get an object s name given its identifier or get an object s identifier given its name. Object Properties Each object has a set of properties that define all that the supporting services need to know about it. These properties have an initial definition when the object is created but which may be subsequently altered by various Novos services. It is the user s responsibility to define the set of objects in each class needed to accomplish the goals of the application. The specific properties for each class will be presented in the sections pertaining to the supported classes. They are also located in the header file NovosObjectProps.h Object Identifiers Every object in every class has a unique identifier that application code references in most services to locate the object on which it is to operate. Because all objects are dynamically created at runtime, their identifiers must reside in RAM. It is the responsibility of the user to ensure that sufficient RAM is available to hold the number of identifiers the application uses. Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 20 of 214

21 Chapter 3: Novos PPS Services With the exception of the Special Services, the Novos PPS environment provides services (or, functions) that operate on objects within a set of supported classes, promoting orderly application design, development and debugging as well as product evolution within a mixed multitasking model that supports execution entities in both the Foreground and the Background. Except where specifically noted, all entities may use any Novos PPS service. The Novos PPS environment considers all services to be extensions of the calling entity, making their invocation simpler than some classic RTOS models. The result is a low overhead design that provides for rapid execution of the intended service, a highly desirable trait. Services are separated by class and generally operate on a user-selected object within that class to achieve some desired program or system behavior. Table 3-2 shows the distribution of services by class as supported by the Novos PPS environment. Table 3-2 Distribution of Novos PPS Service Class # PPS 0 Timebase Counter Services 5 1 Background Task Services 21 2 Foreground Entity Services 7 3 Alarm Services 9 4 Queue Services 8 5 Event Group Services 9 6 Semaphore Services 11 7 Memory Pool Services 9 8 Mutex Services 8 F Special Services 9 TOTALS 96 Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 21 of 214

22 Chapter 4: Chapter 4 Special Services The Novos PPS environment includes some services that do not pertain to specific classes and are considered to be a special class. Amongst these are services to initialize the Novos environment, get the version number of the Novos environment, and entering and exiting an interrupt service routine. System Properties The following structure contains the information the Novos FB initialization procedure, PORT_InitNovos() needs in order for you to be able to use the Novos PPS services. Properties 4-1 Novos PPS System Properties typedef struct char *psysworkspace; /* Pointer to System RAM (workspace RAM) */ uint workspacesize; /* Size of system RAM (in bytes) */ char *puserram; /* Pointer to User RAM for stacks, etc */ uint userramsize; /* Size of User RAM (in bytes) */ char *pbasesysstack; /* Low memory address of System Stack or 0 */ uint SysStackSize; /* Size of System Stack */ uint IdleTaskStackSize; /* Size of Super Loop/Idle Task stack */ void (* far TEHentry) (void); } SYSPROP; The TEHentry element is a pointer to a user-defined Terminal Error Handler. If the default Terminal Error Handler is to be used, this Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 22 of 214

23 Chapter 4: element should be a null pointer. This declaration should be made whether or not DIAGNOSTICS is defined.special Services Special Services The Novos PPS environment includes the following services in the Special Services class: Table 4-1 Summary of Special Services Service Name ES_AllocateSystemRAM ES_AllocateUserRAM ES_DisableTaskScheduler ES_EnableTaskScheduler ES_GetNovosVersion PORT_EnterISR PORT_ExitISR PORT_InitNovos PORT_SchedDIH Service Allocate a specified number of bytes from System RAM Allocate a specified number of bytes from User RAM Stop multitasking of Background tasks so that the Current Task stays the Current Task Allow multitasking of Background tasks if task scheduler is disabled Get the Novos PPS version information Enter an Interrupt Service Routine (ISR) Exit an interrupt service routine (ISR) Initialize the Novos PPS environment From the Immediate Interrupt Handler (IIH) part of an ISR, schedule execution of the associated DIH of these services are found on the following pages. Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 23 of 214

24 Chapter 4: ES_AllocateSystemRAM Allocate a block of n-bytes from System RAM Prototype Inputs nbytes pnscc Output char * > 0 char * = 0 char * ES_AllocateSystemRAM(uint nbytes, NSCC *pnscc) Unsigned integer that defines the number of bytes to allocate from System RAM Pointer to a variable of type NSCC that is to receive the service completion code Pointer to the first byte of the allocated block of System RAM. The pointer is aligned to the RAM Alignment Factor, RAMALIGNMENT, as defined in the TOOL_CPUspecs.h file. If the service fails to fulfill the request due to an insufficient amount of available System RAM and DIAGNOSTICS is not defined, the service returns a null pointer and the CC_INSUFFICIENT_RAM Service Completion Code. If DIAGNOSTICS and RETURN_FROM_TE_MANAGER are both defined and there is insufficient System RAM available, the service returns a null pointer and the Service Completion Code CC_TERMINAL_ERROR. Service Completion Codes Interpretation CC_GOOD CC_INSUFFICIENT_RAM CC_TERMINAL_ERROR The function has succeeded There was not enough System RAM to accommodate the request and DIAGNOSTICS is undefined A terminal error occurred when both DIAGNOSTICS and RETURN_FROM_TE_MANAGER are defined. Function to allocate a defined number of bytes of System RAM. Bytes are allocated from low memory addresses to high memory addresses with any returned pointer aligned in accordance with the defined RAM Alignment Factor, RAMALIGNMENT, as found in file TOOL_CPUspecs.h. Example void myapp(void) char *pbytes; /* Returned pointer to allocated RAM */ NSCC sccode; /* service completion code */ /* Get a block of 32 bytes from System RAM */ if ((pbytes = ES_AllocateSystemRAM(32, &sccode)) == (char *)0) /* Service fails to allocate the RAM and DIAGNOSTICS is undefined. ** The Service Completion Code at this point has to be ** CC_INSUFFICIENT_RAM. */ Deal with the error here } } else /* The service succeeded, proceed with application */ Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 24 of 214

25 Chapter 4: } See Also System Properties Structure Terminal Error Codes (When DIAGNOSTICS defined) TE_INSUFFICIENT_SYSTEM_RAM Function Code given to Terminal Error Handler ALLOCATE_SYS_RAM If there is not enough System RAM to accommodate the request and DIAGNOSTICS is defined but RETURN_FROM_TE_MANAGER is not defined, a Terminal Error exists and the service transfers control to the Terminal Error Handler. The default Terminal Error Manager does not return control to the service. Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 25 of 214

26 Chapter 4: ES_AllocateUserRAM Allocate a block of n-bytes from User RAM Prototype Inputs nbytes pnscc Output char * > 0 char * = 0 char * ES_AllocateUserRAM(uint nbytes, NSCC *pnscc) Unsigned integer that defines the number of bytes to allocate from User RAM Pointer to a variable of type NSCC that is to receive the service completion code Pointer to the first byte of the allocated block of User RAM. The pointer is aligned to the RAM Alignment Factor, RAMALIGNMENT, as defined in the TOOL_CPUspecs.h file. If the service fails to fulfill the request due to an insufficient amount of available User RAM and DIAGNOSTICS is not defined, the service returns a null pointer and the CC_INSUFFICIENT_RAM Service Completion Code. If DIAGNOSTICS and RETURN_FROM_TE_MANAGER are both defined and there is insufficient User RAM available, the service returns a null pointer and the Service Completion Code CC_TERMINAL_ERROR. Service Completion Codes Interpretation CC_GOOD CC_INSUFFICIENT_RAM CC_TERMINAL_ERROR The function has succeeded There was not enough User RAM to accommodate the request and DIAGNOSTICS is undefined A terminal error occurred when both DIAGNOSTICS and RETURN_FROM_TE_MANAGER are defined. Function to allocate a defined number of bytes of User RAM. Bytes are allocated from low memory addresses to high memory addresses with any returned pointer aligned in accordance with the defined RAM Alignment Factor, RAMALIGNMENT, as found in file TOOL_CPUspecs.h. Example void myapp(void) char *pbytes; /* Returned pointer to allocated RAM */ NSCC sccode; /* service completion code */ /* Get a block of 32 bytes from System RAM */ if ((pbytes = ES_AllocateUserRAM(32, &sccode)) == (char *)0) /* Service fails to allocate the RAM. Check the Service Completion ** Code to determine if the error has been treated or not. Assume ** DIAGNOSTICS and RETURN_FROM_TE_MANAGER are both defined */ if (sccode == CC_TERMINAL_ERROR /* There was insufficient User RAM available to fulfill the ** request. It may be a Terminal Error. It has been reported ** to the Terminal Error Manager but control returned ** here so we can determine if it truly is an error or if the Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 26 of 214

27 Chapter 4: ** requested amount of RAM could be in error */ Deal with the error here } } else /* service succeeded, proceed with application */ } See Also System Properties Structure Terminal Error Codes (When DIAGNOSTICS defined) TE_INSUFFICIENT_SYSTEM_RAM Function Code given to Terminal Error Handler ALLOCATE_USER_RAM If there is not enough User RAM to accommodate the request and DIAGNOSTICS is defined but RETURN_FROM_TE_MANAGER is not defined, a Terminal Error exists and the service transfers control to the Terminal Error Handler. The default Terminal Error Manager does not return control to the service. Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 27 of 214

28 Chapter 4: ES_GetNovosVersion Get the Novos version information Prototype Inputs Output VERSION_NO Service Completion Codes VERSION_NO ES_GetNovosVersion(void) The function requires no input parameters A value of type VERSION_NO that contains the Novos environment information, including: Environment (0-7) Version number (0-7) Major Release number (0-31) Minor Release number (0-31) Interpretation The function always succeeds Function to get the Novos version information and return it as a single integer value as follows: ***************************************************************** <- Env # -> <- Vers #-> <-- Major Rel # --> <-- Minor Rel # --> ***************************************************************** Novos PPS Environment = 5 (bits = 101) VERSION_NO version; void myapp(void) } The Version and Major and Minor Release numbers are subject to change. Refer to Modification History for the current values Example /* Get the version number to make sure the application is compatible ** with it */ version = ES_GetNovosVersion(); See Also Terminal Error Codes none Function Code given to Terminal Error Handler none Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 28 of 214

29 Chapter 4: ES_DisableTaskScheduler Stop multitasking of Background tasks Prototype NSCC ES_DisableTaskScheduler(void) Inputs void Output The function requires no input parameters NSCC The Service Completion Code Service Completion Codes CC_GOOD CC_ALREADY_DISABLED void myapp(void) Interpretation The function succeeds and task scheduling is disabled The application has tried to disable the task scheduler when it was already disabled Service to stop the multitasking of Background tasks. The service increments a counter that records the cumulative number of times this service has been invoked since the last time task scheduling was enabled. If task scheduling is currently enabled, this service will increment the counter to disable task scheduling and return the Service Completion Code CC_GOOD. The Current Task will remain the Current Task until the service invocation count becomes zero, or until the Current Task blocks, yields CPU control or terminates. If task scheduling is already disabled, the service will return a Service Completion Code of CC_ALREADY_DISABLED. Example /* Disable scheduling tasks */ if (ES_DisableTaskScheduler()!= CC_GOOD) /* Task scheduling is already disabled. No harm. No foul. */ } /* Task scheduler is disabled */ See Also ES_EnableTaskScheduler Terminal Error Codes none Function Code given to Terminal Error Handler none Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 29 of 214

30 Chapter 4: ES_EnableTaskScheduler Start multitasking of Background tasks Prototype NSCC ES_EnableTaskScheduler(void) Inputs void Output The function requires no input parameters NSCC The Service Completion Code Service Completion Codes CC_GOOD CC_ALREADY_ENABLED CC_STILL_DISABLED void myapp(void) Interpretation The function succeeds and task scheduling is enabled The application has tried to enable the task scheduler when task scheduling is already enabled Task Scheduling has been disabled more than once and this service still leaves task scheduling disabled Service to start or restart the multitasking of Background tasks. The service decrements a counter that records the number of times task scheduling has been disabled since it was last enabled. When the counter transitions from 1 to 0, BG task scheduling will be enabled and the service completes successfully returning the Service Completion Code CC_GOOD. If the counter remains greater than zero, BG task scheduling remains disabled and the service returns the Service Completion Code CC_STILL_DISABLED. If task scheduling is already enabled, it remains enabled, there is no change to the count and the service returns the Service Completion Code CC_ALREADY_ENABLED. Example /* Disable scheduling tasks */ if (ES_EnableTaskScheduler() == CC_STILL_DISABLED) /* Task scheduling is still disabled */ } else /* Task scheduler is enabled */ See Also ES_DisableTaskScheduler Terminal Error Codes none Function Code given to Terminal Error Handler none Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 30 of 214

31 Chapter 4: PORT_EnterISR Mark the entry into an Interrupt Service Routine Prototype Inputs void PORT_EnterISR(void) void The function requires no input parameters Output void The function returns no value Service Completion Codes Interpretation The function always succeeds Processor-specific function to be called ONLY as part of the Immediate Interrupt Handler (IIH) section of an interrupt service routine (ISR) in which common operations take place to mark the entry into the ISR. For example, calling the function to save some or all of the CPU context not automatically saved by the processor as part of the interrupt acknowledgement. Example /************************************************************************ * Function Name: SysTick_Handler * : Interrupt Service Routine for Cortex-M SysTick countdown * * timer used for the System Time Base * Inputs: none * Output: none ************************************************************************/ void SysTick_Handler (void) /* Upon entry into the ISR, the context has already been saved by ** the CPU but the following call allows the user to add additional ** data to the saved context such as SFRs or application-specific data */ PORT_EnterISR(); } /* Schedule the predefined SysTick DIH whose identifier is ** SysTickDIH_ID. Pass it a parameter of 1 to represent the number of ** timer ticks it is to process */ PORT_SchedDIH(SysTickDIH_ID, 1); /* Exit the ISR and let the downstream operations take care of running ** the DIH to process the timer tick. */ PORT_ExitISR(); See Also Terminal Error Codes none PORT_ExitISR Function Code given to Terminal Error Handler none Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 31 of 214

32 Chapter 4: PORT_ExitISR Mark the end of an Interrupt Service Routine Prototype Inputs void PORT_ExitISR(void) The function requires no input parameters Output none The function returns no value Service Completion Codes Interpretation none The function always succeeds Processor-specific function to be called ONLY as part of the Immediate Interrupt Handler (IIH) section of an interrupt service routine (ISR) in which common operations take place to set up the exit from the ISR. Example void SysTick_Handler (void) /* Upon entry into the ISR, the context has already been saved by ** the CPU but the following call allows the user to add additional ** data to the saved context such as SFRs or application-specific data */ PORT_EnterISR(); } /* Schedule the predefined SysTick DIH whose identifier is ** SysTickDIH_ID. Pass it a parameter of 1 to represent the number of ** timer ticks it is to process */ PORT_SchedDIH(SysTickDIH_ID, 1); /* Exit the ISR and let the downstream operations take care of running ** the DIH to process the timer tick. */ PORT_ExitISR(); See Also Terminal Error Codes none PORT_EnterISR, PORT_SchedDIH Function Code given to Terminal Error Handler none Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 32 of 214

33 Chapter 4: PORT_InitNovos Initialize the Novos environment Prototype Inputs psysprop basecstack Output NSCC Service Completion Codes CC_GOOD CC_TERMINAL_ERROR NSCC PORT_InitNovos(SYSPROP *psysprop, uint basecstack) Pointer to the system properties structure Unsigned integer that defines the base address of the C stack The Service Completion Code Interpretation The service completed successfully A terminal error occurred when both DIAGNOSTICS and RETURN_FROM_TE_MANAGER are defined. Processor-specific service to initialize the Novos environment with the values provided in the System Properties Structure. Example /* Application-specific variables, structures, data, etc */ uint Cstack; int main(void) /* Do any preliminary initialization */ /* Get the address of the C stack set up by linker */ Cstack = getmsp; /* Use MSP on Cortex-M */ /* Then initialize the Novos PPS environment */ if (PORT_InitNovos(pSysProps, Cstack)!= CC_GOOD) system initialization failure } else /* The service completed successfully. Do any ** post-initialization setup */ } } /* What follows becomes the Idle Task */ for (;;) ; /* This is the Idle Task. Modify it for your needs */ } Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 33 of 214

34 Chapter 4: See Also Terminal Error Codes (When DIAGNOSTICS defined) TE_INSUFFICIENT_SYSTEM_RAM TE_INSUFFICIENT_USER_RAM Function Code given to Terminal Error Handler INIT_NOVOS Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 34 of 214

35 Chapter 4: PORT_SchedDIH Schedule execution of the Deferred Interrupt Handler (DIH) part of an Interrupt Service Routine Prototype Inputs dih2run userdata void PORT_SchedDIH(DIHID dih2run, int userdata) The identifier of the DIH to execute. The identifier must have been previously defined An integer containing a value to pass to the DIH when it begins execution. This data value may override the data value specified as a DIH property when the DIH was created, provided that that data property value was 0. If it was non-zero, the second parameter in the function call is ignored. The value of userdata may represent an actual number or it could be a pointer typecast as an integer. The interpretation of userdata is left to the DIH. Output void The function returns no value Service Completion Codes Interpretation none The function always succeeds Port-specific function to be called ONLY as part of the Immediate Interrupt Handler (IIH) section of an interrupt service routine (ISR) for the specific and sole purpose of scheduling the execution of the DIH portion of the ISR. Example /* System timebase tick ISR, IIH part */ void SysTick_Handler(void) /* Upon entry into the ISR, save any CPU context that has not already ** been saved by the CPU such as SFRs or application-specific data */ PORT_EnterISR(); } /* Schedule the predefined SysTick DIH whose identifier is ** SysTickDIH_ID. Pass it a parameter of 1 to represent the number of ** timer ticks it is to process */ PORT_SchedDIH(SysTickDIH_ID, 1); /* Exit the ISR and let the downstream operations take care of running ** the DIH to process the timer tick. */ PORT_ExitISR(); See Also Terminal Error Codes none ES_CreateDIH Function Code given to Terminal Error Handler none Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 35 of 214

36 Chapter 5: Chapter 5 Foreground Entities The Novos PPS environment supports three sub-classes of execution entities that operate in the Foreground Deferred Interrupt Handlers (DIH), Event Action Routines (EAR) and Foreground Tasks (FG tasks) Foreground Entity Properties Each of the Foreground entity sub-classes, DIH, EAR and FG Tasks, share a similar properties structure for use in creating a sub-class object. The service references that follow will make reference to these structures. DIH Properties Properties 5-1 DIH Properties typedef struct /* DIH properties structure */ char *pname; /* pointer to name */ void (* far entry) (int); /* entry address of DIH function */ int userdata; /* user data or null */ DIH_PRIORITY priority; /* priority of the DIH in SPPQ */ } DIHPROP; EAR Properties Properties 5-2 EAR Properties typedef struct /* Event Action Routine properties structure */ char *pname; /* pointer to name */ Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 36 of 214

37 Chapter 5: void (* far entry) (int); /* entry address of EAR function */ int userdata; /* user data or null */ } EARPROP; FG Task Properties Properties 5-3 FG Task Properties typedef struct /* Foreground Task properties structure */ char *pname; /* pointer to name */ void (* far entry) (int); /* entry address of FG task function */ int userdata; /* user data or null */ FGT_PRIORITY priority; /* priority of the FG task in SPPQ */ } FGTPROP; Keywords near and far are included because the compilers for some processors require them for proper memory and/or instruction usage. If your processor/compiler does not need them, you should undefined them by modification to the compiler command line Foreground Entity Services The Novos PPS environment supports three services for the DIH sub-class, two for the EAR sub-class and three for the FG task sub-class: Table 5-1 Summary of Foreground Entity Services Service Name ES_CloseDIH ES_CloseEAR ES_CloseFGTask ES_CreateDIH ES_CreateEAR ES_CreateFGTask ES_ExecuteFGTask Service Discontinue use of a given DIH Discontinue use of a given Event Action Routine Discontinue use of a given Foreground Task Create a Deferred Interrupt Handler (DIH) for subsequent use Create an Event Action Routine (EAR) for subsequent use Create a Foreground task and initialize it for subsequent use Schedule execution of a given Foreground Task s of the services follow: Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 37 of 214

38 Chapter 5: ES_CloseDIH Discontinue use of a Deferred Interrupt Handler Prototype NSCC ES_CloseDIH (DIHID dihid) Inputs dihid Identifier of the DIH to close Output NSCC The Service Completion Code Service Completion Codes Interpretation CC_GOOD CC_TERMINAL_ERROR DIHID dihid; Normal completion of the service A terminal error occurred when both DIAGNOSTICS and RETURN_FROM_TE_MANAGER are defined. Discontinue use of a DIH and release it to the pool of free DIH objects so that it can be reused in the future. Example /* Create a DIH and initialize it */ dihid = ES_CreateDIH(&DIH1props, (NSCC *)0); /* Close the DIH to deactivate it */ if(es_closedih(dihid)!= CC_GOOD) /* Terminal Error and the close operation failed */ } else /* the DIH is now closed */ See Also ES_CreateDIH Terminal Error Codes (When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE Function Code given to Terminal Error Handler CLOSE_DIH Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 38 of 214

39 Chapter 5: ES_CloseEAR Discontinue use of an Event Action Routine Prototype Inputs NSCC ES_CloseEAR (EARID earid) earid Identifier of the Event Action Routine to close Output NSCC The Service Completion Code Service Completion Codes Interpretation CC_GOOD CC_TERMINAL_ERROR EARID Normal completion of the service A terminal error occurred when both DIAGNOSTICS and RETURN_FROM_TE_MANAGER are defined. Discontinue use of an EAR and release it to the pool of free EAR objects so that it can be reused in the future. earid; Example /* Create a EAR and initialize it */ earid = ES_CreateEAR(&EAR1props, (NSCC *)0); /* Close the EAR to discontinue its further use */ if(es_closeear(earid)!= CC_GOOD) /* Terminal Error and the close operation failed */ } else /* the EAR is now closed */ See Also ES_CreateEAR Terminal Error Codes (When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE Function Code given to Terminal Error Handler CLOSE_EAR Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 39 of 214

40 Chapter 5: ES_CloseFGTask Discontinue use of a Foreground task (FG task) Prototype Inputs NSCC ES_CloseFGTask(FGTID fgtid) fgtid Identifier of the FG task to close Output NSCC The Service Completion Code Service Completion Codes Interpretation CC_GOOD CC_TERMINAL_ERROR FGTID fgtid; Normal completion of the service A terminal error occurred when both DIAGNOSTICS and RETURN_FROM_TE_MANAGER are defined. Discontinue use of a FG task and release it to the pool of free FG task objects so that it can be reused in the future. Example /* Create a FG task and initialize it */ fgtid = ES_CreateFGTask(&FGT1props, (NSCC *)0); /* Close the FG task to deactivate it from further use */ if (ES_CloseFGTask(fgtID)!= CC_GOOD) /* Terminal Error and the close operation failed */ } else /* the FG task is now closed */ See Also ES_CreateFGTask Terminal Error Codes (When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE Function Code given to Terminal Error Handler CLOSE_FGTASK Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 40 of 214

41 Chapter 5: ES_CreateDIH Create a new Deferred Interrupt Handler (DIH) and initialize its properties Prototype Inputs DIHID ES_CreateDIH(DIHPROP *pdihprop, NSCC *pnscc) pdihprop Pointer to a DIH properties structure of type DIHPROP that contains the properties to be used in initializing the new Deferred Interrupt Handler. Pointer to a variable that is to receive the Service Completion Code as pnscc an enumerated value of type NSCC. If defined as a null pointer, ((NSCC *)0), the service will not return a Service Completion Code. Output DIHID Identifier of the newly created DIH Service Completion Codes Interpretation CC_GOOD CC_TERMINAL_ERROR The DIH was successfully created The terminal error TE_INSUFFICIENT_SYSTEM_RAM occurs when RETURN_FROM_TE_MANAGER is defined Create a new Deferred Interrupt Handler and initialize it to the values stored in the specified DIH properties structure. When finished, the DIH s state will be initialized and ready for scheduling. Example /* Properties for DIH used for processing System Time Base ticks */ DIHPROP SysTickDIH_Props = "TICKER", /* DIH name */ SysTick_DIH, /* Entry to DIH */ 0, /* No specific data to be passed */ MEDIUM_PRI, /* Medium DIH priority = SPPQ priority 2 */ }; void myapp(void) DIHID dihid; /* create and initialize a new DIH */ dihid = ES_CreateDIH(&SysTickDIH_Props, (NSCC *)0); } /* The service was successful. Continue with application */ See Also Terminal Error Codes (When DIAGNOSTICS defined) TE_INSUFFICIENT_SYSTEM_RAM (Can occur when DIAGNOSTICS undefined) TE_ILLEGAL_DIH_PRIORITY Function Code given to Terminal Error Handler CREATE_DIH Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 41 of 214

42 Chapter 5: ES_CreateEAR Create a new Event Action Routine (EAR) and initialize its properties Prototype Inputs EARID ES_CreateEAR(EARPROP *pearprop, NSCC *pnscc) pearprop Pointer to an EAR properties structure of type EARPROP to be used in initializing the new Event Action Routine. Pointer to a variable that is to receive the Service Completion Code as pnscc an enumerated value of type NSCC. If defined as a null pointer, ((NSCC *)0), the service will not return a Service Completion Code. Output EARID Identifier of the newly created EAR Service Completion Codes Interpretation CC_GOOD CC_TERMINAL_ERROR The EAR was successfully created The terminal error TE_INSUFFICIENT_SYSTEM_RAM occurs when RETURN_FROM_TE_MANAGER is defined Create a new Event Action Routine and initialize it to the values stored in the specified EAR properties structure. When finished, the EAR s state will be initialized and ready for scheduling. Example /* Properties structure for EAR used for responding to Queue_Not_Empty ** events */ EARPROP QNE_EARProps = QNE_EAR, /* EAR name */ QNE_EARentry, /* Entry to EAR */ 0, /* No specific data to be passed */ }; void MyApp(void) EARID earid; } /* create and initialize a new EAR */ earid = ES_CreateEAR(&QNE_EARProps, (NSCC *)0); /* The service was successful. Proceed with the application */ See Also Terminal Error Codes TE_INSUFFICIENT_SYSTEM_RAM (Can occur when DIAGNOSTICS undefined) Function Code given to Terminal Error Handler CREATE_EAR Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 42 of 214

43 Chapter 5: ES_CreateFGTask Create a new Foreground task (FG task) and initialize its properties Prototype Inputs pfgtprop pnscc Output FGTID ES_CreateFGTask(FGTPROP *pfgtprop, NSCC *pnscc) Pointer to a Foreground task properties structure of type FGTPROP to be used in initializing the new Foreground task. Pointer to a variable that is to receive the Service Completion Code as an enumerated value of type NSCC. If defined as a null pointer, ((NSCC *)0), the service will not return a Service Completion Code. FGTID Identifier of the newly created FG task expressed as a value of type FGTID Service Completion Codes Interpretation CC_GOOD CC_TERMINAL_ERROR FGTID fgtid; NSCC nscc; The FG task was successfully created The terminal error TE_INSUFFICIENT_SYSTEM_RAM occurs when RETURN_FROM_TE_MANAGER is defined Create a new Foreground task and initialize it to the values stored in the specified FG task properties structure. When finished, the FG task s state will be initialized and ready for scheduling. Once the FG task has been created, it may be scheduled for execution at any time without having to be re-created. Example /* create and initialize a new FG task */ fgtid = ES_CreateFGTask(&MyFGTprops, &nscc); if (nscc!= CC_GOOD) /* Error occurred */ } else /* The service was successful */ See Also Terminal Error Codes ES_CloseFGTask, ES_ExecuteFGTask TE_INSUFFICIENT_SYSTEM_RAM (Can occur when DIAGNOSTICS undefined) Function Code given to Terminal Error Handler CREATE_FGTASK Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 43 of 214

44 Chapter 5: ES_ExecuteFGTask Schedule a given Foreground task and run it Prototype Inputs fgtid NSCC ES_ExecuteFGTask(FGTID fgtid, int userdata) Identifier of the FG task to run An integer specifying a user-defined datum passed to the FG task by the userdata caller. The value of userdata may represent an actual number or it could be a pointer typecast as an integer. The interpretation of userdata is left to the FG task Output NSCC The Service Completion Code Service Completion Codes Interpretation CC_GOOD CC_TERMINAL_ERROR FGTID fgtid; int udata; Normal completion of the service A terminal error occurred when both DIAGNOSTICS and RETURN_FROM_TE_MANAGER are defined. Schedule execution of the given FG task and run it unless a DIH, EAR or another FG task exists at a higher priority. The FG task will execute once and will be removed from further execution until it is re-scheduled by a subsequent call to this service. Example /* Create a FG task and initialize it */ fgtid = ES_CreateFGTask(&FGT1props, (NSCC *)0); /* execute the FG task */ ES_ExecuteFGTask(fgtID, udata); See Also ES_CreateFGTask Terminal Error Codes (When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE Function Code given to Terminal Error Handler EXECUTE_FGTASK Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 44 of 214

45 Chapter 6: Chapter 6 Task Class In the Novos Preemptive Scheduling environment, each Background task that is ready to run gets control of the CPU with respect to its priority, its importance relative to other tasks that are ready. Those tasks that are ready to run are members of the Background Ready Queue, which is constantly changing as tasks move into and out of it as a result of services they invoke. The task in the Background Ready Queue with the highest priority is the Current Task and is in control of the CPU unless there is an active Foreground entity, which can preempt any Background task. The Novos PPS environment also allows Background tasks to use Cooperative and Round Robin scheduling provided that each set of tasks using those scheduling policies have the same priorities. Task Properties When creating a new task for the Novos RRS environment, use the following task properties structure: Properties 6-1 Task Properties Structure typedef struct /* Task properties structure */ char *pname; /* pointer to task's name string */ void ( far *entry) (void); /* Task's entry address */ char *pstack; /* pointer to start of task's stack */ uint16 stksize; /* Size of task's stack */ PRIORITY initpriority /* initial task priority */ TICKS TStimeQuantum; /* default time-slice time quantum */ } TASKPROP; Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 45 of 214

46 Chapter 6: Task Services The Novos PPS environment includes the following services for the Background Task class: Table 6-1 Summary of Task Services Service ES_AbortTask ES_ChangeTaskPriority ES_ChangeTaskTimeQuantum ES_CloseTask ES_CreateTask ES_DefTaskAction ES_DefTaskCommon ES_ExecuteTask ES_FindTask ES_GetSelfTaskID ES_GetTaskCommon ES_GetTaskName ES_GetTaskPriority ES_GetTaskState ES_GetTaskTimeQuantum ES_ResumeTask ES_SleepSelfTask ES_SuspendTask ES_TerminateSelfTask ES_WakeUpTask ES_YieldSelfTask Abort a task other than the Current Task Change a task s execution priority Define a new time-slice time quantum for a task Discontinue further use of a task Create a new task and initialize it for use Associate an Event Action Routine with one of two task events Define a RAM space that the task can use as scratchpad memory or as a common area for a group of related tasks Launch execution of a task Get the identifier of a task given its name Get the identifier of the Current Task Get the location of the task s common RAM space Get the name of a task given its identifier Get the execution priority of a task Get the state of a task other than the Current Task Get a task s current time-slice time quantum Resume a suspended task Put the Current Task to sleep for a period of time Suspend a task Terminate the Current Task Wake up a sleeping task prematurely The Current Task yields CPU control to another task at the same priority s for each service follow. Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 46 of 214

47 Chapter 6: ES_AbortTask Abort execution of a Background task that is not the Current Task Prototype Inputs NSCC ES_AbortTask(TASKID tid) tid Identifier of the BG task to be aborted Output NSCC The Service Completion Code Service Completion Codes Interpretation CC_GOOD CC_UNDEFINED_ABORT_ACTION CC_TERMINAL_ERROR /* Global variables */ TASKID TASK1; /* Local variables */ EARID abort_t1_ear; The service completed successfully No defined Event Action Routine to take when aborting the task A terminal error occurred when both DIAGNOSTICS and RETURN_FROM_TE_MANAGER are defined. Service to abort execution of the referenced BG task, which must be other than the Current Task. If the referenced BG task has an Event Action Routine defined for its ON_ABORT task event, the service will schedule its execution. It will then remove the BG task from any alarm, event group, queue, semaphore, memory pool or mutex on which it finds the task pending. If the BG task has an associated timeout alarm, the service will cancel it. Lastly, the service will unblock the task so that it can continue and process its termination. Example /* Create Task 1 */ TASK1 = ES_CreateTask(&T01_Props, (NSCC *)0); /* Set up EAR to associate with aborting this task */ abort_t1_ear = ES_CreateEAR(&ABRT_T1props, &nscc); /* Associate the EAR with the ON_ABORT event of the Current Task ** so it will run if/when the task is ever aborted */ ES_DefTaskAction(TASK1, ON_ABORT, ONE_SHOT, ABRT_T1_ID, 0); /********************** In some other entity ******************/ /* abort TASK1 */ if (ES_AbortTask(TASK1)!= CC_GOOD) /* The abort attempt failed. See what happened */ } else /* All is well. Continue. TASK1 should be released now */ Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 47 of 214

48 Chapter 6: See Also ES_CreateTask, ES_ExecuteTask, ES_TerminateSelfTask Terminal Error Codes (When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE TE_ILLEGAL_USE_OF_SELF TE_ILLEGAL_USE_OF_CURRENT_TASK TE_ILLEGAL_USE_OF_IDLE_TASK Function Code given to Terminal Error Handler ABORT_TASK The service does not close the BG task nor does it release its stack space. Closing the BG task and releasing its stack space must be done by another task, preferably the task that created it originally. A task that can be aborted should be structured so that it can detect the abort and then go about any necessary housecleaning, which should be followed by a call to the ES_TerminateSelfTask service. Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 48 of 214

49 Chapter 6: ES_ChangeTaskPriority Change the priority of a Background task Prototype Inputs tid NSCC ES_ChangeTaskPriority(TASKID tid, PRIORITY newprio); Identifier of the task that is to receive the new priority definition specified by newprio. If the caller uses SELF for the input parameter, tid, the caller must be a BG task. The value of tid may be SELF, indicating the Current Task is to change its own priority. Use of SELF must not be used by the Idle Task or by a Foreground entity. newprio The referenced task s new priority expressed as a value of type PRIORITY. Output NSCC The Service Completion Code. Service Completion Codes Interpretation CC_GOOD CC_ILLEGAL_PRIORITY CC_TERMINAL_ERROR TASKID Task1; NSCC nscc; The service completed successfully The value is not a value greater than 0 or less than the lowest priority, LOWESTTASKPRIO, as defined in the header file, NovosConfig.h. A terminal error occurred when both DIAGNOSTICS and RETURN_FROM_TE_MANAGER are defined. Service to change the priority of a task. The caller may be the Current Task and use a value of SELF for the parameter tid, provided the Current Task is not the Idle Task. Otherwise, the caller can be any Novos PPS execution entity. When the service determines that the value of newprio is legal and the caller is not the Idle Task, it changes the priority of the given task. If the given task is the Current Task and its new priority is lower than its current priority, a context switch to a higher priority task may result. Similarly, changing the priority of a task other than the Current Task to a priority higher than the Current Task will result in a context switch to the higher priority task. When the service successfully completes, it returns the Service Completion Code CC_GOOD. Example /* Create a task and initialize it. */ Task1 = ES_CreateTask(&T1props, (NSCC *)0); /* sometime later, change the task s priority to 10 */ nscc = ES_ChangeTaskPriority(Task1, (PRIORITY)10); if (nscc!= CC_GOOD) /* The service was not successful */ Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 49 of 214

50 Chapter 6: } else /* the service succeeded *. See Also ES_CreateTask Terminal Error Codes (When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE TE_ILLEGAL_USE_OF_SELF TE_ILLEGAL_TASK_PRIORITY TE_IDLE_TASK_CANNOT_CHANGE_PRIORITY Function Code given to Terminal Error Handler CHANGE_TASK_PRIORITY Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 50 of 214

51 Chapter 6: ES_ChangeTaskTimeQuantum Set or change the time quantum for a Round Robin Background task Prototype Inputs tid newquantum NSCC ES_ChangeTaskTimeQuantum(TASKID tid, TICKS newquantum); Identifier of the task whose time quantum is to be changed. The value may be SELF provided that the caller is neither the Idle Task nor a Foreground entity. Value >0 0 An integer of type TICKS that defines the number of system timebase ticks the system will allow the referenced task to run when it gains CPU control Disable Round Robin (time-sliced) scheduling for the referenced task when its current time quantum expires Output NSCC The Service Completion Code. Service Completion Codes Interpretation CC_GOOD CC_TERMINAL_ERROR TASKID tid; NSCC nscc; The service completed successfully A terminal error occurred when both DIAGNOSTICS and RETURN_FROM_TE_MANAGER are defined. Change the given value of the Background task s time quantum. The caller may change its own time quantum by referencing tid = 0. For a newquantum value greater than 0, the service will set it as the task s time quantum. If Round Robin scheduling is active for the referenced BG task, the service will update the task s control parameters but the new time quantum will not go into effect until the end of the task s current time quantum. If the Round Robin scheduling for the task is currently disabled, the service will update the task s control parameters but the task s new time quantum will not go into effect when it next becomes the Current Task. For a newquantum value of 0, the service will update the referenced task s control parameters so that further Round Robin scheduling of the task will be disabled at the end of its current time quantum. The task will remain in the Robin at its current priority. Successful completion of the service will return a Service Completion Code of CC_GOOD. Example /* create a new task and initialize it */ tid = ES_CreateTask(&T1props, (NSCC *)0); /* Some time later, enable time-slicing on the newly created task Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 51 of 214

52 Chapter 6: ** with a time quantum of 50 timebase ticks */ if (ES_ChangeTaskTimeQuantum(tID, (TICKS)50)!= CC_GOOD) /* must be a terminal error. Deal with it */ } else /* the task now has a new time quantum */ ) See Also ES_CreateTask, ES_GetTaskTimeSlice Terminal Error Codes (When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE TE_ILLEGAL_USE_OF_SELF Function Code given to Terminal Error Handler CHANGE_TASK_TIMEQUANTUM Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 52 of 214

53 Chapter 6: ES_CloseTask Discontinue use of a Background task Prototype Inputs tid Output NSCC Service Completion Codes CC_GOOD CC_TASK_ACTIVE CC_TERMINAL_ERROR NSCC ES_CloseTask(TASKID tid) Identifier of the Background task that the service is to close The Service Completion Code Interpretation The service completed successfully The task is closed or is otherwise unused A terminal error occurred when both DIAGNOSTICS and RETURN_FROM_TE_MANAGER are defined. TASKID tid; Discontinue further use of the referenced Background task provided it is inactive, having been previously terminated or never executed. If true, the service closes the task and releases it to the pool of BG tasks for reuse in the future. The service also removes all defined Event Action Routine associations for the task s events. If the task is not inactive, the service takes no action other than to return the Service Completion Code CC_TASK_ACTIVE. This service frees the task control structure used to manage the task and any user-defined stack dynamically allocated from User RAM at the time of its creation. The service does not free any RAM used for an explicitly defined stack or the task s Common storage area. Example /* create a new task */ tid = ES_CreateTask(&Taskprops, (NSCC *)0); if (ES_CloseTask(tID)!= CC_GOOD) /* close the task */ /* The service could not close the task. Deal with it */ } else /* the service closed the task successfully */ Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 53 of 214

54 Chapter 6: See Also ES_CreateTask, ES_DefTaskAction Terminal Error Codes (When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE TE_ILLEGAL_USE_OF_SELF Function Code given to Terminal Error Handler CLOSE_TASK Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 54 of 214

55 Chapter 6: ES_CloseTask Discontinue use of a Background task Prototype Inputs NSCC ES_CloseTask(TASKID tid) tid Identifier of the Background task that the service is to close Output NSCC The Service Completion Code Service Completion Codes Interpretation CC_GOOD CC_TASK_ACTIVE CC_TERMINAL_ERROR TASKID tid; The service completed successfully The task is closed or is otherwise unused A terminal error occurred when both DIAGNOSTICS and RETURN_FROM_TE_MANAGER are defined. Discontinue further use of the referenced Background task provided it is inactive, having been previously terminated or never executed. If true, the service closes the task and releases it to the pool of BG tasks for reuse in the future. The service also removes all defined Event Action Routine associations for the task s events. If the task is not inactive, the service takes no action other than to return the Service Completion Code CC_TASK_ACTIVE. This service frees the task control structure used to manage the task and any user-defined stack dynamically allocated from User RAM at the time of its creation. The service does not free any RAM used for an explicitly defined stack. Example /* create a new task */ tid = ES_CreateTask(&Taskprops, (NSCC *)0); if (ES_CloseTask(tID)!= CC_GOOD) /* close the task */ /* The service could not close the task. Deal with it */ } else /* the service closed the task successfully */ Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 55 of 214

56 Chapter 6: See Also ES_CreateTask, ES_DefTaskAction Terminal Error Codes (When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE TE_ILLEGAL_USE_OF_SELF Function Code given to Terminal Error Handler CLOSE_TASK Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 56 of 214

57 Chapter 6: ES_CreateTask Create a new Background task and define its properties Prototype Inputs ptprops TASKID ES_CreateTask(TASKPROP *ptprops, NSCC *pnscc) Pointer to the properties structure for the new task Pointer to a variable that is to receive the Service Completion Code as pnscc an enumerated value of type NSCC. If defined as a null pointer, ((NSCC *)0), the service will not return a Service Completion Code. Output TASKID Identifier of the newly created task Service Completion Codes Interpretation CC_GOOD CC_TERMINAL_ERROR TASKID tid; NSCC nscc; The service completed successfully The terminal error TE_INSUFFICIENT_SYSTEM_RAM occurs when RETURN_FROM_TE_MANAGER is defined Create a new Background task and initialize it to the values stored in the specified task properties structure. Upon creation, the task is not ready to run and requires a call to the ES_ExecuteTask service to launch it. Example /* Create a new task and initialize it */ tid = ES_CreateTask(&T1props, &nscc); /* See if the service was succesful */ if (nscc!= CC_GOOD) /* Control will be here only if there is a terminal error in * RETURN_FROM_TE_MANAGER mode */ } else /* The service completed successfully */ See Also Terminal Error Codes ES_CloseTask, ES_ExecuteTask TE_INSUFFICIENT_SYSTEM_RAM (Can occur when DIAGNOSTICS undefined) Function Code given to Terminal Error Handler CREATE_TASK Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 57 of 214

58 Chapter 6: ES_DefTaskAction Define an Event Action Routine to execute on the occurrence of a specific Background task event Prototype Inputs taskid NSCC ES_DefTaskAction(TASKID taskid, TASK_EVENT taskevent, EAR_OPTION option, EARID earid, int userdata) Identifier of the task to associate with the specified event and the EAR taskevent option earid userdata The enumerated value of the task event that invokes the defined Event Action Routine. Permissible values are: Task Event ON_TERMINATE ON_ABORT The Current Task has terminated itself The referenced Background task has been aborted by some entity An enumerated value that represents what the service is to do with respect to the defining the association between the task and the EAR. The permissible values are: EAR Option ONE_SHOT DEFINE_AND_LOCK CLEAR_ONE_EAR CLEAR_ONE_EVENT CLEAR_ALL_EVENTS Option The association between the BG task and the Event Action Routine will exist only until the next occurrence of the task event, ON_TERMINATE or ON_ABORT. The association between the BG task and the Event Action Routine will exist for the next and all subsequent occurrences of the defined task event until the association is discontinued. Discontinue the association of the specified Event Action Routine with the specified task event on the referenced BG task Discontinue all Event Action Routine associations with the specified task event on the referenced BG task Discontinue all Event Action Routine associations with all task events on the referenced BG task Identifier of the Event Action Routine to invoke when the task experiences the event defined by the parameter, taskevent. The EAR must have been previously defined. An integer to be passed to the EAR upon its being scheduled for execution when the specified task event occurs. Depending on how the EAR was created, it may or may not use this parameter Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 58 of 214

59 Chapter 6: Output NSCC Service Completion Codes CC_GOOD CC_TERMINAL_ERROR TASKID task2id; EARID earid; NSCC nscc; The Service Completion Code Interpretation Normal completion of the service A terminal error occurred when both DIAGNOSTICS and RETURN_FROM_TE_MANAGER are defined. Associate a previously defined Event Action Routine with one of the task events, ON_TERMINATE or ON_ABORT as defined by parameter taskevent, so that when the event occurs, the Event Action Routine will be executed. The parameter, option, defines the type and duration of the association. This service is also used to discontinue the associations between one or more Event Action Routines and one or more task events as previously described in the table for the EAR_OPTION parameter, option. Example task2id = ES_CreateTask(&Task2props, (NSCC *)0); /* create a task */ earid = ES_CreateEAR(&EAR2Props, (NSCC *)0); /* create an EAR */ /* Associate an EAR with the ON_TERMINATE event as a one-time event. * Use the task s identifier as the data to pass to the EAR when * it executes */ nscc = ES_DeftaskAction(task2ID, ON_TERMINATE, ONE_SHOT, earid, (int)task2id); if (nscc!= CC_GOOD) /* Can t define the task action. Determine how to proceed */ } else /* When the action routine is successfully defined, continue */ Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 59 of 214

60 Chapter 6: See Also ES_CreateTask, ES_CreateEAR Terminal Error Codes (When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE TE_ILLEGAL_USE_OF_SELF TE_ILLEGAL_USE_OF_CURRENT_TASK Function Code given to Terminal Error Handler DEF_TASK_ACTION Use of the EAR_OPTION, DEFINE_AND_LOCK, while legal, does not make much sense as aborting or terminating the task is going to be strictly a one-time event. Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 60 of 214

61 Chapter 6: ES_DefTaskCommon Define a task s Common RAM area Prototype Inputs tid NSCC ES_DefTaskCommon(TASKID tid, void *pcommon); Identifier of the task that is to receive the definition of the address of its Common RAM area. If the caller uses SELF for the input parameter, tid, the caller must be a Background task. A value of SELF for tid indicates the Current Task is to define its own Common RAM area. pcommon Pointer to the RAM address that will serve as the task s Common RAM area. Output NSCC The Service Completion Code. Service Completion Codes Interpretation CC_GOOD CC_TERMINAL_ERROR void *pt1common; TASKID tid; NSCC nscc; The service completed successfully A terminal error occurred when both DIAGNOSTICS and RETURN_FROM_TE_MANAGER are defined. The service sets up the pointer to the referenced task s Common RAM area, pcommon. Any previous pointer will be overwritten. When the task is initially created, the pointer to its Common RAM area is null. Example /* create a task and initialize it */ tid = ES_CreateTask(&T1props, (NSCC *)0); /* Sometime later define that task s Common RAM area. For the example, ** get some RAM from User RAM and save the returned pointer as the ** pointer to the task s Common RAM ares */ pt1common = ES_AllocUserRAM(32, (NSCC *)0); /* then define the task s Common area */ ES_DefTaskCommon(tID, pt1common, &nscc); if (nscc!= CC_GOOD) /* the service failed with a Terminal Error */ } else /* The service succeeded */ Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 61 of 214

62 Chapter 6: See Also ES_CreateTask, ES_GetTaskCommon Terminal Error Codes (When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE TE_ILLEGAL_USE_OF_SELF Function Code given to Terminal Error Handler DEF_TASK_COMMON Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 62 of 214

63 Chapter 6: ES_ExecuteTask Make a Background task ready for execution Prototype Inputs NSCC ES_ExecuteTask(TASKID tid); tid Identifier of the Background task that the service is to make Ready Output NSCC The Service Completion Code Service Completion Codes Interpretation CC_GOOD CC_TASK_CANNOT_EXECUTE CC_TERMINAL_ERROR TASKID NSCC The service completed successfully The given task cannot execute because it is not in the proper state due to its being closed or because it is already active, having been previously executed. A terminal error occurred when both DIAGNOSTICS and RETURN_FROM_TE_MANAGER are defined. Make the referenced BG task, previously created and initialized, ready for execution by unblocking it and putting it in the Background Ready Queue. In the Novos RRS environment, if the caller is the Idle Task, the referenced BG task will be of higher priority and there will be a context switch to it. Otherwise, if the caller is the Current Task, there will be no context switch because all BG tasks have the same priority. If the caller is a Foreground entity, any change of Background context will be deferred until all activity in the Foreground is complete. TASK1; nscc; Example /* Create a new task */ TASK1 = ES_CreateTask(&Task1Props, (NSCC *)0); if (ES_ExecuteTask(TASK1)!= CC_GOOD) /* Failed attempt to execute the task */ } else /* Task was made Ready successfully */ Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 63 of 214

64 Chapter 6: See Also ES_CreateTask, ES_CloseTask, ES_TerminateSelfTask Terminal Error Codes (When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE TE_ILLEGAL_USE_OF_SELF TE_ILLEGAL_USE_OF IDLE_TASK TE_ILLEGAL_USE_OF_CURRENT_TASK Function Code given to Terminal Error Handler EXECUTE_TASK A Background task that has been previously created and executed may not be executed a second time unless it has first been closed or terminated via the proper service call Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 64 of 214

65 Chapter 6: ES_FindTask Get the identifier of a Background task given its name Prototype Inputs pname pnscc Output TASKID ES_FindTask(char *pname, NSCC *pnscc) Pointer to character string holding the name of the task the service is to find Pointer to a variable that is to receive the Service Completion Code as an enumerated value of type NSCC. If defined as a null pointer, ((NSCC *)0), the service will not return a Service Completion Code. TASKID > 0 Identifier of the task whose name matches the string defined by pname TASKID = 0 A task was not found with a name that matches the pname string. Service Completion Codes Interpretation CC_GOOD Normal completion of the service CC_NO_SUCH_NAME_IN_CLASS No match found with name given by pname TASKID NSCC Find the task whose name matches the given name in the string pname and return its identifier. If not found, return a value of 0. tid1; nscc; Example /* find the task named Task1 */ tid1 = ES_FindTask("Task1", &nscc); if (nscc!= CC_GOOD) /* task not found. Figure out why */ } else /* Name was found and we can proceed */ See Also ES_CreateTask, ES_GetTaskName Terminal Error Codes (When DIAGNOSTICS defined) none Function Code given to Terminal Error Handler FIND_TASK Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 65 of 214

66 Chapter 6: ES_GetSelfTaskID Get the identifier of the Current Task Prototype Inputs TASKID ES_GetSelfTaskID(void); none The service does not require any input parameters Output TASKID The identifier of the Current Task Service Completion Codes Interpretation none TASKID TASK1; The service does not return a Service Completion Code The service returns the identifier of the Current Task Example /* Get the identifier of the Current Task. */ TASK1 = ES_GetSelfTaskID(); See Also ES_CreateTask Terminal Error Codes none Function Code given to Terminal Error Handler GET_SELF_TASK_ID Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 66 of 214

67 Chapter 6: ES_GetTaskCommon Get the pointer to a Background task s Common area, if any Prototype Inputs tid void * ES_GetTaskCommon(TASKID tid, NSCC *pnscc); Identifier of the Background task whose Common area pointer the service is to return. If the caller uses SELF for the input parameter, tid, the caller must be a BG task. Use of SELF indicates that the Current Task is requesting the pointer to its Common RAM area. Pointer to a variable that is to receive the Service Completion Code as pnscc an enumerated value of type NSCC. If defined as a null pointer, ((NSCC *)0), the service will not return a completion code. Output void * > 0 The address of the task s defined Common area in RAM void * = 0 The task has no Common area defined Service Completion Codes Interpretation CC_GOOD CC_TERMINAL_ERROR char TASKID NSCC The service returns only this completion code A terminal error occurred when both DIAGNOSTICS and RETURN_FROM_TE_MANAGER are defined. The service gets the pointer to the referenced BG task s RAM Common area and returns it to the caller. If the caller uses SELF for the input parameter, tid, the caller must be a BG task. *pcomn; TASK1; nscc; Example TASK1 = ES_CreateTask(&Task1Props, (NSCC *)0); /* Create a task. */ /* Define a Common area, whose address is 0x1000, for the task */ ES_DefTaskCommon(TASK1, (char *)0x1000); /* Sometime later get the task s Common area address */ pcomn = (char *)ES_GetTaskCommon(TASK1, &nscc); if (nscc!= CC_GOOD) /* Terminal error. Deal with it */ } else /* Normal completion of the service. Proceed. */ Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 67 of 214

68 Chapter 6: See Also ES_DefTaskCommon Terminal Error Codes (When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE TE_ILLEGAL_USE_OF_SELF Function Code given to Terminal Error Handler GET_TASK_COMMON Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 68 of 214

69 Chapter 6: ES_GetTaskName Get the name of a Background task given its identifier Prototype Inputs tid pnscc Output char * > 0 char * ES_GetTaskName(TASKID tid, NSCC *pnscc) Identifier of the Background task that the service is to find, returning the character pointer to its name string Pointer to a variable that is to receive the Service Completion Code as an enumerated value of type NSCC. If defined as a null pointer, ((NSCC *)0), the service will not return a Service Completion Code. Pointer to the given task s name string. If the task s name was defined as a null string, the service will return a pointer to that null string. The service will return a Service Completion Code of CC_GOOD The given task is not found or is inactive in the Task class as confirmed char * = 0 by the Service Completion Code of CC_OBJECT_NOT_IN_CLASS or CC_INACTIVE_OBJECT Service Completion Codes Interpretation CC_GOOD CC_INACTIVE_OBJECT CC_OBJECT_NOT_IN_CLASS CC_TERMINAL_ERROR TASKID tid; NSCC nscc; char *pname; Successful service completion The given task is not currently being used The given task is not a member of the set of defined tasks A terminal error occurred when both DIAGNOSTICS and RETURN_FROM_TE_MANAGER are defined. Given the identifier for a Background task, return the pointer to its name string if the task is active, i.e., in use. A task named with a null string ( ) has a valid name and the service returns a pointer to the task s name and a Service Completion Code of CC_GOOD. If the task is closed or otherwise inactive, the service returns a null pointer and the Service Completion Code of CC_INACTIVE_OBJECT If the task s identifier is not valid, the service returns a null pointer and the Service Completion Code of CC_OBJECT_NOT_IN_CLASS Example /* create a new task and give it some name */ tid = ES_CreateTask(&T1props, (NSCC *)0); /* soemwhere else, get the task s name */ pname = ES_GetTaskName(tID, &nscc); if (nscc!= CC_GOOD) /* the given task is undefined or its identifier is not legit */ } Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 69 of 214

70 Chapter 6: else /* The task was found and pname points to its name */ See Also ES_CreateTask, ES_FindTask Terminal Error Codes (When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE TE_UNUSABLE_OBJECT Function Code given to Terminal Error Handler GET_TASK_NAME Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 70 of 214

71 Chapter 6: ES_GetTaskPriority Get the priority of a Background task Prototype Inputs tid pnscc Output PRIORITY > 0 PRIORITY ES_GetTaskPriority(TASKID tid, NSCC *pnscc); Identifier of the BG task whose priority the service is to return Pointer to a variable that is to receive the Service Completion Code as an enumerated value of type NSCC. If defined as a null pointer, ((NSCC *)0), the service will not return a completion code. The priority of the referenced BG task expressed as an unsigned integer of type PRIORITY PRIORITY = 0 No priority returned because the BG task is closed or otherwise inactive Service Completion Codes Interpretation CC_GOOD CC_TASK_INACTIVE CC_TERMINAL_ERROR TASKID uint NSCC TASK1; prio; nscc; The service was successful The task is closed or otherwise inactive and its priority has no meaning A terminal error occurred when both DIAGNOSTICS and RETURN_FROM_TE_MANAGER are defined. The service returns the priority of the referenced BG task without regard to its present state, provided the task is not inactive. If it closed or otherwise inactive, the service returns a value of 0. Example TASK1 = ES_CreateTask(&Task1Props, (NSCC *)0); /* Create a task. */ prio = ES_GetTaskPriority(TASK1, &nscc); /* Get the task's priority */ if (nscc!= CC_GOOD) /* the service failed because the task was inactive */ } else /* Success! Continue */ Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 71 of 214

72 Chapter 6: See Also ES_CreateTask, ES_ChangeTaskPriority Terminal Error Codes (When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE TE_ILLEGAL_USE_OF_SELF Function Code given to Terminal Error Handler GET_TASK_PRIORITY Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 72 of 214

73 Chapter 6: ES_GetTaskState Get the current state of the referenced Background task Prototype Inputs tid pnscc Output TASKSTATE TASKSTATE ES_GetTaskState(TASKID tid, NSCC *pnscc); Identifier of the Background task whose state the service is return to the caller Pointer to a variable that is to receive the Service Completion Code as an enumerated value of type NSCC. If defined as a null pointer, ((NSCC *)0), the service will not return a Service Completion Code. An enumerated value of type TASKSTATE with the following meanings: Task State Meaning READY RUNNING BLOCKED SUSPENDED UNDEFINED The task is in the ready state but is not the Current Task The task is the Current Task The task is currently blocked for some reason other than suspension The task is suspended The service has encountered a terminal error and cannot determine the state of the referenced task. This value will only be returned when RETURN_FROM_TE_MANAGER is defined Service Completion Codes CC_GOOD CC_TERMINAL_ERROR TASKID TASK1; TASKSTATE state; NSCC nscc; Interpretation The service completed successfully A terminal error occurred when both DIAGNOSTICS and RETURN_FROM_TE_MANAGER are defined. The service returns the state of the referenced task expressed as one of five enumerated values of type TASKSTATE as shown in the table above. It returns UNDEFINED only if DIAGNOSTICS is defined and the service finds that the caller is not a task but is referencing SELF as the task identifier. In that case, the task is undefined and its state is therefore undefined. If the service detects this situation, it will set up a terminal error code of TE_ILLEGAL_USE_OF_SELF. If RETURN_FROM_TE_MANAGER is defined, the service will return a Service Completion Code of CC_TERMINAL_ERROR. Example TASK1 = ES_CreateTask(&Task1Props, (NSCC *)0); /* Create a task. */ Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 73 of 214

74 Chapter 6: /* Sometime later, get the task's state */ state = ES_GetTaskState(TASK1, &nscc); if (nscc!= CC_GOOD) /* Terminal service failure. Deal with it */ } else /* If the returned state is RUNNING, it is for the Current Task. ** Just move on. */ if (state!= RUNNING) /* Otherwise, the task s state is READY, BLOCKED or SUSPENDED. ** Because the returned Service Completion Code is CC_GOOD, ** it rules out UNDEFINED as a possible task state */ if (state!= READY) /* Is it READY? */ See Also ES_CreateTask, ES_ExecuteTask Terminal Error Codes (When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE TE_ILLEGAL_USE_OF_SELF Function Code given to Terminal Error Handler GET_TASK_STATE Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 74 of 214

75 Chapter 6: ES_GetTaskTimeQuantum Get a Background task s time quantum Prototype Inputs tid pnscc Output TICKS ES_GetTaskTimeQuantum(TASKID tid, NSCC *pnscc); Identifier of the BG task Pointer to a variable that is to receive the Service Completion Code as an enumerated value of type NSCC. If defined as a null pointer, ((NSCC *)0), the service will not return a Service Completion Code. TICKS An integer value that represents the number of timebase ticks in the referenced task s next time quantum Service Completion Codes Interpretation CC_GOOD CC_TERMINAL_ERROR TICKS NSCC The service completed successfully A terminal error occurred when both DIAGNOSTICS and RETURN_FROM_TE_MANAGER are defined. Get the value of the given Background task s next cycle time quantum and return it as a value of type TICKS. The value of the task s time quantum that the service returns represents the value of the next full time quantum. The service does not return the number of timebase ticks remaining in the task s current time quantum. quantum; nscc; Example TASK1 = ES_CreateTask(&Task1Props, (NSCC *)0); /* Create a task. */ /* Set the task s time-slice time quantum to 1000 ticks */ nscc = ES_DefTaskTimeQuantum(TASK1, 1000); /* Sometime later, get the task's time quantum */ quantum = ES_GetTaskTimeQuantum(TASK1, (NSCC *)0); See Also ES_DefTaskTimeQuantum Terminal Error Codes (When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE TE_ILLEGAL_USE_OF_SELF TE_NO_IDLE_TASK_TIME_QUANTUM Function Code given to Terminal Error Handler GET_TASK_TIMEQUANTUM Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 75 of 214

76 Chapter 6: ES_ResumeTask Resume a Background task that is currently suspended Prototype Inputs tid Output NSCC Service Completion Codes CC_GOOD CC_TASK_STILL_BLOCKED CC_TERMINAL_ERROR NSCC ES_ResumeTask(TASKID tid); Identifier of the Background task that the service is to resume from its suspended state The Service Completion Code Interpretation The service completed successfully The referenced task remains blocked after the attempt to resume it from the SUSPENDED state, indicating there is at least one other condition blocking it A terminal error occurred when both DIAGNOSTICS and RETURN_FROM_TE_MANAGER are defined. TASKID NSCC The service removes the SUSPENDED condition on the referenced Background task. If the task s resulting state is READY, the task is eligible to receive CPU control and put into the Background Ready Queue. There will be a context switch if the priority of the resumed task is higher than the priority of the Current Task. If the resumed task s priority is less than the priority of the Current Task, the service makes it eligible according to its priority with respect to the priorities of the other eligible BG tasks. The service returns the Service Completion Code of CC_GOOD. If the state of the referenced BG task remains BLOCKED after removal of the SUSPENDED condition, the task will remain blocked and the service will return to the Current Task with the Service Completion Code CC_TASK_STILL_BLOCKED. If the caller is a Foreground entity, any change of BG task context resulting from this service will be deferred until all Foreground activity is complete. tid; nscc; Example /* create a task and initialize it */ tid = ES_CreateTask(&T2props, (NSCC *)0); /* Sometime later, suspend the task */ ES_SuspendTask(tID); /* Still later, resume the task */ nscc = ES_ResumeTask(tID); if (nscc!= CC_GOOD) Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 76 of 214

77 Chapter 6: /* Either a terminal error occurred or task tid remains blocked */ } else /* All is well. Proceed */ See Also ES_SuspendTask Terminal Error Codes (When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE TE_ILLEGAL_USE_OF_SELF Function Code given to Terminal Error Handler RESUME_TASK If the caller is a Background task and attempts to use SELF for tid, it is not considered an error even though it is improper use. The Current Task will continue in control of the CPU. Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 77 of 214

78 Chapter 6: ES_SleepSelfTask Put the Current Task to sleep for a defined period of time Prototype Inputs sleepticks pnscc Output TICKS = 0 TICKS ES_SleepSelfTask(TICKS sleepticks, NSCC *pnscc); An integer value greater than zero of type TICKS that defines the number of system timebase ticks that the Current Task will sleep before resuming operations. The values of UNTIL and NOPEND are not legal values for this service. Pointer to a variable that is to receive the Service Completion Code as an enumerated value of type NSCC. If defined as a null pointer, ((NSCC *)0), the service will not return a Service Completion Code. A 0 of type TICKS that shows the period of sleep expired normally. A non-zero integer of type TICKS that defines the number of system TICKS > 0 timebase ticks remaining in the specified sleep period that was cut short by another task s call to the ES_WakeUpTask service, as indicated by the Service Completion Code of CC_SLEEP_CANCELLED Service Completion Codes Interpretation CC_GOOD CC_SLEEP_CANCELLED CC_TERMINAL_ERROR TASKID TICKS NSCC The service completed normally The sleep period was terminated prematurely by another task calling ES_WakeUpTask with a reference to the task that issued the request to sleep (i.e., the task that is now the Current Task) A terminal error occurred when both DIAGNOSTICS and RETURN_FROM_TE_MANAGER are defined. The Current Task goes to sleep for a period of time specified by the sleepticks input parameter. The service will complete when the sleep period expires normally, returning a 0 of type TICKS and a Service Completion Code of CC_GOOD. If the sleep period is defined by a sleepticks value of 0, the service will return immediately as for a normal completion. The sleep period may be terminated prematurely by another task issuing a cancellation request with the ES_WakeUpTask service. When the task that requested the sleep period resumes, the service will return the number of timebase ticks that remained on the sleep period when it was cancelled and the Service Completion Code CC_SLEEP_CANCELLED. TASK1; remainder; nscc; Example /* Create a new task */ TASK1 = ES_CreateTask(&Task1Props, (NSCC *)0); /* then launch it &/ ES_ExecuteTask(TASK1); Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 78 of 214

79 Chapter 6: /* Sometime later, go to sleep for 1000 ticks */ remainder = ES_SleepSelfTask((TICKS)1000, &nscc); if (nscc == CC_SLEEP_CANCELLED) /* Somebody wanted this task to wake up. If so, proceed ** after finding out how much time remained on the sleep period. */ do something with the variable remainder } else /* the sleep expired normally. Proceed. */ See Also ES_WakeUpTask Terminal Error Codes (When DIAGNOSTICS defined) TE_CALLER_MUST_BE_CURRENT_TASK TE_ILLEGAL_USE_OF_IDLE_TASK Function Code given to Terminal Error Handler SLEEP_SELF_TASK Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 79 of 214

80 Chapter 6: ES_SuspendTask Block a Background task indefinitely until another entity resumes it Prototype Inputs NSCC ES_SuspendTask(TASKID tid); Identifier of the Background task to be suspended. SELF is a legitimate tid task identifier for this service provided that the caller is not the Idle Task nor a Foreground entity (DIH, EAR or FG task). Output NSCC The Service Completion Code Service Completion Codes Interpretation CC_GOOD CC_CANNOT_BLOCK_IDLE_TASK CC_TERMINAL_ERROR TASKID TASK1; The service completed successfully The caller tried to suspend the Idle Task. No action taken. Note: The service does not return this Service Completion Code when DIAGNOSTICS is defined A terminal error occurred when both DIAGNOSTICS and RETURN_FROM_TE_MANAGER are defined. The given Background task s execution is blocked in a SUSPENDED state and will remain so indefinitely until such time that another entity removes the SUSPENDED state through the service ES_ResumeTask. If the referenced BG task is SELF, there will be a context switch to the next BG task that is eligible to receive CPU control. Example /* Create a new TCB for Task 1 */ TASK1 = ES_CreateTask(&Task1Props, (NSCC *)0); ES_ExecuteTask(TASK1, (NSCC *)0); /* Suspend task 1 */ nscc = ES_SuspendTask(TASK1); if (nscc!= CC_GOOD) /* Failed. Must have been a terminal error */ } else Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 80 of 214

81 Chapter 6: See Also ES_ResumeTask Terminal Error Codes (When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE TE_ILLEGAL_USE_OF_SELF TE_ILLEGAL_USE_OF IDLE_TASK Function Code given to Terminal Error Handler SUSPEND_TASK A request to suspend a task other than SELF is permissible even if the object task is already otherwise blocked. In such a condition, the suspended task cannot regain CPU control until all types of blockages are removed. Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 81 of 214

82 Chapter 6: ES_TerminateSelfTask The Current Task commits suicide Prototype Inputs none Output NSCC ES_TerminateSelfTask(void) This service has no inputs The Service Completion Code, which is returned only when NSCC RETURN_FROM_TE_MANAGER mode is defined and a terminal error is detected Service Completion Codes Interpretation CC_TERMINAL_ERROR NSCC ksrc; A terminal error occurred when both DIAGNOSTICS and RETURN_FROM_TE_MANAGER are defined. Provided the caller is not the Idle Task or a Foreground entity, the service terminates the Current Task and blocks it so that it can be restarted by a subsequent call to ES_ExecuteTask issued by another entity. If there is an Event Action Routine associated with the task event ON_TERMINATE, the service will schedule the EAR for execution. /* Terminate the Curent Task */ nscc = ES_TerminateSelfTask(); Example /* If control passes to this point, there is some kind of error */ if (nscc = CC_TERMINAL_ERROR) /* There was a terminal error and RETURN_FROM_TE_MANAGER * is defined. Log the error and continue */ } Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 82 of 214

83 Chapter 6: See Also ES_CreateTask, ES_ExecuteTask, ES_CloseTask Terminal Error Codes (When DIAGNOSTICS defined) TE_CALLER_MUST_BE_CURRENT_TASK TE_ILLEGAL_USE_OF_IDLE_TASK Function Code given to Terminal Error Handler TERMINATE_SELF_TASK The service does not close the Current Task nor does it release the task s stack space. Closing the task and releasing its stack space must be done by another task, preferably the task that created it originally. The EAR executed as a result of the ON_TERMINATE event may be a good place to do some of the housekeeping that cannot be done by the Current Task. Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 83 of 214

84 Chapter 6: ES_WakeUpTask Wake up a sleeping Background task and make it ready to run Prototype Inputs tid pnscc Output TICKS > 0 TICKS ES_WakeUpTask(TASKID tid, NSCC *pnscc); Identifier of the Background task to awaken Pointer to a variable that is to receive the Service Completion Code as an enumerated value of type NSCC. If defined as a null pointer, ((NSCC *)0), the service will not return a Service Completion Code. The number of system timebase ticks remaining on the task s sleep duration at the time of the call to ES_WakeUpTask. TICKS = 0 The referenced task was not sleeping at the time of this call to ES_WakeUpTask. Service Completion Codes Interpretation CC_GOOD CC_TASK_NOT_SLEEPING CC_TASK_STILL_BLOCKED CC_TERMINAL_ERROR TASKID TICKS NSCC The service completed successfully The referenced task is not sleeping; therefore it cannot be awakened. The referenced task remains blocked by some other condition after removal of the sleep condition A terminal error occurred when both DIAGNOSTICS and RETURN_FROM_TE_MANAGER are defined. The service removes the sleep condition from the referenced Background task, tid, and returns it to the Background Ready Queue with respect its priority and the priorities of the other ready tasks, provided there are no other blocking conditions on the task. After removing sleep condition from the referenced BG task and no other blocking conditions remain on it, a context switch to the referenced BG task will occur if it has a higher priority than that of the Current Task. Likewise, if the priority of the Current Task is higher than that of the referenced task, there will be no context switch. In either case, the service returns a Service Completion Code of CC_GOOD. If other blocking conditions on the referenced BG task persist, the referenced task is not returned to the Background Ready Queue and the service returns the Service Completion Code CC_TASK_STILL_BLOCKED. Should the caller be a Foreground entity, any change to the Background Ready Queue as a result of this service will not go into effect until all Foreground activity is complete. If tid is SELF, the service ignores it and returns immediately with the Service Completion Code CC_TASK_NOT_SLEEPING. A Foreground entity cannot reference tid as SELF. TASK1; remainder; nscc; Example Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 84 of 214

85 Chapter 6: /* Create a new task */ TASK1 = ES_CreateTask(&Task1Props, (NSCC *)0); /* Start the task running and it will eventually go to sleep*/ ES_ExecuteTask(TASK1); /* Later on, awaken the sleeping task */ remainder = ES_WakeUpTask(TASK1, &nscc); if (nscc!= CC_GOOD) /* The task was not sleeping. Deal with it as necessary */ } else /* The task was successfully awakened */ See Also ES_SleepSelfTask Terminal Error Codes (When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE TE_ILLEGAL_USE_OF_SELF TE_ILLEGAL_USE_OF_CURRENT_TASK TE_ILLEGAL_USE_OF IDLE_TASK Function Code given to Terminal Error Handler WAKEUP_TASK Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 85 of 214

86 Chapter 6: ES_YieldSelfTask The Current Task yields control of the CPU Prototype Inputs NSCC ES_YieldSelfTask(void); void The service requires no inputs Output NSCC The Service Completion Code Service Completion Codes Interpretation CC_GOOD CC_NO_YIELD CC_TERMINAL_ERROR The service yielded the Current Task s CPU control successfully The attempt to yield CPU control failed because there was no other task in the Background Ready Queue with the same priority A terminal error occurred when both DIAGNOSTICS and RETURN_FROM_TE_MANAGER are defined. This service must ONLY be called from the Current Task, provided it is not the Idle Task. If the Current Task is not the Idle Task, yielding CPU control can only occur if there is another BG task in the Background Ready Queue with the same priority as that of the Current Task. If so, the service moves the Current Task to the Background Ready Queue with respect to its priority and that of other tasks in the Background Ready Queue. The next BG task in the Background Ready Queue becomes the new Current Task, effecting a context switch. The service completes successfully and returns a Service Completion Code of CC_GOOD. If there is no other BG task having the same priority as the Current Task that is also eligible to receive CPU control, the service makes no change of the Current Task and returns the Service Completion Code CC_NO_YIELD. /* Start of the task code */ /* Do some things in the task Example /* Then have the Current Task give up CPU control */ if(es_yieldselftask() == CC_NO_YIELD) /* The Current Task was the only Ready task in the system ** There was no yield of CPU control and the Current Task ** remains in control. */ } else /* The task yielded successfully and has now become the ** Current Task once again and continues to run */ Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 86 of 214

87 Chapter 6: } See Also ES_ExecuteTask Terminal Error Codes (When DIAGNOSTICS defined) TE_CALLER_MUST_BE_CURRENT_TASK TE_ILLEGAL_USE_OF_IDLE_TASK Function Code given to Terminal Error Handler TERMINATE_SELF_TASK If the yield of CPU control is successful, the task making the request will not receive the Service Completion Code CC_GOOD until it has yielded and has once again become the Current Task. Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 87 of 214

88 Chapter 7: Chapter 7 Counter Class The Counter class in the Novos PPS environment provides services to enable a system timebase for use by the Alarm class. Counter Properties There is no required properties structure for the Counter class. The only counter object is created and initialized during the Novos PPS initialization procedure. Counter Class Services The Novos environments support time-based operations, which require a system timebase that will enable execution entities to establish a future point in time when some action is to take place. Services for system timebase counter included in the Novos environments are: Table 7-1 Summary of Counter Class Services Service Name ES_DisableTimeBaseCounter ES_EnableTimeBaseCounter ES_GetTimeBaseCounter ES_ProcessCounterTicks Service Stop accumulating timebase ticks in the system timebase counter s tick accumulator Start or resume accumulating timebase ticks in the system timebase counter s tick accumulator Get the current number of accumulated ticks in the system timebase counter s tick accumulator Process a given number of system timebase ticks Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 88 of 214

89 Chapter 7: Service Name ES_SetTimeBaseCounter Service Set the system timebase counter s tick accumulator to a given value s for each of the Counter class services follow. Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 89 of 214

90 Chapter 7: ES_DisableTimeBaseCounter Disable further accumulations of timebase ticks and alarm management until further notice. Prototype Inputs void ES_DisableTimeBaseCounter(void) void There is no input to this service Output void This service does not return a value Service Completion Codes Interpretation none This service always completes successfully Stop accumulation of any more timebase ticks until further notice. This action freezes all active alarms so that no alarm expirations will occur during the period when timebase counting is disabled. Example ES_DisableTimeBaseCounter(); /* Start or resume tick accumulation */ See Also ES_EnableTimeBaseCounter Terminal Error Codes none Function Code given to Terminal Error Handler none Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 90 of 214

91 Chapter 7: ES_EnableTimeBaseCounter Enable accumulation of timebase ticks for alarm management Prototype Inputs void ES_EnableTimeBaseCounter(void) void There is no input to this service Output void This service does not return a value Service Completion Codes Interpretation none This service always completes successfully Enable tick accumulation by the system timebase counter so that active alarms can be processed Example ES_EnableTimeBaseCounter(); /* Stop tick accumulation */ See Also ES_DisableTimeBaseCounter Terminal Error Codes none Function Code given to Terminal Error Handler none Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 91 of 214

92 Chapter 7: ES_GetTimeBaseCounter Get the current value of the timebase counter s tick accumulator Prototype Inputs void Output TICKS ES_GetTimeBaseCounter(void) There is no input to this service TICKS An unsigned integer of type TICKS that contains the number of accumulated timebase ticks Service Completion Codes Interpretation none TICKS This service always completes successfully Get the current number of timebase counter ticks nticks; Example /* Get number of accumulated ticks */ nticks = ES_GetTimeBaseCounter(); See Also ES_DisableTimeBaseCounter Terminal Error Codes none Function Code given to Terminal Error Handler none Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 92 of 214

93 Chapter 7: ES_ProcessCounterTicks Update the timebase tick counter accumulator and then process any expired alarms Prototype Inputs NSCC ES_ProcessCounterTicks(TICKS incticks) incticks A value of type TICKS that represents the number of timebase ticks to add to the system timebase counter s accumulator Output NSCC The Service Completion Code Service Completion Codes Interpretation CC_GOOD CC_TIMEBASE_DISABLED The service completed successfully The service cannot be performed because the system timebase counter is disabled If timebase tick counting is enabled, the service adds the given number of timebase ticks in incticks, to the system timebase counter s tick accumulator. It then compares the updated value of the tick accumulator to the set of active alarms to determine if there is an alarm that has expired. If so, it marks the alarm as either expired or recycled, depending on the type of alarm, cyclic or one-shot. For each expired alarm encountered, the service removes it from the set of active alarms. If the expired alarm is cyclic, the service recalculates the alarm s next expiration time and puts the alarm back into the active set. The service performs this processing sequence on all expired alarms until it encounters an alarm that has not expired, at which point the service is complete. If the service encounters an alarm that has expired and for which one or more Background tasks are pending, it removes each task from the alarm s list of pending tasks, unblocks it and puts it into the Background Ready Queue so it can continue. There may be a context switch if the unblocked BG task has a priority higher than that of the Current Task at the time of the alarm expiration. If an alarm expires and has any Event Action Routine associated with the ON_EXPIRE alarm event, the service will schedule them for execution. Example /***********************************************************************/ * Function Name: SysTick_DIH * * : process one or more ticks of the system time base clock * * Inputs: number system time base ticks to add * Output: none * ************************************************************************/ void far SysTick_DIH(int nticks) /* Update the System Timebase counter's tick accumulator and check ** for any alarm expirations, etc. */ ES_ProcessCounterTicks((TICKS)nticks); } Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 93 of 214

94 Chapter 7: See Also ES_DisableTimeBaseCounter, ES_EnableTimeBaseCounter, Terminal Error Codes none Function Code given to Terminal Error Handler none This service is normally used in the Deferred Interrupt Handler of the Interrupt Service Routine for the system timebase. However, that is not a requirement and you may use it anywhere. But it is recommended that its use be confined to Foreground entities for the best results. Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 94 of 214

95 Chapter 7: ES_SetTimeBaseCounter Define a baseline value for the accumulation of timebase ticks Prototype Inputs NSCC ES_SetTimeBaseCounter(TICKS ticks) ticks A value of type TICKS representing the new baseline value for the timebase counter s tick accumulator Output NSCC The Service Completion Code Service Completion Codes Interpretation CC_GOOD CC_ALARMS_ACTIVE NSCC nscc; The service completed successfully There are active alarms being managed and the service cannot compete successfully. No change in the value of the system timebase counter s tick accumulator occurs The service sets a new baseline value for the timebase counter s tick accumulator to which the ES_ProcessCounterTicks service adds new ticks. This operation will successfully complete if and only if there are no active alarms. If there are active alarms, the value of the timebase tick counter s accumulator will not be changed and the service will return a Service Completion Code of CC_ALARMS_ACTIVE. The timebase counter may or may not be disabled when this service is invoked. Example /* initialize SystemTimeBase tick counter s accumulator */ nscc = ES_SetTimeBaseCounter(100); if (nscc!= CC_GOOD) /* No change made to the timebase accumulator */ } else /* the service succeeded */ See Also Terminal Error Codes none ES_GetTimeBaseCounter, ES_EnableTimeBaseCounter, ES_DisableTimeBaseCounter Function Code given to Terminal Error Handler none Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 95 of 214

96 Chapter 8: Chapter 8 Alarm Class The Alarm Class in the Novos PPS environment provides a means of performing actions with respect to time. All entities can make use of the Alarm class services. However, only Background tasks are allowed to wait for the alarm to expire. Alarm Properties For the Novos Foreground environment, use the following alarm properties structure when creating a new alarm: Properties 8-1 Alarm Properties Structure typedef struct /* Alarm Properties Block */ char *pname; /* pointer to char string of alarm name */ TICKS init_first; /* initialization value for first period */ TICKS init_recycle; /* initialization value for recycle periods */ } ALARMPROP; Alarm Class Services Services for Alarms included in the Novos PPS environment are: Table 8-1 Summary of Alarm Class Services Service Name ES_ArmAlarm ES_CancelAlarm Service Arm a given alarm to make it active Stop a given alarm from further activity Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 96 of 214

97 Chapter 8: Service Name ES_CloseAlarm ES_CreateAlarm ES_DefAlarmAction ES_GetAlarmName ES_FindAlarm ES_PendAlarm ES_ReArmAlarm Discontinue use of an alarm Service Create an alarm object for subsequent use Define an Event Action Routine to execute if either the given alarm expires or is cancelled Get the name of an alarm given its identifier Find an alarm given its name and return its identifier Test the status of an alarm to see if it is still active, cancelled or inactive Re-arm an active alarm prior to its expiration s for each of the supported Alarm class services follow. Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 97 of 214

98 Chapter 8: ES_ArmAlarm Make an alarm active Prototype NSCC ES_ArmAlarm(ALARMID alarmid) Inputs alarmid Output Identifier of the alarm to be armed NSCC The Service Completion Code Service Completion Codes CC_GOOD CC_ALARM_ACTIVE CC_ALARM_RECYCLED CC_ALARM_EXPIRED CC_TERMINAL_ERROR Normal completion Interpretation The alarm cannot be armed because it is already actively counting and has not expired The alarm cannot be armed because it has expired but not yet detected and it is now actively counting during its recycle period The initial and recycle durations defined for the alarm are both 0, which will be treated as an expired alarm A terminal error occurred when both DIAGNOSTICS and RETURN_FROM_TE_MANAGER are defined. Only an alarm that is in an inactive state (i.e., initialized, expired or cancelled) can be armed. The service uses the initial and recycle periods currently in force as defined by the alarm s properties when it was created or by the corresponding parameters used to re-arm the alarm. If the value of the initial period is non-zero, the service arms the alarm with an expected expiration defined by that period, making the alarm active and returns the Service Completion Code CC_GOOD. If the value of the initial period is zero and the value of the recycle period is non-zero, the service will arm the alarm with an expected expiration defined by that period but making it a recycled alarm. In this case, the service treats it as an expired alarm and will schedule any Event Action Routines associated with the alarm s expiration event, returning the Service Completion Code CC_GOOD. Similarly, if the recycle period is also zero, the service makes it an expired one-shot alarm and also schedules any Event Action Routines associated with the alarm expiration event but returns the Service Completion Code CC_ALARM_EXPIRED. Referencing an active or recycled alarm causes the service to return a Service Completion Code of CC_ALARM_ACTIVE or CC_ALARM_RECYCLED, respectively, making no change to the alarm s state. Example ALARMID aid1; /* identifier of the alarm */ NSCC nscc; /* variable to receive the Service Completion Code */ /* create an alarm */ aid1 = ES_CreateAlarm(&Alrm1props, (NSCC *)0); Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 98 of 214

99 Chapter 8: /* arm the alarm and test completion */ if (ES_ArmAlarm(aID1)!= CC_GOOD) /* alarm failed to arm */ } else /* alarm is armed and ticking See Also ES_CreateAlarm, ES_ReArmAlarm Terminal Error Codes (DIAGNOSTICS Mode only) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE Function Code given to Terminal Error Handler ARM_ALARM Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 99 of 214

100 Chapter 8: ES_CancelAlarm Cancel an active alarm Prototype Inputs alarmid pnscc Output TICKS > 0 TICKS = 0 Service Completion Codes CC_GOOD CC_ALARM_INACTIVE CC_TERMINAL_ERROR TICKS ES_CancelAlarm(ALARMID alarmid, NSCC *pnscc) Identifier of the alarm to cancel Pointer to a variable that is to receive the Service Completion Code as an enumerated value of type NSCC. If defined as a null pointer, ((NSCC *)0), the service will not return a Service Completion Code. An unsigned integer of type TICKS representing the number of timer ticks remaining on the alarm until its next expiration The alarm is not active at the time of this service call Interpretation Normal completion of the service The alarm is not active at the time of this service call A terminal error occurred when DIAGNOSTICS and RETURN_FROM_TE_MANAGER are both defined Service to cancel an active alarm. If the alarm is active, it is immediately made inactive and removed from the active alarm list on the System Timebase. If there is a defined Event Action Routine associated with the alarm s ON_CANCEL event, the service will schedule it to execute upon completion of the service. The service calculates the number of ticks remaining until its next expiration and returns that value along with a Service Completion Code of CC_GOOD. If the alarm is inactive at the time of the call, the service returns a value of 0 for the number of ticks remaining on the alarm and a Service Completion Code of CC_ALARM_INACTIVE. ALARMID aid1; TICKS remainder; NSCC nscc; Example aid1 = ES_CreateAlarm(&Alrm1props, (NSCC *)0); /* create an alarm */ ES_ArmAlarm(aID1); /* make the alarm active */ /* Now cancel the alarm */ if ((remainder = ES_CancelAlarm(aID1, &nscc))!= CC_GOOD) /* the alarm was inactive */ } else /* Alarm cancellation occurred properly */ Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 100 of 214

101 Chapter 8: See Also ES_CreateAlarm, ES_ArmAlarm, ES_DefAlarmAction Terminal Error Codes (DIAGNOSTICS Modes only) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE Function Code given to Terminal Error Handler CANCEL_ALARM After cancelling the alarm, it is inactive but may be reused by arming it again with the ES_ArmAlarm service. It cannot be re-armed until it is again armed. Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 101 of 214

102 Chapter 8: ES_CloseAlarm Discontinue use of an alarm Prototype Inputs NSCC ES_CloseAlarm(ALARMID alarm) alarm Identifier of the alarm to close Output NSCC The Service Completion Code Service Completion Codes Interpretation CC_GOOD CC_TERMINAL_ERROR Normal completion of the service A terminal error occurred when both DIAGNOSTICS and RETURN_FROM_TE_MANAGER are defined. Service to discontinue use of an alarm. If the alarm is armed and actively counting, the service removes it from the active alarm list. After removing it from the active alarm list, or if the alarm is already inactive, the service closes the alarm, releasing it to the pool of free alarms so that it can be reused in the future. The service also removes all defined Event Action Routine associations for the alarm s events. If there are any BG tasks pending on expiration of the alarm, the service will unblock them and set up the Service Completion Code of CC_ALARM_WAS_CLOSED to indicate to each task when it is next released that the pending operation did not complete and why. When successfully finished, the service returns the Service Completion Code CC_GOOD Example ALARMID aid; NSCC nscc; /* Create an alarm and initialize it */ aid = ES_CreateAlarm(&Alrm1props, (NSCC *)0); ES_CloseAlarm(aID, &nscc); /* Close the alarm to make it inactive */ if (nscc!= CC_GOOD) /* the close operation failed */ } else /* the alarm is now closed */ Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 102 of 214

103 Chapter 8: See Also ES_CreateAlarm, ES_DefAlarmAction, ES_PendAlarm Terminal Error Codes (When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE Function Code given to Terminal Error Handler CLOSE_ALARM Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 103 of 214

104 Chapter 8: ES_CreateAlarm Create a new alarm and initialize its properties Prototype Inputs palarmprop ALARMID ES_CreateAlarm(ALARMPROP *palarmprop, NSCC *pnscc) Pointer to an alarm properties structure of type ALARMPROP to be used in initializing the new alarm. Pointer to a variable that is to receive the Service Completion Code as Pnscc an enumerated value of type NSCC. If defined as a null pointer, ((NSCC *)0), the service will not return a Service Completion Code. Output ALARMID Identifier of the newly created alarm Service Completion Codes Interpretation CC_GOOD CC_TERMINAL_ERROR #define CLKTICK 10 The alarm was successfully created The terminal error TE_INSUFFICIENT_SYSTEM_RAM occurs when RETURN_FROM_TE_MANAGER is defined Create a new alarm and initialize it to the values stored in the specified alarm properties structure, including the alarm s initial duration and recycle count. Other values are set to 0. When finished, the alarm s state will be initialized and ready for arming but it will not be actively ticking until it has been armed trough a call to the ES_ArmAlarm service. Any definition of actions to take for the expiration or cancellation of the alarm must be done through the ES_DefAlarmAction service. Example /* Properties for Alarms used in tests */ ALARMPROP Alarm1Props = "Alarm 1", /* pointer to name */ 250/CLKTICK, /* 250 msec initialization value for first period */ 250/CLKTICK, /* 250 msec initialization value for recycle periods */ }; void myapp(void) ALARMID aid; /* create and initialize a new alarm */ aid = ES_CreateAlarm(&Alarm1Props, (NSCC *)0); /* The service was successful */ See Also Terminal Error Codes ES_ArmAlarm, ES_DefAlarmAction TE_INSUFFICIENT_SYSTEM_RAM (Can occur when DIAGNOSTICS undefined) Function Code given to Terminal Error Handler CREATE_ALARM Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 104 of 214

105 Chapter 8: ES_DefAlarmAction Define an Event Action Routine to execute on either alarm expiration or cancellation Prototype Inputs alarmid NSCC ES_DefAlarmAction(ALARMID alarmid, ALARM_EVENT condition, EAR_OPTION option, EARID earid, int userdata) Identifier of the alarm for which the event action is to be defined condition The enumerated value of the ALARM_EVENT that invokes the defined action. Permissible values are: Alarm Events ON_EXPIRE ON_CANCEL The alarm expires normally after a predefined number of timebase ticks The alarm was cancelled by some entity prior to its expected point of expiration option An enumerated value that represents what the service is to do with respect to the EAR and the alarm. The permissible values are: EAR Option Option ONE_SHOT DEFINE_AND_LOCK CLEAR_ONE_EAR CLEAR_ONE_EVENT CLEAR_ALL_EVENTS The association between the alarm and the Event Action Routine will exist only until the next occurrence of the defined alarm event, ON_EXPIRE or ON_CANCEL The association between the alarm and the Event Action Routine will exist for all subsequent occurrences of the defined alarm event until the association is discontinued Discontinue the association of the specified Event Action Routine with the specified alarm event on the referenced alarm Discontinue all Event Action Routine associations with the specified alarm event on the referenced alarm Discontinue all Event Action Routine associations with all alarm events on the referenced alarm earid userdata Identifier of the Event Action Routine (EAR) to invoke for the given condition. The EAR must have been previously defined. If the value is 0, the service will remove any previous action definition for the given condition. Integer to be passed to the EAR upon its being scheduled for execution when the ALARM_EVENT condition occurs. Depending on how the EAR was created, it may or may not use this parameter Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 105 of 214

106 Chapter 8: Output NSCC The Service Completion Code Service Completion Codes Interpretation CC_GOOD CC_TERMINAL_ERROR ALARMID aid1; EARID earid; NSCC nscc; Normal completion of the service A terminal error occurred when DIAGNOSTICS and RETURN_FROM_TE_MANAGER are both defined Associate a previously created Event Action Routine with one of two possible alarm events, ON_EXPIRE or ON_CANCEL, as defined by the parameter, condition. The type of association of the EAR, ONE_SHOT or DEFINE_AND_LOCK, with the alarm is given by the option parameter. When the specified alarm event occurs, the EAR will be scheduled for immediate execution. This service is also used to discontinue the association between one or more Event Action Routines from one or more alarm events as previously described in the table for the EAR_OPTION parameter, option. Example /* Create an alarm */ aid1 = ES_CreateAlarm(&Alrm1props, (NSCC *)0); /* Create Event Action Routine */ earid = ES_CreateEAR(&earProps, (NSCC *)0); /* Define the action to take when the alarm expires */ nscc = ES_DefAlarmAction(aID1, ON_EXPIRE, ONE_SHOT, earid, 0); if (nscc!= CC_GOOD) /* Can t define the alarm action. Determine how to proceed */ } else ES_ArmAlarm(aID1); /* make the alarm active */ } See Also ES_CreateAlarm, ES_ArmAlarm, ES_CreateEAR, ES_ProcessCounterTicks Terminal Error Codes (When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE TE_ILLEGAL_ALARM_EVENT Function Code given to Terminal Error Handler DEF_ALARM_ACTION Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 106 of 214

107 Chapter 8: ES_FindAlarm Find an alarm given its name Prototype Inputs pname pnscc Output ALARMID ES_FindAlarm(char *pname, NSCC *pnscc) Pointer to character string holding the name of the alarm the service is to find Pointer to a variable that is to receive the Service Completion Code as an enumerated value of type NSCC. If defined as a null pointer, ((NSCC *)0), the service will not return a Service Completion Code. ALARMID > 0 Identifier of the alarm whose name matches the string defined by pname ALARMID = 0 Alarm not found whose name matches the pname string. Service Completion Codes Interpretation CC_GOOD Normal completion of the service CC_NO_SUCH_NAME_IN_CLASS No match found with name given by pname ALARMID aid1; NSCC nscc; Find the alarm whose name matches the given name in the string pname and return its identifier. If not found, return a value of 0. Example /* Find the alarm named Alarm1 */ aid1 = ES_FindAlarm("Alarm1", &nscc); if (nscc!= CC_GOOD) /* failed to find the alarm s name */ } else /* the names match. Service was successful */ See Also ES_CreateAlarm, ES_GetAlarmName Terminal Error Codes (When DIAGNOSTICS defined) none Function Code given to Terminal Error Handler FIND_ALARM Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 107 of 214

108 Chapter 8: ES_GetAlarmName Get a pointer to an alarm s name Prototype Inputs alarm pnscc Output char * > 0 char * = 0 char * ES_GetAlarmName(ALARMID alarm, NSCC *pnscc) Identifier of the alarm whose name the service is to return Pointer to a variable that is to receive the Service Completion Code as an enumerated value of type NSCC. If defined as a null pointer, ((NSCC *)0), the service will not return a Service Completion Code. Pointer to the given alarm s null terminated name string Case 1: The given alarm identifier is not found in the Alarm class as confirmed by the Service Completion Code of CC_OBJECT_NOT_IN_CLASS Case 2: The given alarm and its name are inactive as confirmed by the Service Completion Code CC_INACTIVE_OBJECT Case 3: The given alarm identifier is correct and the alarm was found but its name string in null (i.e., defined by ) as confirmed by the Service Completion Code of CC_GOOD Service Completion Codes Interpretation CC_GOOD CC_INACTIVE_OBJECT CC_OBJECT_NOT_IN_CLASS CC_TERMINAL_ERROR ALARMID aid2; char *pname; NSCC nscc; Successful service completion The alarm is inactive and its name is undefined The given alarm identifier is not a member of the Alarm class A terminal error occurred when both DIAGNOSTICS and RETURN_FROM_TE_MANAGER are defined. Given the identifier for an alarm, return the pointer to its name string if the alarm is active. If the alarm is active but its name has been defined as a null string ( ), the service returns a null pointer for the alarm s name but the service completion is normal. If the alarm is closed or otherwise inactive, the service returns a null pointer and the Service Completion Code of CC_INACTIVE_OBJECT If the alarm s identifier is not valid, the service returns a null pointer and the Service Completion Code of CC_OBJECT_NOT_IN_CLASS Example /* create an alarm and give it a name */ aid2 = ES_CreateAlarm(&Alrm2props, (NSCC *)0); pname = ES_GetAlarmName(aID2, &nscc); /* find the alarm's name */ if (nscc!= CC_GOOD) /* service failed */ } Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 108 of 214

109 Chapter 8: else /* service was successful */ See Also ES_CreateAlarm Terminal Error Codes (When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE TE_UNUSABLE_OBJECT Function Code given to Terminal Error Handler GET_ALARM_NAME Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 109 of 214

110 Chapter 8: ES_PendAlarm Test and/or synchronize with the expiration of an alarm Prototype Inputs alarmid TICKS ES_PendAlarm(ALARMID alarmid, TICKS waitcode, NSCC *pnscc) Identifier of the alarm to test waitcode An integer representing the number of timebase ticks that indicate what the service is to do if the alarm is active but not yet expired. Only the options NOPEND and UNTIL are permissible for this parameter in this service: Option Meaning NOPEND ((TICKS)0) UNTIL ((TICKS)-1) The caller may be a Foreground entity or a Background task. The service does not block the caller and returns immediately The caller must ONLY be a Background task. If the alarm has not expired, the service blocks the calling task until the alarm expires pnscc Output TICKS > 0 TICKS = 0 Pointer to a variable that is to receive the Service Completion Code as an enumerated value of type NSCC. If defined as a null pointer, ((NSCC *)0), the service will not return a Service Completion Code. If the service returns a Service Completion Code of either CC_ALARM_ACTIVE or CC_ALARM_EXPIRED, the returned value is an integer of type TICKS that represents the number of timebase ticks remaining on the alarm until it reaches its next expiration point. If the service returns a Service Completion Code of CC_ALARM_CANCELLED, the alarm has been previously cancelled and the returned value of TICKS is the number of timebase counter ticks remaining on the alarm at the point of its cancellation. Returned when the Service Completion Code is either CC_ALARM_INACTIVE, CC_ALARM_EXPIRED, or CC_ALARM_WAS_CLOSED, representing when the alarm is not ticking and therefore, inactive, or when the alarm has expired and not recycled, or closed, respectively. Returned if RETURN_FROM_TE_MANAGER is defined and the Service Completion Code is CC_TERMINAL_ERROR. Service Completion Codes Interpretation CC_ALARM_ACTIVE CC_ALARM_INACTIVE CC_ALARM_EXPIRED CC_ALARM_CANCELLED CC_ALARM_WAS_CLOSED The alarm is active at the time of the service call The alarm is inactive but not cancelled, or expired The alarm has expired or has been recycled The alarm was cancelled prior to the service call The alarm was closed by another entity during the time when the task was pending on normal completion of this service Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 110 of 214

111 Chapter 8: CC_TERMINAL_ERROR ALARMID aid1; NSCC nscc; TICKS remainder; A terminal error occurred when both DIAGNOSTICS and RETURN_FROM_TE_MANAGER are defined. Tests the referenced alarm for expiration. If it has expired or is otherwise inactive, the service returns a value of 0 and the appropriate Service Completion Code. If the alarm has been previously cancelled, the service returns the number of timebase ticks remaining on the alarm at the time it was cancelled. If the alarm is active or recycled and the value of the waitcode parameter is NOPEND, the service returns the number of ticks remaining on the alarm until its next expiration and the appropriate Service Completion Code. If the alarm is active or recycled and the value of the waitcode parameter is UNTIL, the service blocks the calling BG task to pend on the expiration of the alarm. When the alarm expires, the service will unblock the task, setting the Service Completion Code to CC_ALARM_EXPIRED and a value of 0 for the number of timebase ticks remaining. If another entity closes the alarm during the time the task is pending for the alarm s expiration, the task will be unblocked with the Service Completion Code CC_ALARM_WAS_CLOSED and the number of timebase ticks the alarm had remaining at the time it was closed. Example aid1 = ES_CreateAlarm(&Alrm1props, (NSCC *)0); ES_ArmAlarm(aID1); /* Arm the alarm to make it active */ remainder = ES_PendAlarm(aID1, NOPEND, &nscc); if (nscc == CC_ALARM_ACTIVE) /* the alarm is active because it is ticking */ } else if (nscc == CC_ALARM_EXPIRED) /* The alarm has expired. See if it was a one-shot or recycled by * looking at the returned value of ticks remaining */ if (remainder > 0) /* The alarm has expired and has been recycled, continuing to * tick in an active state */ } else /* The number of ticks remaining is 0, idicating that the alarm * was a one-shot and is now inactive */ Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 111 of 214

112 Chapter 8: } } else if (nscc == CC_ALARM_CANCELLED) /* The alarm was cancelled and the value returned is the number of * timebase counter ticks remaining on it when it was cancelled */ } else /* The alarm is inactive */ } /* Later on, wait for the alarm to expire */ remainder = ES_PendAlarm(AID1, UNTIL, &nscc) /* Check the Service Completion Code to make sure all is well */ if (nscc!= CC_ALARM_EXPIRED) /* Looks like the alarm was closed during the pend. Deal with it */ } /* Otherwise, all is well. Proceed */ See Also ES_CreateAlarm, ES_ArmAlarm, ES_CancelAlarm Terminal Error Codes (When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE TE_IDLE_TASK_CANNOT_WAIT TE_FGE_CANNOT_WAIT Function Code given to Terminal Error Handler PEND_ALARM Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 112 of 214

113 Chapter 8: ES_ReArmAlarm Arm an active alarm with new duration(s) before its current duration expires Prototype Inputs alarmid init_ticks TICKS ES_ReArmAlarm(ALARMID alarmid, TICKS init_ticks, TICKS cycle_ticks, NSCC *pnscc) Identifier of the alarm to be re-armed An integer of type TICKS defining the number of timebase ticks in the alarm s initial period. A value of 0 is permissible. cycle_ticks An integer of type TICKS defining the number of timebase ticks in the periods subsequent to the alarm s initial period. The parameter may be one of the following: Value Meaning 0 A one-shot alarm. After expiration of the initial period, the alarm becomes inactive >0 Number of ticks in the cyclic periods of the alarm. The alarm remains active after each expiration and remains so until it is cancelled. pnscc Output TICKS > 0 Pointer to a variable that is to receive the Service Completion Code as an enumerated value of type NSCC. If defined as a null pointer, ((NSCC *)0), the service will not return a Service Completion Code. The number of ticks remaining on the active or recycled alarm at the time it was re-armed TICKS = 0 No ticks remaining on the alarm because it is expired, cancelled or only initialized at the time of the service call to re-arm Service Completion Codes Interpretation CC_GOOD CC_ALARM_INACTIVE CC_TERMINAL_ERROR The service competed successfully The given alarm is not closed but is inactive A terminal error occurred when both DIAGNOSTICS and RETURN_FROM_TE_MANAGER are defined. Service to re-arm an active alarm. The service removes the alarm from the active alarm set of the System Timebase and then re-arms it by giving it new expiration time based on the values for its new initial and recycle periods. If the value of init_ticks is greater than zero, the service uses it for the alarm s new initial period and saves the value of cycle_ticks as the alarm s recycle period. However, if the value of init_ticks is zero and the value of cycle_ticks is greater than zero, the service will use the latter for both the alarm s initial and recycle periods. The service rearms the alarm using the new initial period value and inserts it into the active alarm set at a position in accordance with its new expiration time. If the values of both the initial and recycle period parameters are defined as 0, the service will treat the alarm as though it reached an expiration point for a one-shot alarm. The service will make the alarm as though it Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 113 of 214

114 Chapter 8: ALARMID aid1; NSCC nscc; TICKS remainder; has expired and will schedule all defined Event Action Routines for the alarm s ON_EXPIRE event. When finished, the service returns the number of ticks remaining on the active alarm at the time of the service call and the Service Completion Code of CC_GOOD An alarm that is inactive cannot be re-armed and will return a value of 0 ticks remaining and the Service Completion Code CC_ALARM_INACTIVE. Example aid1 = ES_CreateAlarm(&Alrm1props, (NSCC *)0); ES_ArmAlarm(aID1); /* make the alarm active */ /* Assign new durations for the alarm */ remainder = ES_ReArmAlarm(aID1, 100, 200, &nscc); if (nscc!= CC_GOOD) /* the alarm was not re-armed */ } else /* the alarm was re-armed successfully */ See Also ES_CreateAlarm, ES_ArmAlarm Terminal Error Codes (When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE Function Code given to Terminal Error Handler REARM_ALARM Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 114 of 214

115 Chapter 9: Chapter 9 Event Group Class The Event Group class provides a means to associate one or more bits (flags) in an event group object with various events and Boolean operators to determine when a specified those events occur. Event Group Properties For the Novos Foreground environment, use the following event group properties structure when creating a new event group: Properties 9-1 Event Group Properties Structure typedef struct /* Event Group properties structure */ char *pname; /* pointer to name */ EGFLAGS init_flags; /* initial value for Event Group's flags */ } EVGRPPROP; Event Groups Services Event Groups services included in the Novos PPS environment are: Table 9-1 Summary of Event Group Class Services Service Name ES_ClearEventGroupFlags ES_CloseEventGroup Service Clear some flags in an event flag group Discontinue use of an event group Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 115 of 214

116 Chapter 9: Service Name ES_CreateEventGroup ES_DefEventGroupAction ES_FindEventGroup ES_GetEventGroupMSFlag ES_GetEventGroupName ES_PendEventGroupFlags ES_SetEventGroupFlags Service Create an event group and initialize it for subsequent use Define an Event Action Routine to execute if a match is found between the flags in an event group and those is a test mask Find an event group given its name and return its identifier Get the bit number of the most significant bit in the event group s flags Get the name of an event group given its identifier Test for a match with an event group s flags and optionally wait for the match if requestor is a task Set the state of specific set of flags in an event group to 1 s for each of the Event Group class services follow. Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 116 of 214

117 Chapter 9: ES_ClearEventGroupFlags Clear one or more flags in an event group Prototype Inputs egid flags pnscc Output EGFLAGS ES_ClearEventGroupFlags(EVGRPID egid, EGFLAGS flags, NSCC *pnscc) The identifier of the event group in which the service is to clear the specified flags The flags (bits) in the event group, egid, the service is to clear Pointer to a variable that is to receive the Service Completion Code as an enumerated value of type NSCC. If defined as a null pointer, ((NSCC *)0), the service will not return a Service Completion Code. EGFLAGS The state of flags in the referenced event group before the service was called Service Completion Codes Interpretation CC_GOOD CC_TERMINAL_ERROR EVGRPID egid1; EGFLAGS oldflags; NSCC nscc; The service always completes successfully A terminal error occurred when both DIAGNOSTICS and RETURN_FROM_TE_MANAGER are defined. The service clears the defined flags in the referenced event group, egid, returning the state of flags in the event group prior to clearing them. Example /* create an event group */ egid1 = ES_CreateEventGroup(&EGprops, (NSCC *)0); /* set its flags to 0xBFEF */ ES_SetEventGroupFlags(egID1, (EGFLAGS)0xBFEF, (NSCC *)0); /* clear flags to get 0xABCD */ oldflags = ES_ClearEventGroupFlags(egID1, (EGFLAGS)0x1422, &nscc); See Also ES_CreateEventGroup, ES_SetEventGroupFlags Terminal Error Codes (When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE Function Code given to Terminal Error Handler CLEAR_EVENTGROUP_FLAGS Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 117 of 214

118 Chapter 9: ES_CloseEventGroup Discontinue use of an event group Prototype Inputs NSCC ES_CloseEventGroup(EVGRPID egid) egid Identifier of the event group that the service is to close Output NSCC The Service Completion Code Service Completion Codes Interpretation CC_GOOD CC_TERMINAL_ERROR EVGRPID egid; NSCC nscc; The service completed successfully A terminal error occurred when both DIAGNOSTICS and RETURN_FROM_TE_MANAGER are defined. Service to discontinue use of an event group. The service closes the event group, releasing it to the pool of free event groups so that it can be reused in the future. The service also removes all defined Event Action Routine associations for the event group s events. If there are any BG tasks pending on the event group, the service will unblock them, put them into the Background Ready Queue with respect to their priorities and those of the other tasks in the queue, and set up the Service Completion Code of CC_EVENT_GROUP_WAS_CLOSED to indicate to each task when it is next released that the pending operation did not complete and why. When it completes successfully, the service returns the Service Completion Code CC_GOOD. Example egid = ES_CreateEventGroup(&EGprops, (NSCC *)0); nscc = ES_CloseEventGroup(egID); /* close the event group */ if (nscc!= CC_GOOD) /* the service failed with terminal error for some reason */ } else /* the service closed the event group successfully */ Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 118 of 214

119 Chapter 9: See Also ES_CreateEventGroup, ES_DefEventGroupAction, ES_PendEventGroupFlags Terminal Error Codes (When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE Function Code given to Terminal Error Handler CLOSE_EVENTGROUP Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 119 of 214

120 Chapter 9: ES_CreateEventGroup Create an event group and initialize its properties Prototype Inputs pegprop EVGRPID ES_CreateEventGroup(EVGRPROP *pegprop, NSCC *pnscc) Pointer to the event group properties structure for the new event group Pointer to a variable that is to receive the Service Completion Code as pnscc an enumerated value of type NSCC. If defined as a null pointer, ((NSCC *)0), the service will not return a Service Completion Code. Output EVGRPID Identifier of the newly created event group Service Completion Codes Interpretation CC_GOOD CC_TERMINAL_ERROR EVGRPID egid; The service successfully created the event group The terminal error TE_INSUFFICIENT_SYSTEM_RAM occurs when RETURN_FROM_TE_MANAGER is defined Create a new event group and initialize its flag settings to the value stored in the specified event group properties structure. Example /* Create a new event group and initialize it */ egid = ES_CreateEventGroup(&EGprops, (NSCC *)0); /* the service was assumed to be succesful */ See Also Terminal Error Codes TE_INSUFFICIENT_SYSTEM_RAM (Can occur when DIAGNOSTICS undefined) Function Code given to Terminal Error Handler CREATE_ EVENTGROUP Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 120 of 214

121 Chapter 9: ES_DefEventGroupAction Define an Event Action Routine to be associated with a match a set of the event group s Prototype Inputs eventid tmask NSCC ES_DefEventGroupAction(EVGRPID eventid, EGFLAGS tmask, FLAGOP flgop, EAR_OPTION option, EARID earid, int userdata) Identifier of the event group for which the event action is to be defined The flags that the service compares to the event group s flags. When the flags in tmask match the flags in the event group, according to the operation specified in flgop, the service will deem it a match and will schedule the defined EAR. flgop The Boolean operator, AND or OR, to apply when comparing the flags in the event group and tmask, and what to do with the flags in case of a match. The two actions are expressed as an enumerated value of type FLAGOP. Legal values are: FLAGOP Value OR_NOCLEAR AND_NOCLEAR OR_CLEAR AND_CLEAR If any of the flags in the event group match those in tmask, a match event occurs. Do not clear the matching flags in the event group If all of the flags in the event group are in the same state as those in tmask, a match event occurs. Do not clear the matching flags in the event group If any of the flags in the event group match those in tmask, a match event occurs. Clear the matching flags in the event group If all of the flags in the event group are in the same state as those in tmask, a match event occurs. Clear the matching flags in the event group Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 121 of 214

122 Chapter 9: option An enumerated value that represents what the service is to do with respect to the EAR and the alarm. The permissible values are: EAR Option Option ONE_SHOT DEFINE_AND_LOCK CLEAR_ONE_EAR CLEAR_ONE_EVENT CLEAR_ALL_EVENTS The association between the event group and the Event Action Routine will exist only until the next occurrence of a match between tmask and the event group s flags. The association between the event group and the Event Action Routine will exist for all subsequent occurrences of a match between tmask and the event group s flags. Discontinue the association of the specified Event Action Routine with the match event on the referenced event group Discontinue all Event Action Routine associations with the match event on the referenced event group Discontinue all Event Action Routine associations with the match event on the referenced event group earid userdata Output NSCC Service Completion Codes CC_GOOD CC_TERMINAL_ERROR Identifier of the Event Action Routine to invoke when tmask matches the event group s flags according to the condition defined by the flgop parameter. The EAR must have been previously defined. An integer to be passed to the EAR upon its being scheduled for execution when a match occurs between tmask and the event group s flags. Depending on how the EAR was created, it may or may not use this parameter The Service Completion Code Interpretation Normal completion of the service A terminal error occurred when DIAGNOSTICS and RETURN_FROM_TE_MANAGER are both defined Associate a previously created Event Action Routine with an event group event. The expected event is a match, with respect to the Boolean operator defined in the flgop value, between the flags in the event group and the flags in a comparator mask, defined by the parameter tmask. The type of association of the EAR and the event group is given by the option parameter. If the option parameter is either ONE_SHOT or DEFINE_AND_LOCK, the service will compare the event group s flags against tmask. If it finds a match, it will schedule the Event Action Routine for immediate execution. Otherwise, the service ends. Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 122 of 214

123 Chapter 9: ALARMID aid1; EARID earid; NSCC nscc; This service is also used to discontinue the associations between one or more Event Action Routines and the match event as previously described in the table for the EAR_OPTION parameter, option. Example /* create an event group */ aid1 = ES_CreateAlarm(&EvGrp1props, (NSCC *)0); /* create an EAR */ earid = ES_CreateEAR(&EAR1Props, (NSCC *)0); /* Associate the EAR with the event group for the next match event */ nscc = ES_DefEventGroupAction(aID1, 0x012F, OR_CLEAR, ONE_SHOT, earid, 0); if (nscc!= CC_GOOD) /* Can t define the event group action. Determine how to proceed */ } else /* Association made. Proeed with application */ } See Also ES_CreateEventGroup, ES_SetEventGroupFlags, ES_CreateEAR Terminal Error Codes (When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE TE_ILLEGAL_EVENT_FLAG_OPERATION TE_TEST_MASK_CANNOT_BE_ZERO TE_ILLEGAL_EAR_ID Function Code given to Terminal Error Handler DEF_EVENTGROUP_ACTION For this service, the EAR_OPTION values of CLEAR_ONE_EVENT and CLEAR_ALL_EVENTS produce identical results because there is only one event available on an event group object. Either value may be used. Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 123 of 214

124 Chapter 9: ES_FindEventGroup Get the identifier of an Event Group given its name Prototype Inputs pname pnscc Output EVGRPID > 0 EVGRPID ES_FindEventGroup(char *pname, NSCC *pnscc) Pointer to character string holding the name of the event group the service is to find Pointer to a variable that is to receive the Service Completion Code as an enumerated value of type NSCC. If defined as a null pointer, ((NSCC *)0), the service will not return a Service Completion Code. Identifier of the event group whose name matches the string defined by pname EVGRPID = 0 An event group was not found with a name that matches the pname string. Service Completion Codes Interpretation CC_GOOD Normal completion of the service CC_NO_SUCH_NAME_IN_CLASS No match found with name given by pname EVGRPID egid1; NSCC nscc; Find the event group whose name matches the given name in the string pname and return its identifier. If the service does not find a match, it returns a value of 0. Example /* find the event group named EventGrp1 */ egid1 = ES_FindEventGroup("EventGrp1", &nscc); if (nscc!= CC_GOOD) /* event group not found. Figure out why */ } else /* Name was found and we can proceed */ See Also ES_CreateEventGroup, ES_GetEventGroupName Terminal Error Codes (When DIAGNOSTICS defined) none Function Code given to Terminal Error Handler FIND_EVENTGROUP Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 124 of 214

125 Chapter 9: ES_GetEventGroupMSFlag Get the bit position of the most significant flag in an event group Prototype Inputs egid KCOUNT ES_GetEventGroupMSFlag(EVGRPID egid, FLAGOP optype, NSCC *pnscc) Identifier of the event group the service is to use optype pnscc The type of clearing operation the service is to perform on the event group, expressed as an enumerated value of type FLAGOP. Legal values are: FLAGOP Value OR_NOCLEAR AND_NOCLEAR OR_CLEAR AND_CLEAR Do not clear the flag in the most significant position in the event group Do not clear the flag in the most significant position in the event group (has same effect as OR_NOCLEAR) Clear the flag in the most significant position in the event group Clear the flag in the most significant position in the event group (same as OR_CLEAR) Pointer to a variable that is to receive the Service Completion Code as an enumerated value of type NSCC. If defined as a null pointer, ((NSCC *)0), the service will not return a Service Completion Code. Output KCOUNT The bit position of the most significant flag in the event group expressed as a value of type KCOUNT Service Completion Codes Interpretation CC_GOOD CC_TERMINAL_ERROR EVGRPID egid1; uint Msflag; NSCC nscc; The service completed successfully A terminal error occurred when both DIAGNOSTICS and RETURN_FROM_TE_MANAGER are defined. The service locates the most significant flag in the event group that is in a 1 state and returns its bit position number as an unsigned integer having a value of 1-16, where 16 is the most significant bit and 1 is the least significant bit position of the event group s flags. If the event group s flags are all in a 0 state, the service returns a value of 0. The FLAGOP parameter determines whether the service clears the flag or not after determining its position. All other flags in the event group remain unchanged. Unless there is a terminal error, the Service Completion Code is CC_GOOD. Example Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 125 of 214

126 Chapter 9: /* create a new event group and initialize it /* egid1 = ES_CreateEventGroup(&Egprops, (NSCC *)0); /* Set its flags to 0x0BCD */ ES_SetEventGroupFlags(egID1, (EGFLAGS)0x0BCD); /* Now get position of the event group s most significant flags, which ** should be bit 12 (as in 0x0BCD). Clear the flag afterwards */ Msflag = ES_GetEventGroupMSFlag(egID1, OR_CLEAR, &nscc); /* At this point, the event group s flags should be 0x03CD */ if (Msflag == 12) /* Bit 12 is set. Handle it and proceed with application */ } See Also ES_ClearEventGroupFlags, ES_SetEventGroupFlags Terminal Error Codes (When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE Function Code given to Terminal Error Handler GET_EVENTGROUP_MSFLAG Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 126 of 214

127 Chapter 9: ES_GetEventGroupName Get the name of an event group given its identifier Prototype Inputs egid pnscc Output char * > 0 char * = 0 char * ES_GetEventGroupName(EVGRPID egid, NSCC *pnscc) Identifier of the event group that the service is to find and return a pointer to its name Pointer to a variable that is to receive the Service Completion Code as an enumerated value of type NSCC. If defined as a null pointer, ((NSCC *)0), the service will not return a Service Completion Code. Pointer to the given event group s name string Case 1: The given event group identifier is not found in the Event Group class as confirmed by the Service Completion Code of CC_OBJECT_NOT_IN_CLASS Case 2: The given event group and its name are inactive as confirmed by the Service Completion Code CC_INACTIVE_OBJECT Case 3: The given event group identifier is correct and the event group was found but its name string in null (i.e., defined by ) as confirmed by the Service Completion Code of CC_GOOD Service Completion Codes Interpretation CC_GOOD CC_INACTIVE_OBJECT CC_OBJECT_NOT_IN_CLASS CC_TERMINAL_ERROR EVGRPID egid; NSCC nscc; char *pname; Successful service completion The event group is inactive and its name is undefined The given event group identifier is not a member of the Event Group class A terminal error occurred when both DIAGNOSTICS and RETURN_FROM_TE_MANAGER are defined. Given the identifier for an event group, return the pointer to its name string if the event group is active. If the event group is active but its name has been defined as a null string ( ), the service returns a null pointer for the event group s name. In either case, the service returns a Service Completion Code of CC_GOOD. If the event group is closed or otherwise inactive, the service returns a null pointer and the Service Completion Code of CC_INACTIVE_OBJECT If the event group s identifier is not valid, the service returns a null pointer and the Service Completion Code of CC_OBJECT_NOT_IN_CLASS Example /* create a new event group and give it some name */ egid = ES_CreateEventGroup(&Egprops, (NSCC *)0); Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 127 of 214

128 Chapter 9: /* somewhere else, get the event group s name */ pname = ES_GetEventGroupName(egID, &nscc); if (nscc!= CC_GOOD) /* the event group is undefined or it identifier is not legit */ } else /* The event group was found and pname points to its name */ See Also ES_CreateEventGroup, ES_FindEventGroup Terminal Error Codes (When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE TE_UNUSABLE_OBJECT Function Code given to Terminal Error Handler GET_EVENTGROUP_NAME Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 128 of 214

129 Chapter 9: ES_PendEventGroupFlags Test an event group for the presence of specified event flags Prototype Inputs egid tmask EGFLAGS ES_PendEventGroupFlags(EVGRPID egid, EGFLAGS tmask, FLAGOP optype, TICKS waitcode, NSCC *pnscc) Identifier of the event group that the service is to test for the presence of the event flags specified by tmask The event flags for which the service is to test the event group to determine if they are set optype waitcode The type of testing operation the service is to perform on the event group, expressed as an enumerated value of type FLAGOP. Legal values are: FLAGOP Value OR_NOCLEAR AND_NOCLEAR OR_CLEAR AND_CLEAR If any of the flags in the event group match those in tmask, a match event occurs. Do not clear the matching flags in the event group If all of the flags in the event group are in the same state as those in tmask, a match event occurs. Do not clear the matching flags in the event group If any of the flags in the event group match those in tmask, a match event occurs. Clear the matching flags in the event group If all of the flags in the event group are in the same state as those in tmask, a match event occurs. Clear the matching flags in the event group An integer of type TICKS representing the number of timebase ticks that indicate what the service is to do if there is no match between the event group s flags and tmask. If there is a match, the service will complete successfully and ignore this parameter. There are three options for this parameter: Option Meaning >0 NOPEND ((TICKS)0) An integer of type TICKS having a value greater than 0 that represents the number of timebase ticks within which the service is expected to complete. The caller using this option must ONLY be a Background task as the service may block the caller. The caller may be a Foreground entity or a Background task. The service does not block the caller and returns immediately. Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 129 of 214

130 Chapter 9: UNTIL ((TICKS)-1) The caller using this option must ONLY be a Background task as the service may block the caller. pnscc Output EGFLAGS > 0 Pointer to a variable that is to receive the Service Completion Code as an enumerated value of type NSCC. If defined as a null pointer, ((NSCC *)0), the service will not return a Service Completion Code. The flags in the event group that match the flags in tmask, according to the comparison method specified by the FLAGOP parameter, optype. EGFLAGS = 0 No flags in the event group match the flags in tmask, according to the comparison method specified by the FLAGOP parameter, optype. Service Completion Codes Interpretation CC_MATCH CC_NO_MATCH CC_TIMEOUT CC_EVENT_GROUP_WAS_CLOSED CC_TERMINAL_ERROR The event flags defined by tmask matched the content of the event group, according to the comparison method specified by FLAGOP. The service returns those flags in the event group that match tmask, according to the chosen comparison method specified by optype. The event flags defined by tmask did not match the content of the event group, according with the comparison method specified by FLAGOP. The service returns a value of 0 of type EGFLAGS The service failed to complete successfully within the amount of time specified by the number of timebase ticks given by the value of the waitcode parameter. The service was terminated before the service could complete because the event group on which the task was pending was closed by another entity. A terminal error occurred when both DIAGNOSTICS and RETURN_FROM_TE_MANAGER are defined. The content of the given event group is compared to the bits specified by tmask to determine if there is a match. The comparison may be a logical OR or logical AND as determined by the selected value of FLAGOP. The logical OR condition will produce a match if any bit tmask in a 1 state matches the corresponding bit in the event group that is also in a 1 state. The logical AND condition will produce a match if and only if all of the bits in tmask that are in a 1 state exactly match the corresponding bits in the event group that are also in a 1 state. Whether the caller is a Foreground entity or a Background task, if there is no match between the contents of the event group s flags and the bits in tmask and the waitcode is NOPEND, the service will return control Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 130 of 214

131 Chapter 9: to the caller immediately with the Service Completion Code CC_NO_MATCH. When the caller is a Background Task and there is no match and the waitcode is either a number of timebase ticks or UNTIL, the service will block the caller and add it to the list of tasks pending for the expected match. If waitcode has a value of UNTIL, the BG task will stay pended until the expected match occurs, regardless of how long that may take. When the match occurs, the service returns a Service Completion Code of CC_MATCH. But if waitcode specifies a number of timebase ticks, the service will use that value to establish a time within which the service expects to complete. If there is a match that occurs before the expected completion time expires, the service will return the Service Completion Code CC_MATCH and cancel the expected timeout. But if the expected completion time expires and no match has occurred, the service will return the Service Completion Code CC_TIMEOUT. If another entity closes the event group during the time that the task is pending for the expected match, the service will return the Service Completion Code CC_EVENT_GROUP_WAS_CLOSED. When an expected event occurs, the event group s flags may be left asis or cleared, depending on the chosen value of the optype parameter. EVGRPID egid1; ECB *pecb; EGFLAGS matchflags = 0; EGFLAGS currflags; NSCC nscc; Example /* create an event group and initialize it */ egid1 = ES_CreateEventGroup(&EGprops, (NSCC *)0); /* Set the event group s event flags to 0xABCD */ ES_SetEventGroupFlags(egID1, 0xABCD); /* Test flags to see of any of the bits in the mask (=0x048A) ** are set but do not clear the bits in the event group is there ** is a match */ matchflags = ES_PendEventGroupFlags(egID1, 0x048A, OR_NOCLEAR, UNTIL, &nscc); if (nscc == CC_MATCH) /* a match occurred. The value of the matching flags are ** returned by the service. See what matched and act accordingly */ if (matchflags!= (EGFLAGS)0x0088) } } else Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 131 of 214

132 Chapter 9: /* there was no match */ } /* Get the current state of the event group s flags */ currflags = ES_PendEventGroupFlags(egID1, (EGFLAGS)~0, OR_NOCLEAR, NOPEND, &nscc); See Also ES_CreateEventGroup, ES_SetEventGroupFlags, ES_CloseEventGroup Terminal Error Codes (When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE IDLE_TASK_CANNOT_WAIT TE_ILLEGAL_EVENT_FLAG_OPERATION TE_INSUFFICIENT_SYSTEM_RAM Function Code given to Terminal Error Handler PEND_EVENTGROUP_FLAGS This service can be used to read the current state of the flags in and event group. Simply use the tmask parameter as a value set to all 1 bits (e.g., ((EGFLAGS)~0), the optype parameter as OR- _NOCLEAR and the waitcode parameter as NOPEND. The returned value of EGFLAGS will be the current flag settings in the event group. Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 132 of 214

133 Chapter 9: ES_SetEventGroupFlags Set the flags in an event group to a specified value Prototype Inputs NSCC ES_SetEventGroupFlags(EVGRPID egid, EGFLAGS Eflags) egid Identifier of the event group for which the service is to set its flags to the value specified by Eflags Eflags The event flags that the service is to set in the event group. Output NSCC The Service Completion Code Service Completion Codes Interpretation CC_GOOD CC_TERMINAL_ERROR EVGRPID egid1; EGFLAGS flags; NSCC nscc; The service completed successfully A terminal error occurred when both DIAGNOSTICS and RETURN_FROM_TE_MANAGER are defined. The bits in a 1 state in the value specified by Eflags are added to the existing flags in the event group by a logical OR operation. The bits in the event group s flags not corresponding to the 1 bits in Eflags remain unchanged. For each test mask and associated Event Action Routine, as previously defined by a call to ES_DefEventGroupAction, the service will determine if there is a match with the event group s updated flags. If there is a match, the service will schedule the associated Event Action Routine. The state of the event group s flags will then be cleared or not, according to the FLAGOP specification given in the previous call to ES_DefEventGroupAction. There can be multiple BG tasks pending on a match between the flags in the event group and a particular test mask defined by the BG task s previous call to the ES_PendEventGroupFlags service. There is one test mask per pending task. The service will examine each test mask in turn to determine if a match exists with the updated flags in the event group. If the service finds a match, it removes the associated BG task from the list of pending tasks, unblocks it and puts it into the Background Ready Queue with respect to its priority and those of the other ready BG tasks. If the BG task employed a timed wait within which it expected to complete its ES_PendEventGroupFlags request, this service deactivates it. When all tests are complete, the service returns a Service Completion Code of CC_GOOD. Changes made to the Background Ready Queue by this service may result in a context switch. If the caller is a Foreground entity, any change to the Background Ready Queue as a result of this service will not take effect until all Foreground operations are complete. Example /* Set the flags in event group egid1to 0xABCD */ ES_SetEventGroupFlags(egID1, (EGFLAGS)0xABCD); Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 133 of 214

134 Chapter 9: /* Then set the flags in the second nibble to all 1s */ ES_SetEventGroupFlags(egID1, (EGFLAGS)0x0F00); /* Use ES_PendEventFlags service to get the event group s current flag ** states, which should now be 0xAFCD */ if((flags = ES_PendEventGroupFlags(egID1, (EGFLAGS)~0, OR_NOCLEAR, NOPEND, &nscc))!= 0xAFCD) /* Something failed. Deal with it */ } else /* Flags were OK. Proceed with application */ See Also ES_ClearEventGroupFlags, ES_GetEventGroupFlags, ES_DefEventGroupAction Terminal Error Codes (When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE Function Code given to Terminal Error Handler SET_EVENTGROUP_FLAGS Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 134 of 214

135 Chapter 10: Chapter 10 Queue Class The Queue class provides a means to pass data between execution entities in FIFO or LIFO order. Queue Properties For the Novos Preemptive Priority Scheduling environment, use the following queue properties structure when creating a new queue: Properties 10-1 Queue Properties Structure typedef struct /* Queue properties structure */ char *pname; /* pointer to name */ char *pbody; /* base address of queue body */ KCOUNT entrysize; /* number of bytes in an entry */ KCOUNT nentries; /* depth of queue, in entries of width bytes */ } QUEUEPROP; Queue Services Services for the Queue class included in this environment are: Table 10-1 Summary of Queue Class Services Service Name ES_CloseQueue ES_CreateQueue Discontinue use of a queue Service Create a queue and initialize it for subsequent use Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 135 of 214

136 Chapter 10: Service Name ES_DefQueueAction ES_DequeueData ES_EnqueueData ES_FindQueue ES_GetQueueName ES_GetQueueSize Service Define an Event Action Routine to execute if the given queue transitions from an Empty to Not_Empty state or from a Full to a Not_Full state Get or peek at an entry at the head or the tail of a given queue Put data into a given queue at its tail or at its head Find a queue given its name and return its identifier Get the name of a queue given its identifier Get the current size of a given queue s for each of the Queue class services follow. Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 136 of 214

137 Chapter 10: ES_CloseQueue Discontinue use of a given queue Prototype Inputs NSCC ES_CloseQueue(QUEUEID qid) qid Identifier of the queue that the service is to close Output NSCC The Service Completion Code Service Completion Codes Interpretation CC_GOOD CC_TERMINAL_ERROR QUEUEID qid; NSCC nscc; The service completed successfully A terminal error occurred when both DIAGNOSTICS and RETURN_FROM_TE_MANAGER are defined. Service to discontinue use of a queue. If there are any BG tasks pending on the queue, the service will unblock them and set up the Service Completion Code of CC_QUEUE_WAS_CLOSED to indicate to each task when it is next released that the pending operation did not complete and why. If the queue body was allocated from RAM at the time of the queue s creation, that RAM is assigned to the Used Block List with respect to its size so that it will be available for future use. Otherwise, the service closes the queue, releasing it to the pool of free queues so that it can be reused in the future. The service also removes all defined Event Action Routine associations for all the queue s events. When finished successfully, the service returns a Service Completion Code of CC_GOOD Example /* create a new queue */ egid = ES_CreateQueue(&Qprops, (NSCC *)0); ES_CloseQueue(qID); /* close the queue */ /* the service closed the queue successfully */ See Also ES_CreateQueue; ES_DefQueueAction, ES_DequeueData, ES_EnqueueData Terminal Error Codes (When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE Function Code given to Terminal Error Handler CLOSE_QUEUE Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 137 of 214

138 Chapter 10: ES_CreateQueue Create a new queue and define its properties Prototype Inputs pqprops QUEUEID ES_CreateQueue(QUEUEPROP *pqprops, NSCC *pnscc) Pointer to the queue properties structure for the new queue Pointer to a variable that is to receive the Service Completion Code as pnscc an enumerated value of type NSCC. If defined as a null pointer, ((NSCC *)0), the service will not return a Service Completion Code. Output QUEUEID Identifier of the newly created queue Service Completion Codes Interpretation CC_GOOD CC_TERMINAL_ERROR QUEUEID qid; NSCC nscc; The service completed successfully The terminal error TE_INSUFFICIENT_SYSTEM_RAM occurs when RETURN_FROM_TE_MANAGER is defined Create a new queue and initialize it to the values stored in the specified queue properties structure. The number of bytes of RAM in the queue body is the product of the size of an entry in the queue, as specified by the property entrysize, and the property specifying the number of entries in the queue, nentries. If the queue property, pbody, is given as a non-null value, the service will use it as the address of the queue body. If the value of pbody is defined as null, the service will first attempt to allocate the required amount of RAM for the queue body from the Used RAM List. If a used block of the required size is not found, the service will attempt to allocate the queue body from User RAM. If insufficient User RAM exists to complete this request successfully, the service will consider it a terminal error. Upon successful creation, the service returns a Service Completion Code of CC_GOOD. At time of creation, the queue does not contain any entries and no Event Action Routines are defined for the queue s events. Example /* Create a new queue and initialize it */ qid = ES_CreateQueue(&Qprops, &nscc); /* See if the serevice was succesful */ if (nscc!= CC_GOOD) /* Control will be here only if there is a terminal error when * RETURN_FROM_TE_MANAGER is defined */ } else Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 138 of 214

139 Chapter 10: See Also /* The service completed succedssfully */ Terminal Error Codes ES_GetQueueSize TE_INSUFFICIENT_SYSTEM_RAM (Can occur when DIAGNOSTICS undefined) Function Code given to Terminal Error Handler CREATE_QUEUE Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 139 of 214

140 Chapter 10: ES_DefQueueAction Define an Event Action Routine to take on a specific queue transition event Prototype Inputs queueid NSCC ES_DefQueueAction(QUEUEID queueid, QUEUE_EVENT qevent, EAR_OPTION option, EARID earid, int userdata) Identifier of the queue to associate with the transition event and the EAR qevent The enumerated value of the queue event that invokes the defined action. Permissible values are: Queue Events Q_NOT_EMPTY Q_NOT_FULL Q_EMPTY Q_FULL The queue transitions from a state of Empty to Not_Empty The queue transitions from a state of Full to Not_Full. The queue transitions from a state of Not_Empty to Empty The queue transitions from a state of Not_Full to Full option An enumerated value that represents what the service is to do with respect to the EAR and the alarm. The permissible values are: EAR Option Option ONE_SHOT DEFINE_AND_LOCK CLEAR_ONE_EAR CLEAR_ONE_EVENT CLEAR_ALL_EVENTS The association between the queue and the Event Action Routine will exist only until the next occurrence of the queue event defined by the qevent parameter. The association between the queue and the Event Action Routine will exist for all subsequent occurrences of the defined queue event until the association is discontinued Discontinue the association of the specified Event Action Routine with the specified queue event on the referenced queue Discontinue all Event Action Routine associations with the specified queue event on the referenced queue Discontinue all Event Action Routine associations with all queue events on the referenced queue Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 140 of 214

141 Chapter 10: earid userdata Output NSCC Service Completion Codes CC_GOOD CC_TERMINAL_ERROR QUEUEID qid1; EARID earid; char Source; NSCC nscc; Identifier of the Event Action Routine to invoke when the queue state transitions to the event defined by the qevent parameter. The EAR must have been previously defined. Integer to be passed to the EAR upon its being scheduled for execution when the specified queue state transition event occurs. Depending on how the EAR was created, it may or may not use this parameter The Service Completion Code Interpretation Normal completion of the service A terminal error occurred when DIAGNOSTICS and RETURN_FROM_TE_MANAGER are both defined Associate an Event Action Routine with a queue event as defined by the qevent parameter, so that when the event occurs, the Event Action Routine will be executed. The given Event Action Routine action must be previously defined. This service is used to discontinue the association between one or more Event Action Routines and one or more queue events as previously described in the table for EAR_OPTION parameter, option. Example qid1 = ES_CreateQueue(&Queue1props, (NSCC *)0); /* create a queue */ earid = ES_CreateEAR(&Q1earProps, (NSCC *)0); /* create an EAR */ /* Define EAR to execute when queue transitions from Empty to * Not_Empty, passing the queue s identifier to the EAR */ nscc = ES_DefQueueAction(qID1, QNE, DEFINE_AND_LOCK, earid, (int)qid1); if (nscc!= CC_GOOD) /* Can t define the queue action. Determine how to proceed */ } /* When the action routine is successfully defined, continue */ Source = A ; /* Put the data into the queue. If the queue becomes Not-Empty, * as a result, the defined EAR for the QNE event will be scheduled * to execute when the ES_EnqueueData service completes */ nscc = ES_EnqueueData(qID1, &Source, NOPEND); if (nscc == CC_GOOD) Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 141 of 214

142 Chapter 10: See Also /* The enqueue was successful ES_CreateQueue, ES_DequeueData, ES_EnqueueData, ES_CreateEAR Terminal Error Codes (When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE TE_ILLEGAL_QUEUE_EVENT Function Code given to Terminal Error Handler DEF_QUEUE_ACTION Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 142 of 214

143 Chapter 10: ES_DequeueData Get an entry from a queue Prototype Inputs qid pdest NSCC ES_DequeueData(QUEUEID qid, void *pdest, QMODE mode, TICKS waitcode) Identifier of the queue from which the service gets the data Pointer to the destination address where the service is to put the data once it has been removed from the queue mode Enumerated value of type QMODE that defines the end of the queue from which the service is to get the data entry from the queue: Transfer Mode TAIL HEAD TAIL_PEEK HEAD_PEEK Get data from tail end of queue and update queue control parameters Get data from front end of queue and update queue control parameters Look at the data at the tail end of the queue but do not update queue control parameters Look at the entry at the front end of the queue but do not update queue control parameters waitcode An integer representing the number of timebase ticks that indicate what the service is to do if the queue is Empty. If the queue is Not_Empty, the service will complete successfully and ignore this parameter. There are three options for this parameter: Option Meaning >0 NOPEND ((TICKS)0) UNTIL ((TICKS)-1) An integer of type TICKS having a value greater than 0 that represents the number of timebase ticks within which the service is expected to complete. The caller using this option must ONLY be a Background task as the service may block the caller. The caller may be a Foreground entity or a Background task. The service does not block the caller and returns immediately. The caller using this option must ONLY be a Background task as the service may block the caller. Output NSCC The Service Completion Code. Service Completion Codes Interpretation Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 143 of 214

144 Chapter 10: CC_GOOD CC_QUEUE_EMPTY CC_TIMEOUT CC_QUEUE_WAS_CLOSED CC_TERMINAL_ERROR The service completed successfully The service returned no data because there was none in the queue The service failed to complete successfully within the amount of time specified by the number of timebase ticks specified by the waitcode parameter. The service was terminated before the service could complete because the queue on which the task was pending was closed by another entity. A terminal error occurred when both DIAGNOSTICS and RETURN_FROM_TE_MANAGER are defined. The service attempts to get an entry from the queue. If the queue contains at least one entry, the service will complete successfully regardless of the value of the waitcode parameter. To complete the request successfully, the service moves the number of bytes defined by the queue s entrysize property from the queue to the location given by the pdest parameter with respect to the option given by the mode parameter. The service may update the queue s control parameters, depending on the mode parameter. If the mode parameter is either TAIL_PEEK or HEAD_PEEK, the service does not update the queue s control parameters and the data remains in the queue. Otherwise, the service updates the queue s control structure. If the queue transitions from Full to Not_Full as a result of successful operation of this service, there may be a BG task pending due to an attempt to put an entry into the queue when it was Full. If so, this service will remove the first BG task in the queue s list of pending tasks, cancel any related expected completion time period and put the pended BG task into the Background Ready Queue with respect to its priority and those of the other BG tasks in the Background Ready Queue. Depending on the priorities of the Current Task and the released BG task, a context switch may result. When the queue contains just one entry at the time of this service, successful completion of this service will cause the queue to transition from Not_Empty to Empty. If the queue transitions from Full to Not_Full or Not_Empty to Empty as a result of this service and there is an Event Action Routine associated with either the Q_NOT_FULL or Q_EMPTY event, respectively, the service will schedule execution of any associated EARs. If no EARs are defined for either event, the service is complete and returns a Service Completion Code of CC_GOOD. If the service finds the queue to be Empty and the waitcode parameter is NOPEND, it is unable to complete successfully and immediately returns a Service Completion Code of CC_QUEUE_EMPTY to the calling entity. A BG task and a Foreground entity can invoke this service with the waitcode parameter NOPEND. However, a Foreground entity must use the waitcode parameter NOPEND because it cannot pend if the service is unable to complete successfully. Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 144 of 214

145 Chapter 10: QUEUEID qid; NSCC nscc; char entry; char destchar; When the Current Task invokes this service and the queue is Empty and the waitcode parameter other than NOPEND, the service will block the Current Task in the expectation that it can complete successfully in the future. The service s further actions depend on the value of the waitcode parameter. For a waitcode parameter having a value greater than zero but less than the value of UNTIL, the service will establish a time period as a value of type TICKS within which the service is expected to complete successfully. For a waitcode parameter of UNTIL, no such time period is established because the BG task will pend as long as it takes for the service to complete successfully. When it is unable to get an entry from the queue, the Current Task will pend until another entity puts an entry into the queue, allowing the task to resume, or until the expected completion time expires, whichever occurs first. If the BG service resumes due to expiration of the expected completion time, the service is unable to complete successfully and returns a Service Completion Code of CC_TIMEOUT, making no changes to the queue s control parameters. Otherwise, the service will complete successfully and returns a Service Completion Code of CC_GOOD. The Service Completion Code CC_QUEUE_WAS_CLOSED is returned only when the requesting BG task is pending completion of this service and another entity closes the queue. It is the user s responsibility to detect this completion code and to take any appropriate measures. Example /* create a queue that has 1-byte entry size */ qid = ES_CreateQueue(&Q2props, (NSCC *)0); entry = A ; /* put some data into the queue */ ES_EnqueueData(qID, &entry, TAIL, NOPEND); /* get an entry from the head of the queue. It will not return until ** it has completed sucessfully, in which case the returned Service ** Completion Code is always CC_GOOD unless the queue was closed */ if (ES_DequeueData(qID, &destchar, HEAD, UNTIL) == CC_QUEUE_WAS_CLOSED) /* the service failed because the queue was closed. Deal with it */ } else /* The service succeeded. Process the data in destchar */ Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 145 of 214

146 Chapter 10: See Also ES_CreateQueue, ES_EnqueueData, ES_DefQueueAction, ES_CloseQueue Terminal Error Codes (When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE TE_ILLEGAL_TRANSFER_MODE TE_MUST_USE_0_TICKS_OR_NOPEND Function Code given to Terminal Error Handler DEQUEUE_DATA Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 146 of 214

147 Chapter 10: ES_EnqueueData Put an entry into a queue Prototype Inputs qid psource NSCC ES_EnqueueData(QUEUEID qid, void *psource, QMODE mode, TICKS waitcode) Identifier of the queue into which the service puts the data Pointer to the source address of the data that the service is to put into the queue mode Enumerated value of type QMODE that defines the end of the queue where the service is to put the new data entry: Transfer Mode TAIL HEAD Move the entry data from the source address, psource, to the tail of the queue Move the entry data from the source address, psource, to the head of the queue waitcode An integer representing the number of timebase ticks that indicate what the service is to do if the queue is Full. If the queue is Not_Full, the service will complete and ignore this parameter. There are three options for this parameter: Option Meaning >0 NOPEND ((TICKS)0) UNTIL ((TICKS)-1) An integer of type TICKS having a value greater than 0 that represents the number of timebase ticks within which the service is expected to complete. The caller using this option must ONLY be a Background task as the service may block the caller. The caller may be a Foreground entity or a Background task. The service does not block the caller and returns immediately. The caller using this option must ONLY be a Background task as the service may block the caller. Output NSCC The Service Completion Code. Service Completion Codes Interpretation CC_GOOD CC_QUEUE_FULL The service completed successfully The service was not successful because the queue was Full Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 147 of 214

148 Chapter 10: CC_TIMEOUT CC_QUEUE_WAS_CLOSED CC_TERMINAL_ERROR The service failed to complete successfully within the amount of time specified by the number of timebase ticks specified by the waitcode parameter. The service was terminated before the service could complete because the queue on which the task was pending was closed by another entity. A terminal error occurred when both DIAGNOSTICS and RETURN_FROM_TE_MANAGER are defined. The service attempts to put an entry into the referenced queue. If the queue contains at least one entry less than the maximum number defined by its nentries creation property, the service will complete successfully regardless of the value of the waitcode parameter. To complete the request successfully, the service moves the number of bytes defined by the queue s entrysize property from the location specified by the pdest parameter to the queue with respect to the specified mode parameter and updates the queue s control structure. If the queue is Empty when this service is invoked, there may be a BG task pending as the result of a previous attempt to dequeue an entry from the empty queue. With this service putting an entry into the queue, the queue state will transition from Empty to Not_Empty, making it possible to resume a BG task to complete its pended dequeue request. In doing so, the service will remove the BG task at the head of the queue s list of pending tasks, cancel any related expected completion time period and unblock it with respect to its priority and those of the other BG tasks in the Background Ready Queue. Depending on the priorities of the Current Task and the released BG task, a context switch may result. When the caller of this service is a Foreground entity, any resulting BG task context switch will not take effect until all Foreground operations are complete. When the queue is Empty at the time of this service, its successful operation will cause the queue to transition from Empty to Not_Empty. When the queue contains one entry less than its maximum size, this service will cause the queue to transition from Not_Full to Full. If there is an Event Action Routine associated with either the Q_NOT_EMPTY or Q_FULL event, respectively, the service will schedule execution of any associated EARs. If no EARs are defined for either event, the service is complete and returns a Service Completion Code of CC_GOOD. A BG task and a Foreground entity can invoke this service with the waitcode parameter NOPEND. However, a Foreground entity must use the waitcode parameter NOPEND because they cannot pend if the service is unable to complete successfully. If the queue is Full and the waitcode parameter is NOPEND, the service is unable to complete successfully and immediately returns a Service Completion Code of CC_QUEUE_FULL to the calling entity. When the caller is the Current Task and the queue is Full and the waitcode parameter is other than NOPEND, the service is unable to complete and will block the Current Task. The service s further action depends on the value of the waitcode parameter. Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 148 of 214

149 Chapter 10: QUEUEID qid; NSCC nscc; char *str; char entry; For a waitcode parameter having a value greater than zero but less than the value of UNTIL, the service will establish a time period of type TICKS within which the service is expected to complete successfully. For a waitcode parameter of UNTIL, no such time period is established because the BG task will remain pended for as long as it takes the service to complete successfully. The Current Task will pend until another entity dequeues an entry from the queue, allowing the task to resume this service or until the expected completion time expires, whichever occurs first. If the BG service resumes due to expiration of the expected completion time, the service is unable to complete successfully and returns a Service Completion Code of CC_TIMEOUT, making no changes to the queue s control parameters. Otherwise, the service will resume and complete successfully as described and return a Service Completion Code of CC_GOOD. The Service Completion Code CC_QUEUE_WAS_CLOSED is returned only when the task is pending completion of this service and another entity closes the queue. It is the user s responsibility to detect this condition and to take any appropriate measures as a result. Example /* set up a string of characters */ str = "ABCDEF"; /* create a new queue that has 1-byte entries */ qid = ES_CreateQueue(&Q2props, (NSCC *)0); while ((entry = *str++)!= (char)0) /* Enqueue the character from the string but don t wait longer than ** 50 timer ticks to do it */ nscc = ES_EnqueueData(qID, &entry, TAIL, 50); ) if (nscc == CC_TIMEOUT) /* failed to put the character into the queue in time. Deal * with it */ } else /* the character went into the queue. Continue the loop */ } Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 149 of 214

150 Chapter 10: See Also ES_CreateQueue, ES_DequeueData, ES_GetQueueSize, ES_DefQueueAction Terminal Error Codes (When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE TE_ILLEGAL_TRANSFER_MODE TE_MUST_USE_0_TICKS_OR_NOPEND Function Code given to Terminal Error Handler ENQUEUE_DATA Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 150 of 214

151 Chapter 10: ES_FindQueue Get the identifier of a queue given its name Prototype Inputs pname pnscc Output QUEUEID ES_FindQueue(char *pname, NSCC *pnscc) Pointer to character string holding the name of the queue the service is to find Pointer to a variable that is to receive the Service Completion Code as an enumerated value of type NSCC. If defined as a null pointer, ((NSCC *)0), the service will not return a Service Completion Code. QUEUEID > 0 Identifier of the queue whose name matches the string defined by pname QUEUEID = 0 A queue was not found with a name that matches the pname string. Service Completion Codes Interpretation CC_GOOD CC_NO_SUCH_NAME_IN_CLASS QUEUEID qid1; NSCC nscc; Normal completion of the service No match found with name given by pname Find the queue whose name matches the given name in the string pname and return its identifier. If not found, return a value of 0. Example /* find the queue named MyQueue1 */ qid1 = ES_FindQueue("MyQueue1", &nscc); if (nscc!= CC_GOOD) /* queue not found. Figure out why */ } else /* Name was found and we can proceed */ See Also ES_CreateQueue, ES_GetQueueName Terminal Error Codes (DIAGNOSTIC Mode only) none Function Code given to Terminal Error Handler FIND_QUEUE Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 151 of 214

152 Chapter 10: ES_GetQueueName Get the name of a queue given its identifier Prototype Inputs qid pnscc Output char * > 0 char * = 0 char * ES_GetQueueName(QUEUEID qid, NSCC *pnscc) Identifier of the queue that the service is to find, returning the character pointer to its name string Pointer to a variable that is to receive the Service Completion Code as an enumerated value of type NSCC. If defined as a null pointer, ((NSCC *)0), the service will not return a Service Completion Code. Pointer to the given queue s name string Case 1: The given queue identifier is not found in the Queue class as confirmed by the Service Completion Code of CC_OBJECT_NOT_IN_CLASS Case 2: The given queue and its name are inactive as confirmed by the Service Completion Code CC_INACTIVE_OBJECT Case 3: The given queue identifier is correct and the queue was found but its name string in null (i.e., defined by ) as confirmed by the Service Completion Code of CC_GOOD Service Completion Codes Interpretation CC_GOOD CC_INACTIVE_OBJECT CC_OBJECT_NOT_IN_CLASS CC_TERMINAL_ERROR QUEUEID qid; NSCC nscc; char *pname; Successful service completion The queue is inactive and its name is undefined The given queue identifier is not a member of the Queue class A terminal error occurred when both DIAGNOSTICS and RETURN_FROM_TE_MANAGER are defined. Given the identifier for a queue, return the pointer to its name string if the queue is active, i.e., in use. If the queue is active but its name has been defined as a null string ( ), the service returns a null pointer for the queue s name. In either case, the service returns a Service Completion Code of CC_GOOD. If the queue is closed or otherwise inactive, the service returns a null pointer and the Service Completion Code of CC_INACTIVE_OBJECT If the queue s identifier is not valid, the service returns a null pointer and the Service Completion Code of CC_OBJECT_NOT_IN_CLASS Example /* create a new queue and give it some name */ qid = ES_CreateQueue(&Q1props, (NSCC *)0); /* soemwhere else, get the queue s name */ pname = ES_GetQueueName(qID, &nscc); Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 152 of 214

153 Chapter 10: if (nscc!= CC_GOOD) /* the given queue is undefined or it identifier is not legit */ } else /* The queue was found and pname points to its name */ See Also ES_CreateQueue, ES_FindQueue Terminal Error Codes (When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE TE_UNUSABLE_OBJECT Function Code given to Terminal Error Handler GET_QUEUE_NAME Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 153 of 214

154 Chapter 10: ES_GetQueueSize Get the current number of entries in the given queue Prototype Inputs qid pnscc Output QSIZE ES_GetQueueSize(QUEUEID qid, NSCC *pnscc) Identifier of the queue from which the service gets the queue s current size Pointer to a variable that is to receive the Service Completion Code as an enumerated value of type NSCC. If defined as a null pointer, ((NSCC *)0), the service will not return a Service Completion Code. QSIZE The number of entries in the queue expressed as a value of type QSIZE Service Completion Codes Interpretation CC_GOOD CC_TERMINAL_ERROR QUEUEID qid; QSIZE qsize; NSCC nscc; The service completed successfully A terminal error occurred when both DIAGNOSTICS and RETURN_FROM_TE_MANAGER are defined. The services gets the current number of entries in the queue and returns that number to the caller Example /* create a queue with a 1-byte entry size */ qid = ES_CreateQueue(&Q2props, (NSCC *)0); /* Enqueue three characters into the queue */ ES_EnqueueData(qID, "A", TAIL, NOPEND, (NSCC *)0); ES_EnqueueData(qID, "B", TAIL, NOPEND, (NSCC *)0); ES_EnqueueData(qID, "C", TAIL, NOPEND, (NSCC *)0); qsize = ES_GetQueueSize(qID, &nscc); if (qsize!= 3) /* something is wrong if there were not 3 entries in the queue */ } else ( /* All is well. Proceed */ Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 154 of 214

155 Chapter 10: See Also ES_CreateQueue, ES_EnqueueData Terminal Error Codes (When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE Function Code given to Terminal Error Handler GET_QUEUE_SIZE Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 155 of 214

156 Chapter 11: Chapter 11 Semaphore Class The Semaphore class in the Novos PPS environment provides execution entities with a simple binary semaphore capability for exclusive access to a resource as well as a means to count the occurrence of events and synchronize with those events. Semaphore Properties For the Novos FCFS environment, use the following semaphore properties structure when creating a new semaphore: Properties 11-1 Semaphore Properties Structure typedef struct /* Semaphore properties structure */ char *pname; /* pointer to name */ SEMACOUNT init_count; /* initialization value of semaphore's count */ SEMACOUNT max_count; /* max number of unprocessed signals allowed */ SEMA_TYPE type_sema; /* semaphore type: OPOW or OPMW */ } SEMAPROP; The type_sema element is an enumerated value of type SEMA_TYPE (found in file ENUMcodes.h) and has the following permissible values: Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 156 of 214

157 Chapter 11: Table 11-1 Semaphore Types Semaphore Type OPOW OPMW Meaning One Post, One Waiter. A signal posted to a semaphore will be passed on only to the task at the head of the list of waiting tasks regardless of the number of tasks in the list One Post, Multiple Waiters. A signal posted to a semaphore of this type will be passed on to all tasks that are waiting for it. Semaphore Services Services for the Semaphore class included in the Novos PPS environment are: Table 11-2 Summary of Semaphore Class Services Service Name ES_CloseSema ES_CreateSema ES_DefSemaAction ES_FindSema ES_GetSemaCount ES_GetSemaName ES_PendSema ES_PendSemaM ES_PostSema ES_PostSemaM ES_SetSemaCount Service Discontinue use of a semaphore Create a new semaphore and initialize it for subsequent use Associate an Event Action Routine to execute when one of the two semaphore events occurs Get a semaphore s identifier given its name Get the number of unprocessed signals on a semaphore Get the name of a semaphore given its identifier Test the unprocessed signal counter for a given semaphore and return an indication of the finding Test all semaphores in a list of semaphores for any one of them having unprocessed signals Increment a semaphore s unprocessed signal counter and executing any associated Event Action Routine if the increment causes a semaphore event to occur Post a signal to each semaphore in a list of semaphores Set a semaphore s unprocessed signal counter to a specific value s for each of the Semaphore class services follow. Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 157 of 214

158 Chapter 11: ES_CloseSema Discontinue use of a given semaphore Prototype Inputs NSCC ES_CloseSema(SEMAID sid) sid Identifier of the semaphore that the service is to close Output NSCC The Service Completion Code Service Completion Codes Interpretation CC_GOOD CC_TERMINAL_ERROR SEMAID NSCC The service completed successfully A terminal error occurred when both DIAGNOSTICS and RETURN_FROM_TE_MANAGER are defined. Discontinue use of a semaphore and release it to the set of free semaphores so that it can be reused in the future. The service also removes all defined Event Action Routine associations for the semaphore s events. If there are any BG tasks pending on the semaphore, the service will unblock them and set up the Service Completion Code of CC_SEMAPHORE_WAS_CLOSED to indicate to each task when it is next released that the pending operation did not complete and why. When successfully finished, the service returns the Service Completion Code CC_GOOD. Any unprocessed signals accumulated in the semaphore s counter will be lost when this service executes. sid; nscc; Example /* create a new semaphore */ sid = ES_CreateSema(&TestSemaProps, (NSCC *)0); ES_CloseSema(sID); /* close the semaphore */ /* the service closed the semaphore successfully */ See Also ES_CreateSema, ES_DefSemaAction, ES_PendSema Terminal Error Codes (When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE Function Code given to Terminal Error Handler CLOSE_SEMA Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 158 of 214

159 Chapter 11: ES_CreateSema Create a new semaphore and initialize its properties for subsequent use Prototype Inputs psemaprops pnscc Output SEMAID ES_CreateSema(SEMAPROP *psemaprops, NSCC *pnscc) Pointer to the properties structure of type SEMAPROP for the new semaphore Pointer to a variable that is to receive the Service Completion Code as an enumerated value of type NSCC. If defined as a null pointer, ((NSCC *)0), the service will not return a Service Completion Code. SEMAID Identifier of the newly created semaphore expressed as an integer of type SEMAID Service Completion Codes Interpretation CC_GOOD CC_TERMINAL_ERROR semaid sid; The service completed successfully The terminal error TE_INSUFFICIENT_SYSTEM_RAM occurs when RETURN_FROM_TE_MANAGER is defined Create a new semaphore and initialize it to the values stored in the specified semaphore properties structure. Upon creation, the semaphore s count and maximum count properties are set to the values defined in the semaphore properties structure. Example /* Create a new semaphore and initialize it */ sid = ES_CreateSema(&S1props, (NSCC *)0); /* the serevice was succesful */ See Also Terminal Error Codes ES_CloseSema TE_INSUFFICIENT_SYSTEM_RAM (Can occur when DIAGNOSTICS undefined) Function Code given to Terminal Error Handler CREATE_SEMA Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 159 of 214

160 Chapter 11: ES_DefSemaAction Define an Event Action Routine to execute on the occurrence of a specific semaphore event Prototype Inputs semaid NSCC ES_DefSemaAction(SEMAID semaid, SEMA_EVENT s4event, EAR_OPTION option, EARID earid, int userdata) Identifier of the semaphore to associate with the specified event and the EAR S4event The enumerated value of the semaphore event that invokes the defined Event Action Routine. Permissible values are: Sema Events SEMA_POSTED SATURATED The semaphore receives a signal post that transitions its unprocessed signal counter from 0 to 1 The semaphore s receives a signal post that causes its unprocessed signal count to exceed the semaphore s defined maximum count value option An enumerated value that represents what the service is to do with respect to the defining the association between the semaphore and the EAR. The permissible values are: EAR Option Option ONE_SHOT DEFINE_AND_LOCK CLEAR_ONE_EAR CLEAR_ONE_EVENT CLEAR_ALL_EVENTS The association between the semaphore and the Event Action Routine will exist only until the next occurrence of the defined semaphore event, SEMA_POSTED or ON_SATURATE The association between the semaphore and the Event Action Routine will exist for the next and all subsequent occurrences of the defined semaphore event until the association is discontinued Discontinue the association of the specified Event Action Routine with the specified semaphore event on the referenced semaphore Discontinue all Event Action Routine associations with the specified semaphore event on the referenced semaphore Discontinue all Event Action Routine associations with all semaphore events on the referenced semaphore Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 160 of 214

161 Chapter 11: earid Identifier of the Event Action Routine to invoke when the semaphore experiences the event defined by the parameter, s4event. The EAR must have been previously defined. An integer to be passed to the EAR upon its being scheduled for userdata execution when the specified semaphore event occurs. Depending on how the EAR was created, it may or may not use this parameter Output NSCC The Service Completion Code Service Completion Codes Interpretation CC_GOOD CC_TERMINAL_ERROR SEMAID sem2id; EARID earid; NSCC nscc; Normal completion of the service A terminal error occurred when both DIAGNOSTICS and RETURN_FROM_TE_MANAGER are defined. Associate a previously defined Event Action Routine with a semaphore event, SEMA_POSTED or SATURATED, as defined by parameter s4event, so that when the event occurs, the Event Action Routine will be executed. The parameter, option, defines the type and duration of the association. This service is used to discontinue the association between one or more Event Action Routines and one or more semaphore events as previously described in the table for EAR_OPTION parameter, option. Example sem2id = ES_CreateSema(&Sema2props, (NSCC *)0); /* create semaphore */ earid = ES_CreateEAR(&EAR2Props, (NSCC *)0); /* Create a EAR */ /* Associate EAR with the SEMA_POSTED event and lock the association * by using DEFINE_AND_LOCK. Use the semaphore s identifier as the * data to pass to the EAR when it executes */ nscc = ES_DefSemaAction(sem2ID, SEMA_POSTED, DEFINE_AND_LOCK, earid, (int)semid); if (nscc!= CC_GOOD) /* Can t define the semaphore action. Determine how to proceed */ } else /* When the EAR association is successfully defined, continue */ Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 161 of 214

162 Chapter 11: See Also ES_CreateSema, ES_PostSema, ES_CreateEAR Terminal Error Codes (When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE TE_ILLEGAL_SEMAPHORE_EVENT Function Code given to Terminal Error Handler DEF_SEMA_ACTION Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 162 of 214

163 Chapter 11: ES_FindSema Get the identifier of a semaphore given its name Prototype Inputs pname Pnscc Output SEMAID > 0 SEMAID ES_FindSema(char *pname, NSCC *pnscc) Pointer to character string holding the name of the semaphore the service is to find Pointer to a variable that is to receive the Service Completion Code as an enumerated value of type NSCC. If defined as a null pointer, ((NSCC *)0), the service will not return a Service Completion Code. Identifier of the semaphore whose name matches the string defined by pname SEMAID = 0 A semaphore was not found with a name that matches the pname string. Service Completion Codes Interpretation CC_GOOD Normal completion of the service CC_NO_SUCH_NAME_IN_CLASS No match found with name given by pname SEMAID NSCC Find the semaphore whose name matches the given name in the string pname and return its identifier. If not found, return a value of 0. sid1; nscc; Example /* find the semaphore named SEMA12 */ sid1 = ES_FindSema ( SEMA12, &nscc); if (nscc!= CC_GOOD) /* Semaphore not found. Figure out why */ } else /* Name was found and we can proceed */ See Also ES_CreateSema, ES_GetSemaName Terminal Error Codes (DIAGNOSTIC Mode only) none Function Code given to Terminal Error Handler FIND_SEMA Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 163 of 214

164 Chapter 11: ES_GetSemaCount Get the number of unprocessed signals on a given semaphore Prototype Inputs sid pnscc Output SEMACOUNT ES_GetSemaCount(SEMAID sid, NSCC *pnscc) Identifier of the semaphore whose counter the service is to get Pointer to a variable that is to receive the Service Completion Code as an enumerated value of type NSCC. If defined as a null pointer, ((NSCC *)0), the service will not return a Service Completion Code. SEMACOUNT The value of the specified semaphore s count property expressed as a value of type SEMACOUNT Service Completion Codes Interpretation CC_GOOD CC_TERMINAL_ERROR SEMAID semaid; SEMACOUNT s4count; Normal completion of the service A terminal error occurred when RETURN_FROM_TE_MANAGER is defined Get the value of the given semaphore s unprocessed signal count and return it to the caller Example /* Create a semaphore */ semaid = ES_CreateSema(&sema2Props, (NSCC *)0); /* Sometime later, get the value of the semaphore s unprocessed * signal count */ S4Count = ES_GetSemaCount(semaID, (NSCC *)0); See Also ES_CreateSema, ES_DefSemaCount Terminal Error Codes (When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE Function Code given to Terminal Error Handler GET_SEMA_COUNT Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 164 of 214

165 Chapter 11: ES_GetSemaName Get the name of a semaphore given its identifier Prototype Inputs sid pnscc Output char * > 0 char * = 0 char * ES_GetSemaName(SEMAID sid, NSCC *pnscc) Identifier of the semaphore that the service is to find, returning the character pointer to its name string Pointer to a variable that is to receive the Service Completion Code as an enumerated value of type NSCC. If defined as a null pointer, ((NSCC *)0), the service will not return a Service Completion Code. Pointer to the given semaphore s name string Case 1: The given semaphore identifier is not found in the Semaphore class as confirmed by the Service Completion Code of CC_OBJECT_NOT_IN_CLASS Case 2: The given semaphore identifier and its name are inactive as confirmed by the Service Completion Code CC_INACTIVE_OBJECT Case 3: The given semaphore identifier is correct and the semaphore was found but its name string in null (i.e., defined by ) as confirmed by the Service Completion Code of CC_GOOD Service Completion Codes Interpretation CC_GOOD CC_INACTIVE_OBJECT CC_OBJECT_NOT_IN_CLASS CC_TERMINAL_ERROR char SEMAID NSCC Successful service completion The semaphore is inactive and its name is undefined The given semaphore identifier is not a member of the Semaphore class A terminal error occurred when both DIAGNOSTICS and RETURN_FROM_TE_MANAGER are defined. Given the identifier for a semaphore, return the pointer to its name string if the semaphore is active, i.e., in use. If the semaphore is active but its name has been defined as a null string ( ), the service returns a null pointer for the semaphore s name. In either case, the service returns a Service Completion Code of CC_GOOD. If the semaphore is closed or otherwise inactive, the service returns a null pointer and the Service Completion Code of CC_INACTIVE_OBJECT If the semaphore s identifier is not valid, the service returns a null pointer and the Service Completion Code of CC_OBJECT_NOT_IN_CLASS *pname; sid; nscc; Example /* Create a semaphore */ sid = ES_CreateSema (&TestSemaProps, (NSCC *)0); /* Find the semaphore given its ID */ Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 165 of 214

166 Chapter 11: pname = ES_GetSemaName(sID, &nscc); if (nscc!= CC_GOOD) /* the service failed to find the semaphore */ } else /* the service succeeded */ See Also ES_CreateSema Terminal Error Codes (When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE TE_UNUSABLE_OBJECT Function Code given to Terminal Error Handler GET_SEMA_NAME Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 166 of 214

167 Chapter 11: ES_PendSema Test a semaphore for unprocessed signals Prototype Inputs sid waitcode NSCC ES_PendSema(SEMAID sid, TICKS waitcode) Identifier of the semaphore whose count the service is to test An integer representing the number of timebase ticks indicating what the service is to do if the semaphore s unprocessed signal count is 0. If the semaphore s unprocessed signal count is greater than 0, the service will complete successfully and ignore this parameter. There are three options for this parameter: Option Meaning >0 NOPEND ((TICKS)0) UNTIL ((TICKS)-1) An integer of type TICKS having a value greater than 0 that represents the number of timebase ticks within which the service is expected to complete. The caller using this option must ONLY be a Background task as the service may block the caller. The caller may be a Foreground entity or a Background task. The service does not block the caller and returns immediately. The caller using this option must ONLY be a Background task as the service may block the caller. Output NSCC The Service Completion Code Service Completion Codes Interpretation CC_GOOD CC_NO_SIGNAL CC_TIMEOUT CC_SEMAPHORE_WAS_CLOSED CC_TERMINAL_ERROR The semaphore s count was > 0, indicating that it had unprocessed signals, which have now been reduced by 1. The service completed successfully. The service completed but semaphore s unprocessed signal count was less than or equal to 0, indicating that there were no unprocessed signals The service failed to complete successfully within the amount of time corresponding to the number of timebase ticks specified by the waitcode parameter. The service was terminated before the service could complete because the semaphore on which the task was pending was closed by another entity. A terminal error occurred when RETURN_FROM_TE_MANAGER is defined Service to test the semaphore for the presence of unprocessed signal postings. The presence of unprocessed signals is indicated by the referenced semaphore s count containing a value greater than zero. If the service detects that the semaphore contains unprocessed signals, it will reduce the unprocessed signal count by 1 and return to the caller Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 167 of 214

168 Chapter 11: SEMAID NSCC immediately with the successful Service Completion Code CC_GOOD, regardless of the value of the waitcode parameter. If the semaphore s unprocessed signal count is less than or equal to zero and the waitcode parameter is NOPEND, the service is unable to complete successfully and immediately returns a Service Completion Code of CC_NO_SIGNAL to the calling entity. The Idle Task and a Foreground entity can call this service provided that they use the waitcode of NOPEND. If the Current Task is not the Idle Task, it can use any permissible waitcode. When the semaphore s unprocessed signal count is less than or equal to zero and the waitcode parameter is not NOPEND, the service is unable to complete and will block the Current Task. The service s further actions depend on the value of the waitcode parameter. For a waitcode parameter having a value greater than zero but less than the value of UNTIL, the service use that value of type TICKS to establish a time period within which the service is expected to complete. For a waitcode parameter of UNTIL, no such time period is established because the BG task will remain pended until the service can complete successfully. The pended Current Task will remain blocked until either another entity posts a signal to the semaphore or the expected completion time period expires, whichever occurs first. When the blockage is removed, and the pended task regains CPU control, it can complete this service. The service will return a Service Completion Code of CC_GOOD and the semaphore s counter will be 0 if the semaphore received the expected signal post. However, should the semaphore not receive a signal post within the expected completion time, the service will return a Service Completion Code of CC_TIMEOUT and will make no changes to the semaphore s unprocessed signals counter. If another entity closes the semaphore during the time that the BG task is blocked while pending on the semaphore to receive a signal post, the task is unblocked and will return the Service Completion Code CC_SEMAPHORE_WAS_CLOSED when it is next released. semaid; nscc; Example /* Create a semaphore. count = 0 */ semaid = ES_CreateSema(&semaXYZProps, (NSCC *)0); /* Sometime later, see if the semaphore has unprocessed signals */ nscc = ES_PendSema(semaID, NOPEND); if (nscc == CC_NO_SIGNAL) /* No signals yet. Do something else */ } else /* There was a signal to the semaphore. Process the event */ Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 168 of 214

169 Chapter 11: } /* Sometime later, pend here until the semaphore receives * a signal post */ if (ES_PendSema(semaID, UNTIL) == CC_SEMAPHORE_WAS_CLOSED) /* Signal post did not happen due to closing of semaphore. * Deal with it */ } /* Otherwise, all is well. Proceed. */ See Also ES_CreateSema, ES_PostSema, ES_CloseSema Terminal Error Codes (When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE Function Code given to Terminal Error Handler PEND_SEMA Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 169 of 214

170 Chapter 11: ES_PendSemaM Test a set of semaphores for unprocessed signals Prototype Inputs plist SEMAID ES_PendSemaM(SEMAID **plist, WAITCODE waitcode, NSCC *pnscc) Pointer to null-terminated list of pointers to semaphore identifiers that define the set to test waitcode An integer representing the number of timebase ticks indicating what the service is to do if each semaphore in the list of semaphores has an unprocessed signal count of 0. If the service encounters one semaphore in the list of semaphores whose unprocessed signal count is greater than 0, the service will complete successfully and ignore this parameter. There are three options for this parameter: Option Meaning >0 NOPEND ((TICKS)0) UNTIL ((TICKS)-1) An integer of type TICKS having a value greater than 0 that represents the number of timebase ticks within which the service is expected to complete. The caller using this option must ONLY be a Background task as the service may block the caller. The caller may be a Foreground entity or a Background task. The service does not block the caller and returns immediately. The caller using this option must ONLY be a Background task as the service may block the caller. Pnscc Output SEMAID > 0 Pointer to a variable that is to receive the Service Completion Code as an enumerated value of type NSCC. If defined as a null pointer, ((NSCC *)0), the service will not return a Service Completion Code. Case 1: The identifier of the first semaphore in plist that the service found to contain an unprocessed signal count > 0 Case 2: The identifier of the semaphore in plist that was closed during the service s pending period when the value of waitcode is not NOPEND and the return Service Completion Code is CC_SEMAPHORE_WAS_CLOSED. Case 3: The identifier of the semaphore that caused the service to return the Service Completion Code CC_USAGE_CONFLICT. The service either failed to complete successfully, as indicated by a Service Completion Code of CC_TIMEOUT or it completed normally SEMAID = 0 when the value of waitcode was NOPEND and the semaphore s count is 0, in which case, the returned Service Completion Code was CC_NO_SIGNAL. Service Completion Codes Interpretation Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 170 of 214

171 Chapter 11: CC_GOOD CC_NO_SIGNAL CC_TIMEOUT CC_USAGE_CONFLICT CC_SEMAPHORE_WAS_CLOSED CC_TERMINAL_ERROR The service completed successfully and there was one semaphore, whose identifier the service returns, that contained unprocessed signals The service completed but all of the semaphores in plist contained unprocessed signal count values less than or equal to 0 and the waitcode is NOPEND The operation to synchronize the calling task with the next signal posted to any of the semaphores in plist did not occur before the number of timebase ticks defined by the value of waitcode elapsed. A semaphore in the set defined by plist is also a member of another semaphore set that is currently active as the result of another task s call to the ES_PendSemaM service. The service was terminated before the service could complete because the semaphore on which the task was pending was closed by another entity. A terminal error occurred when RETURN_FROM_TE_MANAGER is defined Service to allow a set of semaphores to be tested for synchronization with their separate events. The service returns the identity of the first semaphore in the set it finds to have an unprocessed signal count greater than 0. The result is the equivalent of a Boolean OR test. The semaphore set, defined by plist, is a null-terminated list of pointers to semaphore identifiers. No semaphore in the set is can be a member of another semaphore set in active use from a call to this service by another task. If the service finds such a semaphore in the referenced set, it will immediately return the identifier of the semaphore in conflict along with a Service Completion Code of CC_USAGE_CONFLICT, leaving all semaphores in the set unchanged. If there are no usage conflicts, and the service detects that one of the semaphores has unprocessed signals, the service will reduce that semaphore s count value by 1 and immediately return its identifier along with a Service Completion Code of CC_GOOD, regardless of the value of waitcode. If no semaphore in the set contains unprocessed signal posts, the service proceeds with respect to the values of the semaphore s count and the waitcode parameter. A waitcode value of NOPEND causes the service to return immediately to the caller with a value of 0 of type SEMAID and a Service Completion Code of CC_NO_SIGNAL. A waitcode value of UNTIL causes the service to block the Current Task until at least one semaphore in the semaphore set receives a signal post, allowing the service to complete successfully. When the service completes successfully, the service returns the identifier of the semaphore that received the signal post and a Service Completion Code of CC_GOOD A waitcode value other than NOPEND or UNTIL represents the number of timebase counter ticks that the service is to wait for successful completion. The service will block the Current Task until the Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 171 of 214

172 Chapter 11: service can completes successfully or the number of timebase counter ticks elapses, whichever occurs first. If the service completes successfully, it returns the identifier of the semaphore that received the signal post and a Service Completion Code of CC_GOOD. If the time period elapses without success, the service returns an integer value of 0 of type SEMAID and the Service Completion Code CC_TIMEOUT. During the time that the Current Task is pending for an expected signal post, it is possible that another entity could close one of the semaphores in the active set. Should that occur, all other semaphores in the set are removed from the active set and the service returns the identifier of the closed semaphore along with a Service Completion Code of CC_SEMAPHORE_WAS_CLOSED. Example /* These variables are not necessarily locals. They can be ** globals, too. They just need to be in RAM */ SEMAID Q1QNEsema ; SEMAID Q2QNEsema ; SEMAID Q2QNFsema ; SEMAID semalist[] = &Q1QNEsema, &Q2QNEsema, &Q1QNFsema, 0; } /* These variables are most likely to be locals */ NSCC nscc; SEMAID DoneSema; /* Create 3 semaphores for this example and initialize them */ Q1QNEsema = ES_CreateSema(&Q1QNEsemaProps, (NSCC *)0); Q2QNEsema = ES_CreateSema(&Q2QNEsemaProps, (NSCC *)0); Q2QNFsema = ES_CreateSema(&Q2QNFsemaProps, (NSCC *)0); /* Sometime later, test all three semaphores for unprocessed ** signals */ DoneSema = ES_PendSemaM(semalist, UNTIL, &nscc); if (nscc == CC_GOOD) /* there is a semaphore that received a signal post */ switch(donesema) case Q1QNEsema: /* do something about Queue1 being Not Empty */ break; case Q2QNEsema: /* do something about Queue2 being Not Empty */ break; Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 172 of 214

173 Chapter 11: case Q2QNFsema: /* do something about Queue2 being Not Full */ break; } } else /* Some problem occurred. Maybe a CC_USAGE_CONFLICT? ** Check it out and do something about it. */ } See Also ES_PendSema, ES_PostSema, ES_PostSemaM Terminal Error Codes ((When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE TE_MUST_USE_0_TICKS_OR_NOPEND TE_IDLE_TASK_CANNOT_WAIT TE_INSUFFICIENT_SYSTEM_RAM Function Code given to Terminal Error Handler PEND_SEMA_M Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 173 of 214

174 Chapter 11: ES_PostSema Post a signal to a semaphore Prototype Inputs NSCC ES_PostSema(SEMAID sid) sid Identifier of the semaphore to which the service is to post the signal Output NSCC The Service Completion Code Service Completion Codes Interpretation CC_GOOD CC_SEMAPHORE_SATURATED CC_TERMINAL_ERROR The service completed successfully The service completed but the semaphore s counter is now saturated A terminal error occurred when both DIAGNOSTICS and RETURN_FROM_TE_MANAGER are defined. Post a signal to a semaphore specified by the semaphore identifier sid. When the service is invoked from an entity executing in the Foreground, the service can only increment the semaphore s unprocessed signal counter and return a Service Completion Code of CC_GOOD. If the semaphore s unprocessed signal count contains a value <= 0 following the increment, the service will return a Service Completion Code of CC_GOOD but it takes no further action. The semaphore type, an enumerated value of type SEMA_TYPE as defined by the type_sema creation property, determines how the service treats any BG tasks pending for the semaphore to receive the signal post. If the semaphore s unprocessed signal count is 1 after the increment and there is one or more Background tasks waiting for the signal post, the service will take action as follows: Semaphore Type Action Taken OPOW OPMW The semaphore type is One Post, One Waiter. The service will remove the task at the head of the semaphore s list of tasks pending for the signal, unblock it, cancel any timeout period for receipt of the signal post and put the task into the Background Ready Queue with respect to its priority and those of the other BG tasks in the queue. A context switch may result. The semaphore type is One Post, Multiple Waiters. The service will remove all of the tasks in the semaphore s list of tasks pending for the signal, unblocking them, cancelling their timeout periods for receiving the signal post, if any, and putting the tasks into the Background Ready Queue with respect to their priorities and those of the other tasks in the queue. A context switch may result. If the semaphore s unprocessed signal count is 1 after the increment and the semaphore s SEMA_POSTED event is associated with an Event Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 174 of 214

175 Chapter 11: SEMAID semaid; Action Routine, the service will schedule immediate execution of the EAR. If the increment causes the semaphore s unprocessed signal counter to exceed a maximum value defined by its max-count creation property, the service will force the semaphore s counter to the value of max_count and return the CC_SEMAPHORE_SATURATED Service Completion Code. If the semaphore s SATURATED event is defined and associated with an Event Action Routine, the service will schedule execution of the EAR. Example /* Create a semaphore */ semaid = ES_CreateSema(&Q2QNEsemaProps, (NSCC *)0); /* Some time later Post a signal to the semaphore */ if ((ES_PostSema(semaID) == CC_SEMAPHORE_SATURATED) /* Saturated count. Deal with it */ } else /* All is well. Continue */ See Also ES_PendSema, ES_DefSemaAction Terminal Error Codes ((When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE Function Code given to Terminal Error Handler POST_SEMA Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 175 of 214

176 Chapter 11: ES_PostSemaM Post a signal to multiple semaphores simultaneously Prototype Inputs plist Pnscc Output SEMAID = 0 SEMAID ES_PostSemaM(SEMAID **plist, NSCC *pnscc) Pointer to a null terminated list of pointers to semaphore identifiers that defines the set of semaphores to which the service is to post the signal Pointer to a variable that is to receive the Service Completion Code as an enumerated value of type NSCC. If defined as a NULL pointer, ((NSCC *)0), the service will not return a Service Completion Code A value of 0 of type SEMAID indicates there was no semaphore in the set whose count property was saturated as a result of this service Identifier of the last semaphore in the set that the service detects as SEMAID > 0 being saturated. If more than one semaphore saturates as a result of this posting, only one, the last one encountered, will be reported to the caller Service Completion Codes Interpretation CC_GOOD CC_SEMAPHORE_SATURATED CC_TERMINAL_ERROR The service completed successfully The service completed but the posting action has saturated at least one semaphore in the set, the identity of which is the service s output value A terminal error occurred when RETURN_FROM_TE_MANAGER is defined Service to post signals to all the semaphores in a defined set. The set of semaphores may contain both types of semaphores OPOW and OPMW. The service posts a signal to each semaphore in the set by incrementing the semaphore s unprocessed signal count by 1 in the manner described for ES_PostSema. If one of the semaphores in the set contains an unprocessed signal count is 1 after the increment and there is one or more Background tasks waiting for the signal post, the service will take action with respect to the type of semaphore as follows: Semaphore Type Action Taken OPOW OPMW The semaphore type is One Post, One Waiter. The service will remove the task at the head of the semaphore s list of tasks pending for the signal, unblock it, cancel any timeout period for receipt of the signal post and put the task into the Background Ready Queue with respect to its priority and those of the other BG tasks in the queue. A context switch may result. The semaphore type is One Post, Multiple Waiters. The service will remove all of the tasks in the semaphore s list of tasks pending for the signal, unblocking them, cancelling their timeout periods for receiving the signal post, if any, and putting the tasks into the Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 176 of 214

177 Chapter 11: Background Ready Queue with respect to their priorities and those of the other tasks in the queue. A context switch may result. When the service completes processing all the semaphores in the list, it returns a Service Completion Code of CC_GOOD. If the increment causes the semaphore s unprocessed signal counter to exceed a maximum value defined by its max-count creation property, the service will force the semaphore s counter to the value of max_count and return the CC_SEMAPHORE_SATURATED Service Completion Code. If the semaphore s SATURATED event is defined and associated with an Event Action Routine, the service will schedule execution of the EAR. Should the service encounter multiple semaphores in the set that saturate as the result of the signal post, it will return the identifier of only the last one it encounters. Example /* These variables are not necessarily locals. They can be ** globals, too */ SEMAID Q1QNEsema ; SEMAID Q2QNEsema ; SEMAID Q2QNFsema ; SEMAID semalist[] = /* List of semaphores to post */ &Q1QNEsema, &Q2QNEsema, &Q1QNFsema, 0; } /* These variables are most likely to be locals */ SEMAID Satur8Sema = (SEMAID)0; NSCC nscc; /* create a set of semaphores */ Q1QNEsema = ES_CreateSema(&Q1QNEsemaProps, (NSCC *)0); Q2QNEsema = ES_CreateSema(&Q2QNEsemaProps, (NSCC *)0); Q2QNFsema = ES_CreateSema(&Q2QNFsemaProps, (NSCC *)0); */ /* Sometime later, post the signal to all three semaphores */ Satur8Sema = ES_PostSemaM(&semalist, &nscc); if (nscc == CC_SEMAPHORE_SATURATED) /* did one of them saturate */ /* yes, a semaphore saturated and its identifier in in Satur8sema } else Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 177 of 214

178 Chapter 11: See Also /* Success. No semaphore saturated. Continue */ ES_PostSema, ES_PendSema, ES_PendSemaM Terminal Error Codes (When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE Function Code given to Terminal Error Handler POST_SEMA_M Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 178 of 214

179 Chapter 11: ES_SetSemaCount Set the unprocessed signal counter of a semaphore to a specific value Prototype Inputs sid NSCC ES_SetSemaCount(SEMAID sid, int newcount) Identifier of the semaphore whose counter the service is to set The number that defines the unprocessed signal counter property of the newcount referenced semaphore expressed as a value of type SEMACOUNT, which may be less than or equal to zero. Output NSCC The Service Completion Code Service Completion Codes Interpretation CC_GOOD CC_TERMINAL_ERROR SEMAID sid; The service completed successfully A terminal error occurred when both DIAGNOSTICS and RETURN_FROM_TE_MANAGER are defined. Set the unprocessed signal counter of the given semaphore to the value defined by newcount. If the new value triggers one of the semaphore s events, the service will schedule any associated EAR for execution. Example /* Create a semaphore and initialize its count to 0 */ sid = ES_CreateSema(&sema2Props, (NSCC *)0); /* Sometime later, set a new semaphore count < 0 */ ES_SetSemaCount(sID, -5); See Also ES_CreateSema, ES_GetSemaCount, ES_PendSema, ES_PostSemaM Terminal Error Codes (When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE Function Code given to Terminal Error Handler SET_SEMA_COUNT Setting the semaphore s count to a value less than zero means that the semaphore can receive n+1 signal posts before an execution entity can detect the postings with the ES_PendSema service. Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 179 of 214

180 Chapter 12: Chapter 12 Memory Pool Class The Memory Pool class provides Foreground entities with an orderly means of managing use of blocks of RAM. Memory Pool Properties For the Novos EFB environment, use the following memory pool properties structure when creating a new memory pool: Properties 12-1 Memory Pool Properties Structure typedef struct /* Memory Pool properties structure */ char *pname; /* pointer to pool's name */ char *pbase; /* pointer to base address of the pool */ BLOCKSIZE blksiz; /* size of a block in this pool (in bytes) */ KCOUNT maxblkcnt; /* initialized number of blocks in the pool */ POOL_TYPE pooltype; /* Type of memory pool */ } POOLPROP; The pooltype element is an enumerated value of type POOL_TYPE (found in file ENUMcodes.h) and has the following permissible values: Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 180 of 214

181 Chapter 12: Table 12-1 Memory Pool Types Pool Type HARD_FIXED SOFT_FIXED SOFT_DEMAND Meaning All of the elements in the Memory Pool Properties structure are defined by the user at the time of the pool s creation. Specifically, the location of the pool as defined by the pbase element is assigned to a user-defined location in the system s RAM. Only the blksiz and maxblkcnt elements of the Memory Pool Properties structure are defined at the time of the pool s creation. The pbase element is ignored and the pool creation service will allocate the pool s RAM blocks from User RAM. Only the blksiz and maxblkcnt elements of the Memory Pool Properties structure are defined at the time of the pool s creation. The pbase element is ignored but the pool creation service does not allocate any RAM blocks. Instead, when there is a demand for a RAM block from a pool of this type and one is not available in the pool, the service will allocate a block of User RAM of blksiz and assign it to the pool. No more than maxblkcnt blocks can be allocated and assigned to a pool of this type. Memory Pool Services Services for the Memory Pool class included in this environment are: Table 12-2 Summary of Memory Pool Class Services Memory Pool Service ES_ClosePool ES_CreatePool ES_DefPoolAction ES_FindPool ES_FreePoolBlk ES_GetPoolBlk ES_GetPoolBlkSize ES_GetPoolFreeBlkCount ES_GetPoolName Discontinue use of a given memory pool Create a new memory pool and initialize it for subsequent use Associate an Event Action Routine to execute when one of the two memory pool events occurs Get the identifier of a memory pool given its name Free a memory pool block for subsequent use Get a block of RAM from a memory pool Get the size of the RAM blocks in a memory pool Get the number of free RAM blocks in a memory pool Get the name of a memory pool given its identifier s for each service follow. Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 181 of 214

182 Chapter 12: ES_ClosePool Discontinue use of a given memory pool Prototype Inputs NSCC ES_ClosePool(POOLID pid) pid Identifier of the memory pool that the service is to close Output NSCC The Service Completion Code Service Completion Codes Interpretation CC_GOOD CC_TERMINAL_ERROR POOLID pid; The service completed successfully A terminal error occurred when both DIAGNOSTICS and RETURN_FROM_TE_MANAGER are defined. Service to discontinue use of a memory pool. The service will close the memory pool, regardless of POOL_TYPE, and release it so that it can be reused in the future. The service also removes all defined Event Action Routine associations for the pool s events. If the memory pool was created as either a SOFT_FIXED or a SOFT_DEMAND type, the service will free the User RAM blocks assigned to the pool in such a manner that they are reusable by any class if the requested amount of User RAM matches the block size of the closed memory pool. The service makes no attempt to preserve RAM blocks used by a HARD_FIXED type memory pool. If there are any BG tasks pending for a block of RAM from the memory pool from a previously issued call to ES_GetPoolBlk, the service will unblock them and set up their return values as a null pointer and the Service Completion Code of CC_POOL_WAS_CLOSED to indicate to each task when it is next released that the pending operation failed and why. When finished successfully, the service returns a Service Completion Code of CC_GOOD. Example /* create a new memory pool */ pid = ES_CreatePool(&TestPoolProps, (NSCC *)0); if (ES_ClosePool(pID)!= CC_GOOD) /* close the pool */ /* Terminal Error here. Memory pool not closed */ } else /* The pool was successfully closed */ Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 182 of 214

183 Chapter 12: See Also ES_CreatePool, ES_GetPoolBlk Terminal Error Codes (When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE Function Code given to Terminal Error Handler CLOSE_POOL It is the responsibility of the user to ensure that all RAM blocks used by the pool are available (i.e., in the pool) prior to closing the pool with this service. To do otherwise risks memory leaks and possibly other errors. Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 183 of 214

184 Chapter 12: ES_CreatePool Create a new memory pool and initialize its properties Prototype Inputs ppoolprops pnscc Output POOLID ES_CreatePool(POOLPROP *ppoolprops, NSCC *pnscc) Pointer to the properties structure of type POOLPROP for the new memory pool Pointer to a variable that is to receive the Service Completion Code as an enumerated value of type NSCC. If defined as a null pointer, ((NSCC *)0), the service will not return a Service Completion Code. POOLID Identifier of the newly created memory pool expressed as an Integer of type POOLID Service Completion Codes Interpretation CC_GOOD CC_TERMINAL_ERROR POOLID pid; The service completed successfully The terminal error TE_INSUFFICIENT_SYSTEM_RAM occurs when RETURN_FROM_TE_MANAGER is defined Create a new memory pool and initialize it to the values stored in the specified pool properties structure in accordance with the POOL_TYPE property. For the SOFT_FIXED pool type, the service will allocate the amount of User RAM necessary to contain the number of RAM blocks defined by the blksiz and maxblkcnt properties. For pool types of HARD_FIXED and SOFT_FIXED, the service will establish the linkages for the defined number of RAM blocks beginning at the defined address of the HARD_FIXED memory pool or the base address of the allocated User RAM in the case of a SOFT_FIXED pool. For the SOFT_DEMAND pool type, the service does not allocate any RAM blocks for the pool. RAM blocks will be allocated and assigned to the pool on demand. Example /* Create a new memory pool and initialize it */ pid = ES_CreatePool(&PoolProps, (NSCC *)0); /* assume the service was succesful */ See Also Terminal Error Codes ES_ClosePool, FreePoolBlk TE_INSUFFICIENT_SYSTEM_RAM (Can occur when DIAGNOSTICS undefined) Function Code given to Terminal Error Handler CREATE_POOL Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 184 of 214

185 Chapter 12: ES_DefPoolAction Define an Event Action Routine to execute on the occurrence of a specific memory pool event Prototype Inputs poolid NSCC far ES_DefPoolAction(POOLID poolid, POOL_EVENT poolevent, EAR_OPTION option, EARID earid, int userdata) Identifier of the memory pool to associate with the specified event and the EAR poolevent option The enumerated value of the memory pool event that invokes the defined Event Action Routine. Permissible values are: Pool Event POOL_NOT_EMPTY POOL_EMPTY POOL_FULL The memory pool that contains no free RAM blocks (empty) receives a free block from some entity that transitions its free block counter from 0 to 1 The memory pool contains one free RAM block when some entity gets the pool s last free RAM block, causing the memory pool to become empty The memory pool contains all RAM blocks assigned to it An enumerated value that represents what the service is to do with respect to the defining the association between the memory pool and the EAR. The permissible values are: EAR Option Option ONE_SHOT DEFINE_AND_LOCK CLEAR_ONE_EAR CLEAR_ONE_EVENT CLEAR_ALL_EVENTS The association between the memory pool and the Event Action Routine will exist only until the next occurrence of the defined memory pool event, POOL_NOT_EMPTY or POOL_EMPTY The association between the memory pool and the Event Action Routine will exist for all subsequent occurrences of the defined memory pool event until the association is discontinued Discontinue the association of the specified Event Action Routine with the specified pool event on the referenced memory pool Discontinue all Event Action Routine associations with the specified pool event on the referenced memory pool Discontinue all Event Action Routine associations with all pool events on the referenced memory pool Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 185 of 214

186 Chapter 12: earid Identifier of the Event Action Routine to invoke when the memory pool experiences the event defined by the parameter, poolevent. The EAR must have been previously defined. Integer to be passed to the EAR upon its being scheduled for execution userdata when the specified memory pool event occurs. Depending on how the EAR was created, it may or may not use this parameter Output NSCC The Service Completion Code Service Completion Codes Interpretation CC_GOOD CC_TERMINAL_ERROR POOLID pool2id; NSCC nscc; Normal completion of the service The terminal error TE_INSUFFICIENT_SYSTEM_RAM occurs when RETURN_FROM_TE_MANAGER is defined Associate an Event Action Routine with a memory pool event, POOL_NOT_EMPTY, POOL_EMPTY or POOL_FULL as defined by parameter poolevent, so that when the event occurs, the Event Action Routine will be executed. The parameter, option, defines the type and duration of the association. This service is used to discontinue the association between one or more Event Action Routines and one or more pool events as previously described in the table for EAR_OPTION parameter, option. Example /* create a memory pool */ pool2id = ES_CreatePool(&ool2props, (NSCC *)0); earid = ES_CreateEAR(&EAR2Props, (NSCC *)0); /* Create an EAR */ /* Associate an EAR with the POOL_NOT_EMPTY event and lock the * association by using DEFINE_AND_LOCK. Use the memory pool s * identifier as the data to pass to the EAR when it executes */ nscc = ES_DefPoolAction(pool2ID, POOL_NOT_EMPTY, DEFINE_AND_LOCK, earid, (int)poolid); if (nscc!= CC_GOOD) /* Can t define the memory pool action. Determine how to proceed */ } else /* When the action routine is successfully defined, continue */ Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 186 of 214

187 Chapter 12: See Also ES_CreatePool, ES_GetPoolBlk, ES_FreePoolBlk, ES_CreateEAR Terminal Error Codes (When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE TE_ILLEGAL_POOL_EVENT TE_INSUFFICIENT_SYSTEM_RAM (can occur when DIAGNOSTICS undefined) Function Code given to Terminal Error Handler DEF_POOL_ACTION Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 187 of 214

188 Chapter 12: ES_FindPool Get the identifier of a memory pool given its name Prototype Inputs pname pnscc Output POOLID > 0 POOLID ES_FindPool(char *pname, NSCC *pnscc) Pointer to character string holding the name of the memory pool the service is to find Pointer to a variable that is to receive the Service Completion Code as an enumerated value of type NSCC. If defined as a null pointer, ((NSCC *)0), the service will not return a Service Completion Code. Identifier of the memory pool whose name matches the string defined by pname POOLID = 0 A memory pool was not found with a name that matches the pname string. Service Completion Codes Interpretation CC_GOOD Normal completion of the service CC_NO_SUCH_NAME_IN_CLASS No match found with name given by pname POOLID NSCC Find the memory pool whose name matches the given name in the string pname and return its identifier. If not found, return a value of 0. pid1; nscc; Example /* Find the memory pool named Pool_256 */ pid1 = ES_FindPool("Pool_256", &nscc); if (nscc!= CC_GOOD) /* Pool not found. Figure out why */ } else /* Name was found and we can proceed */ See Also ES_CreatePool, ES_GetPoolName Terminal Error Codes (When DIAGNOSTICS defined) none Function Code given to Terminal Error Handler FIND_POOL Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 188 of 214

189 Chapter 12: ES_FreePoolBlk Return (free) a block of RAM to a memory pool Prototype Inputs pid NSCC ES_FreePoolBlk(POOLID pid, void *pblk) Identifier of the memory pool to which the service is to free the specified block of RAM pblk Pointer to the block of RAM that the service is to free to the specified memory pool Output NSCC The Service Completion Code Service Completion Codes Interpretation CC_GOOD CC_POOL_OVERFILLED CC_TERMINAL_ERROR The service completed successfully The number of blocks now available in the referenced pool exceeds the number of blocks assigned to the pool whether initially when it was created, or, dynamically assigned A terminal error occurred when both DIAGNOSTICS and RETURN_FROM_TE_MANAGER are defined. When the referenced pool is Empty, and before releasing the RAM block to the referenced pool, the service checks if there is at least one BG task pending for a RAM block from the memory pool. If so, the service will remove the task at the head of the pool s list of pended BG tasks, assign the referenced RAM block to it, unblock it, cancelling any time period limiting the duration of the task s pend and then put the task into the Background Ready Queue with respect to its priority and those of the other tasks in the queue. In this situation, the service completes successfully, returning a Service Completion Code of CC_GOOD but the state of the pool remains Empty. If there is no BG task pending for a RAM block from the referenced memory pool, the service frees the specified RAM block by linking it into the set of free RAM blocks in the pool and incrementing the number of available free RAM blocks. The service will complete successfully and return a Service Completion Code of CC_GOOD if, after the increment, there is at least one available RAM block in the pool but no more than the number defined by the initialization property, maxblkcnt. As part of successfully freeing a RAM block, the service will test the number of available RAM blocks in the referenced pool. If that number is 1, the POOL_NOT_EMPTY event exists and, if an Event Action Routine is associated with that event, the service will schedule its execution. Likewise, should the available RAM block count be equal to maxblkcnt, the service will trigger the POOL_FULL event and will schedule execution of any associated Event Action Routine. Should freeing the RAM block cause the memory pool to exceed the number of RAM blocks as specified by maxblkcnt, the service returns the Service Completion Code CC_POOL_OVERFILLED as a notice to the caller. It is not necessarily an error. Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 189 of 214

190 Chapter 12: POOLID void pid; *paddrblk1; Example /* create a memory pool */ pid = ES_CreatePool(&TestPoolProps, (NSCC *)0); /* Get next available block in the pool */ paddrblk1 = ES_GetPoolBlk(pID, UNTIL, (NSCC *)0); /* Some time later, free the allocated block of RAM */ if (ES_FreePoolBlk(pID, paddrblk1) == CC_GOOD) /* Block returned successfully. Continue */ See Also ES_CreatePool, ES_GetPoolBlk, ES_DefPoolAction Terminal Error Codes (When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE Function Code given to Terminal Error Handler FREE_POOL_BLOCK The Service Completion Code CC_POOL_OVERFILLED is not necessarily an error. It simply means that the number of RAM blocks assigned to the pool exceeds the number specified as its maximum content when the pool was created. It is the user s responsibility to interpret its significance It is the user s responsibility to ensure that the size of the RAM block being freed is compatible with the block size property of the given memory pool. Freeing a block whose size is shorter than expected will likely cause errors when that block is again allocated. A block whose size is greater than expected will not cause an error but it will waste RAM. Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 190 of 214

191 Chapter 12: ES_GetPoolBlk Get a block of RAM from a memory pool and return its address Prototype Inputs pid void * ES_GetPoolBlk(POOLID pid, TICKS waitcode, NSCC *perrno) Identifier of the memory pool to which the service is to get the block of RAM waitcode A number indicating what the service is to do if the memory pool contains no available RAM blocks. If the pool s available RAM block count is greater than 0, the service will complete successfully and ignore this parameter. There are three options for this parameter: Option Meaning >0 NOPEND ((TICKS)0) UNTIL ((TICKS)-1) An integer of type TICKS having a value greater than 0 that represents the number of timebase ticks within which the service is expected to complete. The caller using this option must ONLY be a Background task as the service may block the caller. The caller may be a Foreground entity or a Background task. The service does not block the caller and returns immediately. The caller using this option must ONLY be a Background task as the service may block the caller. pnscc Output void * > 0 Pointer to a variable that is to receive the Service Completion Code as an enumerated value of type NSCC. If defined as a null pointer, ((NSCC *)0), the service will not return a Service Completion Code. Address of the allocated RAM block, following a successful completion of the service Null pointer indicates that the service failed to allocate a block of RAM void * = 0 from the referenced memory pool. The Service Completion Code gives further indication as to the reason for the failure Service Completion Codes Interpretation CC_GOOD CC_POOL_EMPTY CC_TIMEOUT CC_POOL_WAS_CLOSED CC_TERMINAL_ERROR Normal completion of the service The service was unable to allocate a RAM block because there was none in the referenced memory pool The service failed to complete successfully within the amount of time specified by the number of timebase ticks defined by the waitcode parameter. The service was terminated before the service could complete because the referenced memory pool on which the task was pending was closed by another entity. A terminal error occurred when both DIAGNOSTICS and RETURN_FROM_TE_MANAGER are defined. Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 191 of 214

192 Chapter 12: The service attempts to get a RAM block from a memory pool and return a pointer to it. If the memory pool contains at least one available RAM block, the service removes the RAM block from the list of available RAM blocks in the memory pool, reduces the memory pool s number of available RAM blocks by 1 and returns a Service Completion Code of CC_GOOD. In this case, the service completes successfully regardless of the value of the waitcode parameter. When the referenced memory pool contains no available RAM blocks (the Empty state), further actions of the service are determined by the waitcode parameter and the type of memory pool. For memory pool types HARD_FIXED and SOFT_FIXED, a waitcode parameter of NOPEND, causes the service to return to the calling entity immediately with a Service Completion Code of CC_POOL_EMPTY. If a Foreground entity invokes this service, the only permissible waitcode value is NOPEND. For the Current Task referencing a memory pool of type HARD_FIXED or SOFT_FIXED and using a waitcode parameter other than NOPEND, the service will block it with respect to the value of the waitcode parameter. A waitcode parameter of UNTIL causes the service to pend the Current Task until the service can complete successfully at which time it returns a pointer to the requested RAM block and a Service Completion Code of CC_GOOD. A waitcode value other than UNTIL, represents the number of timebase ticks within which the application expects the service to complete successfully. If the service is unable to do so within the expected completion time, it will return a Service Completion Code of CC_TIMEOUT. When the service succeeds within the expected time, it returns a pointer to the requested RAM block and a Service Completion Code of CC_GOOD. The Service Completion Code CC_POOL_WAS_CLOSED is returned only when the requesting BG task is pending completion of this service and another entity closes the memory pool. It is the user s responsibility to detect this completion code and to take any appropriate measures. If the request references a memory pool of type SOFT_DEMAND that is Empty, the service attempts to allocate a block of the required size from the used RAM list. But if there is no reusable block of the required size, the service will attempt to fulfill the request by allocating the block directly from User RAM. Either method of RAM allocation being successful causes the service to increment the number of blocks assigned to the referenced pool and return a pointer to the block along with the Service Completion Code of CC_GOOD. Once the service has assigned maxblkcnt RAM blocks to the SOFT_DEMAND memory pool, it changes the memory pool s type to SOFT_FIXED for all subsequent operations on the pool. However, if the service cannot fulfill the request from either used RAM or directly from User RAM, it changes the pool type to SOFT_FIXED and sets it maximum number of RAM blocks to the number of blocks currently assigned to it. The service then treats the current request according to the value of the waitcode parameter as described for a SOFT_FIXED memory pool type. Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 192 of 214

193 Chapter 12: POOLID void NSCC Regardless of the referenced memory pool s type, when the service allocates the last available RAM block in the pool and the pool s POOL_EMPTY event is associated with an Event Action Routine, the service will schedule execution of any EAR associated with the event. If no EAR is defined, the service is complete and returns to the caller. pid; *pblockptr; nscc; Example /* create a memory pool */ pid = ES_CreatePool(&TestPoolProps, (NSCC *)0); /* Get next available block in the pool but wait no more than * 500 ticks */ pblockptr = ES_GetPoolBlk(pID, 500, &nscc); if (nscc == CC_TIMEOUT) /* the service timed out. No block of RAM allocated */ } else /* the service succeeded */ Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 193 of 214

194 Chapter 12: See Also ES_CreatePool, ES_FreePoolBlk, ES_DefPoolAction Terminal Error Codes (When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE TE_TICKS_MUST_BE_NOPEND TE_IDLE_TASK_CANNOT_WAIT TE_ILLEGAL_USE_OF_TIMED_WAIT Function Code given to Terminal Error Handler GET_POOL_BLOCK Operation of this service is deterministic if a RAM block is available in the referenced pool at the time of the request, regardless of the memory pool type. Operation of this service is deterministic if a RAM block is available in the referenced pool at the time of the request, regardless of the memory pool type. Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 194 of 214

195 Chapter 12: ES_GetPoolBlkSize Get the size of a block of RAM in a specified memory pool Prototype Inputs pid pnscc Output BLOCKSIZE ES_GetPoolBlkSize(POOLID pid, NSCC *pnscc) Identifier of the memory pool from which the service is to get and return the size of a block of RAM in the pool Pointer to a variable that is to receive the Service Completion Code as an enumerated value of type NSCC. If defined as a null pointer, ((NSCC *)0), the service will not return a Service Completion Code. BLOCKSIZE The size of a RAM block in the given memory pool expressed as a value of type BLOCKSIZE Service Completion Codes Interpretation CC_GOOD CC_TERMINAL_ERROR POOLID pid; BLOCKSIZE blksize; The service completed successfully A terminal error occurred when both DIAGNOSTICS and RETURN_FROM_TE_MANAGER are defined. Get the size of a RAM block in a specified memory pool and return the value to the caller Example /* Create a Memory Pool */ pid = ES_CreatePool(&TestPoolProps, (NSCC *)0); /* Get the memory pool s block size */ blksize = ES_GetPoolBlkSize(pID, (NSCC *)0); See Also ES_CreatePool Terminal Error Codes (When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE Function Code given to Terminal Error Handler GET_POOL_BLOCK_SIZE Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 195 of 214

196 Chapter 12: ES_GetPoolFreeBlkCount Get the number of available RAM blocks in the specified memory pool Prototype Inputs pid pnscc Output KCOUNT ES_GetPoolFreeBlkCount(POOLID pid, NSCC *pnscc) Identifier of the memory pool from which the service is to get and return the number of free RAM blocks that are available in the given memory pool Pointer to a variable that is to receive the Service Completion Code as an enumerated value of type NSCC. If defined as a null pointer, ((NSCC *)0), the service will not return a Service Completion Code. KCOUNT The number of available RAM blocks in the pool expressed as a value of type KCOUNT Service Completion Codes Interpretation CC_GOOD CC_TERMINAL_ERROR POOLID KCOUNT The service completed successfully A terminal error occurred when both DIAGNOSTICS and RETURN_FROM_TE_MANAGER are defined. Get the number of free (i.e., available) RAM blocks in the referenced memory pool and return the value to the caller. pid; blkcnt; Example /* Create a Memory Pool */ pid = ES_CreatePool(&TestPoolProps, (NSCC *)0); /* Get the number of free blocks remaining in the given memory pool */ blkcnt = ES_GetPoolFreeBlkCount(pID, (NSCC *)0); See Also ES_CreatePool Terminal Error Codes (When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE Function Code given to Terminal Error Handler GET_POOL_FREE_BLK_COUNT The default limit on the number of RAM blocks in a given memory pool is 255. If more is required, it will be necessary to adjust the typedef of KCOUNT. Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 196 of 214

197 Chapter 12: ES_GetPoolName Get the name of a memory pool given its identifier Prototype Inputs pid pnscc Output char * > 0 char * = 0 char * ES_GetPoolName(POOLID pid, NSCC *pnscc) Identifier of the memory pool that the service is to find, returning the character pointer to its name string Pointer to a variable that is to receive the Service Completion Code as an enumerated value of type NSCC. If defined as a null pointer, ((NSCC *)0), the service will not return a Service Completion Code. Pointer to the given memory pool s name string Case 1: The referenced pool identifier is not found in the Memory Pool class as confirmed by the Service Completion Code of CC_OBJECT_NOT_IN_CLASS Case 2: The pool identifier and its name are inactive as confirmed by the Service Completion Code CC_INACTIVE_OBJECT Case 3: The pool identifier is correct and the memory pool was found but its name string in null (i.e., defined by ) as confirmed by the Service Completion Code of CC_GOOD Service Completion Codes Interpretation CC_GOOD CC_INACTIVE_OBJECT CC_OBJECT_NOT_IN_CLASS CC_TERMINAL_ERROR char POOLID NSCC Successful service completion The memory pool is inactive and its name is undefined The referenced memory pool identifier is not a member of the Memory Pool class A terminal error occurred when both DIAGNOSTICS and RETURN_FROM_TE_MANAGER are defined. Given the identifier for a memory pool, return the pointer to its name string if the pool is active, i.e., in use. If the pool is active but its name has been defined as a null string ( ), the service returns a pointer to that null string for the pool s name. In either case, the service returns a Service Completion Code of CC_GOOD. If the memory pool is closed or otherwise inactive, the service returns a null pointer and the Service Completion Code of CC_INACTIVE_OBJECT If the pool s identifier is not valid, the service returns a null pointer and the Service Completion Code of CC_OBJECT_NOT_IN_CLASS *pname; pid; nscc; Example /* Create a memory pool */ pid = ES_CreatePool(&TestPoolProps, (NSCC *)0); /* Find the memory pool given its ID */ pname = ES_GetPoolName(poolID, &nscc); Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 197 of 214

198 Chapter 12: if (nscc!= CC_GOOD) /* the service failed to find the memory pool */ } else /* the service succeeded */ See Also ES_CreatePool, ES_FindPool Terminal Error Codes (When DIAGNOSTICS defined) TE_BAD_OBJECT_ID TE_OBJECT_NOT_IN_EXPECTED_CLASS TE_OBJECT_NOT_IN_USE TE_UNUSABLE_OBJECT Function Code given to Terminal Error Handler GET_POOL_NAME Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 198 of 214

199 Chapter 13: Chapter 13 Mutex Class The Mutex Class in the Novos PPS environment provides an expanded means of granting a Background task exclusive access to a resource beyond that provided by the Semaphore Class. In the Mutex Class, a mutex object keeps track of its owner and only its owner can release it. In the Novos PPS environment, Background tasks do not necessarily have the same priority, which can lead to priority inversion situations that the mutex class services must handle. Foreground entities are not allowed to acquire a mutex. Mutex Properties The properties needed to create a mutex are contained in a Mutex Properties structure with a defined type MUTEXPROP as follows: Properties 13-1 Mutex Properties Structure typedef struct /* Mutex properties structure */ char *pname; /* pointer to mutex's name */ PI_MODE PIproto; /* Priority Inversion handling protocol */ PRIORITY CeilingPrio; /* Ceiling Priority for mutex if PIproto is IIP */ } MUTEXPROP; The PIproto defines the protocol for handing priority inversions that occur for the mutex. PIproto is an enumerated value of type PI_MODE (found in the file ENUMcodes.h) and has the following permissible values: Copyright 2016 Embedded Environments Co.- All Rights Reserved Page 199 of 214